@foss.global/forgefixtures 0.2.0

package/ts/classes.reaper.ts

@@ -0,0 +1,126 @@
+import * as plugins from './plugins.js';
+import { forgeFixtureLabels } from './constants.js';
+import {
+  classifyForgeFixtureOwner,
+  parseForgeFixtureOwnerLabels,
+  readCurrentProcessIdentity,
+} from './ownership.js';
+import type { IForgeFixtureOwner, IForgeFixtureReapReport, TForgeFixtureReapReason } from './interfaces.js';
+
+export interface IForgeFixtureReaperOptions {
+  /** Docker Engine socket; omit for `@apiclient.xyz/docker` resolution. */
+  dockerSocketPath?: string;
+}
+
+export interface IForgeFixtureInventory {
+  containers: plugins.docker.DockerContainer[];
+  networks: plugins.docker.DockerNetwork[];
+  volumes: plugins.docker.DockerVolume[];
+}
+
+export const createForgeFixtureDockerHost = (socketPathArg?: string): plugins.docker.DockerHost =>
+  new plugins.docker.DockerHost({
+    ...(socketPathArg === undefined ? {} : { socketPath: socketPathArg }),
+    enableImageStore: false,
+  });
+
+const managedFilter = (): Record<string, string[]> => ({ label: [`${forgeFixtureLabels.managed}=true`] });
+
+/** Lists every Docker resource carrying this package's managed label on one daemon. */
+export const listForgeFixtureResources = async (
+  dockerHostArg: plugins.docker.DockerHost,
+): Promise<IForgeFixtureInventory> => {
+  const [containers, networks, volumes] = await Promise.all([
+    dockerHostArg.listContainers({ all: true, filters: managedFilter() }),
+    dockerHostArg.listNetworks({ filters: managedFilter() }),
+    dockerHostArg.listVolumes({ filters: managedFilter() }),
+  ]);
+  return { containers, networks, volumes };
+};
+
+/**
+ * Removes the Docker resources of lifecycles whose owner process exited,
+ * whose host rebooted, or whose declared lifetime expired. Resources of live
+ * owners and resources with uninterpretable labels are left untouched.
+ */
+export class ForgeFixtureReaper {
+  readonly #options: IForgeFixtureReaperOptions;
+
+  constructor(optionsArg: IForgeFixtureReaperOptions = {}) {
+    this.#options = { ...optionsArg };
+  }
+
+  public async reap(nowArg: Date = new Date()): Promise<IForgeFixtureReapReport> {
+    const dockerHost = createForgeFixtureDockerHost(this.#options.dockerSocketPath);
+    try {
+      return await reapStaleForgeFixtures(dockerHost, nowArg);
+    } finally {
+      await dockerHost.stop();
+    }
+  }
+}
+
+export const reapStaleForgeFixtures = async (
+  dockerHostArg: plugins.docker.DockerHost,
+  nowArg: Date = new Date(),
+): Promise<IForgeFixtureReapReport> => {
+  const current = await readCurrentProcessIdentity();
+  const inventory = await listForgeFixtureResources(dockerHostArg);
+  const report: IForgeFixtureReapReport = {
+    removedContainers: [], removedNetworks: [], removedVolumes: [], reapedLifecycles: [], unrecognizedResources: [],
+  };
+  const verdicts = new Map<string, TForgeFixtureReapReason | 'alive'>();
+  const verdictFor = async (ownerArg: IForgeFixtureOwner): Promise<TForgeFixtureReapReason | 'alive'> => {
+    let verdict = verdicts.get(ownerArg.lifecycleId);
+    if (verdict === undefined) {
+      verdict = await classifyForgeFixtureOwner(ownerArg, current, nowArg);
+      verdicts.set(ownerArg.lifecycleId, verdict);
+      if (verdict !== 'alive') report.reapedLifecycles.push({ lifecycleId: ownerArg.lifecycleId, reason: verdict });
+    }
+    return verdict;
+  };
+  const stale = async (
+    typeArg: 'container' | 'network' | 'volume',
+    idArg: string,
+    labelsArg: Record<string, string> | undefined,
+  ): Promise<boolean> => {
+    const owner = parseForgeFixtureOwnerLabels(labelsArg);
+    if (!owner) {
+      report.unrecognizedResources.push({ type: typeArg, id: idArg });
+      return false;
+    }
+    return (await verdictFor(owner)) !== 'alive';
+  };
+
+  const failures: unknown[] = [];
+  // Dependency order: containers release their network endpoints and volumes first.
+  for (const container of inventory.containers) {
+    if (!await stale('container', container.Id, container.Labels)) continue;
+    try {
+      await container.remove({ force: true, removeAnonymousVolumes: true });
+      report.removedContainers.push(container.Id);
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  for (const network of inventory.networks) {
+    if (!await stale('network', network.Id, network.Labels)) continue;
+    try {
+      await network.remove();
+      report.removedNetworks.push(network.Id);
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  for (const volume of inventory.volumes) {
+    if (!await stale('volume', volume.Name, volume.Labels)) continue;
+    try {
+      await volume.remove({ force: true });
+      report.removedVolumes.push(volume.Name);
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (failures.length > 0) throw new AggregateError(failures, 'Forge fixture reaping left stale resources behind.');
+  return report;
+};

package/ts/classes.tlsterminator.ts

@@ -0,0 +1,136 @@
+import * as plugins from './plugins.js';
+import type { IForgeFixtureServerCertificate } from './classes.certificateauthority.js';
+
+/** RFC 9110 hop-by-hop fields; they describe one connection and are never forwarded. */
+const hopByHopHeaders = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'proxy-connection',
+  'te', 'trailer', 'transfer-encoding', 'upgrade',
+]);
+
+const forwardableHeaders = (headersArg: plugins.http.IncomingHttpHeaders): plugins.http.OutgoingHttpHeaders => {
+  const connectionTokens = new Set(
+    String(headersArg.connection ?? '').split(',').map((tokenArg) => tokenArg.trim().toLowerCase()).filter(Boolean),
+  );
+  const headers: plugins.http.OutgoingHttpHeaders = {};
+  for (const [name, value] of Object.entries(headersArg)) {
+    if (value === undefined || hopByHopHeaders.has(name) || connectionTokens.has(name)) continue;
+    headers[name] = value;
+  }
+  return headers;
+};
+
+/**
+ * Loopback TLS-terminating reverse proxy in front of one loopback HTTP
+ * upstream, configured the way a production proxy is: the client's Host header
+ * is preserved and `X-Forwarded-Proto: https` tells the forge the public scheme.
+ * It listens before the forge starts, so the forge can be configured with its
+ * exact external HTTPS origin.
+ */
+export class ForgeFixtureTlsTerminator {
+  readonly #server: plugins.https.Server;
+  readonly #agent = new plugins.http.Agent({ keepAlive: true, maxSockets: 32 });
+  #upstreamPort: number | undefined;
+  #port: number | undefined;
+  #closed = false;
+  #lastServerError: Error | undefined;
+
+  constructor(certificateArg: IForgeFixtureServerCertificate) {
+    this.#server = plugins.https.createServer({
+      cert: certificateArg.certificatePem,
+      key: certificateArg.privateKeyPem,
+      minVersion: 'TLSv1.2',
+    }, (requestArg, responseArg) => this.#forward(requestArg, responseArg));
+    // Handshake failures concern only that client; the listener stays up.
+    this.#server.on('tlsClientError', (_errorArg, socketArg) => socketArg.destroy());
+    // A server error must never become an unhandled 'error' event that crashes
+    // the test process; it is recorded for diagnostics instead.
+    this.#server.on('error', (errorArg) => {
+      this.#lastServerError = errorArg;
+    });
+  }
+
+  /** Last error the listening server emitted, if any. */
+  public get lastServerError(): Error | undefined {
+    return this.#lastServerError;
+  }
+
+  /** Bound loopback port, available after `listen()`. */
+  public get port(): number {
+    if (this.#port === undefined) throw new Error('The TLS terminator is not listening.');
+    return this.#port;
+  }
+
+  public async listen(): Promise<number> {
+    if (this.#closed) throw new Error('The TLS terminator is closed.');
+    if (this.#port !== undefined) return this.#port;
+    await new Promise<void>((resolveArg, rejectArg) => {
+      const onError = (errorArg: Error) => rejectArg(errorArg);
+      this.#server.once('error', onError);
+      this.#server.listen({ host: '127.0.0.1', port: 0, exclusive: true }, () => {
+        this.#server.off('error', onError);
+        resolveArg();
+      });
+    });
+    const address = this.#server.address();
+    if (address === null || typeof address === 'string') throw new Error('The TLS terminator has no TCP address.');
+    this.#port = address.port;
+    return address.port;
+  }
+
+  /** Requests received before an upstream is set are answered with 503. */
+  public setUpstreamPort(portArg: number): void {
+    if (!Number.isSafeInteger(portArg) || portArg < 1 || portArg > 65535) {
+      throw new TypeError('The upstream port must be an integer from 1 through 65535.');
+    }
+    this.#upstreamPort = portArg;
+  }
+
+  /** Stops listening and destroys every open client and upstream connection. Idempotent. */
+  public async close(): Promise<void> {
+    this.#closed = true;
+    this.#agent.destroy();
+    if (!this.#server.listening) return;
+    const closed = new Promise<void>((resolveArg, rejectArg) => {
+      this.#server.close((errorArg) => (errorArg ? rejectArg(errorArg) : resolveArg()));
+    });
+    this.#server.closeAllConnections();
+    await closed;
+  }
+
+  #forward(requestArg: plugins.http.IncomingMessage, responseArg: plugins.http.ServerResponse): void {
+    const upstreamPort = this.#upstreamPort;
+    if (this.#closed || upstreamPort === undefined) {
+      responseArg.writeHead(503, { 'content-type': 'text/plain', connection: 'close' });
+      responseArg.end('The forge fixture is not ready.\n');
+      return;
+    }
+    const headers = forwardableHeaders(requestArg.headers);
+    headers['x-forwarded-proto'] = 'https';
+    headers['x-forwarded-for'] = requestArg.socket.remoteAddress ?? '127.0.0.1';
+    const upstreamRequest = plugins.http.request({
+      host: '127.0.0.1',
+      port: upstreamPort,
+      method: requestArg.method,
+      path: requestArg.url,
+      headers,
+      agent: this.#agent,
+    }, (upstreamResponse) => {
+      responseArg.writeHead(upstreamResponse.statusCode ?? 502, forwardableHeaders(upstreamResponse.headers));
+      upstreamResponse.pipe(responseArg);
+      upstreamResponse.once('error', () => responseArg.destroy());
+    });
+    upstreamRequest.once('error', () => {
+      if (responseArg.headersSent) {
+        responseArg.destroy();
+        return;
+      }
+      responseArg.writeHead(502, { 'content-type': 'text/plain', connection: 'close' });
+      responseArg.end('The forge fixture upstream is unavailable.\n');
+    });
+    requestArg.once('error', () => upstreamRequest.destroy());
+    responseArg.once('close', () => {
+      if (!responseArg.writableFinished) upstreamRequest.destroy();
+    });
+    requestArg.pipe(upstreamRequest);
+  }
+}

package/ts/constants.ts

@@ -0,0 +1,35 @@
+import type { IForgeFixtureImage } from './interfaces.js';
+
+/** Gitea release that code.foss.global serves (`/api/v1/version`). Rootless variant, uid 1000. */
+export const giteaFixtureImage: IForgeFixtureImage = Object.freeze({
+  version: '1.27.3',
+  tag: 'gitea/gitea:1.27.3-rootless',
+  repoDigest: 'gitea/gitea@sha256:1c17ecaead42eb3b5391553d8708103a4beb0e86edf5b9ebc1eb269c318845f2',
+});
+
+/** Self-managed GitLab Community Edition. The omnibus image runs as root, so it runs on a rootless daemon. */
+export const gitlabFixtureImage: IForgeFixtureImage = Object.freeze({
+  version: '19.4.1',
+  tag: 'gitlab/gitlab-ce:19.4.1-ce.0',
+  repoDigest: 'gitlab/gitlab-ce@sha256:9b33b45b9f42d176bada85ee5ecb81ddab7e506c435f44cd582206e284b2809c',
+});
+
+/** Prefix of every Docker label this package writes. */
+export const forgeFixtureLabelPrefix = 'global.foss.forgefixtures';
+
+export const forgeFixtureLabels = Object.freeze({
+  managed: `${forgeFixtureLabelPrefix}.managed`,
+  lifecycleId: `${forgeFixtureLabelPrefix}.lifecycle`,
+  kind: `${forgeFixtureLabelPrefix}.kind`,
+  machineId: `${forgeFixtureLabelPrefix}.owner.machineid`,
+  hostname: `${forgeFixtureLabelPrefix}.owner.hostname`,
+  bootId: `${forgeFixtureLabelPrefix}.owner.bootid`,
+  pidNamespace: `${forgeFixtureLabelPrefix}.owner.pidns`,
+  pid: `${forgeFixtureLabelPrefix}.owner.pid`,
+  processStartTicks: `${forgeFixtureLabelPrefix}.owner.starttime`,
+  createdAt: `${forgeFixtureLabelPrefix}.createdat`,
+  expiresAt: `${forgeFixtureLabelPrefix}.expiresat`,
+});
+
+export const defaultMaxLifetimeMs = 2 * 60 * 60 * 1000;
+export const defaultPullTimeoutMs = 15 * 60 * 1000;

package/ts/giteaseed.default.ts

@@ -0,0 +1,88 @@
+import type { IGiteaSeedSpec } from './interfaces.giteaseed.js';
+
+/**
+ * A compact seed covering the Gitea behaviours inventory readers must handle:
+ * public, limited and private owners, private repositories, a public
+ * repository of a private organization (which Gitea reports as `internal`),
+ * issue and pull request numbers from one sequence, closed items, labels,
+ * milestones, assignees, comments, tags, releases, an LFS object and a
+ * deleted author whose content Gitea reattributes to its ghost user.
+ */
+export const createDefaultGiteaSeedSpec = (): IGiteaSeedSpec => ({
+  users: [
+    { username: 'alice', fullName: 'Alice Example' },
+    { username: 'bob', fullName: 'Bob Example' },
+    { username: 'carol', visibility: 'private' },
+    { username: 'dora' },
+  ],
+  organizations: [
+    { name: 'team-with-hyphens', visibility: 'public' },
+    { name: 'limited-org', visibility: 'limited' },
+    { name: 'private-org', visibility: 'private' },
+  ],
+  repositories: [
+    {
+      owner: 'team-with-hyphens',
+      name: 'public-repo',
+      private: false,
+      description: 'Public organization repository',
+      collaborators: [{ username: 'bob', permission: 'write' }],
+      files: [{ path: 'src/index.ts', content: 'export const seeded = true;\n' }],
+      branches: [{ name: 'feature-a', files: [{ path: 'src/feature.ts', content: 'export const feature = 1;\n' }] }],
+      labels: [
+        { name: 'bug', color: '#d73a4a' },
+        { name: 'enhancement', color: '#a2eeef' },
+      ],
+      milestones: [
+        { title: 'v1', state: 'open' },
+        { title: 'v0', state: 'closed' },
+      ],
+      tags: [{ name: 'v1.0.0', target: 'main', message: 'First release' }],
+      issuesAndPullRequests: [
+        {
+          kind: 'issue', key: 'open-labelled', title: 'Open labelled issue', body: 'Body with #2 reference', author: 'alice',
+          state: 'open', labels: ['bug'], milestone: 'v1', assignees: ['bob'],
+          comments: [{ author: 'bob', body: 'Confirmed.' }],
+        },
+        { kind: 'pullRequest', key: 'feature-pr', title: 'Add feature', author: 'bob', head: 'feature-a', base: 'main', state: 'open', labels: ['enhancement'] },
+        {
+          kind: 'issue', key: 'closed-by-deleted-user', title: 'Closed issue from a deleted user', author: 'dora', state: 'closed',
+          milestone: 'v0', comments: [{ author: 'dora', body: 'Comment from a user who will be deleted.' }],
+        },
+      ],
+      releases: [{ tagName: 'v1.0.0', target: 'main', name: 'v1.0.0', body: 'Release notes' }],
+      lfsObjects: [{ path: 'assets/blob.bin', content: 'forgefixtures LFS payload\n' }],
+    },
+    {
+      owner: 'limited-org',
+      name: 'limited-repo',
+      private: false,
+      issuesAndPullRequests: [{ kind: 'issue', key: 'limited-issue', title: 'Issue in a limited organization', author: 'alice', state: 'open' }],
+    },
+    {
+      owner: 'private-org',
+      name: 'internal-repo',
+      private: false,
+      collaborators: [{ username: 'alice', permission: 'read' }],
+      issuesAndPullRequests: [{ kind: 'issue', key: 'internal-issue', title: 'Issue in a private organization', author: 'alice', state: 'open' }],
+    },
+    {
+      owner: 'private-org',
+      name: 'secret-repo',
+      private: true,
+      collaborators: [{ username: 'alice', permission: 'read' }],
+      issuesAndPullRequests: [{ kind: 'issue', key: 'private-issue', title: 'Issue in a private repository', author: 'alice', state: 'open' }],
+    },
+    {
+      owner: 'alice',
+      name: 'personal-repo',
+      private: false,
+      branches: [{ name: 'topic', files: [{ path: 'notes.md', content: '# Notes\n' }] }],
+      issuesAndPullRequests: [
+        { kind: 'pullRequest', key: 'closed-pr', title: 'Closed proposal', author: 'alice', head: 'topic', base: 'main', state: 'closed' },
+        { kind: 'issue', key: 'after-pr', title: 'Issue numbered after a pull request', author: 'carol', state: 'closed' },
+      ],
+    },
+  ],
+  deleteUsers: ['dora'],
+});

package/ts/gitlabseed.default.ts

@@ -0,0 +1,86 @@
+import type { IGitlabSeedProject, IGitlabSeedSpec } from './interfaces.gitlabseed.js';
+
+/** Projects created in `bulk-group` so project listings span more than one default page (20). */
+export const defaultGitlabBulkProjectCount = 22;
+
+/**
+ * A compact seed covering the GitLab behaviours inventory readers must handle:
+ * nested groups with public, internal and private visibility, a personal
+ * project, confidential issues and incidents, separate issue and merge request
+ * IID sequences, closed items, labels, milestones, assignees, notes, tags,
+ * releases, a deleted author whose content GitLab moves to its ghost user, and
+ * more projects than one page of a project listing.
+ */
+export const createDefaultGitlabSeedSpec = (): IGitlabSeedSpec => ({
+  users: [
+    { username: 'alice', name: 'Alice Example' },
+    { username: 'bob', name: 'Bob Example' },
+    { username: 'carol' },
+    { username: 'dora' },
+  ],
+  groups: [
+    { path: 'parent-group', visibility: 'public' },
+    { path: 'sub-group', parent: 'parent-group', visibility: 'internal' },
+    { path: 'deep-group', parent: 'parent-group/sub-group', visibility: 'private', members: [{ username: 'alice', accessLevel: 'reporter' }] },
+    { path: 'bulk-group', visibility: 'public' },
+  ],
+  projects: [
+    {
+      namespace: 'parent-group/sub-group',
+      path: 'app',
+      visibility: 'internal',
+      description: 'Internal project in a subgroup',
+      members: [
+        { username: 'alice', accessLevel: 'developer' },
+        { username: 'bob', accessLevel: 'developer' },
+      ],
+      files: [{ path: 'src/index.ts', content: 'export const seeded = true;\n' }],
+      branches: [{ name: 'feature-a', files: [{ path: 'src/feature.ts', content: 'export const feature = 1;\n' }] }],
+      labels: [
+        { name: 'bug', color: '#d73a4a' },
+        { name: 'enhancement', color: '#a2eeef' },
+      ],
+      milestones: [
+        { title: 'v1', state: 'active' },
+        { title: 'v0', state: 'closed' },
+      ],
+      tags: [{ name: 'v1.0.0', ref: 'main', message: 'First release' }],
+      issuesAndMergeRequests: [
+        {
+          kind: 'issue', key: 'open-labelled', title: 'Open labelled issue', description: 'See !1', author: 'alice',
+          state: 'opened', labels: ['bug'], milestone: 'v1', assignees: ['bob'], notes: [{ author: 'bob', body: 'Confirmed.' }],
+        },
+        { kind: 'mergeRequest', key: 'feature-mr', title: 'Add feature', author: 'bob', sourceBranch: 'feature-a', targetBranch: 'main', state: 'opened', labels: ['enhancement'] },
+        { kind: 'issue', key: 'confidential', title: 'Confidential issue', author: 'alice', state: 'opened', confidential: true },
+        { kind: 'issue', key: 'incident', title: 'Production incident', author: 'bob', state: 'closed', issueType: 'incident' },
+        {
+          kind: 'issue', key: 'closed-by-deleted-user', title: 'Closed issue from a deleted user', author: 'dora', state: 'closed',
+          milestone: 'v0', notes: [{ author: 'dora', body: 'Note from a user who will be deleted.' }],
+        },
+      ],
+      releases: [{ tagName: 'v1.0.0', ref: 'main', name: 'v1.0.0', description: 'Release notes' }],
+    },
+    {
+      namespace: 'parent-group/sub-group/deep-group',
+      path: 'secret',
+      visibility: 'private',
+      issuesAndMergeRequests: [{ kind: 'issue', key: 'private-issue', title: 'Issue in a private project', author: 'alice', state: 'opened' }],
+    },
+    {
+      namespace: 'alice',
+      path: 'personal',
+      visibility: 'public',
+      branches: [{ name: 'topic', files: [{ path: 'notes.md', content: '# Notes\n' }] }],
+      issuesAndMergeRequests: [
+        { kind: 'mergeRequest', key: 'closed-mr', title: 'Closed proposal', author: 'alice', sourceBranch: 'topic', targetBranch: 'main', state: 'closed' },
+        { kind: 'issue', key: 'carol-issue', title: 'Issue from another user', author: 'carol', state: 'closed' },
+      ],
+    },
+    ...Array.from({ length: defaultGitlabBulkProjectCount }, (_valueArg, indexArg): IGitlabSeedProject => ({
+      namespace: 'bulk-group',
+      path: `bulk-${String(indexArg + 1).padStart(2, '0')}`,
+      visibility: 'public',
+    })),
+  ],
+  deleteUsers: ['dora'],
+});

package/ts/index.ts

@@ -0,0 +1,17 @@
+export * from './00_commitinfo_data.js';
+export * from './interfaces.js';
+export * from './interfaces.giteaseed.js';
+export * from './interfaces.gitlabseed.js';
+export { giteaFixtureImage, gitlabFixtureImage, forgeFixtureLabelPrefix, forgeFixtureLabels } from './constants.js';
+export * from './classes.certificateauthority.js';
+export * from './classes.tlsterminator.js';
+export * from './classes.httpclient.js';
+export { ForgeFixtureReaper, listForgeFixtureResources } from './classes.reaper.js';
+export type { IForgeFixtureReaperOptions, IForgeFixtureInventory } from './classes.reaper.js';
+export { ForgeFixtureStoppedError } from './classes.containerlifecycle.js';
+export * from './classes.giteafixture.js';
+export * from './classes.gitlabfixture.js';
+export * from './classes.giteaseed.js';
+export * from './giteaseed.default.js';
+export * from './classes.gitlabseed.js';
+export * from './gitlabseed.default.js';

package/ts/interfaces.giteaseed.ts

@@ -0,0 +1,130 @@
+export type TGiteaVisibility = 'public' | 'limited' | 'private';
+
+export interface IGiteaSeedFile {
+  path: string;
+  content: string;
+}
+
+export interface IGiteaSeedUser {
+  username: string;
+  fullName?: string;
+  visibility?: TGiteaVisibility;
+}
+
+export interface IGiteaSeedOrganization {
+  /** Created by the fixture administrator, who becomes its owner. */
+  name: string;
+  visibility: TGiteaVisibility;
+}
+
+export interface IGiteaSeedIssue {
+  kind: 'issue';
+  /** Spec-local identifier used to find this issue in the manifest. */
+  key: string;
+  title: string;
+  body?: string;
+  /** Existing user who opens the issue (through the administrator's sudo). */
+  author: string;
+  state: 'open' | 'closed';
+  /** Applied by the administrator, so they are not dropped for authors without write access. */
+  labels?: string[];
+  milestone?: string;
+  assignees?: string[];
+  comments?: Array<{ author: string; body: string }>;
+}
+
+export interface IGiteaSeedPullRequest {
+  kind: 'pullRequest';
+  key: string;
+  title: string;
+  body?: string;
+  author: string;
+  /** Branch in the same repository. */
+  head: string;
+  base: string;
+  state: 'open' | 'closed';
+  labels?: string[];
+}
+
+export interface IGiteaSeedRepository {
+  /** A seeded user or organization. */
+  owner: string;
+  name: string;
+  private: boolean;
+  description?: string;
+  collaborators?: Array<{ username: string; permission: 'read' | 'write' | 'admin' }>;
+  /** Committed to the default branch (`main`) after auto-initialisation. */
+  files?: IGiteaSeedFile[];
+  /** Each branch is created by one commit of its files on top of `from` (default `main`). */
+  branches?: Array<{ name: string; from?: string; files: [IGiteaSeedFile, ...IGiteaSeedFile[]] }>;
+  tags?: Array<{ name: string; target: string; message?: string }>;
+  labels?: Array<{ name: string; color: string; description?: string }>;
+  milestones?: Array<{ title: string; description?: string; state?: 'open' | 'closed' }>;
+  /** Created in order; Gitea numbers issues and pull requests from one shared sequence. */
+  issuesAndPullRequests?: Array<IGiteaSeedIssue | IGiteaSeedPullRequest>;
+  releases?: Array<{ tagName: string; target: string; name: string; body?: string; draft?: boolean; prerelease?: boolean }>;
+  /** Uploaded through the Git LFS batch API; their pointers are committed to the default branch. */
+  lfsObjects?: IGiteaSeedFile[];
+}
+
+export interface IGiteaSeedSpec {
+  users: IGiteaSeedUser[];
+  organizations: IGiteaSeedOrganization[];
+  repositories: IGiteaSeedRepository[];
+  /** Deleted after everything else; content they authored is then attributed to Gitea's ghost user. */
+  deleteUsers?: string[];
+}
+
+/** What Gitea itself reported after seeding, read back once all mutations finished. */
+export interface IGiteaSeedManifest {
+  baseUrl: string;
+  version: string;
+  users: Array<{ username: string; id: number; deleted: boolean }>;
+  organizations: Array<{ name: string; id: number; visibility: TGiteaVisibility }>;
+  repositories: IGiteaSeedManifestRepository[];
+}
+
+export interface IGiteaSeedManifestAuthor {
+  id: number;
+  login: string;
+}
+
+export interface IGiteaSeedManifestRepository {
+  owner: string;
+  name: string;
+  fullName: string;
+  id: number;
+  ownerId: number;
+  private: boolean;
+  internal: boolean;
+  defaultBranch: string;
+  htmlUrl: string;
+  cloneUrl: string;
+  branches: Array<{ name: string; commitSha: string }>;
+  tags: Array<{ name: string; commitSha: string }>;
+  labels: Array<{ name: string; id: number }>;
+  milestones: Array<{ title: string; id: number; state: 'open' | 'closed' }>;
+  issues: Array<{
+    key: string;
+    id: number;
+    number: number;
+    state: 'open' | 'closed';
+    author: IGiteaSeedManifestAuthor;
+    labels: string[];
+    milestone: string | null;
+    assignees: string[];
+    comments: Array<{ id: number; author: IGiteaSeedManifestAuthor }>;
+  }>;
+  pullRequests: Array<{
+    key: string;
+    id: number;
+    number: number;
+    state: 'open' | 'closed';
+    author: IGiteaSeedManifestAuthor;
+    head: string;
+    base: string;
+    headSha: string;
+  }>;
+  releases: Array<{ tagName: string; id: number; draft: boolean; prerelease: boolean }>;
+  lfsObjects: Array<{ path: string; oid: string; size: number }>;
+}