@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/dist/shared/git-internals.js

@@ -0,0 +1,123 @@
+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); `absolutePath` is where it lands on disk. 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 target = absolutePath ?? path.resolve(rootDir, inputPath.replace(/^[\\/]+/, ''));
+    if (hasGitInternalsSegment(path.relative(path.resolve(rootDir), target)))
+        throw new GitInternalsError();
+    const [realTarget, realRoot] = await Promise.all([resolvedRealPath(target), resolvedRealPath(path.resolve(rootDir))]);
+    if (realTarget === null || realRoot === null)
+        return;
+    if (hasGitInternalsSegment(path.relative(realRoot, realTarget)))
+        throw new GitInternalsError();
+}
+//# 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":"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"}

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/kb-walk.d.ts

@@ -0,0 +1,52 @@
+/**
+ * THE walk of a knowledge-base checkout.
+ *
+ * Every reader of the tree — the access resolver looking for rules, plugin
+ * discovery looking for manifests, a rename looking for grants, the catalog
+ * scanners — used to carry a recursive `readdir` loop of its own, each with
+ * its own skip list, its own idea of what an unreadable folder means and its
+ * own visiting order. Two loops that disagree on one of those are two
+ * answers to "what is in the tree", and every such disagreement was a bug.
+ *
+ * So there is one loop, and it decides three things once:
+ *
+ *   - WHAT IS SKIPPED: {@link isSkippedEntry} — dot-entries (`.git`, a parked
+ *     delete) and vendored dependencies. Nothing else is pruned; a listener
+ *     that stops at a leaf of its own (a skill folder, a plugin folder)
+ *     simply ignores what lies beneath it.
+ *   - IN WHAT ORDER: each folder's entries in {@link comparePathComponents}
+ *     order, so "first by path" means the same thing to every listener.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is
+ *     reported as an event and in the result — never thrown, never silently
+ *     skipped — so a reader can show what it saw and a writer can refuse.
+ *     A folder that vanished between listing and visiting is not a hole.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business (`.bevelignore` included — the explorer honours it,
+ * the resolver must not, so it is a listener's decision, not the walk's).
+ */
+export declare function isSkippedEntry(name: string): boolean;
+/** A directory entry as the walk presents it: a name and what it is. */
+export interface WalkedEntry {
+    name: string;
+    isDirectory(): boolean;
+    isFile(): boolean;
+}
+export interface KbWalkListener {
+    /** A folder was listed. `rel` is repo-relative (`''` for the root); `entries` are its children, skipped ones removed, in walk order. */
+    onDir?(rel: string, entries: readonly WalkedEntry[]): void | Promise<void>;
+    /** A file was seen. `dir` is its folder (`''` for the root), `name` its basename. */
+    onFile?(dir: string, name: string): void | Promise<void>;
+    /** A folder that exists but could not be listed. */
+    onHole?(rel: string, err: unknown): void | Promise<void>;
+}
+export interface KbWalkResult {
+    /** Every folder that could not be listed, repo-relative (`''` for the root). */
+    holes: string[];
+}
+/**
+ * Walk the checkout at `root`, driving every listener from one traversal.
+ * A missing root is an empty tree. Listener errors propagate untouched.
+ */
+export declare function walkKb(root: string, listeners: readonly KbWalkListener[]): Promise<KbWalkResult>;
+//# sourceMappingURL=kb-walk.d.ts.map

package/dist/shared/kb-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-walk.d.ts","sourceRoot":"","sources":["../../src/shared/kb-walk.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,IAAI,OAAO,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,wIAAwI;IACxI,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,qFAAqF;IACrF,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,oDAAoD;IACpD,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,cAAc,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAiCtG"}

package/dist/shared/kb-walk.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { isAbsence } from './fs-errors.js';
+import { comparePathComponents } from './path-order.js';
+/**
+ * THE walk of a knowledge-base checkout.
+ *
+ * Every reader of the tree — the access resolver looking for rules, plugin
+ * discovery looking for manifests, a rename looking for grants, the catalog
+ * scanners — used to carry a recursive `readdir` loop of its own, each with
+ * its own skip list, its own idea of what an unreadable folder means and its
+ * own visiting order. Two loops that disagree on one of those are two
+ * answers to "what is in the tree", and every such disagreement was a bug.
+ *
+ * So there is one loop, and it decides three things once:
+ *
+ *   - WHAT IS SKIPPED: {@link isSkippedEntry} — dot-entries (`.git`, a parked
+ *     delete) and vendored dependencies. Nothing else is pruned; a listener
+ *     that stops at a leaf of its own (a skill folder, a plugin folder)
+ *     simply ignores what lies beneath it.
+ *   - IN WHAT ORDER: each folder's entries in {@link comparePathComponents}
+ *     order, so "first by path" means the same thing to every listener.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is
+ *     reported as an event and in the result — never thrown, never silently
+ *     skipped — so a reader can show what it saw and a writer can refuse.
+ *     A folder that vanished between listing and visiting is not a hole.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business (`.bevelignore` included — the explorer honours it,
+ * the resolver must not, so it is a listener's decision, not the walk's).
+ */
+export function isSkippedEntry(name) {
+    return name.startsWith('.') || name === 'node_modules';
+}
+/**
+ * Walk the checkout at `root`, driving every listener from one traversal.
+ * A missing root is an empty tree. Listener errors propagate untouched.
+ */
+export async function walkKb(root, listeners) {
+    const holes = [];
+    const visit = async (abs, rel) => {
+        let listed;
+        try {
+            listed = await fs.readdir(abs, { withFileTypes: true });
+        }
+        catch (err) {
+            if (isAbsence(err)) {
+                // The root: a checkout without this tree, an empty walk. Deeper: a
+                // folder that vanished between listing and visiting — not a hole.
+                return;
+            }
+            holes.push(rel);
+            for (const l of listeners)
+                await l.onHole?.(rel, err);
+            return;
+        }
+        const entries = listed
+            .filter((e) => !isSkippedEntry(e.name) && (e.isDirectory() || e.isFile()))
+            .sort((a, b) => comparePathComponents(a.name, b.name));
+        for (const l of listeners)
+            await l.onDir?.(rel, entries);
+        for (const entry of entries) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await visit(path.join(abs, entry.name), childRel);
+            }
+            else {
+                for (const l of listeners)
+                    await l.onFile?.(rel, entry.name);
+            }
+        }
+    };
+    await visit(root, '');
+    return { holes };
+}
+//# sourceMappingURL=kb-walk.js.map

package/dist/shared/kb-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-walk.js","sourceRoot":"","sources":["../../src/shared/kb-walk.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,cAAc,CAAC;AACzD,CAAC;AAuBD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAY,EAAE,SAAoC;IAC7E,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,KAAK,GAAG,KAAK,EAAE,GAAW,EAAE,GAAW,EAAiB,EAAE;QAC9D,IAAI,MAAkC,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,mEAAmE;gBACnE,kEAAkE;gBAClE,OAAO;YACT,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAChB,KAAK,MAAM,CAAC,IAAI,SAAS;gBAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACtD,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAkB,MAAM;aAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;aACzE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,SAAS;YAAE,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACzD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;YAC3D,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;YACpD,CAAC;iBAAM,CAAC;gBACN,KAAK,MAAM,CAAC,IAAI,SAAS;oBAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtB,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}