@foss.global/forgefixtures 0.2.0

package/dist_ts/ownership.js

@@ -0,0 +1,140 @@
+import * as plugins from './plugins.js';
+import { forgeFixtureLabels } from './constants.js';
+const machineIdPattern = /^[0-9a-f]{32}$/;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const decimalPattern = /^[0-9]{1,20}$/;
+const pidNamespacePattern = /^pid:\[[0-9]{1,20}\]$/;
+const isErrnoException = (errorArg) => errorArg instanceof Error && 'code' in errorArg;
+/**
+ * Reads field 22 (`starttime`) of `/proc/<pid>/stat`. Returns `undefined` when
+ * the process does not exist. The command name may contain spaces and
+ * parentheses, so fields are counted after its closing parenthesis.
+ */
+export const readProcessStartTicks = async (pidArg) => {
+    let stat;
+    try {
+        stat = await plugins.fs.promises.readFile(`/proc/${pidArg}/stat`, 'utf8');
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    // fields[0] is field 3 (state), so field 22 is fields[19].
+    const startTicks = fields[19];
+    if (startTicks === undefined || !decimalPattern.test(startTicks)) {
+        throw new Error(`Process ${pidArg} has a malformed /proc stat record.`);
+    }
+    return startTicks;
+};
+/**
+ * Stands in for the machine ID of a process whose system has no valid
+ * `/etc/machine-id`, as in many container images. It is fixed for the life of
+ * the process and never matches another process, so every other owner is
+ * foreign to this one, and this owner is foreign to every other process: both
+ * sides judge each other by expiry only.
+ */
+const processLocalMachineId = plugins.crypto.randomBytes(16).toString('hex');
+const readMachineId = async () => {
+    let machineId;
+    try {
+        machineId = (await plugins.fs.promises.readFile('/etc/machine-id', 'utf8')).trim();
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === 'ENOENT')
+            return processLocalMachineId;
+        throw error;
+    }
+    return machineIdPattern.test(machineId) ? machineId : processLocalMachineId;
+};
+export const readCurrentProcessIdentity = async () => {
+    const machineId = await readMachineId();
+    const bootId = (await plugins.fs.promises.readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim();
+    if (!uuidPattern.test(bootId))
+        throw new Error('The kernel boot id is malformed.');
+    const processStartTicks = await readProcessStartTicks(process.pid);
+    if (processStartTicks === undefined)
+        throw new Error('The current process has no /proc stat record.');
+    const pidNamespace = await plugins.fs.promises.readlink('/proc/self/ns/pid');
+    if (!pidNamespacePattern.test(pidNamespace))
+        throw new Error('The current PID namespace identity is malformed.');
+    return { machineId, hostname: plugins.os.hostname(), bootId, pidNamespace, pid: process.pid, processStartTicks };
+};
+export const createForgeFixtureOwner = async (kindArg, maxLifetimeMsArg) => {
+    if (!Number.isSafeInteger(maxLifetimeMsArg) || maxLifetimeMsArg < 60_000) {
+        throw new TypeError('maxLifetimeMs must be an integer of at least 60000.');
+    }
+    const identity = await readCurrentProcessIdentity();
+    const createdAt = new Date();
+    return {
+        lifecycleId: plugins.crypto.randomUUID(),
+        kind: kindArg,
+        ...identity,
+        createdAt: createdAt.toISOString(),
+        expiresAt: new Date(createdAt.getTime() + maxLifetimeMsArg).toISOString(),
+    };
+};
+/** Labels carried by every Docker resource of one lifecycle. */
+export const forgeFixtureOwnerLabels = (ownerArg) => ({
+    [forgeFixtureLabels.managed]: 'true',
+    [forgeFixtureLabels.lifecycleId]: ownerArg.lifecycleId,
+    [forgeFixtureLabels.kind]: ownerArg.kind,
+    [forgeFixtureLabels.machineId]: ownerArg.machineId,
+    [forgeFixtureLabels.hostname]: ownerArg.hostname,
+    [forgeFixtureLabels.bootId]: ownerArg.bootId,
+    [forgeFixtureLabels.pidNamespace]: ownerArg.pidNamespace,
+    [forgeFixtureLabels.pid]: String(ownerArg.pid),
+    [forgeFixtureLabels.processStartTicks]: ownerArg.processStartTicks,
+    [forgeFixtureLabels.createdAt]: ownerArg.createdAt,
+    [forgeFixtureLabels.expiresAt]: ownerArg.expiresAt,
+});
+const isIsoTimestamp = (valueArg) => valueArg !== undefined && !Number.isNaN(Date.parse(valueArg)) && new Date(valueArg).toISOString() === valueArg;
+/** Parses ownership labels; returns `undefined` for anything this package did not write. */
+export const parseForgeFixtureOwnerLabels = (labelsArg) => {
+    if (!labelsArg || labelsArg[forgeFixtureLabels.managed] !== 'true')
+        return undefined;
+    const lifecycleId = labelsArg[forgeFixtureLabels.lifecycleId];
+    const kind = labelsArg[forgeFixtureLabels.kind];
+    const machineId = labelsArg[forgeFixtureLabels.machineId];
+    const hostname = labelsArg[forgeFixtureLabels.hostname];
+    const bootId = labelsArg[forgeFixtureLabels.bootId];
+    const pidNamespace = labelsArg[forgeFixtureLabels.pidNamespace];
+    const pid = labelsArg[forgeFixtureLabels.pid];
+    const processStartTicks = labelsArg[forgeFixtureLabels.processStartTicks];
+    const createdAt = labelsArg[forgeFixtureLabels.createdAt];
+    const expiresAt = labelsArg[forgeFixtureLabels.expiresAt];
+    if (lifecycleId === undefined || !uuidPattern.test(lifecycleId)
+        || (kind !== 'gitea' && kind !== 'gitlab')
+        || machineId === undefined || !machineIdPattern.test(machineId)
+        || !hostname
+        || bootId === undefined || !uuidPattern.test(bootId)
+        || pidNamespace === undefined || !pidNamespacePattern.test(pidNamespace)
+        || pid === undefined || !decimalPattern.test(pid) || !Number.isSafeInteger(Number(pid))
+        || processStartTicks === undefined || !decimalPattern.test(processStartTicks)
+        || !isIsoTimestamp(createdAt) || !isIsoTimestamp(expiresAt))
+        return undefined;
+    return {
+        lifecycleId, kind, machineId, hostname, bootId, pidNamespace, pid: Number(pid), processStartTicks, createdAt, expiresAt,
+    };
+};
+/**
+ * Decides whether a lifecycle is stale. A PID identifies a process only inside
+ * its PID namespace: host-network containers sharing the Docker socket share
+ * hostname and boot id but not PIDs, and machines sharing a remote daemon can
+ * share a host name. Owners on another machine (machine id or host name) or in
+ * another PID namespace are therefore judged by expiry only.
+ */
+export const classifyForgeFixtureOwner = async (ownerArg, currentArg, nowArg) => {
+    if (Date.parse(ownerArg.expiresAt) <= nowArg.getTime())
+        return 'expired';
+    if (ownerArg.machineId !== currentArg.machineId || ownerArg.hostname !== currentArg.hostname)
+        return 'alive';
+    if (ownerArg.bootId !== currentArg.bootId)
+        return 'owner-rebooted';
+    if (ownerArg.pidNamespace !== currentArg.pidNamespace)
+        return 'alive';
+    const startTicks = await readProcessStartTicks(ownerArg.pid);
+    return startTicks === ownerArg.processStartTicks ? 'alive' : 'owner-exited';
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib3duZXJzaGlwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvb3duZXJzaGlwLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBQ3hDLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBWXBELE1BQU0sZ0JBQWdCLEdBQUcsZ0JBQWdCLENBQUM7QUFDMUMsTUFBTSxXQUFXLEdBQUcsZ0VBQWdFLENBQUM7QUFDckYsTUFBTSxjQUFjLEdBQUcsZUFBZSxDQUFDO0FBQ3ZDLE1BQU0sbUJBQW1CLEdBQUcsdUJBQXVCLENBQUM7QUFFcEQsTUFBTSxnQkFBZ0IsR0FBRyxDQUFDLFFBQWlCLEVBQXFDLEVBQUUsQ0FDaEYsUUFBUSxZQUFZLEtBQUssSUFBSSxNQUFNLElBQUksUUFBUSxDQUFDO0FBRWxEOzs7O0dBSUc7QUFDSCxNQUFNLENBQUMsTUFBTSxxQkFBcUIsR0FBRyxLQUFLLEVBQUUsTUFBYyxFQUErQixFQUFFO0lBQ3pGLElBQUksSUFBWSxDQUFDO0lBQ2pCLElBQUksQ0FBQztRQUNILElBQUksR0FBRyxNQUFNLE9BQU8sQ0FBQyxFQUFFLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQyxTQUFTLE1BQU0sT0FBTyxFQUFFLE1BQU0sQ0FBQyxDQUFDO0lBQzVFLENBQUM7SUFBQyxPQUFPLEtBQUssRUFBRSxDQUFDO1FBQ2YsSUFBSSxnQkFBZ0IsQ0FBQyxLQUFLLENBQUMsSUFBSSxLQUFLLENBQUMsSUFBSSxLQUFLLFFBQVE7WUFBRSxPQUFPLFNBQVMsQ0FBQztRQUN6RSxNQUFNLEtBQUssQ0FBQztJQUNkLENBQUM7SUFDRCxNQUFNLE1BQU0sR0FBRyxJQUFJLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxXQUFXLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQ2hFLDJEQUEyRDtJQUMzRCxN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

package/dist_ts/plugins.d.ts

@@ -0,0 +1,13 @@
+import 'reflect-metadata';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import * as net from 'node:net';
+import * as os from 'node:os';
+import * as tls from 'node:tls';
+export { crypto, fs, http, https, net, os, tls };
+import * as docker from '@apiclient.xyz/docker';
+export { docker };
+import * as x509 from '@peculiar/x509';
+export { x509 };

package/dist_ts/plugins.js

@@ -0,0 +1,18 @@
+// Polyfill required by @peculiar/x509 (through tsyringe). This import must precede its evaluation.
+import 'reflect-metadata';
+// Node native scope
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import * as net from 'node:net';
+import * as os from 'node:os';
+import * as tls from 'node:tls';
+export { crypto, fs, http, https, net, os, tls };
+// @apiclient.xyz scope
+import * as docker from '@apiclient.xyz/docker';
+export { docker };
+// third-party scope
+import * as x509 from '@peculiar/x509';
+export { x509 };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsbUdBQW1HO0FBQ25HLE9BQU8sa0JBQWtCLENBQUM7QUFFMUIsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxFQUFFLE1BQU0sU0FBUyxDQUFDO0FBQzlCLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBQ2xDLE9BQU8sS0FBSyxLQUFLLE1BQU0sWUFBWSxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxHQUFHLE1BQU0sVUFBVSxDQUFDO0FBQ2hDLE9BQU8sS0FBSyxFQUFFLE1BQU0sU0FBUyxDQUFDO0FBQzlCLE9BQU8sS0FBSyxHQUFHLE1BQU0sVUFBVSxDQUFDO0FBRWhDLE9BQU8sRUFBRSxNQUFNLEVBQUUsRUFBRSxFQUFFLElBQUksRUFBRSxLQUFLLEVBQUUsR0FBRyxFQUFFLEVBQUUsRUFBRSxHQUFHLEVBQUUsQ0FBQztBQUVqRCx1QkFBdUI7QUFDdkIsT0FBTyxLQUFLLE1BQU0sTUFBTSx1QkFBdUIsQ0FBQztBQUVoRCxPQUFPLEVBQUUsTUFBTSxFQUFFLENBQUM7QUFFbEIsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxJQUFJLE1BQU0sZ0JBQWdCLENBQUM7QUFFdkMsT0FBTyxFQUFFLElBQUksRUFBRSxDQUFDIn0=

package/dist_ts/responses.d.ts

@@ -0,0 +1,7 @@
+/** Narrow readers for forge JSON responses. Each throws with the field it expected. */
+export declare const record: (valueArg: unknown, whatArg: string) => Record<string, unknown>;
+export declare const array: (valueArg: unknown, whatArg: string) => unknown[];
+export declare const integer: (valueArg: unknown, whatArg: string) => number;
+export declare const text: (valueArg: unknown, whatArg: string) => string;
+export declare const boolean: (valueArg: unknown, whatArg: string) => boolean;
+export declare const field: (valueArg: unknown, keyArg: string, whatArg: string) => unknown;

package/dist_ts/responses.js

@@ -0,0 +1,30 @@
+/** Narrow readers for forge JSON responses. Each throws with the field it expected. */
+export const record = (valueArg, whatArg) => {
+    if (typeof valueArg !== 'object' || valueArg === null || Array.isArray(valueArg)) {
+        throw new Error(`Expected ${whatArg} to be an object.`);
+    }
+    return valueArg;
+};
+export const array = (valueArg, whatArg) => {
+    if (!Array.isArray(valueArg))
+        throw new Error(`Expected ${whatArg} to be an array.`);
+    return valueArg;
+};
+export const integer = (valueArg, whatArg) => {
+    if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg)) {
+        throw new Error(`Expected ${whatArg} to be a safe integer.`);
+    }
+    return valueArg;
+};
+export const text = (valueArg, whatArg) => {
+    if (typeof valueArg !== 'string')
+        throw new Error(`Expected ${whatArg} to be a string.`);
+    return valueArg;
+};
+export const boolean = (valueArg, whatArg) => {
+    if (typeof valueArg !== 'boolean')
+        throw new Error(`Expected ${whatArg} to be a boolean.`);
+    return valueArg;
+};
+export const field = (valueArg, keyArg, whatArg) => record(valueArg, whatArg)[keyArg];
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzcG9uc2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvcmVzcG9uc2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLHVGQUF1RjtBQUV2RixNQUFNLENBQUMsTUFBTSxNQUFNLEdBQUcsQ0FBQyxRQUFpQixFQUFFLE9BQWUsRUFBMkIsRUFBRTtJQUNwRixJQUFJLE9BQU8sUUFBUSxLQUFLLFFBQVEsSUFBSSxRQUFRLEtBQUssSUFBSSxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsUUFBUSxDQUFDLEVBQUUsQ0FBQztRQUNqRixNQUFNLElBQUksS0FBSyxDQUFDLFlBQVksT0FBTyxtQkFBbUIsQ0FBQyxDQUFDO0lBQzFELENBQUM7SUFDRCxPQUFPLFFBQW1DLENBQUM7QUFDN0MsQ0FBQyxDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0sS0FBSyxHQUFHLENBQUMsUUFBaUIsRUFBRSxPQUFlLEVBQWEsRUFBRTtJQUNyRSxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUM7UUFBRSxNQUFNLElBQUksS0FBSyxDQUFDLFlBQVksT0FBTyxrQkFBa0IsQ0FBQyxDQUFDO0lBQ3JGLE9BQU8sUUFBUSxDQUFDO0FBQ2xCLENBQUMsQ0FBQztBQUVGLE1BQU0sQ0FBQyxNQUFNLE9BQU8sR0FBRyxDQUFDLFFBQWlCLEVBQUUsT0FBZSxFQUFVLEVBQUU7SUFDcEUsSUFBSSxPQUFPLFFBQVEsS0FBSyxRQUFRLElBQUksQ0FBQyxNQUFNLENBQUMsYUFBYSxDQUFDLFFBQVEsQ0FBQyxFQUFFLENBQUM7UUFDcEUsTUFBTSxJQUFJLEtBQUssQ0FBQyxZQUFZLE9BQU8sd0JBQXdCLENBQUMsQ0FBQztJQUMvRCxDQUFDO0lBQ0QsT0FBTyxRQUFRLENBQUM7QUFDbEIsQ0FBQyxDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0sSUFBSSxHQUFHLENBQUMsUUFBaUIsRUFBRSxPQUFlLEVBQVUsRUFBRTtJQUNqRSxJQUFJLE9BQU8sUUFBUSxLQUFLLFFBQVE7UUFBRSxNQUFNLElBQUksS0FBSyxDQUFDLFlBQVksT0FBTyxrQkFBa0IsQ0FBQyxDQUFDO0lBQ3pGLE9BQU8sUUFBUSxDQUFDO0FBQ2xCLENBQUMsQ0FBQztBQUVGLE1BQU0sQ0FBQyxNQUFNLE9BQU8sR0FBRyxDQUFDLFFBQWlCLEVBQUUsT0FBZSxFQUFXLEVBQUU7SUFDckUsSUFBSSxPQUFPLFFBQVEsS0FBSyxTQUFTO1FBQUUsTUFBTSxJQUFJLEtBQUssQ0FBQyxZQUFZLE9BQU8sbUJBQW1CLENBQUMsQ0FBQztJQUMzRixPQUFPLFFBQVEsQ0FBQztBQUNsQixDQUFDLENBQUM7QUFFRixNQUFNLENBQUMsTUFBTSxLQUFLLEdBQUcsQ0FBQyxRQUFpQixFQUFFLE1BQWMsRUFBRSxPQUFlLEVBQVcsRUFBRSxDQUNuRixNQUFNLENBQUMsUUFBUSxFQUFFLE9BQU8sQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDIn0=

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@foss.global/forgefixtures",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Disposable, digest-pinned Gitea and GitLab CE fixtures with owned cleanup, local TLS and ground-truth seed data for forge integration tests.",
+  "main": "dist_ts/index.js",
+  "typings": "dist_ts/index.d.ts",
+  "exports": {
+    ".": "./dist_ts/index.js"
+  },
+  "type": "module",
+  "author": "Task Venture Capital GmbH",
+  "license": "MIT",
+  "dependencies": {
+    "@apiclient.xyz/docker": "^9.2.0",
+    "@peculiar/x509": "^2.1.0",
+    "reflect-metadata": "^0.2.2"
+  },
+  "files": [
+    "ts/**/*",
+    "dist/**/*",
+    "dist_*/**/*",
+    "dist_ts/**/*",
+    ".smartconfig.json",
+    "readme.md",
+    "changelog.md",
+    "license.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://code.foss.global/foss.global/forgefixtures.git"
+  },
+  "bugs": {
+    "url": "https://code.foss.global/foss.global/forgefixtures/issues"
+  },
+  "homepage": "https://code.foss.global/foss.global/forgefixtures#readme",
+  "keywords": [
+    "foss.global",
+    "gitea",
+    "gitlab",
+    "forge",
+    "fixtures",
+    "docker",
+    "integration testing",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=24.18.0"
+  },
+  "os": [
+    "linux"
+  ],
+  "devDependencies": {
+    "@git.zone/tsbuild": "^5.0.0",
+    "@git.zone/tsrun": "^3.0.0",
+    "@git.zone/tstest": "^6.2.0",
+    "@types/node": "^26.6.1"
+  },
+  "scripts": {
+    "test": "(tstest test/ --verbose)",
+    "test:typecheck": "(tsbuild check 'test/**/*')",
+    "build": "(tsbuild tsfolders)",
+    "buildDocs": "(tsdoc)"
+  }
+}

package/readme.md

@@ -0,0 +1,206 @@
+# @foss.global/forgefixtures
+
+Disposable, digest-pinned forge instances for integration tests. `@foss.global/forgefixtures` starts a real Gitea or GitLab Community Edition from its pinned upstream image behind a verified loopback TLS endpoint, bootstraps an administrator token through the forge's supported tooling, seeds realistic data through the documented REST APIs, and returns a ground-truth manifest read back from the forge itself. Every Docker resource carries ownership labels, so resources left behind by a crashed test process are removed by the next run.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Runtime Requirements
+
+- Linux (ownership checks read `/proc`)
+- Node.js 24.18 or newer
+- a reachable Docker Engine; for Gitea the socket is taken from the `dockerSocketPath` option, otherwise `DOCKER_HOST`, otherwise `/var/run/docker.sock`
+- for GitLab, a **rootless** Docker Engine: the omnibus image runs as root, and `@apiclient.xyz/docker` permits a root container user only after the daemon proves rootless mode. `GitlabFixture` defaults to the current user's rootless socket (`$XDG_RUNTIME_DIR/docker.sock`, otherwise `/run/user/<uid>/docker.sock`); a rootful daemon is refused
+- network access to Docker Hub for the first pull of a pinned image
+
+## Installation
+
+```bash
+pnpm add --save-dev @foss.global/forgefixtures
+```
+
+## Usage
+
+```typescript
+import { GiteaFixture, GiteaSeedBuilder, createDefaultGiteaSeedSpec } from '@foss.global/forgefixtures';
+
+const fixture = new GiteaFixture();
+try {
+  const runtime = await fixture.start();
+  // runtime.baseUrl           https://127.0.0.1:<port>
+  // runtime.caCertificatePem  the only CA that issued the endpoint certificate
+  // runtime.admin.token       administrator token with scope `all`
+  // runtime.version           '1.27.3', verified against the image pin
+
+  const manifest = await new GiteaSeedBuilder(fixture).apply(createDefaultGiteaSeedSpec());
+  const repository = manifest.repositories.find((repositoryArg) => repositoryArg.fullName === 'team-with-hyphens/public-repo');
+  console.log(repository?.issues.map((issueArg) => issueArg.number)); // [1, 3]; #2 is a pull request
+
+  const aliceToken = await fixture.createAccessToken({
+    username: 'alice',
+    tokenName: 'inventory',
+    scopes: ['read:repository', 'read:user'],
+  });
+} finally {
+  await fixture.stop();
+}
+```
+
+`start()` returns only after Gitea answers `/api/healthz`, reports the pinned version through `/api/v1/version`, and the administrator and its token exist. A fixture is single-use: after `stop()` create a new instance. `stop()` may be called while `start()` is still running: the start is cancelled at its next checkpoint (an image pull is aborted), `start()` rejects with `ForgeFixtureStoppedError`, and `stop()` returns only after every resource that start created is removed. `stop()` is idempotent; if a removal fails, the remaining resources stay recorded, the failures are thrown together, and a later `stop()` retries them.
+
+### GitLab
+
+```typescript
+import { GitlabFixture, GitlabSeedBuilder, createDefaultGitlabSeedSpec } from '@foss.global/forgefixtures';
+
+const fixture = new GitlabFixture(); // rootless daemon of the current user
+try {
+  const runtime = await fixture.start(); // several minutes: omnibus runs gitlab-ctl reconfigure on first boot
+  // runtime.admin.username  'root'
+  // runtime.admin.token     personal access token with scopes `api` and `sudo`
+  // runtime.version         '19.4.1', verified against the image pin
+
+  const manifest = await new GitlabSeedBuilder(fixture).apply(createDefaultGitlabSeedSpec());
+  const app = manifest.projects.find((projectArg) => projectArg.pathWithNamespace === 'parent-group/sub-group/app');
+  console.log(app?.issues.map((issueArg) => issueArg.iid)); // [1, 2, 3, 4]; merge requests count separately
+
+  const token = await fixture.createAccessToken({ username: 'carol', tokenName: 'inventory', scopes: ['read_api'] });
+} finally {
+  await fixture.stop();
+}
+```
+
+GitLab is configured through `GITLAB_OMNIBUS_CONFIG` with GitLab's memory-constrained settings (Puma in single mode, Sidekiq concurrency 10, Prometheus monitoring off) and `external_url` set to the fixture's HTTPS origin, with nginx listening on plain HTTP behind the TLS terminator and Let's Encrypt off. `start()` returns once all of these hold:
+
+- the image's post-reconfigure hook (`GITLAB_POST_RECONFIGURE_SCRIPT`, run by the image's `/assets/init-container`) has run, so `gitlab-ctl reconfigure` finished
+- Docker reports the container healthy through the image's own `gitlab-healthcheck`, gated on that hook
+- an unauthenticated `/api/v4/version` answers 401 through the proxy, so nginx, Workhorse and Puma serve the API
+- an administrator token exists and `/api/v4/version` reports the pinned version
+
+Tokens are created with GitLab's documented programmatic method, `gitlab-rails runner`; the script is passed on stdin (`runner -`), so it never appears in process arguments. The default startup deadline is 12 minutes after the container starts; the image pull has its own deadline. Stop-during-start behaves exactly as for Gitea.
+
+### Talking to the fixture
+
+The endpoint certificate is issued by a certificate authority that exists only in the memory of the lifecycle. Nothing changes process-global TLS state, so a client must trust `runtime.caCertificatePem` explicitly. `fixture.http` is such a scoped client: it trusts only that CA, refuses URLs outside the fixture origin before sending credentials, never follows redirects, and bounds time and response size.
+
+```typescript
+const user = await fixture.http.requestJson({
+  method: 'GET',
+  url: '/api/v1/user',
+  headers: { authorization: `token ${runtime.admin.token}` },
+  expectedStatus: [200],
+});
+```
+
+The endpoint is served by an in-process TLS-terminating reverse proxy that listens before the container starts. Each forge is therefore configured with its exact external origin (Gitea `ROOT_URL`, GitLab `external_url`), and the proxy forwards requests with the client's `Host` header and `X-Forwarded-Proto: https`, as a correctly configured production proxy does. Links the forge generates, including pagination `Link` headers (GitLab keyset pagination included), Git LFS action URLs and GitLab `web_url` values, use the fixture origin.
+
+### Seed specs and manifests
+
+`GiteaSeedBuilder.apply(spec)` validates the whole spec before the first request, then creates:
+
+- users (with random, discarded passwords) and organizations with `public`, `limited` or `private` visibility
+- repositories owned by users or organizations, auto-initialised on `main`, plus collaborators
+- files on `main`, branches created by one commit each, labels, milestones and tags
+- issues and pull requests in the given order, authored through the administrator's `Sudo` header; labels, milestones, assignees and closing are applied by the administrator so they are not silently dropped for authors without write access
+- releases, and Git LFS objects uploaded through the batch API with their pointers and `.gitattributes` committed
+- deletion of the users listed in `deleteUsers`, last
+
+The returned `IGiteaSeedManifest` is read back from Gitea after all mutations: stable IDs, numbers, states, authors (after deletion), label and milestone associations, branch and tag commits, pull request head commits, release IDs and LFS object IDs.
+
+`createDefaultGiteaSeedSpec()` covers behaviours an inventory reader must handle. These are observed facts of Gitea 1.27.3, asserted by the opt-in test:
+
+- issues and pull requests share one number sequence per repository
+- a deleted author's issues and comments are reattributed to the ghost user with ID `-1`
+- `internal: true` marks a public repository of a **private** owner; a public repository of a `limited` organization reports `internal: false`
+- private repositories are invisible (404) to anonymous callers, and a non-administrator token is refused on admin endpoints (403)
+
+### GitLab seed specs and manifests
+
+`GitlabSeedBuilder.apply(spec)` validates the whole spec before the first request, then creates, as the `root` administrator unless noted:
+
+- users (with random, discarded passwords), groups and nested subgroups with `public`, `internal` or `private` visibility, and group members
+- projects in groups or personal namespaces, initialised with a README on `main`, plus project members
+- files on `main`, branches created by one commit each, labels, milestones and tags
+- issues (including confidential issues and incidents) and merge requests, authored through the administrator's `Sudo` header; labels, milestones, assignees and closing are applied by the administrator, and the seed fails if GitLab does not apply them
+- releases, and closing of milestones marked closed
+- deletion of the users listed in `deleteUsers`, last, waiting until GitLab finished moving their contributions to its ghost user
+
+The returned `IGitlabSeedManifest` is read back after all mutations: group and project IDs, namespaces, visibility, `web_url` and clone URLs, branch and tag commits, labels, milestones, issue and merge request IDs and IIDs, states, types, confidentiality, authors (after deletion), assignees, notes and releases.
+
+`createDefaultGitlabSeedSpec()` creates 25 projects, more than one default page of 20. These are observed facts of GitLab CE 19.4.1, asserted by the opt-in test or handled by the seed:
+
+- issues and merge requests have separate IID sequences per project
+- a deleted user's issues and notes are reattributed to the `ghost` user; the deletion runs in the background and took about 50 s
+- a closed milestone assigned through the API is silently ignored (the milestone finder defaults to active milestones), so the seed closes milestones after assigning them
+- group members get access to a project created in the group from a background job, so a member can see 404 for a few moments; the seed waits for access before acting as that member
+- keyset pagination `Link` headers carry the fixture origin
+- internal projects are 404 to anonymous callers and visible to any signed-in user; private projects and confidential issues are 404 to non-members; a non-administrator token is refused on admin endpoints (403)
+
+## Ownership and Cleanup
+
+Every container, network and volume of a lifecycle carries labels under `global.foss.forgefixtures.*`: the lifecycle ID, fixture kind, machine ID (`/etc/machine-id`; a process whose system has none, as in many container images, uses a random ID fixed for its lifetime), host name, kernel boot ID, owner PID namespace (`pid:[<inode>]`), owner PID, owner process start time, creation time and expiry. Before starting, each lifecycle runs the reaper, which removes a lifecycle's resources when:
+
+- its `maxLifetimeMs` (default two hours) has passed (`expired`)
+- its owner ran on this machine, and the machine rebooted since (`owner-rebooted`)
+- its owner ran on this machine in the reaper's own PID namespace, and that PID no longer exists or belongs to a process with a different start time (`owner-exited`)
+
+A PID identifies a process only inside its PID namespace. Processes that share the Docker socket can share host name and boot ID without sharing PIDs, for example a runner in a host-network container, and machines sharing a remote daemon can share a host name. Owners with another machine ID or host name, or in another PID namespace, are therefore judged by expiry only. A process without a machine ID therefore judges every other owner by expiry only, and every other process judges its owners the same way. Resources whose labels cannot be interpreted, including labels without a machine ID or PID namespace, are reported and never removed. The reaper can also be run on its own:
+
+```typescript
+import { ForgeFixtureReaper } from '@foss.global/forgefixtures';
+
+const report = await new ForgeFixtureReaper().reap();
+console.log(report.reapedLifecycles, report.unrecognizedResources);
+```
+
+## Pinned Images and Resources
+
+| Fixture | Image | Limits |
+| --- | --- | --- |
+| Gitea | `gitea/gitea:1.27.3-rootless@sha256:1c17ecaead42eb3b5391553d8708103a4beb0e86edf5b9ebc1eb269c318845f2` (multi-architecture index) | 512 MiB memory without swap, 2 CPUs, 512 PIDs |
+| GitLab CE | `gitlab/gitlab-ce:19.4.1-ce.0@sha256:9b33b45b9f42d176bada85ee5ecb81ddab7e506c435f44cd582206e284b2809c` (multi-architecture index) | 5 GiB memory without swap, 4 CPUs, 4096 PIDs, 256 MiB `/dev/shm` |
+
+Images are pulled by digest and the pulled repository digest is verified; a moved tag cannot change what runs. Gitea runs as uid 1000 with SQLite, and its data directory, configuration and Git hooks live in one owned named volume that is removed with the lifecycle; hooks must be executable, which Docker's `noexec` tmpfs mounts would prevent. Only the plain-HTTP port is published, on `127.0.0.1`, on a port the lifecycle picks from the kernel's free loopback ports (a rootless daemon allocates ephemeral ports blind to host listeners); SSH is not published.
+
+GitLab runs as root inside the container, which a rootless daemon maps to the invoking user. Its configuration, data and logs live in three owned named volumes that are removed with the lifecycle. Run one GitLab fixture at a time and check the host's available memory first: the opt-in test refuses to boot GitLab with less than 8 GiB available.
+
+Measured on a 32-CPU host with the image already present:
+
+- Gitea: start to ready in 7–8 s, the default seed in about 7 s, about 170 MiB of memory while idle after seeding, and a 3.6 MiB data volume.
+- GitLab CE (four runs): start to ready in 253–269 s, the default seed in 63–138 s (about 50 s of it waiting for the user deletion), a token created through `gitlab-rails runner` in up to a minute. Anonymous memory is about 2.8 GiB while idle after seeding and peaked at 3.6 GiB while a token runner shared the container with Puma; a 4 GiB limit was reached through page cache (reclaimed by the kernel, no OOM kills), so the default limit is 5 GiB to leave headroom for anonymous memory peaks. After seeding the data volume holds 486 MB, the log volume 11 MB and the configuration volume 0.2 MB. The image is 3.8 GB.
+
+## Tests
+
+`pnpm test` runs the Docker-free tests only. The Docker tests are opt-in:
+
+```bash
+FORGEFIXTURES=gitea pnpm exec tstest test/test.gitea.node.ts --verbose --logfile
+FORGEFIXTURES=gitea pnpm exec tstest test/test.gitea.crash.node.ts --verbose --logfile
+FORGEFIXTURES=gitlab pnpm exec tstest test/test.gitlab.node.ts --verbose --logfile
+```
+
+`FORGEFIXTURES` takes a comma list (`gitea,gitlab`) or `all`. All GitLab assertions live in one file, so GitLab boots fully once per run; that file also stops three GitLab starts at different phases, one at a time.
+
+`test.gitea.crash.node.ts` starts a fixture in a child process that kills itself with `SIGKILL`, then proves the reaper removes the container, network and volume that outlived it.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license.md](./license.md) file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@foss.global/forgefixtures',
+  version: '0.2.0',
+  description: 'Disposable, digest-pinned Gitea and GitLab CE fixtures with owned cleanup, local TLS and ground-truth seed data for forge integration tests.'
+}