@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/dist/shared/git-internals.js

@@ -0,0 +1,181 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { GitInternalsError } from './domain-errors.js';
+import { isAbsence } from './fs.contract.js';
+/**
+ * The repository's internal git folder is never a workspace path.
+ *
+ * `.git/` holds the object database, the refs and the clone's config — the
+ * credential helper among it. No file tool and no workspace route reads,
+ * lists, writes or moves anything there; git itself is the only writer. The
+ * rule is judged on segments, never on a prefix, so `.github/` and
+ * `.gitkeep` stay ordinary paths.
+ *
+ * Two checks, both needed:
+ *   - {@link hasGitInternalsSegment} is LEXICAL: any spelling that names the
+ *     folder — `.GIT`, `%2egit`, `a/../.git`, `a\.git` — is refused before
+ *     anything touches the disk, so a refusal takes no lock and records no
+ *     read.
+ *   - {@link assertNotGitInternals} adds the RESOLVED form: the deepest part
+ *     of the path that exists is run through `realpath`, so a symbolic link
+ *     in the repository that points into the folder is refused the same way.
+ */
+/**
+ * Percent-decode until the spelling stops changing (`%252e` is `.` twice
+ * removed), however many layers deep. No pass limit is needed: a pass that
+ * changes anything makes the string shorter, so the loop always ends.
+ */
+function percentDecoded(value) {
+    let current = value;
+    for (;;) {
+        const next = current.replace(/%([0-9a-f]{2})/gi, (_m, hex) => String.fromCharCode(parseInt(hex, 16)));
+        if (next === current)
+            return current;
+        current = next;
+    }
+}
+/**
+ * Whether one path segment names the git folder. Case-folded, because a
+ * case-insensitive volume opens `.GIT` as `.git`; trailing dots and spaces
+ * dropped, because Windows does the same to `.git.` and `.git `.
+ */
+function isGitSegment(segment) {
+    return segment.replace(/[. ]+$/, '').toLowerCase() === '.git';
+}
+/** True when any segment of `inputPath`, in any spelling, is the git folder. */
+export function hasGitInternalsSegment(inputPath) {
+    if (typeof inputPath !== 'string')
+        return false;
+    return percentDecoded(inputPath)
+        .split(/[\\/]+/)
+        .some(isGitSegment);
+}
+/** Refuse `inputPath` lexically. See {@link hasGitInternalsSegment}. */
+export function assertNoGitInternalsSegment(inputPath) {
+    if (hasGitInternalsSegment(inputPath))
+        throw new GitInternalsError();
+}
+const errCode = (err) => err?.code;
+/** `null` for "nothing resolvable here" (absent, or a link loop); every other filesystem error is rethrown. */
+function nullWhenUnresolvable(err) {
+    if (isAbsence(err) || errCode(err) === 'ELOOP')
+        return null;
+    throw err;
+}
+/** Dangling links followed by hand before the chain counts as a loop (Linux's own limit). */
+const MAX_LINK_HOPS = 40;
+/**
+ * `realpath` of the deepest existing ancestor of `absolutePath`, with the
+ * missing rest joined back on. A DANGLING link on the way is followed by hand:
+ * `realpath` refuses it, but a write through it lands at its target, so the
+ * target is what gets judged (`notes.md -> .git/hooks/post-checkout`).
+ */
+async function resolvedRealPath(absolutePath) {
+    let existing = absolutePath;
+    const rest = [];
+    let hops = 0;
+    for (;;) {
+        const real = await fs.realpath(existing).catch(nullWhenUnresolvable);
+        if (real !== null)
+            return path.join(real, ...rest);
+        // EINVAL is "not a link": nothing to follow. Any other failure — a
+        // permission error, say — is thrown, never guessed past lexically.
+        const target = hops < MAX_LINK_HOPS
+            ? await fs.readlink(existing).catch((err) => (errCode(err) === 'EINVAL' ? null : nullWhenUnresolvable(err)))
+            : null;
+        if (target !== null) {
+            const parent = await fs.realpath(path.dirname(existing)).catch(nullWhenUnresolvable);
+            if (parent !== null) {
+                hops++;
+                existing = path.resolve(parent, target);
+                continue;
+            }
+        }
+        const up = path.dirname(existing);
+        if (up === existing)
+            return null;
+        rest.unshift(path.basename(existing));
+        existing = up;
+    }
+}
+/**
+ * Refuse a path under `rootDir` that names the git folder or resolves into it.
+ *
+ * `inputPath` is the caller's own spelling (checked lexically, encoded forms
+ * included, and probed on disk every way it could land — see
+ * {@link candidateTargets}); `absolutePath`, when a layer has already
+ * decided where the path goes, is that place, judged AS WELL. Both in one
+ * call, because the two answer different questions — a link reached by a
+ * reading this layer does not use is caught only by the spelling, a link the
+ * layer's own resolution follows only by the place — and one call walks the
+ * root once and probes a place that both name once. Only the part below
+ * `rootDir` is judged, so a workspaces root that itself sits under some
+ * `.git` directory does not refuse everything. A link that leaves the root
+ * is judged on its target's path relative to the root, so a link into
+ * another checkout's `.git` is refused too; whether such a link may be
+ * followed at all is the containment checks' business.
+ */
+export async function assertNotGitInternals(rootDir, inputPath, absolutePath) {
+    assertNoGitInternalsSegment(inputPath);
+    const root = path.resolve(rootDir);
+    const realRoot = await resolvedRealPath(root);
+    // Each place once, remembering whether a layer resolved it (probed as
+    // given) or only a spelling named it (probed only inside the root).
+    const targets = new Map();
+    for (const target of candidateTargets(root, inputPath))
+        targets.set(target, false);
+    if (absolutePath !== undefined)
+        targets.set(absolutePath, true);
+    for (const [target, resolved] of targets) {
+        const relative = path.relative(root, target);
+        if (hasGitInternalsSegment(relative))
+            throw new GitInternalsError();
+        if (realRoot === null)
+            continue;
+        // A raw spelling fans out into candidates, and one of them can name a
+        // place outside the workspace entirely — `/etc/…`, a deep climb. Such a
+        // candidate is judged by the lexical reading above (a link into another
+        // checkout's `.git` is named there) but NOT probed on disk: probing it
+        // would let an unreadable external directory answer with its own
+        // `EACCES` instead of the path rule's typed refusal for a spelling that
+        // was never a workspace path. A path a layer already resolved is the one
+        // place it is, so it is probed as given.
+        // `..` and `../…` are the climbs; `..link` is an ordinary name that merely
+        // starts with those characters, and a link by that name can point into the
+        // folder — so it is probed like any other entry under the root.
+        const climbsOut = relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+        if (!resolved && (relative === '' || climbsOut))
+            continue;
+        const realTarget = await resolvedRealPath(target);
+        if (realTarget !== null && hasGitInternalsSegment(path.relative(realRoot, realTarget)))
+            throw new GitInternalsError();
+    }
+}
+/**
+ * Every place one raw spelling could LAND, because a spelling is not yet a
+ * path until something decides how to read it.
+ *
+ * A backslash separates segments on Windows and is an ordinary character in a
+ * filename here, so `kb\\Notes\\..\\link` is read BOTH ways; an absolute path
+ * is both the path it names and — as every workspace caller reads it — that
+ * path with its leading slashes dropped, under the workspace; and a leading
+ * climb (`../kb/link`) is both the climb it spells and the path left when the
+ * climb is dropped, which is how a lenient reader takes it. The spelling is
+ * refused when ANY reading lands in the git folder: which reading a later
+ * layer picks is not something this rule should have to predict.
+ *
+ * This is what a CALLER's own spelling needs. A path some layer has already
+ * resolved arrives as `absolutePath` and is judged as the one place it is.
+ */
+function candidateTargets(root, inputPath) {
+    const targets = new Set();
+    for (const spelling of new Set([inputPath, inputPath.replace(/\\/g, '/')])) {
+        const anchored = spelling.replace(/^[\\/]+/, '');
+        targets.add(path.resolve(root, anchored));
+        targets.add(path.resolve(root, anchored.replace(/^(\.\.?[\\/])+/, '')));
+        if (/^[\\/]/.test(spelling))
+            targets.add(path.resolve(spelling));
+    }
+    return [...targets];
+}
+//# sourceMappingURL=git-internals.js.map

package/dist/shared/git-internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-internals.js","sourceRoot":"","sources":["../../src/shared/git-internals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,EAAE,EAAE,GAAW,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9G,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,OAAO,CAAC;QACrC,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;AAChE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,sBAAsB,CAAC,SAAkB;IACvD,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,cAAc,CAAC,SAAS,CAAC;SAC7B,KAAK,CAAC,QAAQ,CAAC;SACf,IAAI,CAAC,YAAY,CAAC,CAAC;AACxB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,2BAA2B,CAAC,SAAkB;IAC5D,IAAI,sBAAsB,CAAC,SAAS,CAAC;QAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,GAAY,EAAW,EAAE,CAAE,GAA0B,EAAE,IAAI,CAAC;AAE7E,+GAA+G;AAC/G,SAAS,oBAAoB,CAAC,GAAY;IACxC,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,GAAG,CAAC;AACZ,CAAC;AAED,6FAA6F;AAC7F,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB;;;;;GAKG;AACH,KAAK,UAAU,gBAAgB,CAAC,YAAoB;IAClD,IAAI,QAAQ,GAAG,YAAY,CAAC;IAC5B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACrE,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;QACnD,mEAAmE;QACnE,mEAAmE;QACnE,MAAM,MAAM,GACV,IAAI,GAAG,aAAa;YAClB,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC;YACrH,CAAC,CAAC,IAAI,CAAC;QACX,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;YACrF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,IAAI,EAAE,CAAC;gBACP,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBACxC,SAAS;YACX,CAAC;QACH,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClC,IAAI,EAAE,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACjC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtC,QAAQ,GAAG,EAAE,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAe,EAAE,SAAiB,EAAE,YAAqB;IACnG,2BAA2B,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC9C,sEAAsE;IACtE,oEAAoE;IACpE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC3C,KAAK,MAAM,MAAM,IAAI,gBAAgB,CAAC,IAAI,EAAE,SAAS,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACnF,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAChE,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,OAAO,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,sBAAsB,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC;QACpE,IAAI,QAAQ,KAAK,IAAI;YAAE,SAAS;QAChC,sEAAsE;QACtE,wEAAwE;QACxE,wEAAwE;QACxE,uEAAuE;QACvE,iEAAiE;QACjE,wEAAwE;QACxE,yEAAyE;QACzE,yCAAyC;QACzC,2EAA2E;QAC3E,2EAA2E;QAC3E,gEAAgE;QAChE,MAAM,SAAS,GAAG,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QACzG,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,KAAK,EAAE,IAAI,SAAS,CAAC;YAAE,SAAS;QAC1D,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,UAAU,KAAK,IAAI,IAAI,sBAAsB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC;IACxH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,gBAAgB,CAAC,IAAY,EAAE,SAAiB;IACvD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,QAAQ,IAAI,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACjD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACxE,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC"}

package/dist/shared/git.contract.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The contract for RUNNING git. Nothing here spawns anything — the one
+ * implementation is `NodeGitRunner` in `modules/workflow/git`, wired once by
+ * the composition root and injected into every module that shells out to git,
+ * so no module carries an `execFile('git', …)` of its own.
+ *
+ * WHY THERE IS A PORT AT ALL. Git was spawned from six places, each with its
+ * own environment, its own buffer ceiling and its own error shape. Four of the
+ * six had no deadline at all, and the two that did (the KB startup runner, the
+ * setup screen's `ls-remote`) set `execFile`'s own `timeout`, which signals git
+ * and then goes on waiting for output pipes a surviving transport helper still
+ * holds — see `killTree` in the implementation for what that measured out at.
+ * A git process that never returns is not
+ * a hypothetical: an unreachable host, a hung credential helper, or a remote
+ * that accepts the connection and then stops talking all produce one. And a
+ * hung git is not one stalled request. It holds the workspace mutex, which is
+ * what serializes every other operation on that clone, so one dead remote takes
+ * the workspace with it — and, while the commit worker is single-flight, every
+ * other workspace too. The file is on disk and shows as saved; git history
+ * silently stops moving.
+ *
+ * So the point of this contract is the DEADLINE, and the deadline is not
+ * optional: {@link https://github.com/Bevel-Software/Hexis Hexis}'s
+ * "Opened Connections Have a Closing Owner" invariant requires that a spawned
+ * child be closed on every path including timeout and abandonment, and a wait
+ * that can never be abandoned cannot satisfy it. Every call made through this
+ * port carries one, and the implementation kills the child when it expires.
+ *
+ * WHAT THIS PORT DOES NOT DO. It does not lock. Serializing git against a
+ * clone is the `WorkspaceMutex`'s job, under the canonical workspace id, and
+ * moving that responsibility here would give the codebase two answers to
+ * "which operations exclude each other". A runner is told what to run and
+ * where; whether it was safe to run it there was decided before the call.
+ *
+ * It also does not stream. A long-lived child whose output is piped somewhere
+ * as it arrives — `git http-backend` serving a clone, `git archive` piped into
+ * a download — is a different lifetime with a different owner, and stays with
+ * the code that owns it.
+ */
+/**
+ * Strip the configured git token out of text on its way into an error, a log
+ * line or a response.
+ *
+ * git puts the remote URL into a great many of its messages, and on a
+ * token-authenticated remote that URL carries the credential. Without this, a
+ * push failure writes the deployment's token into the container log, the API
+ * response, and any change request the recovery agent opens about it.
+ *
+ * Read from the environment at call time rather than captured: the setup screen
+ * can supply a token after boot, and `DeploymentSettingsService.syncGitTokenEnv`
+ * puts it here — a value captured at module load would be the empty string for
+ * exactly the deployments that configure their token that way.
+ */
+export declare function redactGitToken(text: string): string;
+/**
+ * What a completed git invocation produced. `stdout` is decoded text unless
+ * the call asked for bytes (see {@link GitRunOptions.encoding}); `stderr` is
+ * always text, since its only use is a message.
+ */
+export interface GitRunResult<TOut = string> {
+    stdout: TOut;
+    stderr: string;
+}
+export interface GitRunOptions {
+    /**
+     * Bytes to feed the subprocess on stdin — used by the
+     * `--pathspec-from-file=-` commit/add paths so that a several-hundred-file
+     * batch never has to ride the argv (Windows caps a command line at ~32K
+     * characters), and by `cat-file --batch` to name the objects it wants.
+     */
+    input?: string;
+    /**
+     * Override the runner's default deadline for this one call. For an operation
+     * whose legitimate duration is unlike the rest — a first clone of a large
+     * repository, say — rather than raising the deployment-wide default to
+     * accommodate it.
+     */
+    timeoutMs?: number;
+    /**
+     * Environment entries laid over the runner's own for this one call. For the
+     * variables git reads as INPUT to a specific command — `GIT_DIR`,
+     * `GIT_INDEX_FILE` and `GIT_WORK_TREE` pointing a plumbing command at a
+     * scratch index, `GIT_AUTHOR_*` naming a committer, a helper-read credential
+     * — never for the settings that make every invocation safe, which the
+     * runner sets and a caller cannot unset.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * `'buffer'` returns stdout as raw bytes. For output whose framing is in
+     * BYTES rather than characters: `cat-file --batch` announces each object as
+     * `<oid> <type> <size>` and follows it with exactly `size` bytes, and a
+     * decoded string cannot be walked by that count once the content is not
+     * ASCII. Default `'utf8'`.
+     */
+    encoding?: 'utf8' | 'buffer';
+}
+/**
+ * A git invocation that did not succeed: a non-zero exit, a failure to spawn,
+ * or a deadline that expired.
+ *
+ * `exitCode` and `stderr` are carried so that callers can tell an EXPECTED
+ * non-zero exit (`merge-base` exiting 1 for "no common ancestor", `diff
+ * --quiet` exiting 1 for "there are differences") from an infrastructure
+ * failure, without parsing message text. Several callers already read
+ * `exitCode` this way.
+ *
+ * `timedOut` is the distinction the deadline adds, and it matters: a timeout is
+ * a statement about the host or the network, never about the repository. Code
+ * that treats a non-zero exit as a permanent answer — "there is no such ref",
+ * "there is nothing to commit" — would draw exactly the wrong conclusion from
+ * one, so a caller that interprets exit codes must exclude it first.
+ */
+export declare class GitRunError extends Error {
+    /** Process exit code, when the process ran and exited. */
+    readonly exitCode?: number;
+    /** Captured stderr, with any configured git token redacted. */
+    readonly stderr?: string;
+    /** True when the deadline expired and the child was killed. */
+    readonly timedOut: boolean;
+    /**
+     * No `cause`, on purpose: the child-process error it would carry holds the
+     * unredacted command line and stderr, and a logger that serializes errors
+     * walks the cause chain. Everything a caller can act on is on the fields
+     * above, redacted.
+     */
+    constructor(message: string, opts?: {
+        exitCode?: number;
+        stderr?: string;
+        timedOut?: boolean;
+    });
+}
+/** Whether a failure came from the deadline rather than from git's own answer. */
+export declare function isGitTimeout(err: unknown): boolean;
+/**
+ * Runs one git command to completion and returns what it wrote.
+ *
+ * `cwd` is the directory git runs in; `args` are passed to the executable
+ * verbatim, never through a shell. Throws {@link GitRunError} for every
+ * failure, the deadline included.
+ */
+export interface IGitRunner {
+    /**
+     * The deadline a call gets when it names none — the deployment's configured
+     * ceiling. A caller whose command is legitimately long (a first clone) asks
+     * for `Math.max(defaultTimeoutMs, itsOwnFloor)`, so an operator who raised
+     * the ceiling raises it there too rather than being overridden by a
+     * constant.
+     */
+    readonly defaultTimeoutMs: number;
+    run(cwd: string, args: string[], opts: GitRunOptions & {
+        encoding: 'buffer';
+    }): Promise<GitRunResult<Buffer>>;
+    run(cwd: string, args: string[], opts?: GitRunOptions & {
+        encoding?: 'utf8';
+    }): Promise<GitRunResult>;
+}
+//# sourceMappingURL=git.contract.d.ts.map

package/dist/shared/git.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.contract.d.ts","sourceRoot":"","sources":["../../src/shared/git.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,IAAI,GAAG,MAAM;IACzC,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO;CAOnG;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG;QAAE,QAAQ,EAAE,QAAQ,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9G,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACvG"}

package/dist/shared/git.contract.js

@@ -0,0 +1,103 @@
+/**
+ * The contract for RUNNING git. Nothing here spawns anything — the one
+ * implementation is `NodeGitRunner` in `modules/workflow/git`, wired once by
+ * the composition root and injected into every module that shells out to git,
+ * so no module carries an `execFile('git', …)` of its own.
+ *
+ * WHY THERE IS A PORT AT ALL. Git was spawned from six places, each with its
+ * own environment, its own buffer ceiling and its own error shape. Four of the
+ * six had no deadline at all, and the two that did (the KB startup runner, the
+ * setup screen's `ls-remote`) set `execFile`'s own `timeout`, which signals git
+ * and then goes on waiting for output pipes a surviving transport helper still
+ * holds — see `killTree` in the implementation for what that measured out at.
+ * A git process that never returns is not
+ * a hypothetical: an unreachable host, a hung credential helper, or a remote
+ * that accepts the connection and then stops talking all produce one. And a
+ * hung git is not one stalled request. It holds the workspace mutex, which is
+ * what serializes every other operation on that clone, so one dead remote takes
+ * the workspace with it — and, while the commit worker is single-flight, every
+ * other workspace too. The file is on disk and shows as saved; git history
+ * silently stops moving.
+ *
+ * So the point of this contract is the DEADLINE, and the deadline is not
+ * optional: {@link https://github.com/Bevel-Software/Hexis Hexis}'s
+ * "Opened Connections Have a Closing Owner" invariant requires that a spawned
+ * child be closed on every path including timeout and abandonment, and a wait
+ * that can never be abandoned cannot satisfy it. Every call made through this
+ * port carries one, and the implementation kills the child when it expires.
+ *
+ * WHAT THIS PORT DOES NOT DO. It does not lock. Serializing git against a
+ * clone is the `WorkspaceMutex`'s job, under the canonical workspace id, and
+ * moving that responsibility here would give the codebase two answers to
+ * "which operations exclude each other". A runner is told what to run and
+ * where; whether it was safe to run it there was decided before the call.
+ *
+ * It also does not stream. A long-lived child whose output is piped somewhere
+ * as it arrives — `git http-backend` serving a clone, `git archive` piped into
+ * a download — is a different lifetime with a different owner, and stays with
+ * the code that owns it.
+ */
+/**
+ * Strip the configured git token out of text on its way into an error, a log
+ * line or a response.
+ *
+ * git puts the remote URL into a great many of its messages, and on a
+ * token-authenticated remote that URL carries the credential. Without this, a
+ * push failure writes the deployment's token into the container log, the API
+ * response, and any change request the recovery agent opens about it.
+ *
+ * Read from the environment at call time rather than captured: the setup screen
+ * can supply a token after boot, and `DeploymentSettingsService.syncGitTokenEnv`
+ * puts it here — a value captured at module load would be the empty string for
+ * exactly the deployments that configure their token that way.
+ */
+export function redactGitToken(text) {
+    const token = process.env.GITHUB_TOKEN;
+    const scrubbed = token ? text.replaceAll(token, '***') : text;
+    // URL userinfo as well: a remote spelled `https://user:pass@host` would
+    // otherwise leak `pass` verbatim through every git failure that quotes the
+    // URL back, whatever the token setting.
+    return scrubbed.replace(/:\/\/[^/@\s]+@/g, '://***@');
+}
+/**
+ * A git invocation that did not succeed: a non-zero exit, a failure to spawn,
+ * or a deadline that expired.
+ *
+ * `exitCode` and `stderr` are carried so that callers can tell an EXPECTED
+ * non-zero exit (`merge-base` exiting 1 for "no common ancestor", `diff
+ * --quiet` exiting 1 for "there are differences") from an infrastructure
+ * failure, without parsing message text. Several callers already read
+ * `exitCode` this way.
+ *
+ * `timedOut` is the distinction the deadline adds, and it matters: a timeout is
+ * a statement about the host or the network, never about the repository. Code
+ * that treats a non-zero exit as a permanent answer — "there is no such ref",
+ * "there is nothing to commit" — would draw exactly the wrong conclusion from
+ * one, so a caller that interprets exit codes must exclude it first.
+ */
+export class GitRunError extends Error {
+    /** Process exit code, when the process ran and exited. */
+    exitCode;
+    /** Captured stderr, with any configured git token redacted. */
+    stderr;
+    /** True when the deadline expired and the child was killed. */
+    timedOut;
+    /**
+     * No `cause`, on purpose: the child-process error it would carry holds the
+     * unredacted command line and stderr, and a logger that serializes errors
+     * walks the cause chain. Everything a caller can act on is on the fields
+     * above, redacted.
+     */
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = 'GitRunError';
+        this.exitCode = opts.exitCode;
+        this.stderr = opts.stderr;
+        this.timedOut = opts.timedOut ?? false;
+    }
+}
+/** Whether a failure came from the deadline rather than from git's own answer. */
+export function isGitTimeout(err) {
+    return err instanceof GitRunError && err.timedOut;
+}
+//# sourceMappingURL=git.contract.js.map

package/dist/shared/git.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.contract.js","sourceRoot":"","sources":["../../src/shared/git.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,wEAAwE;IACxE,2EAA2E;IAC3E,wCAAwC;IACxC,OAAO,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;AACxD,CAAC;AA8CD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,0DAA0D;IACjD,QAAQ,CAAU;IAC3B,+DAA+D;IACtD,MAAM,CAAU;IACzB,+DAA+D;IACtD,QAAQ,CAAU;IAE3B;;;;;OAKG;IACH,YAAY,OAAe,EAAE,OAAmE,EAAE;QAChG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACzC,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,WAAW,IAAI,GAAG,CAAC,QAAQ,CAAC;AACpD,CAAC"}

package/dist/shared/http-errors.d.ts

@@ -0,0 +1,33 @@
+import type { WorkflowDomainError } from './domain-errors.js';
+/**
+ * THE response body for a domain refusal: the error's own message, plus
+ * whatever its payload carries, for a client that switches on the shape
+ * rather than on the prose.
+ *
+ * The payload is an open `Record<string, unknown>` and deliberately stays
+ * that way — `WorkflowValidationError` takes one from its caller — so this
+ * lists no closed set. The discriminator to reach for is `kind`
+ * (`path-traversal`, `unreadable-archive`, `no-shared-history`, …), which
+ * most refusals carry; beside it they add whatever context that kind needs
+ * (`branchName`, `head`/`base`, `conflictedPaths`, `feature`), and
+ * `AccessConfigError` carries `accessConfigErrors` instead. Read the
+ * subclass to know what its own refusal brings.
+ *
+ * Eight route surfaces built this object by hand, and seven of them spread
+ * the payload AFTER the message:
+ *
+ *   { error: err.message, ...err.payload }   // payload wins
+ *
+ * A payload is a `Record<string, unknown>`, so a key named `error` is
+ * expressible — and in that shape it silently replaces the one line the
+ * client renders, leaving a refusal that says something else entirely. The
+ * eighth site had it right and said so in a comment; this is that comment
+ * made into the only way to build the body.
+ *
+ * The STATUS is deliberately not decided here. Each surface keeps its own
+ * 5xx policy — the admin roster routes never leak a 5xx detail, while the
+ * workspace routes surface `AccessConfigError`'s message because an admin
+ * has to read it — and those differ on purpose, not by drift.
+ */
+export declare function domainErrorBody(err: WorkflowDomainError): Record<string, unknown>;
+//# sourceMappingURL=http-errors.d.ts.map

package/dist/shared/http-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-errors.d.ts","sourceRoot":"","sources":["../../src/shared/http-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGjF"}

package/dist/shared/http-errors.js

@@ -0,0 +1,35 @@
+/**
+ * THE response body for a domain refusal: the error's own message, plus
+ * whatever its payload carries, for a client that switches on the shape
+ * rather than on the prose.
+ *
+ * The payload is an open `Record<string, unknown>` and deliberately stays
+ * that way — `WorkflowValidationError` takes one from its caller — so this
+ * lists no closed set. The discriminator to reach for is `kind`
+ * (`path-traversal`, `unreadable-archive`, `no-shared-history`, …), which
+ * most refusals carry; beside it they add whatever context that kind needs
+ * (`branchName`, `head`/`base`, `conflictedPaths`, `feature`), and
+ * `AccessConfigError` carries `accessConfigErrors` instead. Read the
+ * subclass to know what its own refusal brings.
+ *
+ * Eight route surfaces built this object by hand, and seven of them spread
+ * the payload AFTER the message:
+ *
+ *   { error: err.message, ...err.payload }   // payload wins
+ *
+ * A payload is a `Record<string, unknown>`, so a key named `error` is
+ * expressible — and in that shape it silently replaces the one line the
+ * client renders, leaving a refusal that says something else entirely. The
+ * eighth site had it right and said so in a comment; this is that comment
+ * made into the only way to build the body.
+ *
+ * The STATUS is deliberately not decided here. Each surface keeps its own
+ * 5xx policy — the admin roster routes never leak a 5xx detail, while the
+ * workspace routes surface `AccessConfigError`'s message because an admin
+ * has to read it — and those differ on purpose, not by drift.
+ */
+export function domainErrorBody(err) {
+    // Payload FIRST, `error` LAST: the message always wins.
+    return { ...(err.payload ?? {}), error: err.message };
+}
+//# sourceMappingURL=http-errors.js.map

package/dist/shared/http-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-errors.js","sourceRoot":"","sources":["../../src/shared/http-errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,eAAe,CAAC,GAAwB;IACtD,wDAAwD;IACxD,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;AACxD,CAAC"}

package/dist/shared/logger.contract.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The contract for LOGGING. Nothing here writes anywhere — the one default
+ * implementation is the console sink in `shared/logging.ts`, and a deployment's
+ * shell installs whatever it runs in production (the server shell installs
+ * pino). Modules never import a sink; they ask for a tagged logger and log.
+ *
+ * WHY A PORT. The backend logged through 294 bare `console.*` calls with no
+ * level a filter could act on, no request or workspace a line could be
+ * grouped by, and no shape a machine could parse. When something fails at
+ * three in the morning the log cannot be reduced to one request or one
+ * severity. A library would have fixed that in the published package — and
+ * imposed a logging stack on every npm consumer, the enterprise overlay
+ * included, which very likely logs its own way already; two loggers
+ * interleaved is worse than either. So the package owns the contract and a
+ * dependency-free default, and the shell that actually runs owns the choice.
+ *
+ * WHAT A LINE CARRIES. A message, for a person; fields, for a machine; and
+ * the bindings of the logger it came from — at least `module`, the tag every
+ * call used to spell by hand in square brackets. Bindings and fields are one
+ * flat set on the line: a `child`'s bindings override its parent's under the
+ * same key, and a call's fields override the bindings — except `module`,
+ * which is the tag: the default sink fixes the `[tag]` from the logger's own
+ * bindings when it is made, and a call-time `module` is printed as an
+ * ordinary field beside it. Leave that key to the tag.
+ * An error goes under `err`, by that name: it is the key both the default
+ * sink and pino recognise as an error, and render with its stack. Put an
+ * `Error` there, not a string: the type cannot insist, and a string under
+ * `err` is logged as text — one line, escaped, but with no stack to show.
+ */
+export type LogFields = Record<string, unknown>;
+export interface ILogger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    /** A logger whose every line also carries `bindings`. */
+    child(bindings: LogFields): ILogger;
+}
+/**
+ * `text` as one terminal-safe line. A message often carries text the process
+ * did not write — a branch name from a request, a path from a plugin, git's
+ * stderr — and written raw, a newline in it starts a forged line and an
+ * escape sequence paints the terminal. Every sink applies this, so the rule
+ * "one event, one line" is kept in one place rather than by each call site
+ * remembering `printable`. Shared with the shell's sink through this contract
+ * module because pino's JSON escapes only the C0 range: a C1 control or a
+ * line separator would pass through it to the terminal that tails the log.
+ */
+export declare function oneLine(text: string): string;
+/**
+ * `err` with the text it carries made terminal-safe, its frames untouched.
+ *
+ * An error's message is very often not the process's own words: it quotes a
+ * path, a branch name, git's stderr, a file's contents. Its stack frames ARE
+ * the process's own and read best as the lines they are, so only the
+ * message — and the head of the stack, which repeats it — is escaped. A
+ * `cause` that is itself an error is treated the same way, since the console
+ * prints it too (a chain that loops back on itself is cut where it loops).
+ * The original is never mutated: an error is often rethrown or inspected
+ * after it was logged.
+ */
+export declare function oneLineError(err: Error): Error;
+//# sourceMappingURL=logger.contract.d.ts.map

package/dist/shared/logger.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.contract.d.ts","sourceRoot":"","sources":["../../src/shared/logger.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACjD,yDAAyD;IACzD,KAAK,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;CACrC;AAWD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,GAAG,KAAK,CAE9C"}