@foss.global/interfaces 1.1.0 → 2.0.0

package/changelog.md

@@ -1,5 +1,22 @@
 # 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

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@foss.global/interfaces',
-    version: '1.1.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

@@ -118,6 +118,10 @@ export interface IForgeSourceOwnerTotals {
     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;
@@ -126,10 +130,22 @@ export interface IForgeSourceGitCounts {
     /** 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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.",
   "exports": {

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`,
@@ -194,7 +212,7 @@ import fidelity, checksummed manifests, or durable recovery checkpoints.
 `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, LFS objects, issues, pull requests,
+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
@@ -209,6 +227,13 @@ 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.

package/ts/00_commitinfo_data.ts

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

package/ts/data/forgesourceinventory.ts

@@ -126,6 +126,10 @@ export interface IForgeSourceOwnerTotals {
   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;
@@ -134,11 +138,23 @@ export interface IForgeSourceGitCounts {
   /** 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 {

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.
  *