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

package/src/shared/git-failure.ts

@@ -0,0 +1,196 @@
+/**
+ * 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;
+}
+
+const CAUSES: Record<Exclude<GitFailureKind, 'step-failed'>, string> = {
+  '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: string): GitFailure {
+  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:/;
+
+/** 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 function classifyGitFailure(text: string, context: GitFailureContext = {}): GitFailure {
+  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: Exclude<GitFailureKind, 'step-failed'>): GitFailure {
+  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 {
+  /**
+   * `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,
+    readonly failure: GitFailure,
+    opts?: { cause?: unknown },
+  ) {
+    super(message, opts);
+    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: Exclude<GitFailureKind, 'step-failed'>): GitFailure {
+  return known(kind);
+}
+
+/** The classification a failure carries, else one read from its message. */
+export function failureOf(err: unknown): GitFailure {
+  if (err instanceof ClassifiedFailure) return err.failure;
+  return classifyGitFailure(err instanceof Error ? err.message : String(err));
+}

package/src/shared/git-internals.ts

@@ -0,0 +1,124 @@
+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: string): string {
+  let current = value;
+  for (;;) {
+    const next = current.replace(/%([0-9a-f]{2})/gi, (_m, hex: string) => 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: string): boolean {
+  return segment.replace(/[. ]+$/, '').toLowerCase() === '.git';
+}
+
+/** True when any segment of `inputPath`, in any spelling, is the git folder. */
+export function hasGitInternalsSegment(inputPath: unknown): boolean {
+  if (typeof inputPath !== 'string') return false;
+  return percentDecoded(inputPath)
+    .split(/[\\/]+/)
+    .some(isGitSegment);
+}
+
+/** Refuse `inputPath` lexically. See {@link hasGitInternalsSegment}. */
+export function assertNoGitInternalsSegment(inputPath: unknown): void {
+  if (hasGitInternalsSegment(inputPath)) throw new GitInternalsError();
+}
+
+const errCode = (err: unknown): unknown => (err as { code?: unknown })?.code;
+
+/** `null` for "nothing resolvable here" (absent, or a link loop); every other filesystem error is rethrown. */
+function nullWhenUnresolvable(err: unknown): null {
+  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: string): Promise<string | null> {
+  let existing = absolutePath;
+  const rest: string[] = [];
+  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: unknown) => (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: string, inputPath: string, absolutePath?: string): Promise<void> {
+  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();
+}

package/src/shared/git.contract.ts

@@ -0,0 +1,170 @@
+/**
+ * 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: string): string {
+  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, '://***@');
+}
+
+/**
+ * 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 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 } = {}) {
+    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: unknown): boolean {
+  return err instanceof GitRunError && err.timedOut;
+}
+
+/**
+ * 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>;
+}

package/src/shared/http-errors.ts

@@ -0,0 +1,36 @@
+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 function domainErrorBody(err: WorkflowDomainError): Record<string, unknown> {
+  // Payload FIRST, `error` LAST: the message always wins.
+  return { ...(err.payload ?? {}), error: err.message };
+}

package/src/shared/logger.contract.ts

@@ -0,0 +1,141 @@
+/**
+ * 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;
+}
+
+/**
+ * C0 and C1 control characters (U+009B among them: the one-byte CSI that
+ * starts an ANSI sequence by itself) and the JS line separators. The rule
+ * against control characters in a regex guards against accidental ones; these
+ * are the point.
+ */
+const CONTROL_CHARS = new RegExp(`[\x00-\x1F\x7F-\x9F${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
+const NAMED: Record<string, string> = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+
+/**
+ * `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 function oneLine(text: string): string {
+  return text.replace(CONTROL_CHARS, (c) => NAMED[c] ?? `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+/**
+ * `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 function oneLineError(err: Error): Error {
+  return escapedCopy(err, new Set());
+}
+
+function escapedCopy(err: Error, seen: Set<Error>): Error {
+  seen.add(err);
+  const message = oneLine(err.message);
+  const copy = Object.create(Object.getPrototypeOf(err) as object) as Error & { cause?: unknown };
+  Object.defineProperty(copy, 'message', { value: message, enumerable: false, writable: true, configurable: true });
+  Object.defineProperty(copy, 'name', { value: err.name, enumerable: false, writable: true, configurable: true });
+  if (typeof err.stack === 'string') {
+    // Node's stack is the error's own `toString()` — `<name>: <message>` —
+    // followed by `\n    at …` frames. The frames are looked for AFTER that
+    // header, not from the top: a message that itself holds a line shaped
+    // like a frame would otherwise move the boundary up and pass the rest of
+    // itself through raw. A stack that does not open with the header is not
+    // one this code knows the shape of, and is escaped whole.
+    // The frames keep their lines; each is still escaped within its line, for
+    // a stack that is not Node's own (a foreign runtime's, a hand-built one)
+    // and carries a control character after a frame-shaped line.
+    const head = Error.prototype.toString.call(err);
+    const frames = err.stack.startsWith(head) ? err.stack.indexOf('\n    at ', head.length) : -1;
+    const stack =
+      frames === -1
+        ? oneLine(err.stack)
+        : `${oneLine(err.stack.slice(0, frames))}\n${err.stack
+            .slice(frames + 1)
+            .split('\n')
+            .map(oneLine)
+            .join('\n')}`;
+    Object.defineProperty(copy, 'stack', { value: stack, enumerable: false, writable: true, configurable: true });
+  }
+  const nested = (value: unknown): unknown =>
+    value instanceof Error
+      ? seen.has(value)
+        ? '[circular]'
+        : escapedCopy(value, seen)
+      : typeof value === 'string'
+        ? oneLine(value)
+        : value;
+  const cause = (err as { cause?: unknown }).cause;
+  if (cause !== undefined) {
+    Object.defineProperty(copy, 'cause', { value: nested(cause), enumerable: false, writable: true, configurable: true });
+  }
+  // An `AggregateError`'s failures — non-enumerable there, and the whole
+  // point of it; kept as enumerable as the source had it, so an ordinary
+  // error that carries an `errors` list of its own still shows it.
+  const errors = (err as { errors?: unknown }).errors;
+  if (Array.isArray(errors)) {
+    Object.defineProperty(copy, 'errors', {
+      value: errors.map(nested),
+      enumerable: Object.prototype.propertyIsEnumerable.call(err, 'errors'),
+      writable: true,
+      configurable: true,
+    });
+  }
+  // Own enumerable fields (a `code`, a `status`) travel with the error.
+  for (const [key, value] of Object.entries(err)) {
+    if (!(key in copy)) (copy as unknown as Record<string, unknown>)[key] = typeof value === 'string' ? oneLine(value) : value;
+  }
+  // `seen` is the path down, not everything met: one failure listed twice
+  // under an AggregateError is copied twice, and only a true loop is cut.
+  seen.delete(err);
+  return copy;
+}