paperlint 2.0.0

package/src/doctor.ts

@@ -0,0 +1,356 @@
+/**
+ * `paperlint doctor` — the command that makes SILENCE VISIBLE.
+ *
+ * 🔴 WHY THIS EXISTS AT ALL, when none of the eight tools surveyed for `docs/install.md` ships a
+ * `doctor`. None of them needs one: a formatter that is misconfigured formats nothing and you see
+ * it immediately. This package has `paper-edit-guard`, whose success state IS silence — it reports
+ * nothing while guarding correctly and reports nothing while guarding a directory that does not
+ * exist. From outside, "installed" and "protecting you" are the same picture.
+ *
+ * Measured 2026-09-18, and this is the failure the command was written for: a consumer who follows
+ * the documented install exactly — `paperlint init`, then point the config at their papers — gets a guard
+ * that allows every Bash write to their paper sources. It only appears to work when the directory
+ * path happens to contain the segment `papers`, because that is the default the hook falls back to.
+ * (Issue #33.)
+ *
+ * 🔴 THE ROOT THE HOOK WOULD USE IS ASKED OF THE HOOK, NOT RE-DERIVED. `papersRoot` is imported
+ * from `paper-edit-guard.hook.mjs` itself. A second implementation here would be a second source of
+ * truth, which is the very defect this command reports — and it would drift silently, because a
+ * copy that disagrees with the original still prints a confident answer.
+ *
+ * Prior art for the shape: `brew doctor`, `flutter doctor`, `npm doctor`, `expo-doctor`.
+ */
+// eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+// eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+import { spawnSync } from "node:child_process";
+// Types come from `paper-edit-guard.hook.d.mts`; see the block above for why the import points at
+// the hook itself rather than at a shared module.
+import {
+  papersRoot,
+  CONFIG_KEY,
+  DEFAULT_PAPERS_ROOT,
+  PAPERS_DIR_FIELD,
+  OLD_PAPERS_DIR_FIELD,
+} from "../hooks/paper-edit-guard.hook.mjs";
+import {
+  LEGACY_CONFIG_KEY,
+  LEGACY_KEY_MESSAGE,
+  declaredSettings,
+} from "../lib/paper-config.mjs";
+import { PAPER_MARKERS } from "./build.ts";
+import { linkSkills, SKILLS_HOME, type LinkReport } from "./link-skills.ts";
+import { doctorHooks } from "./hooks-settings.ts";
+
+export interface Program {
+  readonly bin: string;
+  readonly from: string;
+  readonly without: string;
+  readonly install: string;
+}
+
+/**
+ * The programs the SKILLS shell out to. `paperlint lint` needs none of them — it reads files and reports.
+ * Every one of these fails quietly, which is the only reason the list is worth printing: a missing
+ * checker and a passing checker produce the same silence.
+ */
+/**
+ * TeX Live is installed by paperlint itself, with every package the venue profiles declare. `paperlint build`
+ * uses that tree even when its `pdflatex` is not on PATH, so a ✗ here with the cache installed
+ * only means the skills' own shell calls will not find it.
+ */
+export const TEX_INSTALL =
+  "npx paperlint toolchain   (paperlint build uses its TeX Live without PATH; the skills need its bin on PATH)";
+
+export const PROGRAMS: readonly Program[] = [
+  {
+    bin: "pdflatex",
+    from: "TeX Live",
+    without: "no PDF is produced",
+    install: TEX_INSTALL,
+  },
+  {
+    bin: "bibtex",
+    from: "TeX Live",
+    without: "the bibliography is not resolved",
+    install: TEX_INSTALL,
+  },
+  {
+    bin: "texcount",
+    from: "TeX Live",
+    without: "the length checks cannot run",
+    install: TEX_INSTALL,
+  },
+  {
+    bin: "java",
+    from: "any JRE",
+    without: "TeXtidote does not run, and nothing else spell-checks the text",
+    install: "apt-get install -y default-jre-headless",
+  },
+  {
+    bin: "perl",
+    from: "your system (macOS ships it)",
+    without:
+      "banal cannot run: page size, columns and font sizes are null in the facts file",
+    install:
+      "apt-get install -y perl, then npx paperlint toolchain (it fetches banal)",
+  },
+  {
+    bin: "python3",
+    from: "your system",
+    without: "the analysis and report scripts do not start",
+    install: "apt-get install -y python3",
+  },
+];
+
+export const found = (bin: string, run = spawnSync): boolean =>
+  run("command", ["-v", bin], { shell: true, stdio: "ignore" }).status === 0;
+
+/** Directories that look like papers, used to REPLACE a guessed default with a measurement. */
+export function detectPapers(cwd: string, depth = 2): string[] {
+  const hits: string[] = [];
+  const skip = new Set(["node_modules", ".git", "dist", "_build", ".claude"]);
+  const walk = (dir: string, left: number): void => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith(".") || skip.has(e.name))
+        continue;
+      const here = join(dir, e.name);
+      // A directory whose CHILDREN look like papers is the papers root — not the paper itself.
+      let children;
+      try {
+        children = readdirSync(here, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      // A dot-child is not a paper: `<papers>/.template/` holds the project's paper TEMPLATE,
+      // markers and all, and a folder holding only that is not a papers root yet.
+      const isPapersRoot = children.some(
+        (c) =>
+          c.isDirectory() &&
+          !c.name.startsWith(".") &&
+          PAPER_MARKERS.some((m) => existsSync(join(here, c.name, m))),
+      );
+      if (isPapersRoot) hits.push(relative(cwd, here));
+      else if (left > 0) walk(here, left - 1);
+    }
+  };
+  walk(resolve(cwd), depth);
+  return hits;
+}
+
+/**
+ * The declaration's verdict. The old field name and two differing keys are failures (every reader
+ * refuses them); the old KEY is read and named; a missing declaration is a warning.
+ */
+function declarationVerdict(rawPkg: string): { lines: string[]; bad: number } {
+  const out: string[] = [];
+  const found = (() => {
+    try {
+      return declaredSettings(JSON.parse(rawPkg));
+    } catch {
+      return declaredSettings(undefined);
+    }
+  })();
+  if (found.conflict !== null)
+    return { lines: [`  ✗ ${found.conflict}`], bad: 1 };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
+  const settings = found.settings as Record<string, any> | undefined;
+  const key = found.legacy ? LEGACY_CONFIG_KEY : CONFIG_KEY;
+  const declared = settings?.[PAPERS_DIR_FIELD];
+  if (found.legacy) out.push(`  ⚠ ${LEGACY_KEY_MESSAGE}`);
+  // The old field name is a failure, not a warning: every reader refuses it.
+  if (settings && Object.hasOwn(settings, OLD_PAPERS_DIR_FIELD))
+    return {
+      lines: [
+        ...out,
+        `  ✗ "${OLD_PAPERS_DIR_FIELD}" was renamed to "${PAPERS_DIR_FIELD}" in package.json → "${key}"`,
+      ],
+      bad: 1,
+    };
+  // 🔴 A MISSING DECLARATION IS A WARNING, NOT A REFUSAL, and that is a decision, not an
+  // oversight. Without it the hook takes the `papers` default; if the papers do live there, the
+  // install WORKS — just by coincidence, and it will break silently on the day the directory
+  // moves. Failing on a working install is not allowed here: for an `error`-level check a false
+  // positive costs more than a miss, because people do not fix it, they switch it off — together
+  // with the binary findings below, which the command was written for. A real breakage (the roots
+  // drifted apart, the directory does not exist) is caught where it is binary.
+  if (declared === undefined)
+    out.push(
+      `  ⚠ package.json has no "${CONFIG_KEY}": { "${PAPERS_DIR_FIELD}": … } — the hooks fall back to "${DEFAULT_PAPERS_ROOT}"`,
+      `      it works only while your papers happen to live there; declare it and it keeps working`,
+    );
+  else
+    out.push(
+      `  ✓ package.json → ${key}.${PAPERS_DIR_FIELD} = ${JSON.stringify(declared)}`,
+    );
+  return { lines: out, bad: 0 };
+}
+
+/**
+ * The papers-directory verdict: whether the CLI and the hooks agree, and whether the directory
+ * they name exists. `bad` counts the failures.
+ */
+function papersVerdict(
+  root: string,
+  cliPapers: string | null,
+  hookSays: string | null,
+): { lines: string[]; bad: number } {
+  const out: string[] = [];
+  let bad = 0;
+  if (cliPapers && hookSays) {
+    const same = resolve(root, cliPapers) === resolve(root, hookSays);
+    out.push(
+      same
+        ? `  ✓ the same directory — what is linted is what is guarded`
+        : `  ✗ DIFFERENT directories. Every Bash write to ${cliPapers} passes the guard unseen.`,
+    );
+    if (!same) bad++;
+  }
+  // A declared directory that does not exist is a failure only when papers live SOMEWHERE ELSE:
+  // then every write to them passes the guard unseen (issue #33). With no papers anywhere, the
+  // project is simply new — `init --yes` declares the default and creates no paper — and failing
+  // it would teach people to ignore doctor.
+  if (hookSays && !existsSync(join(root, hookSays))) {
+    const guesses = detectPapers(root);
+    if (guesses.length) {
+      out.push(
+        `  ✗ ${hookSays} does not exist — the guard is watching nothing`,
+      );
+      out.push(`      papers look like they live in: ${guesses.join(", ")}`);
+      bad++;
+    } else
+      out.push(
+        `  ⚠ ${hookSays} does not exist yet — no papers yet. \`npx paperlint new <name>\` creates the first one there`,
+      );
+  }
+  return { lines: out, bad };
+}
+
+export interface DoctorOptions {
+  log?: typeof console.log;
+  cwd?: string;
+  /** The project root the hooks are anchored to. Claude Code sets this; it defaults to `cwd`. */
+  projectDir?: string;
+  run?: typeof spawnSync;
+  /** The directory the CLI resolved from its own config, so both sides can be compared. */
+  cliPapers?: string | null;
+  /** Reads the skill links without writing any. Injected only so a test can fake the install. */
+  skillLinks?: (root: string) => LinkReport;
+}
+
+/**
+ * @returns 2 when the guard and the linter do not agree, or the declaration is unusable — those
+ * are binary and are the reason this command exists. A missing external program is a FACT, not a
+ * verdict: it is printed and does not fail the run, because which programs you need depends on
+ * which skills you use. A doctor that exits non-zero on an advisory line gets piped to /dev/null.
+ */
+export function doctor({
+  log = console.log,
+  // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
+  cwd = process.cwd(),
+  projectDir,
+  run = spawnSync,
+  cliPapers = null,
+  skillLinks = (r: string) => linkSkills(r, { write: false }),
+}: DoctorOptions = {}): number {
+  const root = projectDir ?? cwd;
+  const pkgPath = join(root, "package.json");
+  const out: string[] = [
+    "",
+    "paperlint doctor — what is wired, and what only looks wired",
+    "",
+  ];
+  let bad = 0;
+
+  out.push("declaration");
+  const rawPkg = existsSync(pkgPath) ? readFileSync(pkgPath, "utf8") : "";
+  if (!rawPkg) {
+    out.push(`  ✗ no package.json at ${root}`);
+    out.push(
+      `      the hooks read their papers directory from there and refuse without it`,
+    );
+    bad++;
+  } else {
+    const declaration = declarationVerdict(rawPkg);
+    out.push(...declaration.lines);
+    bad += declaration.bad;
+  }
+  if (existsSync(join(root, "rpp.json")))
+    out.push(`  ⚠ rpp.json is present — deprecated; the hooks never read it`);
+
+  out.push("", "papers directory");
+  const hookRoot = rawPkg ? papersRoot(rawPkg) : null;
+  const hookSays = typeof hookRoot === "string" ? hookRoot : null;
+  out.push(
+    `  the CLI will lint    ${cliPapers ?? "(nothing — no declaration found)"}`,
+  );
+  out.push(
+    `  the hooks will guard ${hookSays ?? "(nothing — the guard refuses and says why on first use)"}`,
+  );
+  const verdict = papersVerdict(root, cliPapers, hookSays);
+  out.push(...verdict.lines);
+  bad += verdict.bad;
+
+  // A skill that is not linked is ADVISORY, like a missing program: `paperlint lint`, the hooks and CI
+  // work without it, and an entry of the same name that `init` refused to replace is the
+  // consumer's own decision. What this section removes is the silence — before it, a consumer
+  // without links had no `/paper-pipeline` and nothing anywhere said so.
+  out.push(
+    "",
+    `skills (Claude Code finds project skills only in ${SKILLS_HOME}/)`,
+  );
+  const links = skillLinks(root);
+  if (!links.ok) out.push(`  ⚠ not checked — ${links.error}`);
+  else {
+    const gaps = links.links.filter((l) => l.status !== "present");
+    const total = String(links.links.length);
+    if (gaps.length === 0)
+      out.push(
+        `  ✓ all ${total} shipped skills are reachable as ${join(SKILLS_HOME, "<name>")}`,
+      );
+    else {
+      out.push(
+        `  ⚠ ${String(gaps.length)} of ${total} shipped skills are NOT reachable as ${join(SKILLS_HOME, "<name>")}:`,
+      );
+      for (const g of gaps)
+        out.push(
+          `      ${g.name} — ${g.status === "missing" ? "not linked" : `${g.reason ?? "occupied"}, not the shipped skill`}`,
+        );
+      out.push(
+        `      \`npx paperlint init\` links the missing ones; it never replaces an entry it did not make`,
+      );
+    }
+  }
+
+  out.push(
+    "",
+    "external programs (the skills shell out to these; `paperlint lint` needs none of them)",
+  );
+  for (const p of PROGRAMS) {
+    if (found(p.bin, run)) out.push(`  ✓ ${p.bin.padEnd(10)} ${p.from}`);
+    else {
+      out.push(`  ✗ ${p.bin.padEnd(10)} ${p.from} — ${p.without}`);
+      out.push(`      ${p.install}`);
+    }
+  }
+
+  // 🔴 THE HOOKS ARE READ FROM THE FILE THAT CARRIES THEM. Until `init` wrote them into
+  // `.claude/settings.json`, the only carrier was a plugin and this section said "cannot be
+  // checked from a terminal". Advisory, like the skills: `--no-hooks` is a choice, not a fault.
+  out.push("");
+  try {
+    out.push(...doctorHooks(root));
+  } catch (e) {
+    out.push(`hooks`, `  ⚠ not checked — ${(e as Error).message}`);
+  }
+  out.push("");
+  log(out.join("\n"));
+  return bad > 0 ? 2 : 0;
+}

package/src/domain/geometry.ts

@@ -0,0 +1,108 @@
+/**
+ * A paper's page geometry, as the domain sees it — measured by some measurer, or not measured and
+ * why — with no tool named. The facts file's flat schema-2 fields are DERIVED from it
+ * (`flatGeometry`), so `geometry_source` and the nine columns always come from the same branch.
+ */
+import type { Lines } from "./text.ts";
+
+/** What a page-geometry measurer found, in the domain's field names. */
+export interface PageGeometry {
+  readonly pageWidthIn: number | null;
+  readonly pageHeightIn: number | null;
+  readonly columns: number | null;
+  readonly bodyPt: number | null;
+  readonly refPt: number | null;
+  readonly bodyPages: number;
+  readonly refPages: number;
+  readonly appendixPages: number;
+  readonly pagesByType: Readonly<Record<string, number>>;
+}
+
+/**
+ * Who measured: `tool` is what the facts file writes as `geometry_source`, `path` the program that
+ * ran, `how` which rule found it, in the adapter's words. Only a measurer's adapter builds one.
+ */
+export interface Provenance {
+  readonly tool: string;
+  readonly path: string;
+  readonly how: string;
+}
+
+export type Geometry =
+  | {
+      readonly kind: "measured";
+      readonly by: Provenance;
+      readonly geometry: PageGeometry;
+    }
+  | {
+      readonly kind: "unmeasured";
+      readonly why: Lines;
+      /** The measurer that was run and failed; null when none was found. */
+      readonly tried: Provenance | null;
+    };
+
+/** Why there is no geometry, in one line — naming the measurer that failed, when one ran. */
+export function whyNoGeometry(
+  g: Extract<Geometry, { kind: "unmeasured" }>,
+): string {
+  const line = g.why.join("; ");
+  return g.tried
+    ? `${line} (${g.tried.tool} from ${g.tried.how}: ${g.tried.path})`
+    : line;
+}
+
+/** The geometry columns as the facts file spells them. */
+export interface FlatGeometry {
+  readonly page_w_in: number | null;
+  readonly page_h_in: number | null;
+  readonly columns: number | null;
+  readonly body_pt: number | null;
+  readonly ref_pt: number | null;
+  readonly body_pages: number;
+  readonly ref_pages: number;
+  readonly appendix_pages: number;
+  readonly pages_by_type: Readonly<Record<string, number>>;
+}
+
+/** The geometry columns with nothing measured: every one null. */
+export type NullGeometry = { readonly [K in keyof FlatGeometry]: null };
+
+/**
+ * The flat schema-2 fields. `geometry_source` is tied to its branch: a measurer's name only beside
+ * measured columns, null only beside nine nulls — the file cannot name a measurer over an empty
+ * measurement.
+ */
+export type FactsGeometryFields =
+  | ({ readonly geometry_source: string } & FlatGeometry)
+  | ({ readonly geometry_source: null } & NullGeometry);
+
+export const NO_GEOMETRY: NullGeometry = {
+  page_w_in: null,
+  page_h_in: null,
+  columns: null,
+  body_pt: null,
+  ref_pt: null,
+  body_pages: null,
+  ref_pages: null,
+  appendix_pages: null,
+  pages_by_type: null,
+};
+
+/** The ONE place the domain's names become the file's: camelCase in, schema-2 snake_case out. */
+const flat = (g: PageGeometry): FlatGeometry => ({
+  page_w_in: g.pageWidthIn,
+  page_h_in: g.pageHeightIn,
+  columns: g.columns,
+  body_pt: g.bodyPt,
+  ref_pt: g.refPt,
+  body_pages: g.bodyPages,
+  ref_pages: g.refPages,
+  appendix_pages: g.appendixPages,
+  pages_by_type: g.pagesByType,
+});
+
+/** The projection onto the file: one branch in, the matching fields out. */
+export const flatGeometry = (g: Geometry): FactsGeometryFields =>
+  g.kind === "measured"
+    ? { geometry_source: g.by.tool, ...flat(g.geometry) }
+    : { geometry_source: null, ...NO_GEOMETRY };

package/src/domain/host.ts

@@ -0,0 +1,23 @@
+/**
+ * The environment, as a VALUE. The composition root reads `process.env` and the host's directories
+ * once and passes them in; nothing inside reads the environment again, so no signature below the
+ * root carries `process`.
+ */
+
+export type Environment = Readonly<Record<string, string | undefined>>;
+
+/** The three directories the host knows and the environment does not say. All absolute. */
+export interface HostDirs {
+  readonly home: string;
+  readonly tmp: string;
+  /** What a relative path from the environment is relative to. */
+  readonly cwd: string;
+}
+
+/** An environment as a child process gets it: every value a string, none undefined. */
+export const childEnv = (env: Environment): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(env).filter(
+      (e): e is [string, string] => e[1] !== undefined,
+    ),
+  );

package/src/domain/page-layout.ts

@@ -0,0 +1,32 @@
+/**
+ * A page as text boxes: the page size in points and every text item with its position, size, font,
+ * fill and orientation. The domain's picture of a laid-out page — what a page-geometry measurer
+ * takes, with no tool named: pdf.js produces it (`adapters/pdfjs/fill.ts`, `pdf-facts.ts`), and
+ * banal's adapter writes it as the XML banal reads (`adapters/banal/xml.ts`).
+ */
+
+/** The fill a text item was drawn with. `unknown` is drawn as black, as pdftohtml's default is. */
+export type Fill =
+  | { readonly kind: "rgb"; readonly hex: string }
+  | { readonly kind: "invisible" }
+  | { readonly kind: "unknown" };
+
+/** One text item, in points, top-down. `size` is the font size in points. */
+export interface TextBox {
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  readonly height: number;
+  readonly size: number;
+  readonly font: string;
+  readonly text: string;
+  readonly upright: boolean;
+  readonly fill: Fill;
+}
+
+/** A page's size in points and every text item on it, in content order. */
+export interface PageLayout {
+  readonly widthPt: number;
+  readonly heightPt: number;
+  readonly boxes: readonly TextBox[];
+}

package/src/domain/paths.ts

@@ -0,0 +1,5 @@
+/** Paths as the domain holds them. */
+import type { Opaque } from "ts-essentials";
+
+/** An absolute path. Minted at the composition root (`abs`), so nothing inside resolves a cwd. */
+export type AbsolutePath = Opaque<string, "AbsolutePath">;

package/src/domain/result.test.ts

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { andThen, err, map, match, ok, type Result } from "./result.ts";
+
+const half = (n: number): Result<number, string> =>
+  n % 2 === 0 ? ok(n / 2) : err(`${n} is odd`);
+
+test("map and andThen run on ok and pass an error through untouched", () => {
+  assert.deepEqual(
+    map(ok(2), (n) => n + 1),
+    ok(3),
+  );
+  assert.deepEqual(andThen(ok(8), half), ok(4));
+  // Guards: an error short-circuits — the function after it is not called.
+  assert.deepEqual(
+    andThen(half(3), () => assert.fail("called after an error")),
+    err("3 is odd"),
+  );
+});
+
+test("match picks the branch by `ok`", () => {
+  const say = (r: Result<number, string>) =>
+    match(r, { ok: (n) => `got ${n}`, err: (e) => `no: ${e}` });
+  assert.equal(say(half(4)), "got 2");
+  assert.equal(say(half(5)), "no: 5 is odd");
+});

package/src/domain/result.ts

@@ -0,0 +1,29 @@
+/**
+ * The outcome of something that can fail, as a value: the shape paperlint already spoke in plain unions
+ * (`{ ok: true, … } | { ok: false, … }`), made generic. No classes and no fluent API — a `switch`
+ * on `ok` reads the same as every other union in the package.
+ */
+export type Result<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
+export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });
+
+export const map = <T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E> =>
+  r.ok ? ok(f(r.value)) : r;
+
+export const andThen = <T, U, E, F>(
+  r: Result<T, E>,
+  f: (t: T) => Result<U, F>,
+): Result<U, E | F> => (r.ok ? f(r.value) : r);
+
+export const match = <T, E, R>(
+  r: Result<T, E>,
+  on: { readonly ok: (t: T) => R; readonly err: (e: E) => R },
+): R => (r.ok ? on.ok(r.value) : on.err(r.error));
+
+/** The `default` of an exhaustive `switch`: a new variant is a compile error, not a silent fall-through. */
+export function assertNever(x: never): never {
+  throw new Error(`unhandled variant: ${JSON.stringify(x)}`);
+}

package/src/domain/sha256.test.ts

@@ -0,0 +1,12 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { parseSha256, sha256Hex } from "./sha256.ts";
+
+test("parseSha256 refuses a typo in a pin", () => {
+  assert.throws(() => parseSha256("abc"), /not a sha256/);
+});
+
+test("sha256Hex hashes bytes into a value parseSha256 accepts", () => {
+  const h = sha256Hex(new TextEncoder().encode("banal"));
+  assert.equal(parseSha256(h), h);
+});

package/src/domain/sha256.ts

@@ -0,0 +1,21 @@
+/**
+ * A sha256 as a value: bytes hashed, or a digest written down as text and checked where it is
+ * written. Tool-free — a pinned download, a facts file's `pdf_sha256` and a cache key all use it.
+ */
+import { createHash } from "node:crypto";
+import type { Opaque } from "ts-essentials";
+
+/** 64 lowercase hex digits. Minted by `parseSha256` (a literal) or `sha256Hex` (bytes) only. */
+export type Sha256 = Opaque<string, "Sha256">;
+
+const SHA256 = /^[0-9a-f]{64}$/;
+
+/** A sha256 written down as text — a pin, an option — checked where it is written, not where it is used. */
+export function parseSha256(s: string): Sha256 {
+  if (!SHA256.test(s))
+    throw new Error(`not a sha256 (64 lowercase hex digits): ${s}`);
+  return s as Sha256;
+}
+
+export const sha256Hex = (bytes: Uint8Array): Sha256 =>
+  createHash("sha256").update(bytes).digest("hex") as Sha256;

package/src/domain/text.ts

@@ -0,0 +1,11 @@
+/** Text shapes every layer speaks: a message of one or more lines, and the line a failure shows. */
+
+/** A message: the first line says what happened, any further lines are detail. Never empty. */
+export type Lines = readonly [string, ...string[]];
+
+/** The first non-blank line of a stream — what a failure shows. */
+export const firstLine = (s: string): string =>
+  s
+    .split("\n")
+    .map((l) => l.trim())
+    .find(Boolean) ?? "";