@foss.global/interfaces 2.0.0 → 2.1.1

package/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026-10-13 - 2.1.1
+
+### Fixes
+
+- Correct the atomic push contract docs: `http` push remotes must be loopback IP literals (`127.0.0.0/8`, `[::1]`), never `localhost`; a ref already at `newObjectId` reports `ok` without a lease check
+
+## 2026-10-13 - 2.1.0
+
+### Features
+
+- add origin and atomic push contracts for the Gitea import (data)
+  - `IOriginRef` and `TOriginState`: where a native entity came from (`native`, `imported` with the source forge instance and entity id, or `unknown`); an identity only, never a URL, path or authority.
+  - `IGitManagerAtomicPushRequest` with leased `IGitManagerAtomicPushRefUpdate`s and the all-or-nothing `IGitManagerAtomicPushResult` (`ok`, `stale` or `rejected` per ref); https or loopback-http remotes only.
+  - `IGitManagerSetDefaultBranchRequest` points a repository's HEAD at an existing branch.
+
 ## 2026-10-13 - 2.0.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/gitmanager.d.ts

@@ -14,6 +14,14 @@ export interface IGitManagerRepositoryInfo extends IGitManagerRepositorySelector
 export interface IGitManagerInitBareRepositoryRequest extends IGitManagerRepositorySelector {
     defaultBranch?: string;
 }
+/**
+ * Points a repository's HEAD at an existing branch, which clones then check
+ * out by default.
+ */
+export interface IGitManagerSetDefaultBranchRequest extends IGitManagerRepositorySelector {
+    /** Branch name without `refs/heads/`, as in `IGitManagerRepositoryInfo.defaultBranch`; the branch must exist. */
+    defaultBranch: string;
+}
 /**
  * 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
@@ -55,6 +63,66 @@ export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySel
 /** Fetches every ref of an imported mirror's remote again, pruning refs the remote no longer has. */
 export interface IGitManagerRefreshMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
 }
+/**
+ * One ref change of an atomic push, guarded by a lease: the remote applies it
+ * only while its ref still points at `expectedOldObjectId`. Both object IDs
+ * are full hexadecimal object IDs; at least one of them is non-null.
+ */
+export interface IGitManagerAtomicPushRefUpdate {
+    /** Full ref name on the remote, for example `refs/heads/main`. */
+    ref: string;
+    /** Object the remote ref must point at now; null creates the ref, which must not exist. */
+    expectedOldObjectId: string | null;
+    /** Object to set the remote ref to, present in the managed repository; null deletes the ref. */
+    newObjectId: string | null;
+}
+/**
+ * Pushes ref updates from a managed repository to a remote as one atomic
+ * transaction: the remote applies every update or none. The remote must
+ * advertise the `atomic` receive-pack capability; without it the push fails
+ * before any ref is sent and never falls back to ref-by-ref updates.
+ *
+ * `remoteUrl` is used for this push only and is never stored in the
+ * repository. It must be `https`, or `http` to a loopback IP address
+ * (`127.0.0.0/8` or `[::1]`); host names such as `localhost` are refused for
+ * `http` because their resolution is not checked. `ssh`, `git`, `file` and
+ * scp-like URLs are refused. Transfer options behave as for `importMirror`,
+ * except that a push credential is also accepted for `http` to a loopback IP
+ * address, which never leaves the machine; the URL must not carry user
+ * information.
+ */
+export interface IGitManagerAtomicPushRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
+    remoteUrl: string;
+    /** Updates of distinct refs; at least one. */
+    updates: IGitManagerAtomicPushRefUpdate[];
+}
+/**
+ * Outcome of one ref as the remote reported it. `stale` means the lease
+ * failed: the remote ref did not point at the expected object. A ref that
+ * already points at `newObjectId` is reported `ok` without its lease being
+ * checked, because git skips it as up to date before the lease check; such a
+ * ref is not changed, so an `ok` result never overwrote an object the caller
+ * did not expect. `rejected`
+ * covers every other refusal, such as a hook or ref protection, and also the
+ * refs the remote refused only because another ref of the same atomic push
+ * failed.
+ */
+export type TGitManagerAtomicPushRefStatus = 'ok' | 'rejected' | 'stale';
+export interface IGitManagerAtomicPushRefResult {
+    ref: string;
+    status: TGitManagerAtomicPushRefStatus;
+    /** Reason text the remote reported for the ref, when it gave one; credentials are redacted. */
+    message?: string;
+}
+/**
+ * Result of an atomic push. `applied` means every ref is `ok`; `rejected`
+ * means no ref changed on the remote, and `refs` says why.
+ */
+export interface IGitManagerAtomicPushResult extends IGitManagerRepositorySelector {
+    status: 'applied' | 'rejected';
+    /** One result per requested update, in request order. */
+    refs: IGitManagerAtomicPushRefResult[];
+}
 /**
  * The object database of one repository when it was measured. Objects of
  * alternate object stores are not counted.

package/dist_ts/data/index.d.ts

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

package/dist_ts/data/index.js

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

package/dist_ts/data/origin.d.ts

@@ -0,0 +1,35 @@
+/** Kinds of source entity an import records its origin for. */
+export type TOriginEntityKind = 'repository';
+/**
+ * Identity of the source entity a native entity was imported from.
+ *
+ * It names the source by stable identifiers only. It carries no URLs, paths,
+ * configuration or run IDs, digests, or authority: it neither locates the
+ * source nor grants access to it.
+ */
+export interface IOriginRef {
+    /** Operator-minted instanceId of the forge connection the entity was imported from. */
+    instanceId: string;
+    entityKind: TOriginEntityKind;
+    /** Source row ID as an opaque string; for a Gitea repository, its decimal repository ID. */
+    entityId: string;
+    /**
+     * Source ID of the parent when entity IDs are parent-scoped; otherwise null.
+     * Null for repositories, because Gitea repository IDs are unique within an
+     * instance. Later entity kinds define their parent.
+     */
+    parentId: string | null;
+}
+/**
+ * Where a native entity came from: created natively, imported from a
+ * recorded source, or not known, for example for an entity that predates
+ * origin tracking. `unknown` must never be read as `native`.
+ */
+export type TOriginState = {
+    kind: 'native';
+} | {
+    kind: 'imported';
+    origin: IOriginRef;
+} | {
+    kind: 'unknown';
+};

package/dist_ts/data/origin.js

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

package/package.json

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

package/readme.md

@@ -171,6 +171,36 @@ remote URL.
 do not depend on packing) and `storageBytes` (every file of the object
 database, which does).
 
+### GitManager atomic push and default branch contracts
+
+`IGitManagerAtomicPushRequest` pushes `IGitManagerAtomicPushRefUpdate`s from a
+managed repository to `remoteUrl` as one transaction: the remote applies every
+update or none, and a remote that does not advertise the `atomic` capability is
+refused rather than pushed to ref by ref. Every update is leased:
+`expectedOldObjectId` is the object the remote ref must point at now (null to
+create a ref that must not exist), and `newObjectId` is the object to set (null
+to delete). The URL is used for that push only; it must be `https`, or `http` to
+a loopback host. The transfer options are those of `importMirror`, except that
+a push credential is also accepted for loopback `http`.
+
+`IGitManagerAtomicPushResult` is `applied` when every ref is `ok` and
+`rejected` when no ref changed. Each `IGitManagerAtomicPushRefResult` is `ok`,
+`stale` (the lease failed) or `rejected` (a hook, ref protection, or another
+ref of the same push failed), with the remote's reason as `message`.
+
+`IGitManagerSetDefaultBranchRequest` points a repository's HEAD at an existing
+branch, named as in `IGitManagerRepositoryInfo.defaultBranch`.
+
+### Origin contracts
+
+`TOriginState` records where a native entity came from: `native`, `imported`
+with an `IOriginRef`, or `unknown`, which never means native. An `IOriginRef`
+names the source by the operator-minted forge connection `instanceId`, the
+`entityKind` (`repository`), the source `entityId` (a Gitea repository's
+decimal ID) and `parentId` (null for repositories, whose Gitea IDs are unique
+per instance). It carries no URLs, paths, configuration or run IDs, digests, or
+authority.
+
 ### Forge inventory contracts
 
 `IForgeInventoryReport`, `IForgeInventoryPage<TItem>`, `IForgeInventoryNamespace`,
@@ -256,7 +286,7 @@ 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, forge and forge source inventories, 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/push API results, origin references, 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: '2.0.0',
+  version: '2.1.1',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 }

package/ts/data/gitmanager.ts

@@ -29,6 +29,15 @@ export interface IGitManagerInitBareRepositoryRequest extends IGitManagerReposit
   defaultBranch?: string;
 }
 
+/**
+ * Points a repository's HEAD at an existing branch, which clones then check
+ * out by default.
+ */
+export interface IGitManagerSetDefaultBranchRequest extends IGitManagerRepositorySelector {
+  /** Branch name without `refs/heads/`, as in `IGitManagerRepositoryInfo.defaultBranch`; the branch must exist. */
+  defaultBranch: string;
+}
+
 /**
  * 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
@@ -74,6 +83,71 @@ export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySel
 /** Fetches every ref of an imported mirror's remote again, pruning refs the remote no longer has. */
 export interface IGitManagerRefreshMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {}
 
+/**
+ * One ref change of an atomic push, guarded by a lease: the remote applies it
+ * only while its ref still points at `expectedOldObjectId`. Both object IDs
+ * are full hexadecimal object IDs; at least one of them is non-null.
+ */
+export interface IGitManagerAtomicPushRefUpdate {
+  /** Full ref name on the remote, for example `refs/heads/main`. */
+  ref: string;
+  /** Object the remote ref must point at now; null creates the ref, which must not exist. */
+  expectedOldObjectId: string | null;
+  /** Object to set the remote ref to, present in the managed repository; null deletes the ref. */
+  newObjectId: string | null;
+}
+
+/**
+ * Pushes ref updates from a managed repository to a remote as one atomic
+ * transaction: the remote applies every update or none. The remote must
+ * advertise the `atomic` receive-pack capability; without it the push fails
+ * before any ref is sent and never falls back to ref-by-ref updates.
+ *
+ * `remoteUrl` is used for this push only and is never stored in the
+ * repository. It must be `https`, or `http` to a loopback IP address
+ * (`127.0.0.0/8` or `[::1]`); host names such as `localhost` are refused for
+ * `http` because their resolution is not checked. `ssh`, `git`, `file` and
+ * scp-like URLs are refused. Transfer options behave as for `importMirror`,
+ * except that a push credential is also accepted for `http` to a loopback IP
+ * address, which never leaves the machine; the URL must not carry user
+ * information.
+ */
+export interface IGitManagerAtomicPushRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
+  remoteUrl: string;
+  /** Updates of distinct refs; at least one. */
+  updates: IGitManagerAtomicPushRefUpdate[];
+}
+
+/**
+ * Outcome of one ref as the remote reported it. `stale` means the lease
+ * failed: the remote ref did not point at the expected object. A ref that
+ * already points at `newObjectId` is reported `ok` without its lease being
+ * checked, because git skips it as up to date before the lease check; such a
+ * ref is not changed, so an `ok` result never overwrote an object the caller
+ * did not expect. `rejected`
+ * covers every other refusal, such as a hook or ref protection, and also the
+ * refs the remote refused only because another ref of the same atomic push
+ * failed.
+ */
+export type TGitManagerAtomicPushRefStatus = 'ok' | 'rejected' | 'stale';
+
+export interface IGitManagerAtomicPushRefResult {
+  ref: string;
+  status: TGitManagerAtomicPushRefStatus;
+  /** Reason text the remote reported for the ref, when it gave one; credentials are redacted. */
+  message?: string;
+}
+
+/**
+ * Result of an atomic push. `applied` means every ref is `ok`; `rejected`
+ * means no ref changed on the remote, and `refs` says why.
+ */
+export interface IGitManagerAtomicPushResult extends IGitManagerRepositorySelector {
+  status: 'applied' | 'rejected';
+  /** One result per requested update, in request order. */
+  refs: IGitManagerAtomicPushRefResult[];
+}
+
 /**
  * The object database of one repository when it was measured. Objects of
  * alternate object stores are not counted.

package/ts/data/index.ts

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

package/ts/data/origin.ts

@@ -0,0 +1,33 @@
+/** Kinds of source entity an import records its origin for. */
+export type TOriginEntityKind = 'repository';
+
+/**
+ * Identity of the source entity a native entity was imported from.
+ *
+ * It names the source by stable identifiers only. It carries no URLs, paths,
+ * configuration or run IDs, digests, or authority: it neither locates the
+ * source nor grants access to it.
+ */
+export interface IOriginRef {
+  /** Operator-minted instanceId of the forge connection the entity was imported from. */
+  instanceId: string;
+  entityKind: TOriginEntityKind;
+  /** Source row ID as an opaque string; for a Gitea repository, its decimal repository ID. */
+  entityId: string;
+  /**
+   * Source ID of the parent when entity IDs are parent-scoped; otherwise null.
+   * Null for repositories, because Gitea repository IDs are unique within an
+   * instance. Later entity kinds define their parent.
+   */
+  parentId: string | null;
+}
+
+/**
+ * Where a native entity came from: created natively, imported from a
+ * recorded source, or not known, for example for an entity that predates
+ * origin tracking. `unknown` must never be read as `native`.
+ */
+export type TOriginState =
+  | { kind: 'native' }
+  | { kind: 'imported'; origin: IOriginRef }
+  | { kind: 'unknown' };