@foss.global/interfaces

Shared TypeScript DTOs and TypedRequest contracts for the foss.global Git platform ecosystem.

This package intentionally contains contracts only. Runtime forge adapters belong in @foss.global/codefeed, and the Git storage/protocol engine belongs in @foss.global/gitmanager.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @foss.global/interfaces

Usage

import type { data, requests } from '@foss.global/interfaces';

const repo: data.IPublicRepo = {
  id: 1,
  org: 'foss.global',
  name: 'interfaces',
  slug: 'foss.global/interfaces',
  orgAvatarUrl: '',
  description: 'Shared contracts',
  language: 'TypeScript',
  htmlUrl: 'https://code.foss.global/foss.global/interfaces',
  cloneUrl: 'https://code.foss.global/foss.global/interfaces.git',
  sshUrl: 'ssh://git@code.foss.global:29419/foss.global/interfaces.git',
  starsCount: 0,
  forksCount: 0,
  watchersCount: 0,
  openIssuesCount: 0,
  openPrCount: 0,
  releaseCount: 0,
  size: 0,
  defaultBranch: 'main',
  updatedAt: new Date().toISOString(),
  createdAt: new Date().toISOString(),
  archived: false,
  topics: [],
};

type PublicOverviewRequest = requests.IReq_PublicOverview;

Archived pull request contracts

IPublicArchivedPullRequest is a pull request archived from the source forge, read-only, with its whole conversation embedded: comments, and reviews each with its own comments on the diff (diffHunk as recorded; an archive computes no diff). Every field is as the source recorded it: state with merged, the merge fields, base, head (with the head repository), mergeBase, draft, locked, pinOrder, dueDate, and labels and milestone as snapshots. Each person is an IPublicArchivedPullRequestAccount: the source account's id and login, never an email, and user, the native user it resolves to or null. A review's state is the source's value (APPROVED, COMMENT, REQUEST_CHANGES, REQUEST_REVIEW); a pending review is never archived. It extends IPublicArchivedPullRequestSummary, the same fields without the conversation and with commentCount and reviewCount. IReq_PublicRepo's response carries the optional archivedPullRequests (summaries, like every list of that response) and selectedArchivedPullRequest (the archived pull request pullRequestNumber names when no native one holds it, with its conversation); both are absent from servers that predate the archive. IPublicPullRequest stays the native pull request alone.

Repository release API contracts

The code host's native release API, /api/v1/repositories/:org/:repo/releases, as JSON on the wire. IRepositoryReleaseCreateRequest (POST, answered 201) names the tag and optionally name (the tag name by default), body, prerelease and draft; the code host resolves the tag's target object. IRepositoryReleaseUpdateRequest (PUT …/releases/:tag, answered 200) changes any of the four and leaves an omitted one as it is; draft: false publishes. Both bodies are closed and no field is nullable. Answers are envelopes: IRepositoryReleaseListResponse ({ releases }, drafts included), IRepositoryReleaseResponse ({ release }) and IRepositoryReleaseAssetResponse ({ asset }, for POST …/releases/:tag/assets/:name). An IRepositoryRelease carries its releaseId, targetObjectId, author (an IPublicUser), ready assets and ISO 8601 times; publishedAt is null until the first publication and stays set when a release turns back into a draft. An IRepositoryReleaseAsset always carries its verified sha256 and sizeBytes. IPublicRelease stays the public website's read model.

Runner and CI contracts

Runner protocol v1 is exposed through runnerProtocolVersion. The package root and the data namespace both export the complete runner and CI DTO set:

import {
  runnerProtocolVersion,
  type IClaimJobResponse,
  type ICiEnqueueJobRequest,
  type IRegisterRunnerRequest,
} from '@foss.global/interfaces';

const registration: IRegisterRunnerRequest = {
  registrationRequestId: 'registration-1',
  protocolVersion: runnerProtocolVersion,
  runnerVersion: '0.1.0',
  name: 'linux-amd64-1',
  labels: ['linux', 'amd64'],
  capabilities: {
    executor: 'oci',
    runtime: 'docker',
    networks: ['none', 'bridge'],
    sourceArchives: ['tar.gz'],
    artifacts: false,
    caches: false,
    serviceContainers: false,
  },
};

const enqueue: ICiEnqueueJobRequest = {
  idempotencyKey: 'build-main-1',
  tenantId: 'foss.global',
  repositoryId: 'foss.global/interfaces',
  requiredLabels: ['linux', 'amd64'],
  job: {
    image: 'node:24',
    command: ['pnpm', 'test'],
    network: 'none',
  },
};

type ClaimedJob = IClaimJobResponse;

The runner lifecycle contracts cover registration, sessions, runner and job heartbeats, claim/lease identity, fencing tokens, ordered log chunks, completion, abandonment, and recovery. The CI control-plane contracts cover job enqueue and summaries, log pages, cancellation, and runner drain state.

Protocol v1 describes OCI execution with Docker or Podman and tar.gz source archives. Artifacts, caches, and service containers are explicitly unsupported in the v1 capability shape. Supported job network modes are none and bridge; the execution service remains responsible for enforcing the advertised capability.

GitManager ref inventory contracts

IGitManagerRefRequest, IGitManagerRef, and TGitManagerRefInventoryResult describe a complete, paginated ref inventory. Without prefixes, every ref under refs/ is listed, including notes, pull, keep-around, and provider-internal namespaces. HEAD is reported separately in head. Annotated tags carry their fully peeled object. Symbolic refs carry their target ref name; a symbolic ref whose target does not resolve is still listed, with a null objectId and objectType.

import type {
  IGitManagerRef,
  IGitManagerRefRequest,
  TGitManagerRefInventoryResult,
} from '@foss.global/interfaces';

declare function listRefs(
  request: IGitManagerRefRequest,
): Promise<TGitManagerRefInventoryResult>;

const collectRefs = async (): Promise<IGitManagerRef[]> => {
  const refs: IGitManagerRef[] = [];
  let cursor: string | undefined;
  while (true) {
    const result = await listRefs({ org: 'foss.global', repo: 'interfaces', cursor });
    if (result.status === 'stale') {
      refs.length = 0;
      cursor = undefined;
      continue;
    }
    refs.push(...result.refs);
    if (result.pagination.status === 'exhausted') {
      return refs;
    }
    cursor = result.pagination.cursor;
  }
};

// A complete ref name as the only prefix is an exact lookup.
const main = await listRefs({
  org: 'foss.global',
  repo: 'interfaces',
  prefixes: ['refs/heads/main'],
});

Prefixes match whole path components, so refs/heads/ma does not select refs/heads/main. Overlapping prefixes select their de-duplicated union, and an empty prefixes array is rejected as invalid. Pages are sorted by ref name in byte order and each carries inventoryDigest, the SHA-256 of the complete selection defined on IGitManagerRefInventoryPage. A cursor is opaque and bound to the repository, the prefix set, and that digest. When the selected refs or HEAD change between pages, the next call returns status: 'stale' instead of a page that would mix two states; the caller restarts without a cursor. A cursor is a transport continuation, not a durable replication checkpoint.

GitManager remote transfer and size contracts

IGitManagerImportMirrorRequest and IGitManagerRefreshMirrorRequest take IGitManagerRemoteTransferOptions: an optional credential (TGitManagerRemoteCredential, HTTP Basic), optional caCertificates (PEM, used as Git's CA bundle for that transfer) and an optional timeoutMs (default 120000, at most 21600000). A credential reaches Git only through the Git process environment as an Authorization header, so it never appears in the remote URL, on a command line, in the repository's Git config, or in an error. It requires an https remote without user information, and Git does not follow redirects while it carries one. A refresh reuses the mirror's stored remote URL. Import and refresh never take an SSH key: it belongs to the push alone (TGitManagerAtomicPushCredential).

IGitManagerRepositorySize measures a repository's object database: objectCount distinct objects, objectBytes (their uncompressed sizes, which do not depend on packing) and storageBytes (every file of the object database, which does).

GitManager atomic push and default branch contracts

IGitManagerAtomicPushRequest pushes IGitManagerAtomicPushRefUpdates from a managed repository to remoteUrl as one transaction: the remote applies every update or none, and a remote that does not advertise the atomic capability is refused rather than pushed to ref by ref. Every update is leased: expectedOldObjectId is the object the remote ref must point at now (null to create a ref that must not exist), and newObjectId is the object to set (null to delete). The URL is used for that push only; it must be https, or http to a loopback host. The transfer options are those of importMirror, except that a push credential is also accepted for loopback http.

A push also goes over SSH: its credential is a TGitManagerAtomicPushCredential, the transfer credentials plus IGitManagerRemoteSshKeyCredential (kind: 'sshKey', an unencrypted privateKey and the remote's hostKey). The host key is required and pinned: one OpenSSH key line, <type> <base64>, with no host name or comment, and every other host key is refused. An SSH key goes with an ssh://<user>@<host>[:<port>]/<path> URL and only with one; a path outside [A-Za-z0-9._/-] is refused, never escaped. caCertificates with an sshKey credential are refused. TGitManagerRemoteCredential, which import and refresh share, has no SSH member.

import type { IGitManagerAtomicPushRequest } from '@foss.global/interfaces';

const push: IGitManagerAtomicPushRequest = {
  org: 'freeze',
  repo: 'canary',
  remoteUrl: 'ssh://git@code.foss.global:29419/freeze-canary/probe.git',
  credential: { kind: 'sshKey', privateKey, hostKey: 'ssh-ed25519 AAAAC3Nz...' },
  updates: [{ ref: 'refs/heads/canary', expectedOldObjectId: null, newObjectId }],
};

An https push may set connectAddress, an IP literal (IPv6 without brackets) that the push connects to directly, never through a proxy, instead of the address DNS gives for the URL's host, on the URL's port. The Host header and the TLS server name stay the URL's host, and the certificate is verified against that name, so one name can be pushed to through a second network path. It is refused with an sshKey credential, a URL that is not https, a URL whose host is an IP literal, and an address that is not an IP literal. Only the push takes it: IGitManagerRemoteTransferOptions, which import and refresh share, has no connectAddress.

const directPush: IGitManagerAtomicPushRequest = {
  org: 'freeze',
  repo: 'canary',
  remoteUrl: 'https://code.foss.global/freeze-canary/probe.git',
  connectAddress: '192.0.2.10',
  credential: { kind: 'basic', username: 'freeze-canary-probe', password },
  updates: [{ ref: 'refs/heads/canary', expectedOldObjectId: null, newObjectId }],
};

IGitManagerAtomicPushResult is applied when every ref is ok and rejected when no ref changed. Each IGitManagerAtomicPushRefResult is ok, stale (the lease failed) or rejected (a hook, ref protection, or another ref of the same push failed), with the remote's reason as message. Every ref that is not ok also carries a classified TGitManagerAtomicPushRefReason: stale-lease, atomic-collateral (refused only because another ref failed), transaction-failed (the remote could not commit, typically a concurrent change; read the remote back), hook-declined, non-fast-forward, local-rejected or remote-rejected for any other refusal.

Every result carries remoteMessages, the remote's remote: lines in order (a hook's output, for example) without the prefix and trailing padding, for https and ssh alike, and empty when the remote sent none. The engine bounds the list in count and bytes and says so in its last element when it cut it; credentials are redacted as in message. It is free text: a consumer may look for a value it chose, such as a freeze nonce, and never branches on anything else.

IGitManagerSetDefaultBranchRequest points a repository's HEAD at an existing branch, named as in IGitManagerRepositoryInfo.defaultBranch. With allowUnborn: true the branch may not exist yet: HEAD then names it unborn until a push creates it, so that one atomic push can create the new default branch and delete the old one, which Git refuses while HEAD names the old one.

An IGitManagerProtectedRefViolation names a ref update that the protected ref rules or a held tag refuse and the TGitManagerProtectedRefViolationRule it breaks: create, delete, force-push (the old object is not an ancestor of the new one), not-a-commit or held-tag (a release holds the tag at its stored object, and the update's new object is not that object: moving the tag, deleting it, or creating a missing held tag at another object; pointing it at exactly the held object is allowed, whatever the old object was). GitManager decides it with the same check its pre-receive hook enforces.

Origin contracts

TOriginState records where a native entity came from: native, imported with an IOriginRef, or unknown, which never means native. An IOriginRef names the source by the operator-minted forge connection instanceId, the entityKind (repository), the source entityId (a Gitea repository's decimal ID) and parentId (null for repositories, whose Gitea IDs are unique per instance). It carries no URLs, paths, configuration or run IDs, digests, or authority.

Forge inventory contracts

IForgeInventoryReport, IForgeInventoryPage<TItem>, IForgeInventoryNamespace, IForgeInventoryRepository and IForgeInventoryIssue describe operator inventory observations. They are exported from both the package root and data. This package supplies types; it does not scan a forge or validate network responses.

Stable provider identifiers are opaque strings qualified by instance and ID namespace. Mutable paths remain separate segment arrays, preserving GitLab subgroups and literal hyphens. A source without a stable identifier reports an unresolved identity. URLs must be credential-free, and inventory responses need operator authorization rather than anonymous public exposure.

Issue observations separate the provider row ID from its repository-local number (GitLab iid) and retain the repository identity. They preserve empty body text, unknown metadata, open/closed state, provider issue classification, confidentiality, reported author identity and provider content timestamps. The reported author does not prove original attribution for previously imported issues. Comments, labels, milestones, assignees, attachments and history require their own inventory and preservation work; this metadata DTO does not claim that those collections or external writes are implemented.

Every canonical entity class has an explicit capability and collection result, including classes not inspected or unavailable. Additional provider features have their own entries. enumerated means the selected collection was exhausted for its recorded visibility scope; a public or caller-visible live scan does not establish a complete frozen migration inventory. Page continuation, exhaustion, and interrupted enumeration have distinct discriminated shapes.

Counts and byte quantities use nonnegative decimal strings to avoid JSON integer precision loss. Unknown size differs from zero, and estimated repository storage size is not the size of a future Git push. Runtime adapters must validate values, scope consistency, capability/result agreement, cursor binding, diagnostics, and authorization. These DTOs do not establish replication authority, historical import fidelity, checksummed manifests, or durable recovery checkpoints.

Forge source inventory contracts

IForgeSourceInventoryReport is the authenticated, read-only measurement of a source forge before its one-time migration, read with a site administrator's token. It counts users, organizations, teams, memberships, keys, packages by type (and, when a run selects them, records each package and each repository's issues and pull requests), and per repository the Git refs and objects, LFS objects, issues, pull requests, comments, reviews, reactions, attachments, releases (drafts included) with asset bytes, wiki pages, access settings, webhooks, push mirrors, Actions settings, and the Actions runs and artifacts that are archived rather than migrated.

Every count is a TForgeSourceMeasure: complete with a decimal-string value, partial with the value observed before a retryable failure, or notMeasured when no read was attempted. inventoryComplete is true only when discovery finished and no measure is partial or not measured; incompleteReasons lists why not. limitations names source data the provider exposes to no administrator read and that is reissued rather than migrated, such as Gitea's user-scoped Actions secrets; everything readable is a measure instead. Reasons are sanitized text, never raw response bodies or URLs.

Git counts other than the forge-reported size, and LFS counts, are read at the Git level from a mirror clone of every advertised ref: refs by namespace, distinct objects and their uncompressed bytes, and the LFS objects that pointers in any reachable revision reference. LFS objects are checked through the forge's LFS batch API and split into held objects with their bytes and missingObjects, which cannot be migrated.

The same mirror records the repository's head, an IForgeSourceRepositoryHead: the ref HEAD names as target (null when HEAD is detached or not symbolic) and whether it resolves. An empty repository's HEAD is unborn and does not resolve; in any other repository a HEAD that does not resolve names a missing branch, such as a default branch deleted at the source, and an import's HEAD diverges from the source at apply time until the source names an existing branch. A target that differs from the API's defaultBranch shows that the forge's setting and its Git HEAD disagree. head is null when the mirror was not measured and absent in reports from generators that predate it.

The same mirror records refDigests, an IForgeSourceRefDigests with one IForgeSourceRefNamespaceDigest each for refs/heads/, refs/tags/ and refs/notes/: GitManager's inventoryDigest over HEAD and the refs under that prefix, as an IGitManagerRefInventoryPage defines it, and the refCount of that selection. The digest does not cover the repository's name, so a consumer compares it with the digest of the same prefix in any other GitManager repository to prove both hold the same refs. Pull request refs have no digest. git.otherRefs includes the notes refs, so git.otherRefs - notes.refCount refs belong to no digested namespace. refDigests is null when the mirror was not measured or any digest could not be read, never partial, and absent in reports from generators that predate it.

A repository records its description verbatim as the forge's API reports it, without trimming or normalising; '' means the source repository has no description. It is never null. It is absent in reports from generators that predate it, and a consumer treats an absent description as unread, never as ''.

Beside its counts, a repository records each release as a TForgeSourceRelease in releaseRecords, drafts included: the source ids, tag, target, name, body, flags, the forge's creation and publication times, an IForgeSourceReleaseAuthor snapshot (the source account's id and login, never a native user) and its IForgeSourceReleaseAssets with their storage uuid, name as stored, size and download count. The forge exposes no asset digest, so none is recorded; a consumer verifies content itself. The download count moves with every download and never decides whether a release changed. A release is an IForgeSourcePublishedRelease (draft: false), whose publishedAt is always a time, or an IForgeSourceDraftRelease (draft: true), whose publishedAt is null when the forge reports none, as Gitea 28 does for every draft. Both times are the forge's values verbatim: Gitea 28 reports the date of the commit a release points at as createdAt. protections records, as read, the branch and tag protection rules that access counts: an IForgeSourceBranchProtection keeps the rule name (an exact name or a glob), whether anyone may push or force-push, every allowlist with its switch, and the review, status check, signing and file pattern restrictions; an IForgeSourceTagProtection keeps its name pattern and allowlist. Whether a rule can be enforced natively is the consumer's verdict. Releases, assets and tag rules sort by numeric id, branch rules by name in code-unit order. Both are null when their counts are not complete and absent in reports from generators that predate them.

Owners are a TForgeSourceOwnerInventory union: an organization carries its members, teams, team memberships and repository grants, labels and Actions secret count; a user carries its account flags and SSH and GPG key counts. Both carry repositories, webhooks, Actions variables, runners and packages by type. totals.owners sums the owner-level counts; the repository-shaped totals sum repositories only.

Beside their counts, owners and repositories record who may access what, as the forge reports it and without a verdict:

  • A user's userRecord is an IForgeSourceUserRecord: id, login, the active, administrator, restricted and sign-in-prohibited flags, profile visibility, and every SSH key as an IForgeSourceUserSshKey (id, title, fingerprint, OpenSSH key type and public key), and fullName, the forge's full name verbatim ('' when unset). It is null when sshKeys is not complete; fullName is absent in reports from generators that predate it.
  • An organization's teamRecords are IForgeSourceTeamRecords: id, name, permission, unitsMap (null when the forge reports none), whether the team includes all repositories and may create them, its visibility, its members by id and login, and the ids of its repositories. Gitea 28 reports a granular team as permission none with a units map, and the Owners team as owner with a units map, so a consumer recognises Owners by permission alone. They are null when teams, teamMemberships or teamRepositoryGrants is not complete.
  • An organization's profile is an IForgeSourceOrganizationProfile: its fullName, description, website and location, each verbatim and '' when unset. website is not validated, because a value a forge's web form stored may not be a valid URL. The organization's email (personal data), its avatar URL (hosted by the forge, so it dies with it; a consumer acknowledges the avatar as not migrated), Gitea's repo_admin_change_team_access (the native forge has no teams) and its visibility (already on the owner) are deliberately not recorded. It is absent in reports from generators that predate it.
  • A repository's accessRecords is an IForgeSourceRepositoryAccess: its collaborators with the effectivePermission the forge reports for each, its SSH deploy keys (binding id, shared key row id, title, fingerprint, public key and mode) and its deploy tokens (id, title and mode only). The effective permission is the strongest of the collaboration, teams, ownership, site administration and public access, never the collaboration's own mode, which no REST endpoint reports. A deploy token is a credential that is reissued, so neither the token nor the masked form the forge reports in its place is recorded. It is null when access.collaborators, access.deployKeys or access.deployTokens is not complete; a producer reports access.collaborators complete only when it also read every collaborator's effective permission.

Records sort by numeric id (collaborators by user id) and access modes are a TForgeSourceAccessMode. All three are absent in reports from generators that predate them. access.deployTokens counts deploy tokens; when it is present, access.deployKeys counts SSH deploy keys only, while a generator that predates it counted the forge's whole deploy key list, which on Gitea 28 includes deploy tokens.

A repository's collaboration.byKind, an IForgeSourceCollaborationKindCounts, splits issues from pull requests: issueComments, issueReactions, issueAttachments and issueAttachmentBytes beside their pull request twins, and pull requests by state (openPullRequests, closedPullRequests for those closed without a merge, mergedPullRequests, which sum to pullRequests). Each mixed measure is the sum of its two kinds, so a disabled pull request unit leaves every issue measure measured. Every member of byKind is required, so the split is whole or absent; it is absent in reports from generators that predate it. collaboration.projects counts the repository's project boards and an owner's projects its own boards, both absent in reports from generators that predate them.

Issues and pull requests are recorded one collaboration unit per repository when a run selects the collaboration class, so their bodies never compete with the repository unit for the unit bound:

  • Discovery's collaboration: true selects the class; every discovered repository then has a { kind: 'collaboration', owner, name, id } unit, keyed by the repository's discovered id. A consumer refuses such a discovery while any repository lacks id, and never keys by name.
  • An IForgeSourceCollaborationInventory carries highestNumber, the highest number the forge lists among the repository's issues and pull requests, which share one sequence (0 when it lists none; a deleted number, or one a disabled unit hides, is invisible to every read), and the record lists labels, milestones, issues and pullRequests. pullRequests is absent in results from generators that predate it, and then unread.
  • Each list is a TForgeSourceCollaborationRecords: complete with every record, or notMeasured with a reason when no read was attempted, as for the issues of a repository whose issue unit is disabled. A read that fails fails the unit, so records are never partial, and unread is never empty. A list shares status with TForgeSourceMeasure, so a tool that finds measures by status reports a notMeasured list as a gap by its path (for example collaboration.issues); it never reads value from a complete list.
  • An IForgeSourceIssue is an issue, never a pull request: source id, number as a decimal string, title and body verbatim (never trimmed), state, the forge's creation, update and closing times, the poster as an IForgeSourceAccountRef (id and verbatim login, never a native user; a deleted account reads as the forge's placeholder), the IForgeSourceOriginalAuthor Gitea records for content it imported from another service (null when none), assignees, label ids, milestone id, locked, pinOrder (0 when not pinned), dueDate, ref (the branch or tag a user set, '' when none), projectIds (the project boards it is on, [] when none), timeEstimate (seconds, 0 when none), the counts trackedTimes (tracked time entries) and dependencies (issues it depends on), and the attachment and reaction counts of the issue itself. Gitea's content_version is not recorded: it counts concurrent edits and is not content. Its IForgeSourceIssueComments carry id, verbatim body, times, poster, original author and their own attachment and reaction counts.
  • An IForgeSourcePullRequest is recorded for an archive, never as a native pull request's state: source id, number as a decimal string, title and body verbatim, state (open or closed; a merged pull request is closed) with merged, mergedAt, mergeCommitSha and mergedBy as the source recorded them (null when it reports none; the forge reports no merge style), base (label, ref, sha, '' when the forge reports none) and head (the same plus the head repository's repositoryId, -1 when Gitea no longer has it, and repositoryFullName, null then), mergeBase ('' when the forge reports none), draft, the creation, update and closing times, the poster and original author, assignees, requestedReviewers (source accounts) and requestedReviewerTeams (IForgeSourceTeamRef: id and name), labels and milestone as snapshots of what the forge reports on the pull request (never ids to resolve), locked, pinOrder, dueDate, allowMaintainerEdit (recorded, never enforced), ref, projectIds, timeEstimate, trackedTimes and dependencies with the same sentinels as on an issue, its own attachment and reaction counts, its conversation comments as IForgeSourceIssueComments, its reviews and pendingReviews. A person is an IForgeSourceAccountRef (id and login), never an email or a native user.
  • An IForgeSourcePullRequestReview is a submitted review or a review request: id, reviewer (null when the forge names none, as for a review requested from a team), team, state (APPROVED, COMMENT, REQUEST_CHANGES or REQUEST_REVIEW, the forge's values verbatim), body, commitId, stale, official, dismissed, the submission and update times, attachments and reactions (decimal string counts for the review's own comment, the one that holds its body; 0 for a REQUEST_REVIEW, which has none), and its IForgeSourcePullRequestReviewComments (id, body, times, poster, resolver, path, commitId, originalCommitId, diffHunk, position and originalPosition as decimal strings, and their own attachments and reactions counts). Files and reactions on reviews and review comments are counted on these records only, never in the mixed attachments and reactions measures of the counts unit. A pending (draft) review, which only its author and administrators can see, is never a record: its pull request's pendingReviews counts it, without body or comments.
  • labels are IForgeSourceLabels (id, verbatim name, colour, description, exclusive, archived): every repository label, used or not, and never an organization label. An issue's labelIds may also name an organization label, which resolves against the owning organization's labelRecords (repository and organization labels share one id space). A consumer refuses a run where an issue names a label id found in neither list, or an organization label while that organization's labelRecords is null. milestones are every repository milestone, used or not, as IForgeSourceMilestones (id, title, description, state, creation, update and closing times, dueOn).
  • An organization's labelRecords are all its labels, the only place they are stored, so a consumer can name the ones no issue carries; null when labels is not complete.
  • Labels, milestones, comments, reviews, review comments, assignees, requested reviewers and teams sort by numeric id, issues and pull requests by numeric number, label ids numerically. The inventory's collaboration and each organization's labelRecords are present exactly when discovery's collaboration is present; absent means unread, never none. A collaboration unit over the unit bound fails with unit-over-bound.

Packages are recorded one per unit when a run selects the package class:

  • Discovery's packages lists each package as an IForgeSourcePackageRef (owner, type, name). The forge keeps one package per owner, type and lowercased name and exposes no other package id (Gitea's v1 package API reports the version id as id), so an IForgeSourcePackageInventory is identified by ownerId, type and its lowercased name.
  • A package record lists every IForgeSourcePackageVersion (id, version as stored, the forge's creation time, informational only) and, in blobs, each distinct content once as an IForgeSourcePackageBlob: the SHA-256 and size the forge reports and every IForgeSourcePackageFile (version id, file id, name as stored) holding it. Versions sort by numeric id, blobs by SHA-256, files by version id and file id. repositoryId is the linked repository's id or null.
  • A container version is a tag, lowercased, or a manifest digest sha256:<hex>, so a version is tagged exactly when it does not start with sha256:. Its manifest digest is the SHA-256 of the blob holding its manifest.json. An index version carries references, the sorted digests of the manifests it references; no other version carries the field.
  • Only state the forge can change without replacing a version is recorded beside the files: npm distTags (every dist-tag the forge serves, a derived latest included, since no read tells it from a stored one) and each version's deprecated message, and each Cargo version's yanked flag. Metadata fixed at publication (an npm version document, a Cargo index entry, Swift release metadata) is read when the version is transferred, except a Swift version's manifests (below). Download counts are never recorded.
  • A Swift version carries manifests, the IForgeSourceSwiftManifests (key, size, SHA-256 of the bytes the forge served) sorted by key in code-unit order, so a consumer that stores manifests beside the archive can size the version. The key is the trimmed Swift version the forge keys a manifest by (5.7, 5.7.1), '' for Package.swift. The producer takes the candidate keys from the manifest file names in the version's archive, after checking the archive against its recorded blob, and asks the forge for each. The field has three states, and neither unread state is ever read as no manifests or zero bytes:
    • absent: the inventory was recorded by a generator that predates it;
    • null: the archive was larger than the producer's read bound and was not read;
    • a list: exactly the manifests the forge answered 200 for, Package.swift always among them.
  • totals.packageContent is an IForgeSourcePackageContentTotals, a pure function of the package records: distinct digests and their bytes for every owner together and per owner, each by type, over all versions and over the tagged versions plus the manifests their indexes reference. It sizes stores that keep each digest once (Gitea globally, the native container registry per owner); a store that keeps every file needs the per-version file sums of the owners' package counts.
  • packages and totals.packageContent are present exactly when discovery's packages is present, an empty list included: a source without packages reads packages: [] and complete zeros. Absent means the package class is unread, never that the source holds no packages.
  • A unit result must fit forgeSourceInventoryUnitMaxBytes (4 MiB of UTF-8 JSON). A package or collaboration unit over it fails with the reason unit-over-bound; its record is never truncated.

A run first reads IForgeSourceInventoryDiscovery, then measures independent TForgeSourceInventoryUnits (the instance, each owner, each repository and, when discovery lists them, each package and, when discovery selects collaboration, each repository's collaboration). A consumer handles every unit kind and refuses one it does not know, since package and collaboration units carry owner and name like a repository unit. A failed unit, or one holding a partial measure, is measured again on resume. Discovery records each repository's id as a decimal string and its unit carries it, so a unit whose name now answers with another id fails instead of measuring the repository that took the name. id is absent in discoveries from generators that predate it; a consumer that keys on ids refuses those. IForgeSourceInventory is deterministic: it carries no run timestamps (the source's own times, such as release creation, are source state), owners sort by kind and name, repositories and collaborations by owner and name, packages by owner, type and name. The report adds collisionCheck, the source owner and repository names that already exist natively, exactly or case-insensitively, sorted by subject, source and native name. A report is a complete planning basis only when inventoryComplete is true and the collision check ran.

A report never contains secret values, credentials, tokens or the masked forms a forge reports in their place, private keys, Actions secret or variable values, webhook secrets, or mirror remote URLs.

forgeSourceReadStampFields lists the read stamps: fields the source changes when it is only read, so two inventories of a source nobody wrote to differ in them and in nothing else. Today that is a release asset's downloadCount. Each entry is the path from the root of an IForgeSourceInventory to the field, an object member by name and '*' for every list element; a null or absent member on the way holds no field. A consumer that compares inventories across a source freeze removes exactly these fields before it digests them.

Forge source freeze contracts

A freeze proof reads facts from the source and sends canaries to it; the producer reports facts only, and the consumer decides. Neither type carries a token, key, credential or response body.

IForgeSourceQuiescenceReport is read with GET requests only and the connection's read-only administrator token: the generator, the source identity with the forge's version verbatim, enabledRunners (every enabled runner in any scope, every page read, sorted by numeric id; each runner's status and busy are evidence only, because a frozen source stops runners from updating them), jobsInProgress (the forge's in_progress count as a decimal string, always with blindSpot: 'cancelling': the forge selects cancelling jobs under no filter, so the count never proves none is cancelling), every cron task with its schedule verbatim, and the queuedRuns (every queued or pending run with its repository, number, event, ref and commit, sorted by numeric id). Past forgeSourceQuiescenceQueuedRunMaxRecords (1000) the queue is overBound with the forge's count and no records, never a truncated list. A part whose read did not finish is null, and incompleteReasons says why. A consumer calls the source quiescent only when the version is the one it qualified, enabledRunners is empty, the job count is '0', every schedule is -, the queue is complete and incompleteReasons is empty.

IForgeSourceFreezeCanaryOutcome is what one HTTP canary (TForgeSourceFreezeHttpCanary: receive-pack-discovery, archive-get, issue-post, release-post, generic-package-put, oci-blob-upload, lfs-put, lfs-off) got from one IForgeSourceFreezeOrigin: the httpStatus of its own request (for oci-blob-upload the upload POST, for lfs-put the object PUT, for lfs-off the batch request; null without a response), the X-Gitea-Freeze header as freezeMarker (null when absent), wrote, the identity of what a 2xx created (null otherwise, and always for receive-pack-discovery and lfs-off, which create nothing), and a sanitized errorCode when the canary did not complete as sent. An origin is a baseUrl with an optional connectAddress: the IP address the connection goes to instead of DNS, while Host, TLS server name and certificate check stay baseUrl's host, so one name reached through the edge and directly at the host are two origins. The SSH canary is an atomic push through GitManager, whose result carries remoteMessages.

Exports

  • data: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, pull requests (native and archived), activity, news, stats, codefeed commit results, GitManager repository/read/push API results, origin references, forge and forge source inventories, forge source freeze facts, the native repository release API, and runner/CI contracts.
  • requests: TypedRequest contracts for codefeed, publicOverview, publicOrg, publicRepo, publicFile, and publicCommits.
  • Barrel exports: all public data and request interfaces are also exported from the package root.

Testing

pnpm test
pnpm run build

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

S
Description
No description provided
Readme MIT
1.6 MiB
0 Stars 3 Watchers 0 Forks
Languages
TypeScript 100%