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

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

@@ -0,0 +1,206 @@
+/**
+ * The contracts for READING the disk without locks: walking a tree, honouring
+ * `.bevelignore`, and probing a path. Nothing here touches the disk — the one
+ * implementation is `NodeFs` in `modules/kb-fs`, wired once by the
+ * composition root and injected into every module that reads the disk, so no
+ * module carries a `readdir` loop, an `exists()` or an errno check of its own.
+ *
+ * THE directory walk ({@link ITreeWalker.walk}). Every reader of a tree — the
+ * access resolver looking for rules, plugin discovery looking for manifests,
+ * the explorer building its tree, the diff baseline mirroring a checkout, a
+ * template seeding a repository — 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 what differs between readers is SAID
+ * in its {@link TreeWalkOptions}, never re-implemented:
+ *
+ *   - WHAT IS SKIPPED: `skip` — names that are never reported nor entered;
+ *     `ignore` — whether the `.bevelignore` files on the way down are
+ *     honoured; `leaf` — a folder that is reported and then left alone (a
+ *     skill folder, a plugin).
+ *   - IN WHAT ORDER: each folder's entries in `comparePathComponents` order
+ *     (see `shared/path-order.ts`), always, so "first by path" means the same
+ *     thing to every reader.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is either
+ *     reported — as an event and in the result — and walked around, or the
+ *     walk's own error (`unreadable: 'throw'`). Never silently skipped. A
+ *     folder that vanished between listing and visiting is not a hole, and a
+ *     missing root is an empty tree.
+ *   - WHAT AN ENTRY IS: a file or a folder. Anything else (a symlink, a
+ *     socket) is never entered and never a file — it is told to `onOther`,
+ *     so a reader that must say so (or delete it) can.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business.
+ */
+/** The ignore file's own name — every reader that names it agrees on the spelling. */
+export declare const IGNORE_FILENAME = ".bevelignore";
+/**
+ * The knowledge-base walk's skip list: dot-entries (`.git`, a parked delete)
+ * and vendored dependencies are never seen — by {@link ITreeWalker.walkKb},
+ * and by any reader listing one folder of a checkout on its own.
+ */
+export declare function isSkippedEntry(name: string): boolean;
+/**
+ * THE definition of absence: whether a filesystem error means "there is no
+ * such path". ENOENT is nothing at the name; ENOTDIR is nothing that could be
+ * there, because a parent segment is a file (`notes.md/deeper`). Those two are
+ * the one failure a reader may treat as an ordinary answer.
+ *
+ * Everything else (permissions, I/O, a loop) is a failure to READ what is
+ * there, and a caller that folds it into absence turns an outage into a wrong
+ * answer: an unreadable `access.md` read as "no rules" grants what it would
+ * have denied, and an unreadable file read as "not there" lets a write
+ * destroy bytes nothing ever saw.
+ *
+ * A PURE predicate over a value, like {@link isSkippedEntry} — it touches no
+ * disk, so it is a function every reader imports rather than a method on
+ * {@link IFsProbe}. The probes below all apply it; a reader catching its own
+ * error calls it directly.
+ */
+export declare function isAbsence(err: unknown): boolean;
+/** What a probe says of an entry: what it is, and nothing about the disk that said so. */
+export interface EntryStat {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+/** A directory entry as the walk presents it: a name and what it is. */
+export interface WalkedEntry extends EntryStat {
+    name: string;
+}
+/**
+ * A stack of `.bevelignore` rule sets, layered like git: each file applies
+ * beneath the folder it lives in, deeper files extend — and can override,
+ * `!pattern` included — shallower ones. Immutable: extending returns a new
+ * stack.
+ */
+export interface IgnoreRules {
+    /**
+     * The rules in force inside `dir`: these plus `dir`'s own file. No file is
+     * no change. A file that is there but cannot be read is NOT — the rules
+     * are unknown — and that error is the caller's (the walk makes it a hole).
+     */
+    extendedWith(dir: string): Promise<IgnoreRules>;
+    /** Whether the entry at `absolutePath` is hidden. `isDirectory` lets `foo/`-style rules match folders only. */
+    isIgnored(absolutePath: string, isDirectory: boolean): boolean;
+}
+/** A folder the walk is in. */
+export interface WalkedDir {
+    /** Repo-relative, `''` for the root. */
+    rel: string;
+    abs: string;
+    /** Everything the folder holds — files and folders, skipped names removed, in walk order — BEFORE its ignore rules. */
+    listed: readonly WalkedEntry[];
+    /** The `.bevelignore` rules in force inside this folder; empty when the walk does not honour them. */
+    ignore: IgnoreRules;
+}
+export interface TreeWalkOptions {
+    /** Entries left out of every listing — never reported, never entered. Default: nothing. */
+    skip?: (entry: WalkedEntry) => boolean;
+    /**
+     * Honour the `.bevelignore` files on the way down: each folder's rules
+     * extend its parent's, and an entry a rule names is neither reported nor
+     * entered (a listener can still see it in `WalkedDir.listed`). `true`
+     * starts with no rules above the root; a stack starts with the rules in
+     * force there. OFF by default — the explorer honours the files, the access
+     * resolver must not — so every reader says which it is.
+     */
+    ignore?: boolean | IgnoreRules;
+    /** A folder whose listing satisfies this is reported, then left alone: nothing beneath it is visited. */
+    leaf?: (dir: WalkedDir, entries: readonly WalkedEntry[]) => boolean;
+    /** Checked before every listing and every entry: once true, the walk ends. For a reader that stops at its first find. */
+    until?: () => boolean;
+    /**
+     * What a folder that exists but cannot be listed is: a `'hole'` (default —
+     * told to `onHole`, named in the result, walked around) or the walk's error.
+     */
+    unreadable?: 'hole' | 'throw';
+}
+export interface WalkListener {
+    /** A folder was listed. `rel` is repo-relative (`''` for the root); `entries` are its children, skipped and ignored ones removed, in walk order. */
+    onDir?(rel: string, entries: readonly WalkedEntry[], dir: WalkedDir): 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>;
+    /** An entry that is neither a file nor a folder (a symlink, a socket) — never entered, never a file. */
+    onOther?(dir: string, entry: WalkedEntry): void | Promise<void>;
+    /** A folder that exists but could not be listed. */
+    onHole?(rel: string, err: unknown): void | Promise<void>;
+}
+export interface WalkResult {
+    /** Every folder that could not be listed, repo-relative (`''` for the root). */
+    holes: string[];
+}
+/** A strict listing's refusal: the directory (relative to the root, `''` for the root itself) it could not list. */
+export declare class WalkError extends Error {
+    readonly relDir: string;
+    readonly cause: unknown;
+    constructor(relDir: string, cause: unknown);
+}
+export interface ITreeWalker {
+    /**
+     * Walk the tree at `root`, driving every listener from one traversal.
+     * A missing root is an empty tree. Listener errors propagate untouched.
+     */
+    walk(root: string, options: TreeWalkOptions, listeners: readonly WalkListener[]): Promise<WalkResult>;
+    /**
+     * The walk of a knowledge-base checkout: {@link walk} with the checkout's
+     * skip list — dot-entries (`.git`, a parked delete) and vendored
+     * dependencies are never seen. Nothing else is pruned by default; a reader
+     * that honours `.bevelignore`, has a leaf of its own, or must stop at a
+     * hole says so in `options`.
+     */
+    walkKb(root: string, listeners: readonly WalkListener[], options?: Omit<TreeWalkOptions, 'skip'>): Promise<WalkResult>;
+    /**
+     * The file listing catalog scanners want, on top of {@link walkKb}:
+     * relative (`/`-separated) paths of files under `root` whose basename
+     * matches, in walk order. A missing root yields `[]`; skipped entries are
+     * never entered. A directory that cannot be listed is SKIPPED by default —
+     * right for a catalog, which shows what it can. A caller that must see
+     * EVERYTHING or nothing passes `strict`, and the listing throws a
+     * {@link WalkError} naming the directory instead.
+     */
+    walkFiles(root: string, match: (basename: string) => boolean, opts?: {
+        strict?: boolean;
+    }): Promise<string[]>;
+}
+/**
+ * Probing a single path. Every `OrNull`/`exists` below answers null/false for
+ * {@link isAbsence} and lets every other error out, so no reader has to
+ * decide what a failed probe meant.
+ */
+export interface IFsProbe {
+    /** Whether SOMETHING is at `p` — a link included, followed or not. */
+    exists(p: string): Promise<boolean>;
+    /** What is at `p`, links followed; null when nothing is there. */
+    statOrNull(p: string): Promise<EntryStat | null>;
+    /** What is at `p` itself, a link as a link; null when nothing is there. */
+    lstatOrNull(p: string): Promise<EntryStat | null>;
+    /** Whether the entry at `p` is itself a directory (a link to one is not). */
+    isDirectory(p: string): Promise<boolean>;
+    /**
+     * ONE folder's own entries — files, folders and the rest — in walk order,
+     * nothing skipped; null when there is no such folder. Any other failure to
+     * list it is the error: a listing with a hole is not a listing.
+     */
+    listDir(p: string): Promise<WalkedEntry[] | null>;
+    /** The JSON object in the file at `p`; null when the file is absent, not JSON, or not an object. */
+    readJsonObject(p: string): Promise<Record<string, unknown> | null>;
+    /**
+     * The file at `p` as UTF-8 text. THROWS as the filesystem does — absence
+     * included — because a caller that can stand in for a missing file must say
+     * so itself (`isAbsence`), and one that cannot should fail. The sibling
+     * above answers `null` instead because "not JSON" and "not there" are the
+     * same non-answer to it; there is no such collapse for raw text.
+     */
+    readTextFile(p: string): Promise<string>;
+    /**
+     * Bytes still writable on the volume holding `p`, as an unprivileged process
+     * sees them; null when the volume cannot say. The one question the readiness
+     * answer asks of the disk: a volume that fills turns every git write into a
+     * failure, and the queue behind those writes stops moving.
+     */
+    freeBytes(p: string): Promise<number | null>;
+}
+//# sourceMappingURL=fs.contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fs.contract.d.ts","sourceRoot":"","sources":["../../src/shared/fs.contract.ts"],"names":[],"mappings":"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"}

package/dist/shared/fs.contract.js

@@ -0,0 +1,79 @@
+/**
+ * The contracts for READING the disk without locks: walking a tree, honouring
+ * `.bevelignore`, and probing a path. Nothing here touches the disk — the one
+ * implementation is `NodeFs` in `modules/kb-fs`, wired once by the
+ * composition root and injected into every module that reads the disk, so no
+ * module carries a `readdir` loop, an `exists()` or an errno check of its own.
+ *
+ * THE directory walk ({@link ITreeWalker.walk}). Every reader of a tree — the
+ * access resolver looking for rules, plugin discovery looking for manifests,
+ * the explorer building its tree, the diff baseline mirroring a checkout, a
+ * template seeding a repository — 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 what differs between readers is SAID
+ * in its {@link TreeWalkOptions}, never re-implemented:
+ *
+ *   - WHAT IS SKIPPED: `skip` — names that are never reported nor entered;
+ *     `ignore` — whether the `.bevelignore` files on the way down are
+ *     honoured; `leaf` — a folder that is reported and then left alone (a
+ *     skill folder, a plugin).
+ *   - IN WHAT ORDER: each folder's entries in `comparePathComponents` order
+ *     (see `shared/path-order.ts`), always, so "first by path" means the same
+ *     thing to every reader.
+ *   - WHAT A HOLE IS: a folder that exists but could not be listed is either
+ *     reported — as an event and in the result — and walked around, or the
+ *     walk's own error (`unreadable: 'throw'`). Never silently skipped. A
+ *     folder that vanished between listing and visiting is not a hole, and a
+ *     missing root is an empty tree.
+ *   - WHAT AN ENTRY IS: a file or a folder. Anything else (a symlink, a
+ *     socket) is never entered and never a file — it is told to `onOther`,
+ *     so a reader that must say so (or delete it) can.
+ *
+ * Listeners see the same events in the same order; what each makes of them
+ * is its own business.
+ */
+/** The ignore file's own name — every reader that names it agrees on the spelling. */
+export const IGNORE_FILENAME = '.bevelignore';
+/**
+ * The knowledge-base walk's skip list: dot-entries (`.git`, a parked delete)
+ * and vendored dependencies are never seen — by {@link ITreeWalker.walkKb},
+ * and by any reader listing one folder of a checkout on its own.
+ */
+export function isSkippedEntry(name) {
+    return name.startsWith('.') || name === 'node_modules';
+}
+/**
+ * THE definition of absence: whether a filesystem error means "there is no
+ * such path". ENOENT is nothing at the name; ENOTDIR is nothing that could be
+ * there, because a parent segment is a file (`notes.md/deeper`). Those two are
+ * the one failure a reader may treat as an ordinary answer.
+ *
+ * Everything else (permissions, I/O, a loop) is a failure to READ what is
+ * there, and a caller that folds it into absence turns an outage into a wrong
+ * answer: an unreadable `access.md` read as "no rules" grants what it would
+ * have denied, and an unreadable file read as "not there" lets a write
+ * destroy bytes nothing ever saw.
+ *
+ * A PURE predicate over a value, like {@link isSkippedEntry} — it touches no
+ * disk, so it is a function every reader imports rather than a method on
+ * {@link IFsProbe}. The probes below all apply it; a reader catching its own
+ * error calls it directly.
+ */
+export function isAbsence(err) {
+    const code = err?.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+/** A strict listing's refusal: the directory (relative to the root, `''` for the root itself) it could not list. */
+export class WalkError extends Error {
+    relDir;
+    cause;
+    constructor(relDir, cause) {
+        super(`${relDir || '.'} could not be listed — ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.relDir = relDir;
+        this.cause = cause;
+        this.name = 'WalkError';
+    }
+}
+//# sourceMappingURL=fs.contract.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fs.contract.js","sourceRoot":"","sources":["../../src/shared/fs.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC;AAE9C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,cAAc,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,GAAY;IACpC,MAAM,IAAI,GAAI,GAAiC,EAAE,IAAI,CAAC;IACtD,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC;AACjD,CAAC;AAiFD,oHAAoH;AACpH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEvB;IACA;IAFX,YACW,MAAc,EACd,KAAc;QAEvB,KAAK,CAAC,GAAG,MAAM,IAAI,GAAG,0BAA0B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAHjG,WAAM,GAAN,MAAM,CAAQ;QACd,UAAK,GAAL,KAAK,CAAS;QAGvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/shared/git-failure.d.ts

@@ -0,0 +1,80 @@
+/**
+ * What went wrong between this deployment and its git host, in the terms an
+ * admin can act on.
+ *
+ * ONE classifier for every place that talks to the KB remote on the admin's
+ * behalf: the connection check (Test connection, and the save that proves the
+ * connection first) and the setup-time KB startup phase. Two tables of git
+ * wordings drift — a host that changes its phrasing gets learned in one and
+ * misread in the other — so there is exactly one, here.
+ *
+ * The raw text is an INPUT, never an output: a `cause` is a fixed sentence per
+ * kind (the one exception is a startup step's own name, which is code, not
+ * git output). What git actually said belongs in the server log.
+ */
+export type GitFailureKind = 'credentials-rejected' | 'not-found' | 'unreachable' | 'write-refused' | 'push-refused-by-policy' | 'step-failed' | 'unknown';
+export interface GitFailure {
+    kind: GitFailureKind;
+    /** One sentence: what to do about it. */
+    cause: string;
+}
+/** What a failure's text is the answer to, when the caller knows. */
+export interface GitFailureContext {
+    /**
+     * `write`: the text answers a push. The startup phase's own pushes say so in
+     * their `git push failed:` prefix; the connection check's dry-run push says
+     * so here. Either way the repository was just READ with these credentials,
+     * so a bare 403 or 404, or a generic "denied" / "forbidden", is the host
+     * refusing the write — not a missing repository, not a bad login.
+     */
+    operation?: 'read' | 'write';
+}
+/**
+ * Classify a failure from its text. Raw text is safe here — none of it reaches
+ * the result — and is the better input where a caller holds it: a scrub
+ * replacing a token that happens to spell part of git's wording would change
+ * the reading.
+ *
+ * Order is load-bearing:
+ *  1. Refusals that NAME a policy, then a permission, come first — GitHub
+ *     answers a read-only token's push with a 403 that would otherwise read as
+ *     "bad credentials", and GitLab's protected-branch refusal also says "not
+ *     allowed to push".
+ *  2. Authentication failures come before the generic refusals of a write: a
+ *     public repository reads anonymously, so a push is where a made-up token
+ *     is first presented, and "the host rejected the token" is not "grant it a
+ *     permission". GitLab's auth failure says "Access denied", which a write's
+ *     generic "denied" would otherwise claim.
+ *  3. Then a write's generic refusals, a missing repository, and an
+ *     unreachable host — "unable to access" last, because a refusal arrives
+ *     wrapped in it.
+ */
+export declare function classifyGitFailure(text: string, context?: GitFailureContext): GitFailure;
+/**
+ * A failure whose message is already scrubbed for the log, carrying the
+ * classification read from the text BEFORE the scrub.
+ *
+ * Scrubbing and classifying both want the raw text, and they cannot share it
+ * in order: a scrub is free to rewrite the very words the classifier reads (a
+ * token that spells `connect` turns "Failed to connect" into something else),
+ * while carrying the raw text on to wherever classification happens would put
+ * the secret into every error that travels. So the place that holds the raw
+ * text does both, once, and only the scrubbed message and the fixed-sentence
+ * classification leave it.
+ */
+export declare class ClassifiedFailure extends Error {
+    readonly failure: GitFailure;
+    /**
+     * `cause` carries the failure this one classifies when a caller still needs
+     * its shape — a `GitRunError` whose fields say whether git ran at all. It is
+     * a redacted error by then, never the raw text.
+     */
+    constructor(message: string, failure: GitFailure, opts?: {
+        cause?: unknown;
+    });
+}
+/** A failure of a known kind, with its fixed sentence — for a caller that knows the kind without reading text. */
+export declare function gitFailure(kind: Exclude<GitFailureKind, 'step-failed'>): GitFailure;
+/** The classification a failure carries, else one read from its message. */
+export declare function failureOf(err: unknown): GitFailure;
+//# sourceMappingURL=git-failure.d.ts.map

package/dist/shared/git-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-failure.d.ts","sourceRoot":"","sources":["../../src/shared/git-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,cAAc,GACtB,sBAAsB,GACtB,WAAW,GACX,aAAa,GACb,eAAe,GACf,wBAAwB,GACxB,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;CACf;AAiCD,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,UAAU,CA2D5F;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAQxC,QAAQ,CAAC,OAAO,EAAE,UAAU;IAP9B;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACN,OAAO,EAAE,UAAU,EAC5B,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAK7B;AAED,kHAAkH;AAClH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,cAAc,EAAE,aAAa,CAAC,GAAG,UAAU,CAEnF;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAGlD"}

package/dist/shared/git-failure.js

@@ -0,0 +1,139 @@
+/**
+ * What went wrong between this deployment and its git host, in the terms an
+ * admin can act on.
+ *
+ * ONE classifier for every place that talks to the KB remote on the admin's
+ * behalf: the connection check (Test connection, and the save that proves the
+ * connection first) and the setup-time KB startup phase. Two tables of git
+ * wordings drift — a host that changes its phrasing gets learned in one and
+ * misread in the other — so there is exactly one, here.
+ *
+ * The raw text is an INPUT, never an output: a `cause` is a fixed sentence per
+ * kind (the one exception is a startup step's own name, which is code, not
+ * git output). What git actually said belongs in the server log.
+ */
+const CAUSES = {
+    'credentials-rejected': 'The host rejected the credentials — check the access token, and that the token username matches the host (GitHub x-access-token, GitLab oauth2, Bitbucket x-token-auth).',
+    'not-found': 'There is no repository at that address, or the token cannot see it — check the repository address and that the token has access to that repository.',
+    unreachable: "This server could not reach the git host — check the repository address and this server's network access to that host, then retry.",
+    'write-refused': 'The token can read the repository but not write to it — grant it write (push) access to the repository, then retry.',
+    'push-refused-by-policy': "A branch protection rule or hook on the repository refused the initialization push — allow the deployment's account to push to the protected branches, then retry.",
+    unknown: 'The knowledge base could not be initialized for a reason not listed here — the server log has the full error.',
+};
+function stepFailed(step) {
+    return {
+        kind: 'step-failed',
+        cause: `The startup step "${step}" failed — the server log has its error; fix what it names, then retry.`,
+    };
+}
+/**
+ * How the startup runner prefixes a failure it attributes to a step
+ * (`kb-startup-runner.ts`): a throw, or a declared `stopBoot`.
+ */
+const STEP_PREFIX = /KB startup step "([^"]+)" (?:failed|stopped the boot): ([\s\S]*)/;
+/** How `kb-git.ts` prefixes a failed git invocation: `git <subcommand> failed: …`. */
+const GIT_PREFIX = /^git \S+ failed:/;
+/**
+ * Classify a failure from its text. Raw text is safe here — none of it reaches
+ * the result — and is the better input where a caller holds it: a scrub
+ * replacing a token that happens to spell part of git's wording would change
+ * the reading.
+ *
+ * Order is load-bearing:
+ *  1. Refusals that NAME a policy, then a permission, come first — GitHub
+ *     answers a read-only token's push with a 403 that would otherwise read as
+ *     "bad credentials", and GitLab's protected-branch refusal also says "not
+ *     allowed to push".
+ *  2. Authentication failures come before the generic refusals of a write: a
+ *     public repository reads anonymously, so a push is where a made-up token
+ *     is first presented, and "the host rejected the token" is not "grant it a
+ *     permission". GitLab's auth failure says "Access denied", which a write's
+ *     generic "denied" would otherwise claim.
+ *  3. Then a write's generic refusals, a missing repository, and an
+ *     unreachable host — "unable to access" last, because a refusal arrives
+ *     wrapped in it.
+ */
+export function classifyGitFailure(text, context = {}) {
+    let body = text;
+    const step = STEP_PREFIX.exec(text);
+    if (step) {
+        // A step that failed IN GIT is classified by what git said — that cause is
+        // the more actionable one. A step that failed on its own terms is named;
+        // its message is prose we cannot promise to read correctly.
+        if (!GIT_PREFIX.test(step[2].trimStart()))
+            return stepFailed(step[1]);
+        body = step[2];
+    }
+    // A status number proves nothing from inside a URL — `/acme/404-notes.git`
+    // or a port carries the digits with no refusal having happened, and a failed
+    // command's message quotes its whole argv — nor from curl's own
+    // `Failed to connect to <host> port 403`. Words still count wherever they
+    // appear; digits only outside URLs and port numbers.
+    const m = body.replace(/\bhttps?:\/\/\S+/gi, ' ').replace(/\bport \d+/gi, ' ');
+    const isWrite = context.operation === 'write' || /\bgit push failed\b/i.test(m);
+    if (/pre-receive hook declined|hook declined|protected branch|GH006|GH013|\[remote rejected\]/i.test(m)) {
+        return known('push-refused-by-policy');
+    }
+    // Each host's own words for "this token may not push": GitHub classic and
+    // fine-grained, GitLab, Bitbucket, Azure DevOps.
+    if (/Permission to \S+ denied|write access to repository not granted|not allowed to push|push access denied|lack one or more required privilege scopes|GenericContribute/i.test(m)) {
+        return known('write-refused');
+    }
+    if (/Authentication failed|could not read Username|could not read Password|Invalid username or (?:token|password)|invalid credentials|HTTP Basic: Access denied|\b401\b/i.test(m) ||
+        // On a read a 403 is the login refused; on a write the host already knows
+        // who this is (see below).
+        (!isWrite && /\b403\b/.test(m))) {
+        return known('credentials-rejected');
+    }
+    // A write refused in no host's particular words: these credentials just
+    // read the repository, so it exists and the login worked.
+    if (isWrite && /\b40[34]\b|\bdenied\b|forbidden|not found/i.test(m)) {
+        return known('write-refused');
+    }
+    if (/not found|repository .* does not exist|\b404\b/i.test(m)) {
+        return known('not-found');
+    }
+    if (/timed out|ETIMEDOUT|could not resolve host|Failed to connect|Connection refused|ECONNREFUSED|Network is unreachable|SSL|\bTLS\b|certificate|unable to access/i.test(m)) {
+        return known('unreachable');
+    }
+    return known('unknown');
+}
+function known(kind) {
+    return { kind, cause: CAUSES[kind] };
+}
+/**
+ * A failure whose message is already scrubbed for the log, carrying the
+ * classification read from the text BEFORE the scrub.
+ *
+ * Scrubbing and classifying both want the raw text, and they cannot share it
+ * in order: a scrub is free to rewrite the very words the classifier reads (a
+ * token that spells `connect` turns "Failed to connect" into something else),
+ * while carrying the raw text on to wherever classification happens would put
+ * the secret into every error that travels. So the place that holds the raw
+ * text does both, once, and only the scrubbed message and the fixed-sentence
+ * classification leave it.
+ */
+export class ClassifiedFailure extends Error {
+    failure;
+    /**
+     * `cause` carries the failure this one classifies when a caller still needs
+     * its shape — a `GitRunError` whose fields say whether git ran at all. It is
+     * a redacted error by then, never the raw text.
+     */
+    constructor(message, failure, opts) {
+        super(message, opts);
+        this.failure = failure;
+        this.name = 'ClassifiedFailure';
+    }
+}
+/** A failure of a known kind, with its fixed sentence — for a caller that knows the kind without reading text. */
+export function gitFailure(kind) {
+    return known(kind);
+}
+/** The classification a failure carries, else one read from its message. */
+export function failureOf(err) {
+    if (err instanceof ClassifiedFailure)
+        return err.failure;
+    return classifyGitFailure(err instanceof Error ? err.message : String(err));
+}
+//# sourceMappingURL=git-failure.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git-failure.js","sourceRoot":"","sources":["../../src/shared/git-failure.ts"],"names":[],"mappings":"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"}

package/dist/shared/git-internals.d.ts

@@ -0,0 +1,23 @@
+/** True when any segment of `inputPath`, in any spelling, is the git folder. */
+export declare function hasGitInternalsSegment(inputPath: unknown): boolean;
+/** Refuse `inputPath` lexically. See {@link hasGitInternalsSegment}. */
+export declare function assertNoGitInternalsSegment(inputPath: unknown): void;
+/**
+ * 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 declare function assertNotGitInternals(rootDir: string, inputPath: string, absolutePath?: string): Promise<void>;
+//# sourceMappingURL=git-internals.d.ts.map

package/dist/shared/git-internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-internals.d.ts","sourceRoot":"","sources":["../../src/shared/git-internals.ts"],"names":[],"mappings":"AA+CA,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAKlE;AAED,wEAAwE;AACxE,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAEpE;AA+CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BpH"}