@foss.global/interfaces 0.11.1 → 0.12.0

package/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026-09-04 - 0.12.0
+
+### Features
+
+- add forge inventory DTO contracts (forgeinventory)
+  - Introduce typed forge inventory instances, identities, scopes, pages, collections, reports, namespaces, and repositories.
+  - Export the new forge inventory contracts through the data module.
+  - Document inventory semantics and add fixtures for identity precision, visibility, pagination, incomplete scans, and collection coverage.
+
+### Fixes
+
+- update development tooling dependencies (deps)
+  - Bump @git.zone/tsrun to ^2.0.6, @git.zone/tstest to ^4.0.0, and @types/node to ^26.4.1.
+  - Update pnpm package manager version to 11.25.0.
+
 ## 2026-08-31 - 0.11.1
 
 ### Fixes

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/forgeinventory.d.ts

@@ -0,0 +1,173 @@
+/** Provider identity for inventory observations, not a replication authority. */
+export type TForgeKind = 'gitea' | 'gitlab' | 'native';
+export interface IForgeInventoryInstance {
+    /** Operator-assigned identity retained when the instance URL changes. */
+    instanceId: string;
+    kind: TForgeKind;
+    /** Observed server version, or null when it could not be established. */
+    version: string | null;
+}
+/**
+ * Identity namespaces describe the source identifier, for example
+ * gitea.repository.id, gitlab.project.id, or gitlab.group.id. They must not
+ * silently change between adapter versions. IDs are opaque strings; paths,
+ * display names, and issue numbers must not replace provider row IDs.
+ */
+export interface IForgeInventoryObjectRef {
+    instanceId: string;
+    idNamespace: string;
+    objectId: string;
+    /** Stable parent ID when identifiers are parent-scoped; otherwise null. */
+    parentObjectId: string | null;
+}
+/** A missing stable identifier must block automatic correspondence. */
+export type TForgeInventoryIdentity = {
+    status: 'identified';
+    ref: IForgeInventoryObjectRef;
+} | {
+    status: 'unresolved';
+    reason: string;
+};
+/** Mutable location observed separately from identity. URLs never contain credentials. */
+export interface IForgeInventoryLocation {
+    /** Decoded namespace/repository segments, without splitting literal hyphens. */
+    pathSegments: string[];
+    webUrl: string | null;
+}
+export type TForgeInventoryScope = {
+    kind: 'instance';
+} | {
+    kind: 'namespace';
+    identity: TForgeInventoryIdentity;
+    location: IForgeInventoryLocation;
+    includeDescendants: boolean;
+} | {
+    kind: 'repository';
+    identity: TForgeInventoryIdentity;
+    location: IForgeInventoryLocation;
+};
+/** Internal visibility must never be silently normalized to public. */
+export type TForgeInventoryVisibility = 'public' | 'internal' | 'private';
+/** Values are canonical nonnegative decimal integers, retaining JSON precision. */
+export type TForgeInventoryQuantity = {
+    status: 'measured';
+    value: string;
+    accuracy: 'exact' | 'estimate' | 'lowerBound';
+} | {
+    status: 'unknown';
+    reason: string;
+};
+export interface IForgeInventoryNamespace {
+    identity: TForgeInventoryIdentity;
+    location: IForgeInventoryLocation;
+    kind: 'organization' | 'group' | 'user';
+    /** null means no parent; an unknown parent is explicitly unresolved. */
+    parent: TForgeInventoryIdentity | null;
+    visibility: TForgeInventoryVisibility | null;
+}
+export interface IForgeInventoryRepository {
+    identity: TForgeInventoryIdentity;
+    namespace: TForgeInventoryIdentity;
+    location: IForgeInventoryLocation;
+    description: string | null;
+    visibility: TForgeInventoryVisibility | null;
+    archived: boolean | null;
+    /** null means no observed default branch, not proof of an empty repository. */
+    defaultBranch: string | null;
+    httpCloneUrl: string | null;
+    sshCloneUrl: string | null;
+    /** Git storage bytes only; never an admission estimate for an outgoing push. */
+    gitSizeBytes: TForgeInventoryQuantity;
+}
+export type TForgeInventoryEntityClass = 'namespaces' | 'users' | 'teams' | 'memberships' | 'repositories' | 'gitRefs' | 'gitObjects' | 'protectedRefs' | 'publicSshKeys' | 'deployKeys' | 'issues' | 'issueComments' | 'pullRequests' | 'reviews' | 'reviewComments' | 'labels' | 'milestones' | 'assignees' | 'reactions' | 'releases' | 'releaseAssets' | 'lfsObjects' | 'packages' | 'packageVersions' | 'packageBlobs' | 'webhooks' | 'webhookDeliveries' | 'ciWorkflows' | 'ciRuns' | 'ciArtifacts' | 'wikis' | 'projects';
+/** Availability of an inventory read, never a claim of write/import fidelity. */
+export type TForgeInventoryCapability = {
+    status: 'available';
+    limitations: string[];
+} | {
+    status: 'unavailable' | 'unverified';
+    reason: string;
+};
+/** Whether the observation includes entities hidden from an ordinary caller. */
+export type TForgeInventoryAccess = 'publicOnly' | 'callerVisible' | 'entireScope';
+/** Live pagination is not a point-in-time export, even after its last page. */
+export type TForgeInventoryConsistency = {
+    status: 'live';
+} | {
+    status: 'frozen';
+    checkpointId: string;
+};
+export interface IForgeInventoryObservation {
+    /** ISO 8601 UTC start and end of this observation, not provider content times. */
+    startedAt: string;
+    finishedAt: string;
+    access: TForgeInventoryAccess;
+    consistency: TForgeInventoryConsistency;
+}
+/**
+ * Transport cursors are opaque, credential-free, and bound to the exact
+ * instance, scope, query, adapter version, and page-size policy. They are not
+ * durable replication checkpoints and must not be followed as arbitrary URLs.
+ */
+export type TForgeInventoryPagination = {
+    status: 'more';
+    cursor: string;
+} | {
+    status: 'exhausted';
+} | {
+    status: 'incomplete';
+    reason: string;
+};
+export interface IForgeInventoryPage<TItem> {
+    schemaVersion: 1;
+    instance: IForgeInventoryInstance;
+    scope: TForgeInventoryScope;
+    observation: IForgeInventoryObservation;
+    items: TItem[];
+    pagination: TForgeInventoryPagination;
+}
+/**
+ * Enumeration describes the observed scope only. Exhaustion does not prove
+ * global visibility, source quiescence, object integrity, or migration fidelity.
+ * An interrupted/denied/limited scan cannot return an enumerated result.
+ */
+export type TForgeInventoryCollectionResult = {
+    status: 'enumerated';
+    observation: IForgeInventoryObservation;
+    /** Exact distinct entities observed, not a point-in-time total for live scans. */
+    count: string;
+    sizeBytes: TForgeInventoryQuantity;
+} | {
+    status: 'incomplete';
+    observation: IForgeInventoryObservation;
+    /** Distinct observed entities only; provider estimates are not lower bounds. */
+    observedCount: string;
+    reason: string;
+} | {
+    status: 'notInspected' | 'unavailable';
+    reason: string;
+};
+export interface IForgeInventoryCollection {
+    capability: TForgeInventoryCapability;
+    result: TForgeInventoryCollectionResult;
+}
+/** Unknown provider features must remain visible rather than silently disappearing. */
+export interface IForgeInventoryAdditionalCollection extends IForgeInventoryCollection {
+    /** Provider-qualified feature key, distinct from the canonical collection keys. */
+    name: string;
+}
+/**
+ * Operator-facing inventory data shared by adapters and the website. This is
+ * not a public anonymous DTO, a persisted model, or a sealed migration manifest.
+ * Every canonical class is present, including unavailable and uninspected ones.
+ * Reasons and limitations are sanitized diagnostics, never raw response bodies,
+ * credentials, private keys, or secret bindings. Validate these types at runtime
+ * in the owning adapter/API; TypeScript alone does not validate network input.
+ */
+export interface IForgeInventoryReport {
+    schemaVersion: 1;
+    instance: IForgeInventoryInstance;
+    scope: TForgeInventoryScope;
+    collections: Record<TForgeInventoryEntityClass, IForgeInventoryCollection>;
+    additionalCollections: IForgeInventoryAdditionalCollection[];
+}

package/dist_ts/data/forgeinventory.js

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

package/dist_ts/data/index.d.ts

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

package/dist_ts/data/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.",
   "exports": {
@@ -15,9 +15,9 @@
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsdoc": "^2.1.1",
-    "@git.zone/tsrun": "^2.0.5",
-    "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^26.1.1"
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "^4.0.0",
+    "@types/node": "^26.4.1"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -95,6 +95,33 @@ 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.
 
+### Forge inventory contracts
+
+`IForgeInventoryReport`, `IForgeInventoryPage<TItem>`, `IForgeInventoryNamespace`,
+and `IForgeInventoryRepository` 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.
+
+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.
+
 ## 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.

package/ts/00_commitinfo_data.ts

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

package/ts/data/forgeinventory.ts

@@ -0,0 +1,205 @@
+/** Provider identity for inventory observations, not a replication authority. */
+export type TForgeKind = 'gitea' | 'gitlab' | 'native';
+
+export interface IForgeInventoryInstance {
+  /** Operator-assigned identity retained when the instance URL changes. */
+  instanceId: string;
+  kind: TForgeKind;
+  /** Observed server version, or null when it could not be established. */
+  version: string | null;
+}
+
+/**
+ * Identity namespaces describe the source identifier, for example
+ * gitea.repository.id, gitlab.project.id, or gitlab.group.id. They must not
+ * silently change between adapter versions. IDs are opaque strings; paths,
+ * display names, and issue numbers must not replace provider row IDs.
+ */
+export interface IForgeInventoryObjectRef {
+  instanceId: string;
+  idNamespace: string;
+  objectId: string;
+  /** Stable parent ID when identifiers are parent-scoped; otherwise null. */
+  parentObjectId: string | null;
+}
+
+/** A missing stable identifier must block automatic correspondence. */
+export type TForgeInventoryIdentity =
+  | { status: 'identified'; ref: IForgeInventoryObjectRef }
+  | { status: 'unresolved'; reason: string };
+
+/** Mutable location observed separately from identity. URLs never contain credentials. */
+export interface IForgeInventoryLocation {
+  /** Decoded namespace/repository segments, without splitting literal hyphens. */
+  pathSegments: string[];
+  webUrl: string | null;
+}
+
+export type TForgeInventoryScope =
+  | { kind: 'instance' }
+  | {
+      kind: 'namespace';
+      identity: TForgeInventoryIdentity;
+      location: IForgeInventoryLocation;
+      includeDescendants: boolean;
+    }
+  | {
+      kind: 'repository';
+      identity: TForgeInventoryIdentity;
+      location: IForgeInventoryLocation;
+    };
+
+/** Internal visibility must never be silently normalized to public. */
+export type TForgeInventoryVisibility = 'public' | 'internal' | 'private';
+
+/** Values are canonical nonnegative decimal integers, retaining JSON precision. */
+export type TForgeInventoryQuantity =
+  | { status: 'measured'; value: string; accuracy: 'exact' | 'estimate' | 'lowerBound' }
+  | { status: 'unknown'; reason: string };
+
+export interface IForgeInventoryNamespace {
+  identity: TForgeInventoryIdentity;
+  location: IForgeInventoryLocation;
+  kind: 'organization' | 'group' | 'user';
+  /** null means no parent; an unknown parent is explicitly unresolved. */
+  parent: TForgeInventoryIdentity | null;
+  visibility: TForgeInventoryVisibility | null;
+}
+
+export interface IForgeInventoryRepository {
+  identity: TForgeInventoryIdentity;
+  namespace: TForgeInventoryIdentity;
+  location: IForgeInventoryLocation;
+  description: string | null;
+  visibility: TForgeInventoryVisibility | null;
+  archived: boolean | null;
+  /** null means no observed default branch, not proof of an empty repository. */
+  defaultBranch: string | null;
+  httpCloneUrl: string | null;
+  sshCloneUrl: string | null;
+  /** Git storage bytes only; never an admission estimate for an outgoing push. */
+  gitSizeBytes: TForgeInventoryQuantity;
+}
+
+export type TForgeInventoryEntityClass =
+  | 'namespaces'
+  | 'users'
+  | 'teams'
+  | 'memberships'
+  | 'repositories'
+  | 'gitRefs'
+  | 'gitObjects'
+  | 'protectedRefs'
+  | 'publicSshKeys'
+  | 'deployKeys'
+  | 'issues'
+  | 'issueComments'
+  | 'pullRequests'
+  | 'reviews'
+  | 'reviewComments'
+  | 'labels'
+  | 'milestones'
+  | 'assignees'
+  | 'reactions'
+  | 'releases'
+  | 'releaseAssets'
+  | 'lfsObjects'
+  | 'packages'
+  | 'packageVersions'
+  | 'packageBlobs'
+  | 'webhooks'
+  | 'webhookDeliveries'
+  | 'ciWorkflows'
+  | 'ciRuns'
+  | 'ciArtifacts'
+  | 'wikis'
+  | 'projects';
+
+/** Availability of an inventory read, never a claim of write/import fidelity. */
+export type TForgeInventoryCapability =
+  | { status: 'available'; limitations: string[] }
+  | { status: 'unavailable' | 'unverified'; reason: string };
+
+/** Whether the observation includes entities hidden from an ordinary caller. */
+export type TForgeInventoryAccess = 'publicOnly' | 'callerVisible' | 'entireScope';
+
+/** Live pagination is not a point-in-time export, even after its last page. */
+export type TForgeInventoryConsistency =
+  | { status: 'live' }
+  | { status: 'frozen'; checkpointId: string };
+
+export interface IForgeInventoryObservation {
+  /** ISO 8601 UTC start and end of this observation, not provider content times. */
+  startedAt: string;
+  finishedAt: string;
+  access: TForgeInventoryAccess;
+  consistency: TForgeInventoryConsistency;
+}
+
+/**
+ * Transport cursors are opaque, credential-free, and bound to the exact
+ * instance, scope, query, adapter version, and page-size policy. They are not
+ * durable replication checkpoints and must not be followed as arbitrary URLs.
+ */
+export type TForgeInventoryPagination =
+  | { status: 'more'; cursor: string }
+  | { status: 'exhausted' }
+  | { status: 'incomplete'; reason: string };
+
+export interface IForgeInventoryPage<TItem> {
+  schemaVersion: 1;
+  instance: IForgeInventoryInstance;
+  scope: TForgeInventoryScope;
+  observation: IForgeInventoryObservation;
+  items: TItem[];
+  pagination: TForgeInventoryPagination;
+}
+
+/**
+ * Enumeration describes the observed scope only. Exhaustion does not prove
+ * global visibility, source quiescence, object integrity, or migration fidelity.
+ * An interrupted/denied/limited scan cannot return an enumerated result.
+ */
+export type TForgeInventoryCollectionResult =
+  | {
+      status: 'enumerated';
+      observation: IForgeInventoryObservation;
+      /** Exact distinct entities observed, not a point-in-time total for live scans. */
+      count: string;
+      sizeBytes: TForgeInventoryQuantity;
+    }
+  | {
+      status: 'incomplete';
+      observation: IForgeInventoryObservation;
+      /** Distinct observed entities only; provider estimates are not lower bounds. */
+      observedCount: string;
+      reason: string;
+    }
+  | { status: 'notInspected' | 'unavailable'; reason: string };
+
+export interface IForgeInventoryCollection {
+  capability: TForgeInventoryCapability;
+  result: TForgeInventoryCollectionResult;
+}
+
+/** Unknown provider features must remain visible rather than silently disappearing. */
+export interface IForgeInventoryAdditionalCollection extends IForgeInventoryCollection {
+  /** Provider-qualified feature key, distinct from the canonical collection keys. */
+  name: string;
+}
+
+/**
+ * Operator-facing inventory data shared by adapters and the website. This is
+ * not a public anonymous DTO, a persisted model, or a sealed migration manifest.
+ * Every canonical class is present, including unavailable and uninspected ones.
+ * Reasons and limitations are sanitized diagnostics, never raw response bodies,
+ * credentials, private keys, or secret bindings. Validate these types at runtime
+ * in the owning adapter/API; TypeScript alone does not validate network input.
+ */
+export interface IForgeInventoryReport {
+  schemaVersion: 1;
+  instance: IForgeInventoryInstance;
+  scope: TForgeInventoryScope;
+  collections: Record<TForgeInventoryEntityClass, IForgeInventoryCollection>;
+  additionalCollections: IForgeInventoryAdditionalCollection[];
+}

package/ts/data/index.ts

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