@foss.global/interfaces 0.13.0 → 1.0.0

package/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026-09-25 - 1.0.0
+
+### Breaking Changes
+
+- replace the GitManager ref listing contract with a complete paginated ref inventory (gitmanager)
+  - `IGitManagerRefRequest` gains `prefixes`, `cursor`, and `limit`; without prefixes every ref under `refs/` is selected, overlapping prefixes select their de-duplicated union, an empty array is invalid, and a complete ref name as the only prefix is an exact lookup.
+  - `IGitManagerRef` now carries `name`, `objectId`, `objectType`, `peeledObjectId`, `peeledObjectType`, and `symbolicTarget`; `objectId` and `objectType` are null only for a symbolic ref whose target does not resolve. The per-ref `org`, `repo`, `shortName`, `refType`, `updatedAt`, and `subject` fields and `TGitManagerRefType` are removed.
+  - Add `TGitManagerRefInventoryResult`: an `IGitManagerRefInventoryPage` with HEAD, total count, inventory digest, and cursor pagination, or `IGitManagerRefInventoryStale` when the selected refs or HEAD changed between pages.
+
+### Maintenance
+
+- Update release tooling to pnpm 12.4.2, `@git.zone/tsbuild` 5.0.0, `@git.zone/tsrun` 3.0.0, `@git.zone/tstest` 6.2.0, `@git.zone/tsdoc` 2.2.2 and `@types/node` 26.6.1 (tooling)
+  - pnpm 12.5.x and `@types/node` 26.6.2 are inside the seven-day release-age window, so pnpm stays on 12.4.2 and `@types/node` on 26.6.1.
+  - No source migration is needed: no `ts*` folder carries its own `tsconfig.json` (tsbuild 5), no script reads `process.argv` (tsrun 3), and both test files end in `tap.start()` without `TapNodeTools` (tstest 5 and 6).
+
 ## 2026-09-05 - 0.13.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/gitmanager.d.ts

@@ -1,4 +1,3 @@
-export type TGitManagerRefType = 'branch' | 'tag' | 'other';
 export type TGitManagerObjectType = 'blob' | 'tree' | 'commit' | 'tag' | 'other';
 export type TGitManagerTreeEntryType = 'file' | 'dir' | 'symlink' | 'submodule' | 'other';
 export type TGitManagerDiffFileStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'copied' | 'typechange' | 'unmerged' | 'unknown';
@@ -18,17 +17,92 @@ export interface IGitManagerInitBareRepositoryRequest extends IGitManagerReposit
 export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector {
     remoteUrl: string;
 }
-export interface IGitManagerRef extends IGitManagerRepositorySelector {
-    name: string;
-    shortName: string;
-    objectId: string;
-    objectType: TGitManagerObjectType;
-    refType: TGitManagerRefType;
-    updatedAt: string;
-    subject: string;
-}
+/**
+ * One page request of a repository's complete ref inventory.
+ *
+ * Without `prefixes`, every ref under `refs/` is listed: branches, tags, and
+ * all other namespaces such as `refs/notes/*`, `refs/pull/*`,
+ * `refs/keep-around/*`, and provider-internal refs. A prefix selects refs on
+ * full path components: `refs/heads/` selects every branch, and a complete
+ * ref name such as `refs/heads/main` selects exactly that ref.
+ */
 export interface IGitManagerRefRequest extends IGitManagerRepositorySelector {
+    /**
+     * `refs/`-rooted prefixes; omit to list every ref. An empty array is
+     * rejected as invalid. Overlapping prefixes select the de-duplicated union,
+     * so each ref appears once.
+     */
+    prefixes?: string[];
+    /** Opaque cursor from the preceding page; omit to start a new inventory. */
+    cursor?: string;
+    /** Maximum refs in this page. The engine owns the default and maximum. */
+    limit?: number;
 }
+export interface IGitManagerRef {
+    /** Full ref name, for example `refs/heads/main`. */
+    name: string;
+    /**
+     * Object the ref points at; for a symbolic ref, the object its target
+     * resolves to. Null only for a symbolic ref whose target does not resolve,
+     * such as `refs/remotes/origin/HEAD` pointing at a deleted branch; such refs
+     * are listed, never dropped.
+     */
+    objectId: string | null;
+    /** Type of `objectId`; null exactly when `objectId` is null. */
+    objectType: TGitManagerObjectType | null;
+    /** Fully peeled object for annotated tags, including nested tags; otherwise null. */
+    peeledObjectId: string | null;
+    peeledObjectType: TGitManagerObjectType | null;
+    /** Target ref name when this ref is symbolic; otherwise null. */
+    symbolicTarget: string | null;
+}
+/** Repository HEAD, which is reported separately and never listed in `refs`. */
+export interface IGitManagerRefHead {
+    /** Target ref name when HEAD is symbolic; null when detached. */
+    symbolicTarget: string | null;
+    /** Resolved object; null when HEAD points at an unborn branch. */
+    objectId: string | null;
+}
+export type TGitManagerRefInventoryPagination = {
+    status: 'more';
+    cursor: string;
+} | {
+    status: 'exhausted';
+};
+/**
+ * A coherent page of the selected ref inventory, sorted by ref name in byte
+ * order. Every page carries the digest of the complete selection it was cut
+ * from; a cursor is honoured only while that digest is unchanged, so pages of
+ * one inventory never mix two ref states.
+ *
+ * `inventoryDigest` is the lowercase hex SHA-256 over the UTF-8 bytes of
+ * `HEAD\0<head.symbolicTarget or empty>\0<head.objectId or empty>\n` followed
+ * by `<name>\0<objectId or empty>\0<symbolicTarget or empty>\n` for each
+ * selected ref in ref-name byte order over the complete selection. Peeled
+ * values and object types follow from the object IDs and are not part of the
+ * digest.
+ */
+export interface IGitManagerRefInventoryPage extends IGitManagerRepositorySelector {
+    status: 'page';
+    inventoryDigest: string;
+    /** Number of refs in the complete selection, not in this page. */
+    refCount: number;
+    head: IGitManagerRefHead;
+    refs: IGitManagerRef[];
+    pagination: TGitManagerRefInventoryPagination;
+}
+/**
+ * The selected refs or HEAD changed since the cursor was issued. The caller
+ * restarts the inventory without a cursor; no partial page is returned.
+ */
+export interface IGitManagerRefInventoryStale extends IGitManagerRepositorySelector {
+    status: 'stale';
+    /** Digest bound to the rejected cursor. */
+    expectedInventoryDigest: string;
+    /** Digest of the current selection. */
+    inventoryDigest: string;
+}
+export type TGitManagerRefInventoryResult = IGitManagerRefInventoryPage | IGitManagerRefInventoryStale;
 export type TGitManagerMergeMethod = 'merge' | 'squash' | 'rebase';
 export type TGitManagerMergeStatus = 'merged' | 'already_merged' | 'conflicting' | 'stale';
 export interface IGitManagerMergeRequest extends IGitManagerRepositorySelector {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "0.13.0",
+  "version": "1.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": "^4.4.2",
-    "@git.zone/tsdoc": "^2.1.1",
-    "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^4.0.0",
-    "@types/node": "^26.4.1"
+    "@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"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -95,6 +95,64 @@ The runner lifecycle contracts cover registration, sessions, runner and job hear
 
 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`.
+
+```ts
+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.
+
 ### Forge inventory contracts
 
 `IForgeInventoryReport`, `IForgeInventoryPage<TItem>`, `IForgeInventoryNamespace`,

package/ts/00_commitinfo_data.ts

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

package/ts/data/gitmanager.ts

@@ -1,5 +1,3 @@
-export type TGitManagerRefType = 'branch' | 'tag' | 'other';
-
 export type TGitManagerObjectType = 'blob' | 'tree' | 'commit' | 'tag' | 'other';
 
 export type TGitManagerTreeEntryType = 'file' | 'dir' | 'symlink' | 'submodule' | 'other';
@@ -35,17 +33,95 @@ export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySel
   remoteUrl: string;
 }
 
-export interface IGitManagerRef extends IGitManagerRepositorySelector {
+/**
+ * One page request of a repository's complete ref inventory.
+ *
+ * Without `prefixes`, every ref under `refs/` is listed: branches, tags, and
+ * all other namespaces such as `refs/notes/*`, `refs/pull/*`,
+ * `refs/keep-around/*`, and provider-internal refs. A prefix selects refs on
+ * full path components: `refs/heads/` selects every branch, and a complete
+ * ref name such as `refs/heads/main` selects exactly that ref.
+ */
+export interface IGitManagerRefRequest extends IGitManagerRepositorySelector {
+  /**
+   * `refs/`-rooted prefixes; omit to list every ref. An empty array is
+   * rejected as invalid. Overlapping prefixes select the de-duplicated union,
+   * so each ref appears once.
+   */
+  prefixes?: string[];
+  /** Opaque cursor from the preceding page; omit to start a new inventory. */
+  cursor?: string;
+  /** Maximum refs in this page. The engine owns the default and maximum. */
+  limit?: number;
+}
+
+export interface IGitManagerRef {
+  /** Full ref name, for example `refs/heads/main`. */
   name: string;
-  shortName: string;
-  objectId: string;
-  objectType: TGitManagerObjectType;
-  refType: TGitManagerRefType;
-  updatedAt: string;
-  subject: string;
+  /**
+   * Object the ref points at; for a symbolic ref, the object its target
+   * resolves to. Null only for a symbolic ref whose target does not resolve,
+   * such as `refs/remotes/origin/HEAD` pointing at a deleted branch; such refs
+   * are listed, never dropped.
+   */
+  objectId: string | null;
+  /** Type of `objectId`; null exactly when `objectId` is null. */
+  objectType: TGitManagerObjectType | null;
+  /** Fully peeled object for annotated tags, including nested tags; otherwise null. */
+  peeledObjectId: string | null;
+  peeledObjectType: TGitManagerObjectType | null;
+  /** Target ref name when this ref is symbolic; otherwise null. */
+  symbolicTarget: string | null;
+}
+
+/** Repository HEAD, which is reported separately and never listed in `refs`. */
+export interface IGitManagerRefHead {
+  /** Target ref name when HEAD is symbolic; null when detached. */
+  symbolicTarget: string | null;
+  /** Resolved object; null when HEAD points at an unborn branch. */
+  objectId: string | null;
+}
+
+export type TGitManagerRefInventoryPagination =
+  | { status: 'more'; cursor: string }
+  | { status: 'exhausted' };
+
+/**
+ * A coherent page of the selected ref inventory, sorted by ref name in byte
+ * order. Every page carries the digest of the complete selection it was cut
+ * from; a cursor is honoured only while that digest is unchanged, so pages of
+ * one inventory never mix two ref states.
+ *
+ * `inventoryDigest` is the lowercase hex SHA-256 over the UTF-8 bytes of
+ * `HEAD\0<head.symbolicTarget or empty>\0<head.objectId or empty>\n` followed
+ * by `<name>\0<objectId or empty>\0<symbolicTarget or empty>\n` for each
+ * selected ref in ref-name byte order over the complete selection. Peeled
+ * values and object types follow from the object IDs and are not part of the
+ * digest.
+ */
+export interface IGitManagerRefInventoryPage extends IGitManagerRepositorySelector {
+  status: 'page';
+  inventoryDigest: string;
+  /** Number of refs in the complete selection, not in this page. */
+  refCount: number;
+  head: IGitManagerRefHead;
+  refs: IGitManagerRef[];
+  pagination: TGitManagerRefInventoryPagination;
+}
+
+/**
+ * The selected refs or HEAD changed since the cursor was issued. The caller
+ * restarts the inventory without a cursor; no partial page is returned.
+ */
+export interface IGitManagerRefInventoryStale extends IGitManagerRepositorySelector {
+  status: 'stale';
+  /** Digest bound to the rejected cursor. */
+  expectedInventoryDigest: string;
+  /** Digest of the current selection. */
+  inventoryDigest: string;
 }
 
-export interface IGitManagerRefRequest extends IGitManagerRepositorySelector {}
+export type TGitManagerRefInventoryResult = IGitManagerRefInventoryPage | IGitManagerRefInventoryStale;
 
 export type TGitManagerMergeMethod = 'merge' | 'squash' | 'rebase';