@foss.global/interfaces 1.0.0 → 2.0.0

package/changelog.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 2026-10-13 - 2.0.0
+
+### Features
+
+- add GitManager remote transfer options and the repository size contract (gitmanager)
+  - `IGitManagerRemoteTransferOptions` on `IGitManagerImportMirrorRequest` and the new `IGitManagerRefreshMirrorRequest`: an HTTP Basic `credential` carried outside the URL, command line and Git config, `caCertificates` for a private CA, and a `timeoutMs` up to six hours.
+  - `IGitManagerRepositorySize`: object count, uncompressed object bytes and object database storage bytes.
+
+### Breaking Changes
+
+- measure Git objects and LFS presence in the forge source inventory (data)
+  - `IForgeSourceGitCounts` gains the required measures `objects` and `objectBytes`, and `IForgeSourceLfsCounts` gains `missingObjects`; producers must fill them. LFS `objects` and `bytes` now count only the referenced objects the forge holds.
+
+### Maintenance
+
+- update release tooling: pnpm 12.10.1 (deps)
+
+## 2026-10-13 - 1.1.0
+
+### Features
+
+- add forge source inventory contracts (data)
+  - `IForgeSourceInventoryReport`: an authenticated, read-only, deterministic measurement of a source forge before its migration, with `complete`, `partial` and `notMeasured` measures as decimal strings, organization and user owner inventories with owner totals, and per-repository Git, LFS, collaboration, release (drafts, asset counts and bytes), access and Actions counts.
+  - Run units (`TForgeSourceInventoryUnit`, `TForgeSourceInventoryUnitResult`, `IForgeSourceInventoryDiscovery`) for resumable measurement, and `TForgeSourceCollisionCheck` for the native name collision check.
+  - A report never carries secret values; secrets and variables are counted, never named.
+
+### Maintenance
+
+- release tooling: `@git.zone/tsbuild` ^6.0.2 (TypeScript 7; the tsconfig needs no change), `@git.zone/tstest` ^7.2.1, `@git.zone/tsrun` ^3.0.3, `@git.zone/tsdoc` ^3.0.2 (its CLI moved to smartconsole; `buildDocs` is unchanged), `@types/node` ^26.6.4 and pnpm 12.10.0 (26.6.5 and pnpm 12.11.x are younger than seven days)
+
 ## 2026-09-25 - 1.0.0
 
 ### Breaking Changes

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@foss.global/interfaces',
-    version: '1.0.0',
+    version: '2.0.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHFHQUFxRztDQUNuSCxDQUFBIn0=

package/dist_ts/data/forgesourceinventory.d.ts

@@ -0,0 +1,352 @@
+import type { TForgeInventoryVisibility } from './forgeinventory.js';
+/**
+ * Authenticated, read-only measurement of a source forge before its one-time
+ * migration. Unlike the caller-visible inventory in `forgeinventory.ts`, it is
+ * read with a site administrator's token and counts per owner and repository.
+ *
+ * A report never contains secret values: no credentials, tokens, private keys,
+ * Actions secret or variable values, webhook secrets, or mirror remote URLs.
+ * Secrets and variables are counted, never named in the report. Reasons are
+ * sanitized diagnostics, never raw response bodies or URLs.
+ */
+/** Source forges the inventory can read. */
+export type TForgeSourceKind = 'gitea';
+/**
+ * Values are canonical nonnegative decimal integers, retaining JSON precision.
+ * `partial` was attempted and did not finish (a resumed run retries it);
+ * `notMeasured` was not attempted, for example because no read exists yet.
+ */
+export type TForgeSourceMeasure = {
+    status: 'complete';
+    value: string;
+} | {
+    status: 'partial';
+    observedValue: string;
+    reason: string;
+} | {
+    status: 'notMeasured';
+    reason: string;
+};
+export interface IForgeSourceIdentity {
+    /** Operator-assigned identity retained when the instance URL changes. */
+    instanceId: string;
+    kind: TForgeSourceKind;
+    /** Origin and path prefix only; never carries credentials. */
+    baseUrl: string;
+    version: string;
+}
+/** The account whose token read the source; an inventory requires a site administrator. */
+export interface IForgeSourceReader {
+    login: string;
+    siteAdmin: boolean;
+}
+export interface IForgeSourceUserCounts {
+    total: TForgeSourceMeasure;
+    active: TForgeSourceMeasure;
+    admins: TForgeSourceMeasure;
+    restricted: TForgeSourceMeasure;
+    prohibitLogin: TForgeSourceMeasure;
+    /** Users authenticated through an external source such as LDAP or OAuth2. */
+    externalAuth: TForgeSourceMeasure;
+    twoFactor: TForgeSourceMeasure;
+}
+export interface IForgeSourceInstanceInventory {
+    users: IForgeSourceUserCounts;
+    organizations: TForgeSourceMeasure;
+    /** System and default webhooks. */
+    systemWebhooks: TForgeSourceMeasure;
+    /** Instance-scoped Actions runners; their registrations are reissued. */
+    runners: TForgeSourceMeasure;
+    /** Repositories on disk that the forge database does not know. */
+    unadoptedRepositories: TForgeSourceMeasure;
+}
+export interface IForgeSourcePackageTypeCounts {
+    /** Provider package type, such as `npm`, `generic` or `container`. */
+    type: string;
+    packages: TForgeSourceMeasure;
+    versions: TForgeSourceMeasure;
+    files: TForgeSourceMeasure;
+    bytes: TForgeSourceMeasure;
+}
+export interface IForgeSourceUserAccount {
+    admin: boolean;
+    active: boolean;
+    restricted: boolean;
+    prohibitLogin: boolean;
+    externalAuth: boolean;
+}
+export interface IForgeSourceOwnerInventoryBase {
+    name: string;
+    /** Provider row id as a decimal string. */
+    id: string;
+    visibility: TForgeInventoryVisibility;
+    repositories: TForgeSourceMeasure;
+    webhooks: TForgeSourceMeasure;
+    actionsVariables: TForgeSourceMeasure;
+    runners: TForgeSourceMeasure;
+    /** Sorted by type. */
+    packages: IForgeSourcePackageTypeCounts[];
+}
+export interface IForgeSourceOrganizationInventory extends IForgeSourceOwnerInventoryBase {
+    kind: 'organization';
+    members: TForgeSourceMeasure;
+    teams: TForgeSourceMeasure;
+    teamMemberships: TForgeSourceMeasure;
+    teamRepositoryGrants: TForgeSourceMeasure;
+    labels: TForgeSourceMeasure;
+    actionsSecrets: TForgeSourceMeasure;
+}
+/** User-scoped Actions secrets have no list read; see `IForgeSourceInventory.limitations`. */
+export interface IForgeSourceUserInventory extends IForgeSourceOwnerInventoryBase {
+    kind: 'user';
+    account: IForgeSourceUserAccount;
+    sshKeys: TForgeSourceMeasure;
+    gpgKeys: TForgeSourceMeasure;
+}
+export type TForgeSourceOwnerInventory = IForgeSourceOrganizationInventory | IForgeSourceUserInventory;
+/** Owner-level settings summed over every owner; repository settings are summed separately. */
+export interface IForgeSourceOwnerTotals {
+    webhooks: TForgeSourceMeasure;
+    actionsSecrets: TForgeSourceMeasure;
+    actionsVariables: TForgeSourceMeasure;
+    runners: TForgeSourceMeasure;
+    members: TForgeSourceMeasure;
+    teams: TForgeSourceMeasure;
+    teamMemberships: TForgeSourceMeasure;
+    teamRepositoryGrants: TForgeSourceMeasure;
+    labels: TForgeSourceMeasure;
+    sshKeys: TForgeSourceMeasure;
+    gpgKeys: TForgeSourceMeasure;
+}
+/**
+ * Ref and object counts read at the Git level, from a mirror clone of every
+ * ref the forge advertises, except `reportedSizeKiB`.
+ */
+export interface IForgeSourceGitCounts {
+    /** As reported by the forge, in KiB; not a transfer size. */
+    reportedSizeKiB: TForgeSourceMeasure;
+    branches: TForgeSourceMeasure;
+    tags: TForgeSourceMeasure;
+    /** Hidden refs that preserve pull request heads. */
+    pullRequestRefs: TForgeSourceMeasure;
+    otherRefs: TForgeSourceMeasure;
+    /** Distinct Git objects reachable from those refs. */
+    objects: TForgeSourceMeasure;
+    /** Sum of the uncompressed sizes of those objects; independent of how the forge packs them. */
+    objectBytes: TForgeSourceMeasure;
+}
+/**
+ * LFS objects that pointers in any reachable revision reference, by distinct
+ * object ID, checked for presence through the forge's LFS batch API.
+ */
+export interface IForgeSourceLfsCounts {
+    /** Referenced objects the forge holds. */
+    objects: TForgeSourceMeasure;
+    /** Sizes of the objects the forge holds. */
+    bytes: TForgeSourceMeasure;
+    /** Referenced objects the forge does not hold; they cannot be migrated. */
+    missingObjects: TForgeSourceMeasure;
+}
+export interface IForgeSourceCollaborationCounts {
+    issues: TForgeSourceMeasure;
+    pullRequests: TForgeSourceMeasure;
+    /** Conversation comments on issues and pull requests. */
+    comments: TForgeSourceMeasure;
+    reviews: TForgeSourceMeasure;
+    reviewComments: TForgeSourceMeasure;
+    labels: TForgeSourceMeasure;
+    milestones: TForgeSourceMeasure;
+    /** Reactions on issues, pull requests and their comments. */
+    reactions: TForgeSourceMeasure;
+    /** Files attached to issues, pull requests and their comments. */
+    attachments: TForgeSourceMeasure;
+    attachmentBytes: TForgeSourceMeasure;
+}
+export interface IForgeSourceReleaseCounts {
+    /** Includes drafts and prereleases. */
+    releases: TForgeSourceMeasure;
+    drafts: TForgeSourceMeasure;
+    assets: TForgeSourceMeasure;
+    assetBytes: TForgeSourceMeasure;
+}
+export interface IForgeSourceAccessCounts {
+    collaborators: TForgeSourceMeasure;
+    teams: TForgeSourceMeasure;
+    deployKeys: TForgeSourceMeasure;
+    webhooks: TForgeSourceMeasure;
+    branchProtections: TForgeSourceMeasure;
+    tagProtections: TForgeSourceMeasure;
+    /** Push mirror configurations; their remote credentials are reissued. */
+    pushMirrors: TForgeSourceMeasure;
+}
+export interface IForgeSourceActionsCounts {
+    /** Workflow files on the default branch. */
+    workflows: TForgeSourceMeasure;
+    secrets: TForgeSourceMeasure;
+    variables: TForgeSourceMeasure;
+    runners: TForgeSourceMeasure;
+    /** Run history and artifacts are archived, not migrated; counted to size the archive. */
+    runs: TForgeSourceMeasure;
+    artifacts: TForgeSourceMeasure;
+    artifactBytes: TForgeSourceMeasure;
+}
+/** Repository units the forge enables. */
+export interface IForgeSourceRepositoryFeatures {
+    issues: boolean;
+    pullRequests: boolean;
+    wiki: boolean;
+    releases: boolean;
+    packages: boolean;
+    actions: boolean;
+    projects: boolean;
+}
+export interface IForgeSourceRepositoryInventory {
+    owner: string;
+    name: string;
+    id: string;
+    visibility: TForgeInventoryVisibility;
+    fork: boolean;
+    /** `owner/name` of the fork parent, or null. */
+    parent: string | null;
+    mirror: boolean;
+    template: boolean;
+    archived: boolean;
+    empty: boolean;
+    /** Git object format such as `sha1` or `sha256`. */
+    objectFormat: string;
+    defaultBranch: string;
+    features: IForgeSourceRepositoryFeatures;
+    git: IForgeSourceGitCounts;
+    lfs: IForgeSourceLfsCounts;
+    collaboration: IForgeSourceCollaborationCounts;
+    releases: IForgeSourceReleaseCounts;
+    wikiPages: TForgeSourceMeasure;
+    access: IForgeSourceAccessCounts;
+    actions: IForgeSourceActionsCounts;
+}
+export interface IForgeSourceRepositoryTotals {
+    total: TForgeSourceMeasure;
+    private: TForgeSourceMeasure;
+    internal: TForgeSourceMeasure;
+    forks: TForgeSourceMeasure;
+    mirrors: TForgeSourceMeasure;
+    templates: TForgeSourceMeasure;
+    archived: TForgeSourceMeasure;
+    empty: TForgeSourceMeasure;
+    withWiki: TForgeSourceMeasure;
+}
+/**
+ * Sums over every owner and repository; a sum is complete only when every
+ * addend is. Repository-shaped groups sum repositories only.
+ */
+export interface IForgeSourceInventoryTotals {
+    organizations: TForgeSourceMeasure;
+    users: TForgeSourceMeasure;
+    repositories: IForgeSourceRepositoryTotals;
+    git: IForgeSourceGitCounts;
+    lfs: IForgeSourceLfsCounts;
+    collaboration: IForgeSourceCollaborationCounts;
+    releases: IForgeSourceReleaseCounts;
+    wikiPages: TForgeSourceMeasure;
+    access: IForgeSourceAccessCounts;
+    actions: IForgeSourceActionsCounts;
+    owners: IForgeSourceOwnerTotals;
+    /** Sorted by type. */
+    packages: IForgeSourcePackageTypeCounts[];
+}
+export interface IForgeSourceInventoryGenerator {
+    package: string;
+    version: string;
+}
+/**
+ * The deterministic measurement of one source: the same source state yields
+ * the same document. It carries no timestamps; run times belong to the run.
+ * Owners sort by kind then name, repositories by owner then name, and reason
+ * lists by code-unit order.
+ */
+export interface IForgeSourceInventory {
+    generators: IForgeSourceInventoryGenerator[];
+    source: IForgeSourceIdentity;
+    reader: IForgeSourceReader;
+    /** True only when discovery finished and no measure is partial or not measured. */
+    inventoryComplete: boolean;
+    incompleteReasons: string[];
+    /**
+     * Source data that the migration reissues rather than copies and that the
+     * provider exposes to no administrator read, such as user-scoped Actions
+     * secrets on Gitea. Nothing that is migrated may be listed here instead of
+     * being measured.
+     */
+    limitations: string[];
+    instance: IForgeSourceInstanceInventory;
+    owners: TForgeSourceOwnerInventory[];
+    repositories: IForgeSourceRepositoryInventory[];
+    totals: IForgeSourceInventoryTotals;
+}
+/** A source name that already exists natively and would block an import under that name. */
+export interface IForgeSourceCollision {
+    subject: 'owner' | 'repository';
+    /** `owner` or `owner/name` at the source. */
+    source: string;
+    /** The existing native name. */
+    native: string;
+    nativeKind: 'namespace' | 'repository' | 'user';
+    match: 'exact' | 'caseInsensitive';
+}
+export type TForgeSourceCollisionCheck = {
+    status: 'checked';
+    collisions: IForgeSourceCollision[];
+} | {
+    status: 'notChecked';
+    reason: string;
+};
+/**
+ * A report is a complete basis for migration planning only when
+ * `inventoryComplete` is true and the collision check ran. Collisions sort by
+ * subject, then source, then native name.
+ */
+export interface IForgeSourceInventoryReport extends IForgeSourceInventory {
+    collisionCheck: TForgeSourceCollisionCheck;
+}
+/** The complete list of what a run measures, read before any unit. */
+export interface IForgeSourceInventoryDiscovery {
+    source: IForgeSourceIdentity;
+    reader: IForgeSourceReader;
+    owners: Array<{
+        kind: 'organization' | 'user';
+        name: string;
+    }>;
+    repositories: Array<{
+        owner: string;
+        name: string;
+    }>;
+    /** Non-empty when discovery could not finish; such a run can never be complete. */
+    incompleteReasons: string[];
+}
+/** One independently measured and resumable part of a run. */
+export type TForgeSourceInventoryUnit = {
+    kind: 'instance';
+} | {
+    kind: 'owner';
+    ownerKind: 'organization' | 'user';
+    name: string;
+} | {
+    kind: 'repository';
+    owner: string;
+    name: string;
+};
+/** A failed unit, or one holding a partial measure, is measured again when a run resumes. */
+export type TForgeSourceInventoryUnitResult = {
+    kind: 'instance';
+    instance: IForgeSourceInstanceInventory;
+} | {
+    kind: 'owner';
+    owner: TForgeSourceOwnerInventory;
+} | {
+    kind: 'repository';
+    repository: IForgeSourceRepositoryInventory;
+} | {
+    kind: 'failed';
+    unit: TForgeSourceInventoryUnit;
+    reason: string;
+};

package/dist_ts/data/forgesourceinventory.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZm9yZ2Vzb3VyY2VpbnZlbnRvcnkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2Zvcmdlc291cmNlaW52ZW50b3J5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/dist_ts/data/gitmanager.d.ts

@@ -14,9 +14,65 @@ export interface IGitManagerRepositoryInfo extends IGitManagerRepositorySelector
 export interface IGitManagerInitBareRepositoryRequest extends IGitManagerRepositorySelector {
     defaultBranch?: string;
 }
-export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector {
+/**
+ * HTTP Basic credentials for a remote Git transfer, such as a forge user name
+ * with an access token as the password. Neither part may contain control
+ * characters, and the user name may not contain `:`.
+ */
+export interface IGitManagerRemoteBasicCredential {
+    kind: 'basic';
+    username: string;
+    password: string;
+}
+export type TGitManagerRemoteCredential = IGitManagerRemoteBasicCredential;
+/**
+ * Options for one transfer from a remote repository.
+ *
+ * A credential reaches Git only through the Git process environment, as an
+ * `Authorization` header. It never appears in the remote URL, on a command
+ * line, in the repository's Git config, or in an error. A credential requires
+ * an `https` remote URL without user information, and Git does not follow
+ * HTTP redirects while it carries one.
+ */
+export interface IGitManagerRemoteTransferOptions {
+    credential?: TGitManagerRemoteCredential;
+    /**
+     * PEM certificates that Git uses as its CA bundle for this transfer, in
+     * place of the default bundle file, for a remote behind a private CA.
+     */
+    caCertificates?: string[];
+    /** Wall-clock limit for the transfer in milliseconds; defaults to 120000, at most 21600000 (six hours). */
+    timeoutMs?: number;
+}
+/**
+ * Clones every ref of a remote into a new mirror repository. The stored
+ * `remote.origin.url` is `remoteUrl`, so it must never carry credentials;
+ * pass them as `credential`.
+ */
+export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
     remoteUrl: string;
 }
+/** Fetches every ref of an imported mirror's remote again, pruning refs the remote no longer has. */
+export interface IGitManagerRefreshMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
+}
+/**
+ * The object database of one repository when it was measured. Objects of
+ * alternate object stores are not counted.
+ */
+export interface IGitManagerRepositorySize extends IGitManagerRepositorySelector {
+    /** Distinct commits, trees, blobs and annotated tags, reachable or not. */
+    objectCount: number;
+    /**
+     * Sum of the uncompressed sizes of those objects. It does not depend on
+     * how the objects are packed, so equal object sets give equal values.
+     */
+    objectBytes: number;
+    /**
+     * Bytes of every file in the object database: loose objects, packs, their
+     * indexes and other pack metadata. It depends on packing.
+     */
+    storageBytes: number;
+}
 /**
  * One page request of a repository's complete ref inventory.
  *

package/dist_ts/data/index.d.ts

@@ -1,5 +1,6 @@
 export * from './codefeed.js';
 export * from './forgeinventory.js';
+export * from './forgesourceinventory.js';
 export * from './gitmanager.js';
 export * from './public.js';
 export * from './runner.js';

package/dist_ts/data/index.js

@@ -1,6 +1,7 @@
 export * from './codefeed.js';
 export * from './forgeinventory.js';
+export * from './forgesourceinventory.js';
 export * from './gitmanager.js';
 export * from './public.js';
 export * from './runner.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDIn0=

package/dist_ts/data/runner.d.ts

@@ -1,4 +1,4 @@
-export declare const runnerProtocolVersion: "1";
+export declare const runnerProtocolVersion: '1';
 export type TRunnerProtocolVersion = typeof runnerProtocolVersion;
 export type TOciRuntime = 'docker' | 'podman';
 export type TJobNetwork = 'none' | 'bridge';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.",
   "exports": {
@@ -13,11 +13,11 @@
     "@api.global/typedrequest-interfaces": "^7.1.0"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.0.0",
-    "@git.zone/tsdoc": "^2.2.2",
-    "@git.zone/tsrun": "^3.0.0",
-    "@git.zone/tstest": "^6.2.0",
-    "@types/node": "^26.6.1"
+    "@git.zone/tsbuild": "^6.0.2",
+    "@git.zone/tsdoc": "^3.0.2",
+    "@git.zone/tsrun": "^3.0.3",
+    "@git.zone/tstest": "^7.2.1",
+    "@types/node": "^26.6.4"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -153,6 +153,24 @@ 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.
+
+`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).
+
 ### Forge inventory contracts
 
 `IForgeInventoryReport`, `IForgeInventoryPage<TItem>`, `IForgeInventoryNamespace`,
@@ -189,9 +207,56 @@ 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 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.
+
+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.
+
+A run first reads `IForgeSourceInventoryDiscovery`, then measures independent
+`TForgeSourceInventoryUnit`s (the instance, each owner and each repository). A
+failed unit, or one holding a partial measure, is measured again on resume.
+`IForgeSourceInventory` is deterministic: it carries no timestamps, owners sort
+by kind and name, repositories by owner 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, private keys,
+Actions secret or variable values, webhook secrets, or mirror remote URLs.
+
 ## Exports
 
-- `data`: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, activity, news, stats, codefeed commit results, GitManager repository/read API results, and runner/CI contracts.
+- `data`: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, activity, news, stats, codefeed commit results, GitManager repository/read API results, forge and forge source inventories, 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.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@foss.global/interfaces',
-  version: '1.0.0',
+  version: '2.0.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 }

package/ts/data/forgesourceinventory.ts

@@ -0,0 +1,351 @@
+import type { TForgeInventoryVisibility } from './forgeinventory.js';
+
+/**
+ * Authenticated, read-only measurement of a source forge before its one-time
+ * migration. Unlike the caller-visible inventory in `forgeinventory.ts`, it is
+ * read with a site administrator's token and counts per owner and repository.
+ *
+ * A report never contains secret values: no credentials, tokens, private keys,
+ * Actions secret or variable values, webhook secrets, or mirror remote URLs.
+ * Secrets and variables are counted, never named in the report. Reasons are
+ * sanitized diagnostics, never raw response bodies or URLs.
+ */
+
+/** Source forges the inventory can read. */
+export type TForgeSourceKind = 'gitea';
+
+/**
+ * Values are canonical nonnegative decimal integers, retaining JSON precision.
+ * `partial` was attempted and did not finish (a resumed run retries it);
+ * `notMeasured` was not attempted, for example because no read exists yet.
+ */
+export type TForgeSourceMeasure =
+  | { status: 'complete'; value: string }
+  | { status: 'partial'; observedValue: string; reason: string }
+  | { status: 'notMeasured'; reason: string };
+
+export interface IForgeSourceIdentity {
+  /** Operator-assigned identity retained when the instance URL changes. */
+  instanceId: string;
+  kind: TForgeSourceKind;
+  /** Origin and path prefix only; never carries credentials. */
+  baseUrl: string;
+  version: string;
+}
+
+/** The account whose token read the source; an inventory requires a site administrator. */
+export interface IForgeSourceReader {
+  login: string;
+  siteAdmin: boolean;
+}
+
+export interface IForgeSourceUserCounts {
+  total: TForgeSourceMeasure;
+  active: TForgeSourceMeasure;
+  admins: TForgeSourceMeasure;
+  restricted: TForgeSourceMeasure;
+  prohibitLogin: TForgeSourceMeasure;
+  /** Users authenticated through an external source such as LDAP or OAuth2. */
+  externalAuth: TForgeSourceMeasure;
+  twoFactor: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceInstanceInventory {
+  users: IForgeSourceUserCounts;
+  organizations: TForgeSourceMeasure;
+  /** System and default webhooks. */
+  systemWebhooks: TForgeSourceMeasure;
+  /** Instance-scoped Actions runners; their registrations are reissued. */
+  runners: TForgeSourceMeasure;
+  /** Repositories on disk that the forge database does not know. */
+  unadoptedRepositories: TForgeSourceMeasure;
+}
+
+export interface IForgeSourcePackageTypeCounts {
+  /** Provider package type, such as `npm`, `generic` or `container`. */
+  type: string;
+  packages: TForgeSourceMeasure;
+  versions: TForgeSourceMeasure;
+  files: TForgeSourceMeasure;
+  bytes: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceUserAccount {
+  admin: boolean;
+  active: boolean;
+  restricted: boolean;
+  prohibitLogin: boolean;
+  externalAuth: boolean;
+}
+
+export interface IForgeSourceOwnerInventoryBase {
+  name: string;
+  /** Provider row id as a decimal string. */
+  id: string;
+  visibility: TForgeInventoryVisibility;
+  repositories: TForgeSourceMeasure;
+  webhooks: TForgeSourceMeasure;
+  actionsVariables: TForgeSourceMeasure;
+  runners: TForgeSourceMeasure;
+  /** Sorted by type. */
+  packages: IForgeSourcePackageTypeCounts[];
+}
+
+export interface IForgeSourceOrganizationInventory extends IForgeSourceOwnerInventoryBase {
+  kind: 'organization';
+  members: TForgeSourceMeasure;
+  teams: TForgeSourceMeasure;
+  teamMemberships: TForgeSourceMeasure;
+  teamRepositoryGrants: TForgeSourceMeasure;
+  labels: TForgeSourceMeasure;
+  actionsSecrets: TForgeSourceMeasure;
+}
+
+/** User-scoped Actions secrets have no list read; see `IForgeSourceInventory.limitations`. */
+export interface IForgeSourceUserInventory extends IForgeSourceOwnerInventoryBase {
+  kind: 'user';
+  account: IForgeSourceUserAccount;
+  sshKeys: TForgeSourceMeasure;
+  gpgKeys: TForgeSourceMeasure;
+}
+
+export type TForgeSourceOwnerInventory = IForgeSourceOrganizationInventory | IForgeSourceUserInventory;
+
+/** Owner-level settings summed over every owner; repository settings are summed separately. */
+export interface IForgeSourceOwnerTotals {
+  webhooks: TForgeSourceMeasure;
+  actionsSecrets: TForgeSourceMeasure;
+  actionsVariables: TForgeSourceMeasure;
+  runners: TForgeSourceMeasure;
+  members: TForgeSourceMeasure;
+  teams: TForgeSourceMeasure;
+  teamMemberships: TForgeSourceMeasure;
+  teamRepositoryGrants: TForgeSourceMeasure;
+  labels: TForgeSourceMeasure;
+  sshKeys: TForgeSourceMeasure;
+  gpgKeys: TForgeSourceMeasure;
+}
+
+/**
+ * Ref and object counts read at the Git level, from a mirror clone of every
+ * ref the forge advertises, except `reportedSizeKiB`.
+ */
+export interface IForgeSourceGitCounts {
+  /** As reported by the forge, in KiB; not a transfer size. */
+  reportedSizeKiB: TForgeSourceMeasure;
+  branches: TForgeSourceMeasure;
+  tags: TForgeSourceMeasure;
+  /** Hidden refs that preserve pull request heads. */
+  pullRequestRefs: TForgeSourceMeasure;
+  otherRefs: TForgeSourceMeasure;
+  /** Distinct Git objects reachable from those refs. */
+  objects: TForgeSourceMeasure;
+  /** Sum of the uncompressed sizes of those objects; independent of how the forge packs them. */
+  objectBytes: TForgeSourceMeasure;
+}
+
+/**
+ * LFS objects that pointers in any reachable revision reference, by distinct
+ * object ID, checked for presence through the forge's LFS batch API.
+ */
+export interface IForgeSourceLfsCounts {
+  /** Referenced objects the forge holds. */
+  objects: TForgeSourceMeasure;
+  /** Sizes of the objects the forge holds. */
+  bytes: TForgeSourceMeasure;
+  /** Referenced objects the forge does not hold; they cannot be migrated. */
+  missingObjects: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceCollaborationCounts {
+  issues: TForgeSourceMeasure;
+  pullRequests: TForgeSourceMeasure;
+  /** Conversation comments on issues and pull requests. */
+  comments: TForgeSourceMeasure;
+  reviews: TForgeSourceMeasure;
+  reviewComments: TForgeSourceMeasure;
+  labels: TForgeSourceMeasure;
+  milestones: TForgeSourceMeasure;
+  /** Reactions on issues, pull requests and their comments. */
+  reactions: TForgeSourceMeasure;
+  /** Files attached to issues, pull requests and their comments. */
+  attachments: TForgeSourceMeasure;
+  attachmentBytes: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceReleaseCounts {
+  /** Includes drafts and prereleases. */
+  releases: TForgeSourceMeasure;
+  drafts: TForgeSourceMeasure;
+  assets: TForgeSourceMeasure;
+  assetBytes: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceAccessCounts {
+  collaborators: TForgeSourceMeasure;
+  teams: TForgeSourceMeasure;
+  deployKeys: TForgeSourceMeasure;
+  webhooks: TForgeSourceMeasure;
+  branchProtections: TForgeSourceMeasure;
+  tagProtections: TForgeSourceMeasure;
+  /** Push mirror configurations; their remote credentials are reissued. */
+  pushMirrors: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceActionsCounts {
+  /** Workflow files on the default branch. */
+  workflows: TForgeSourceMeasure;
+  secrets: TForgeSourceMeasure;
+  variables: TForgeSourceMeasure;
+  runners: TForgeSourceMeasure;
+  /** Run history and artifacts are archived, not migrated; counted to size the archive. */
+  runs: TForgeSourceMeasure;
+  artifacts: TForgeSourceMeasure;
+  artifactBytes: TForgeSourceMeasure;
+}
+
+/** Repository units the forge enables. */
+export interface IForgeSourceRepositoryFeatures {
+  issues: boolean;
+  pullRequests: boolean;
+  wiki: boolean;
+  releases: boolean;
+  packages: boolean;
+  actions: boolean;
+  projects: boolean;
+}
+
+export interface IForgeSourceRepositoryInventory {
+  owner: string;
+  name: string;
+  id: string;
+  visibility: TForgeInventoryVisibility;
+  fork: boolean;
+  /** `owner/name` of the fork parent, or null. */
+  parent: string | null;
+  mirror: boolean;
+  template: boolean;
+  archived: boolean;
+  empty: boolean;
+  /** Git object format such as `sha1` or `sha256`. */
+  objectFormat: string;
+  defaultBranch: string;
+  features: IForgeSourceRepositoryFeatures;
+  git: IForgeSourceGitCounts;
+  lfs: IForgeSourceLfsCounts;
+  collaboration: IForgeSourceCollaborationCounts;
+  releases: IForgeSourceReleaseCounts;
+  wikiPages: TForgeSourceMeasure;
+  access: IForgeSourceAccessCounts;
+  actions: IForgeSourceActionsCounts;
+}
+
+export interface IForgeSourceRepositoryTotals {
+  total: TForgeSourceMeasure;
+  private: TForgeSourceMeasure;
+  internal: TForgeSourceMeasure;
+  forks: TForgeSourceMeasure;
+  mirrors: TForgeSourceMeasure;
+  templates: TForgeSourceMeasure;
+  archived: TForgeSourceMeasure;
+  empty: TForgeSourceMeasure;
+  withWiki: TForgeSourceMeasure;
+}
+
+/**
+ * Sums over every owner and repository; a sum is complete only when every
+ * addend is. Repository-shaped groups sum repositories only.
+ */
+export interface IForgeSourceInventoryTotals {
+  organizations: TForgeSourceMeasure;
+  users: TForgeSourceMeasure;
+  repositories: IForgeSourceRepositoryTotals;
+  git: IForgeSourceGitCounts;
+  lfs: IForgeSourceLfsCounts;
+  collaboration: IForgeSourceCollaborationCounts;
+  releases: IForgeSourceReleaseCounts;
+  wikiPages: TForgeSourceMeasure;
+  access: IForgeSourceAccessCounts;
+  actions: IForgeSourceActionsCounts;
+  owners: IForgeSourceOwnerTotals;
+  /** Sorted by type. */
+  packages: IForgeSourcePackageTypeCounts[];
+}
+
+export interface IForgeSourceInventoryGenerator {
+  package: string;
+  version: string;
+}
+
+/**
+ * The deterministic measurement of one source: the same source state yields
+ * the same document. It carries no timestamps; run times belong to the run.
+ * Owners sort by kind then name, repositories by owner then name, and reason
+ * lists by code-unit order.
+ */
+export interface IForgeSourceInventory {
+  generators: IForgeSourceInventoryGenerator[];
+  source: IForgeSourceIdentity;
+  reader: IForgeSourceReader;
+  /** True only when discovery finished and no measure is partial or not measured. */
+  inventoryComplete: boolean;
+  incompleteReasons: string[];
+  /**
+   * Source data that the migration reissues rather than copies and that the
+   * provider exposes to no administrator read, such as user-scoped Actions
+   * secrets on Gitea. Nothing that is migrated may be listed here instead of
+   * being measured.
+   */
+  limitations: string[];
+  instance: IForgeSourceInstanceInventory;
+  owners: TForgeSourceOwnerInventory[];
+  repositories: IForgeSourceRepositoryInventory[];
+  totals: IForgeSourceInventoryTotals;
+}
+
+/** A source name that already exists natively and would block an import under that name. */
+export interface IForgeSourceCollision {
+  subject: 'owner' | 'repository';
+  /** `owner` or `owner/name` at the source. */
+  source: string;
+  /** The existing native name. */
+  native: string;
+  nativeKind: 'namespace' | 'repository' | 'user';
+  match: 'exact' | 'caseInsensitive';
+}
+
+export type TForgeSourceCollisionCheck =
+  | { status: 'checked'; collisions: IForgeSourceCollision[] }
+  | { status: 'notChecked'; reason: string };
+
+/**
+ * A report is a complete basis for migration planning only when
+ * `inventoryComplete` is true and the collision check ran. Collisions sort by
+ * subject, then source, then native name.
+ */
+export interface IForgeSourceInventoryReport extends IForgeSourceInventory {
+  collisionCheck: TForgeSourceCollisionCheck;
+}
+
+/** The complete list of what a run measures, read before any unit. */
+export interface IForgeSourceInventoryDiscovery {
+  source: IForgeSourceIdentity;
+  reader: IForgeSourceReader;
+  owners: Array<{ kind: 'organization' | 'user'; name: string }>;
+  repositories: Array<{ owner: string; name: string }>;
+  /** Non-empty when discovery could not finish; such a run can never be complete. */
+  incompleteReasons: string[];
+}
+
+/** One independently measured and resumable part of a run. */
+export type TForgeSourceInventoryUnit =
+  | { kind: 'instance' }
+  | { kind: 'owner'; ownerKind: 'organization' | 'user'; name: string }
+  | { kind: 'repository'; owner: string; name: string };
+
+/** A failed unit, or one holding a partial measure, is measured again when a run resumes. */
+export type TForgeSourceInventoryUnitResult =
+  | { kind: 'instance'; instance: IForgeSourceInstanceInventory }
+  | { kind: 'owner'; owner: TForgeSourceOwnerInventory }
+  | { kind: 'repository'; repository: IForgeSourceRepositoryInventory }
+  | { kind: 'failed'; unit: TForgeSourceInventoryUnit; reason: string };

package/ts/data/gitmanager.ts

@@ -29,10 +29,70 @@ export interface IGitManagerInitBareRepositoryRequest extends IGitManagerReposit
   defaultBranch?: string;
 }
 
-export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector {
+/**
+ * HTTP Basic credentials for a remote Git transfer, such as a forge user name
+ * with an access token as the password. Neither part may contain control
+ * characters, and the user name may not contain `:`.
+ */
+export interface IGitManagerRemoteBasicCredential {
+  kind: 'basic';
+  username: string;
+  password: string;
+}
+
+export type TGitManagerRemoteCredential = IGitManagerRemoteBasicCredential;
+
+/**
+ * Options for one transfer from a remote repository.
+ *
+ * A credential reaches Git only through the Git process environment, as an
+ * `Authorization` header. It never appears in the remote URL, on a command
+ * line, in the repository's Git config, or in an error. A credential requires
+ * an `https` remote URL without user information, and Git does not follow
+ * HTTP redirects while it carries one.
+ */
+export interface IGitManagerRemoteTransferOptions {
+  credential?: TGitManagerRemoteCredential;
+  /**
+   * PEM certificates that Git uses as its CA bundle for this transfer, in
+   * place of the default bundle file, for a remote behind a private CA.
+   */
+  caCertificates?: string[];
+  /** Wall-clock limit for the transfer in milliseconds; defaults to 120000, at most 21600000 (six hours). */
+  timeoutMs?: number;
+}
+
+/**
+ * Clones every ref of a remote into a new mirror repository. The stored
+ * `remote.origin.url` is `remoteUrl`, so it must never carry credentials;
+ * pass them as `credential`.
+ */
+export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
   remoteUrl: string;
 }
 
+/** Fetches every ref of an imported mirror's remote again, pruning refs the remote no longer has. */
+export interface IGitManagerRefreshMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {}
+
+/**
+ * The object database of one repository when it was measured. Objects of
+ * alternate object stores are not counted.
+ */
+export interface IGitManagerRepositorySize extends IGitManagerRepositorySelector {
+  /** Distinct commits, trees, blobs and annotated tags, reachable or not. */
+  objectCount: number;
+  /**
+   * Sum of the uncompressed sizes of those objects. It does not depend on
+   * how the objects are packed, so equal object sets give equal values.
+   */
+  objectBytes: number;
+  /**
+   * Bytes of every file in the object database: loose objects, packs, their
+   * indexes and other pack metadata. It depends on packing.
+   */
+  storageBytes: number;
+}
+
 /**
  * One page request of a repository's complete ref inventory.
  *

package/ts/data/index.ts

@@ -1,5 +1,6 @@
 export * from './codefeed.js';
 export * from './forgeinventory.js';
+export * from './forgesourceinventory.js';
 export * from './gitmanager.js';
 export * from './public.js';
 export * from './runner.js';