IF Commons GitHub

Git hosts

0001Draft

0001-githost · owner if · domain commons

The interface

FR-001checkpassing

Git hosts MUST be reached only through one GitHostClient interface, shaped at the same time for GitHub (public and private repositories), GitLab (public and private repositories, groups to any depth) and plain Git, and the interface MUST NOT be fixed until the three adapters pass the same conformance tests.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-adapters.test.ts, githost-live.test.ts: GitHub, GitLab and plain Git pass the same conformance function (githost-conformance.ts)

Proved by: githost/suite/githost-adapters.test.ts, githost/suite/githost-gitlab-anonymous.test.ts, githost/suite/githost-live.test.ts

Written in: githost/src/git.ts, githost/src/github.ts, githost/src/gitlab.ts, githost/src/types.ts

Tests: passed: suite/githost-adapters.test.ts the GitHub adapter passes the shared conformance tests; passed: suite/githost-adapters.test.ts the plain Git adapter passes the shared conformance tests on a real repository and a real ; passed: suite/githost-adapters.test.ts the GitLab adapter passes the shared conformance tests, groups to any depth included; passed: suite/githost-gitlab-anonymous.test.ts a public GitLab project answered with no credential, and with no archived key, is read as ; passed: suite/githost-live.test.ts GitHub over the live transport: public and private repositories, the credential only in a and 1 more

Cited by: git, github, gitlab, Githost, mod, Intellectual Frontiers Capabilities Configuration Management

FR-002checkpassing

Every Git host kind MUST offer the common capabilities: the clone URL of a repository (ifccm:CloneUrl), authentication (ifccm:Credentials), the default branch (ifccm:DefaultBranch) and whether a commit's signature verifies (ifccm:SignedCommits); and GitHub and GitLab MUST also offer protected branches (ifccm:ProtectedBranches), issues (ifccm:Issues) and pull or merge requests (ifccm:ChangeRequests) behind the same calls.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-adapters.test.ts: GitHub issues with their parent and sub-issues, pull requests, protected branches and signatures, and the GitLab counterparts through the same calls

Proved by: githost/suite/githost-adapters.test.ts

Written in: githost/src/capabilities.ts

Tests: passed: suite/githost-adapters.test.ts GitHub: issues with their parent and sub-issues, pull requests, protected branches and sig; passed: suite/githost-adapters.test.ts GitLab: issues and merge requests, protected branches and signatures, as the API offers th

Cited by: capabilities, Githost, types, Intellectual Frontiers Capabilities Configuration Management

FR-003checkpassing

A capability that a Git host kind does not list (ifccm:supports) MUST be answered with a typed result that says it is unsupported, naming the host and the capability, and MUST NOT be silently skipped, emulated or thrown: GitLab alone offers groups to any depth (ifccm:NestedGroups), and plain Git offers no protected branches, issues or change requests.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-adapters.test.ts, githost-remote.test.ts: a capability a kind lacks is a typed unsupported result naming the host and the capability

Proved by: githost/suite/githost-adapters.test.ts, githost/suite/githost-remote.test.ts

Tests: passed: suite/githost-adapters.test.ts the GitHub adapter passes the shared conformance tests; passed: suite/githost-adapters.test.ts the plain Git adapter passes the shared conformance tests on a real repository and a real ; passed: suite/githost-adapters.test.ts plain Git: a remote that wants a credential is unauthorized, never a prompt, and the progr; passed: suite/githost-remote.test.ts a capability a kind lacks is a typed answer naming both, and the depth a kind allows is to

Cited by: capabilities, git, Githost, types, Intellectual Frontiers Capabilities Configuration Management

FR-004checkpassing

A Git host adapter MUST authenticate through a Git credential helper, through the host's own command-line tool (gh, glab) or through a token read from the environment it is handed, and MUST NOT write a credential into any file, a remote URL, a result or an error; a token MUST be sent only to the host the client serves, and in a header alone.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-adapters.test.ts, githost-live.test.ts, githost-remote.test.ts: a private repository asked with no credential is not found and typed; the token is read from the environment given to clientFor, sent in a header to the one host it serves, and held in no result, URL or error

Proved by: githost/suite/githost-adapters.test.ts, githost/suite/githost-live.test.ts, githost/suite/githost-remote.test.ts

Written in: githost/src/http.ts, githost/src/mod.ts

Tests: passed: suite/githost-adapters.test.ts plain Git: a remote that wants a credential is unauthorized, never a prompt, and the progr; passed: suite/githost-adapters.test.ts GitHub: a private repository asked with no credential is not-found, as GitHub says, and ev; passed: suite/githost-adapters.test.ts GitLab: a private project asked with no credential is not-found, as GitLab says, and every; passed: suite/githost-live.test.ts GitHub over the live transport: public and private repositories, the credential only in a ; passed: suite/githost-live.test.ts GitLab over the live transport: the credential in `PRIVATE-TOKEN` or `JOB-TOKEN`, never in and 2 more

Cited by: github, Githost, Intellectual Frontiers Capabilities Configuration Management

Remotes

FR-005checkpassing

The kind of host for a remote MUST be GitHub for github.com, GitLab for gitlab.com and for a host a map names as GitLab, and plain Git for every other host; a self-hosted GitLab MUST be named and MUST NOT be guessed from a URL.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-remote.test.ts, githost-live.test.ts: GitHub for github.com, GitLab for gitlab.com and the hosts a map names, plain Git for every other, and a self-managed GitLab never guessed

Proved by: githost/suite/githost-gitlab-anonymous.test.ts, githost/suite/githost-live.test.ts, githost/suite/githost-remote.test.ts

Tests: passed: suite/githost-gitlab-anonymous.test.ts a public GitLab project answered with no credential, and with no archived key, is read as ; passed: suite/githost-live.test.ts clientFor reads a token only from the environment it is given, only for a host that may ho; passed: suite/githost-remote.test.ts the kind of host is GitHub, GitLab or plain Git by the rule, and a self-managed GitLab is

Cited by: Githost, remote, Intellectual Frontiers Capabilities Configuration Management

FR-006checkpassing

A repository whose path is deeper than its host kind supports (more than two segments on a host without ifccm:NestedGroups) MUST be told by the depth the kind allows (maxDepth), so that a caller can refuse it naming the host and the path.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-remote.test.ts, githost-adapters.test.ts: maxDepth is two for a kind without nested groups and unbounded for GitLab, whose groups go to any depth

Proved by: githost/suite/githost-adapters.test.ts, githost/suite/githost-remote.test.ts

Written in: githost/tools/check.ts, githost/tools/pack.ts

Tests: passed: suite/githost-adapters.test.ts the GitLab adapter passes the shared conformance tests, groups to any depth included; passed: suite/githost-remote.test.ts a capability a kind lacks is a typed answer naming both, and the depth a kind allows is to

Cited by: gitlab, Githost, mod, types, Intellectual Frontiers Capabilities Configuration Management

FR-007checkpassing

The https, http, git, ssh and scp-like (git@host:owner/repo) spellings of one remote MUST read as one RepoRef, the host in lower case, the port, the credential and the .git dropped; and a text that is not a remote of a host (a path on this computer, a file: URL, an owner with no repository) MUST be refused with what is wrong with it, holding no credential.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-remote.test.ts: https, ssh, scp-like and git forms of one remote are one repository, a credential in a remote is dropped, and a text that is not a remote is told by what is wrong with it

Proved by: githost/suite/githost-remote.test.ts

Written in: githost/src/remote.ts

Tests: passed: suite/githost-remote.test.ts a credential in a remote is dropped, and no result and no error holds it; passed: suite/githost-remote.test.ts a text that is not a remote of a host is told by what is wrong with it; passed: suite/githost-remote.test.ts https, ssh, scp-like and git forms of one remote are one repository

Cited by: Githost, remote

FR-008checkpassing

A remote as a person writes it MUST be read where the domain says the rest: github.com/owner/repo and gitlab.example.com/group/sub/repo with no scheme, owner/repo as a repository of GitHub, github:owner/repo and gitlab:group/sub/repo, and the address of a branch's page (.../tree/main, GitLab's /-/tree/main) as the repository and that branch; a path on this computer MUST still be refused.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-remote.test.ts: a remote with no scheme, owner/repo, the host prefixes and the address of a branch's page are read, and a path on this computer is still refused

Proved by: githost/suite/githost-remote.test.ts

Tests: passed: suite/githost-remote.test.ts a remote as a person writes it needs no scheme where the domain says the rest, `owner/repo

Cited by: Githost, remote

The library

FR-009checkpassing

The types, the table of capabilities and the reader of a remote MUST import core alone, and the adapters MUST import only node: built-ins, core, net and system, so that the types are pure and no other library is needed to read a remote.

Enforced (check): .github: cd commons/githost && bun test suite/ — githost-boundaries.test.ts: the types, the table and the reader import core alone, and the adapters only node: built-ins, core, net and system

Proved by: githost/suite/githost-boundaries.test.ts

Tests: passed: suite/githost-boundaries.test.ts the types, the table of capabilities and the reader of a remote import core alone, and the

FR-010checkno test run

The library MUST be published to npm as compiled modules with their declarations, one entry for the package (.) and one for each module (./types, ./capabilities, ./remote, ./github, ./gitlab, ./git), and its declarations MUST name no package it does not declare (commons 0032-libraries-by-concern FR-005, FR-013).

Enforced (check): .github: cd commons/githost && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/commons-packages.test.ts installs the tarball, runs every entry on Node 26 and Bun and type-checks a consumer

Written in: githost/about.ts, githost/library.ts

Acceptance scenarios

  1. Given a recorded GitHub, a recorded GitLab and a real plain Git repository, When the same conformance tests run on each adapter, Then all three pass, per FR-001.
  2. Given a capability a kind does not offer, When it is asked, Then the answer is a typed unsupported result naming the host and the capability, per FR-003.
  3. Given a token in the environment, When a client is made, Then the token is held in the client, sent in a header to the one host it serves, and appears in no result, URL or error, per FR-004.
  4. Given git@github.com:octo/hello.git and https://github.com/octo/hello, When each is read, Then they are one repository, per FR-007.
  5. Given octocat/Hello-World and gitlab.com/g/s/r/-/tree/feature, When each is read, Then the first is a repository of GitHub and the second is a repository of GitLab on the branch feature, per FR-008.

Out of scope

  • A host's account, its tokens and the network's reliability: a live test of the hosts is skipped where there is no account.
  • The typed model of GitHub Actions workflows: another library's.

Edge cases

  • A GitHub or GitLab project that is private, asked with no credential: not found, as the host says, and typed, per FR-004.
  • A self-hosted GitLab not named in the map: plain Git, never guessed, per FR-005.
  • A remote with a credential in it: the credential is dropped and never in an error, per FR-007.

Assumptions

  • The hosts' REST APIs (GitHub v3, GitLab v4) keep the fields the adapters read.

Open questions

  • None.

Key entities

  • GitHostClient - the one interface to a Git host.
  • RepoRef - a repository on a host: its kind, its host and its path.
  • Capability - what a kind of host offers, from ifccm:GitCapability.

Success criteria

SC-001success criterion

A check or a workspace reads any remote a person writes and asks any of the three kinds of host through one interface.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

capabilities, git, github, gitlab, Githost, mod, remote, types, Intellectual Frontiers Capabilities Configuration Management

Titles, headings, exports, tables, columns and requirements. Esc closes.