@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/spawn.test.ts

@@ -0,0 +1,34 @@
+import crossSpawn from "cross-spawn";
+import { describe, expect, it, vi } from "vitest";
+import { execFileSync, spawnSync } from "./spawn.ts";
+
+const node = process.execPath;
+
+describe("spawnSync", () => {
+  it("returns status and output like child_process.spawnSync", () => {
+    const r = spawnSync(node, ["-e", "process.stdout.write('hi'); process.exit(3)"], { encoding: "utf8" });
+    expect(r.status).toBe(3);
+    expect(r.stdout).toBe("hi");
+  });
+});
+
+describe("execFileSync", () => {
+  it("returns stdout on exit 0", () => {
+    expect(execFileSync(node, ["-e", "process.stdout.write('ok')"], { encoding: "utf8" })).toBe("ok");
+  });
+
+  it("throws with the exit code on a nonzero exit", () => {
+    expect(() => execFileSync(node, ["-e", "process.exit(2)"], {})).toThrow(/exited with 2$/);
+  });
+
+  // Mocked: Windows has no signals, so a real kill reports an exit code there.
+  it("throws with the signal when the child is killed", () => {
+    const sync = vi.spyOn(crossSpawn, "sync").mockReturnValueOnce({ status: null, signal: "SIGTERM" } as never);
+    expect(() => execFileSync("bun", ["install"], {})).toThrow(/^bun install exited with SIGTERM$/);
+    sync.mockRestore();
+  });
+
+  it("throws the spawn error for a missing command", () => {
+    expect(() => execFileSync("repo-no-such-command-e2e", [], {})).toThrow(/Executable not found in \$PATH|ENOENT/);
+  });
+});

package/cli/spawn.ts

@@ -0,0 +1,27 @@
+import type { SpawnSyncOptions, SpawnSyncOptionsWithStringEncoding, SpawnSyncReturns } from "node:child_process";
+import crossSpawn from "cross-spawn";
+
+/**
+ * child_process twins for starting bun and the tools it installs. On Windows a package bin is a
+ * .cmd shim that child_process cannot start without a shell (spawnSync ENOENT); cross-spawn
+ * resolves and escapes it. Elsewhere it is plain spawnSync.
+ */
+export function spawnSync(
+  cmd: string,
+  args: string[],
+  opts: SpawnSyncOptionsWithStringEncoding,
+): SpawnSyncReturns<string>;
+export function spawnSync(cmd: string, args: string[], opts?: SpawnSyncOptions): SpawnSyncReturns<Buffer>;
+export function spawnSync(cmd: string, args: string[], opts?: SpawnSyncOptions): SpawnSyncReturns<string | Buffer> {
+  return crossSpawn.sync(cmd, args, opts);
+}
+
+/** execFileSync semantics: throw unless the command exits 0. */
+export function execFileSync(cmd: string, args: string[], opts?: SpawnSyncOptions): string | Buffer {
+  const r = spawnSync(cmd, args, opts);
+  if (r.error) throw r.error;
+  if (r.status !== 0) {
+    throw new Error(`${cmd} ${args.join(" ")} exited with ${r.status ?? r.signal}`);
+  }
+  return r.stdout;
+}

package/cli/staged-change.constants.ts

@@ -0,0 +1,11 @@
+/** The names `repo` reads from `git diff --numstat` and `git check-attr` output. */
+
+/** The tokens `git check-attr -z` prints per path: the path, the attribute and its value. */
+export const ATTR_TOKENS = 3;
+/** Where the value sits in a `git check-attr -z` triple. */
+export const ATTR_VALUE_AT = 2;
+/** The two paths a numstat rename lists after its counts. */
+export const RENAME_PATHS = 2;
+/** The attribute values that mark a path as set. */
+export const ATTR_SET = "set";
+export const ATTR_TRUE = "true";

package/cli/staged-change.ts

@@ -0,0 +1,79 @@
+import path from "node:path";
+import { ATTR_SET, ATTR_TOKENS, ATTR_TRUE, ATTR_VALUE_AT, RENAME_PATHS } from "./staged-change.constants.ts";
+import { type GitRun, runGit } from "./sync/standards.ts";
+
+/** Files whose size says nothing about the change: lockfiles, by name anywhere, and the lint baseline. */
+const UNCOUNTED_NAMES: readonly string[] = [
+  "bun.lock",
+  "bun.lockb",
+  "package-lock.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+];
+const UNCOUNTED_PATHS: readonly string[] = [".repo/lint-baseline.json"];
+
+/** The staged change: every path, and the changed lines that count toward the size limit. */
+export type StagedChange = { files: string[]; changedLines: number };
+
+/** Where numstat output came from: the repo, the git to ask, and the `check-attr` flags that pick the tree. */
+type Reader = { root: string; attrArgs: readonly string[]; git: GitRun };
+
+/** One `git diff --numstat -z` entry: its path, and its changed lines, or null for a binary file. */
+type Numstat = { file: string; lines: number | null };
+
+/** The entries of `git diff --numstat -z`; a rename is `a\td\t` followed by its old and new path. */
+function parseNumstat(out: string): Numstat[] {
+  const tokens = out.split("\0");
+  const entries: Numstat[] = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const match = /^(-|\d+)\t(-|\d+)\t(.*)$/s.exec(tokens[i] /* i < tokens.length */ as string);
+    if (match === null) continue;
+    const [, added, deleted, named] = match;
+    const file = named ? named : (tokens[(i += RENAME_PATHS)] /* a rename lists both paths */ as string);
+    entries.push({ file, lines: added === "-" ? null : Number(added) + Number(deleted) });
+  }
+  return entries;
+}
+
+/** The paths among `files` that `.gitattributes` (`attrArgs` picks which: the index, or a commit's) mark `linguist-generated`. */
+function generatedPaths(files: readonly string[], { root, attrArgs, git }: Reader): Set<string> {
+  const result = git(root, ["check-attr", ...attrArgs, "-z", "--stdin", "linguist-generated"], files.join("\0"));
+  const tokens = result.stdout.split("\0");
+  const generated = new Set<string>();
+  for (let i = 0; i + ATTR_VALUE_AT < tokens.length; i += ATTR_TOKENS) {
+    if (tokens[i + ATTR_VALUE_AT] === ATTR_SET || tokens[i + ATTR_VALUE_AT] === ATTR_TRUE)
+      generated.add(tokens[i] /* i < tokens.length */ as string);
+  }
+  return generated;
+}
+
+/** The files and counted lines of `numstat` output, leaving out binaries, lockfiles, the baseline and generated paths. */
+function summarize(numstat: string, reader: Reader): StagedChange {
+  const entries = parseNumstat(numstat);
+  const files = entries.map((entry) => entry.file);
+  const generated = generatedPaths(files, reader);
+  const counted = entries.filter(
+    ({ file }) =>
+      !UNCOUNTED_NAMES.includes(path.posix.basename(file)) && !UNCOUNTED_PATHS.includes(file) && !generated.has(file),
+  );
+  return { files, changedLines: counted.reduce((sum, entry) => sum + (entry.lines ?? 0), 0) };
+}
+
+/**
+ * The staged change at `root`: every staged path, and the insertions plus deletions that count toward the size
+ * limit, leaving out binaries, lockfiles, the lint baseline and `linguist-generated` paths. Nothing outside a repo.
+ */
+export function stagedChange(root: string, git: GitRun = runGit): StagedChange {
+  const diff = git(root, ["diff", "--cached", "--numstat", "-z"]);
+  return diff.status !== 0
+    ? { files: [], changedLines: 0 }
+    : summarize(diff.stdout, { root, attrArgs: ["--cached"], git });
+}
+
+/** The change commit `sha` made, counted as `stagedChange` counts, with `.gitattributes` read as of that commit. */
+export function commitChange(root: string, sha: string, git: GitRun = runGit): StagedChange {
+  const shown = git(root, ["show", "--numstat", "-z", "--format=", sha]);
+  return shown.status !== 0
+    ? { files: [], changedLines: 0 }
+    : summarize(shown.stdout, { root, attrArgs: ["--source", sha], git });
+}

package/cli/stryker-preload.test.ts

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { spawnSync } from "./spawn.ts";
+import { toolEnv } from "./scripts/lint.ts";
+import { childEnv } from "./env.ts";
+
+const PRELOAD = path.join(import.meta.dirname, "stryker-preload.ts");
+const THROWS = "First argument must be an Error object";
+// Babel's stack rewriter wraps the native hook; follow-redirects' CustomError captures a stack on a non-Error.
+const REPRO = `
+const orig = Error.prepareStackTrace;
+Error.prepareStackTrace = (e, t) => (orig ? orig(e, t) : "");
+function C() { Error.captureStackTrace(this, C); }
+C.prototype = new Error();
+new C();
+`;
+let dir = "";
+
+afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+function repro(preload: boolean) {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "stryker-preload-"));
+  const file = path.join(dir, "repro.ts");
+  fs.writeFileSync(file, REPRO);
+  const args = preload ? ["--preload", PRELOAD, file] : [file];
+  const run = spawnSync(process.execPath, args, { encoding: "utf8", env: toolEnv(childEnv()) });
+  return { code: run.status, text: `${run.stdout}${run.stderr}` };
+}
+
+it("bun still throws on a non-Error that captures a stack; delete cli/stryker-preload.ts and its --preload once it does not", () => {
+  const bare = repro(false);
+  expect(bare.text).toContain(THROWS);
+  expect(bare.code).not.toBe(0);
+});
+
+it("the preload clears the native hook, so the same code runs", () => {
+  expect(repro(true)).toEqual({ code: 0, text: "" });
+});
+
+it("sets prepareStackTrace to undefined when loaded", async () => {
+  const before = Error.prepareStackTrace;
+  try {
+    await import("./stryker-preload.ts");
+    expect(Error.prepareStackTrace).toBeUndefined();
+  } finally {
+    Error.prepareStackTrace = before;
+  }
+});

package/cli/stryker-preload.ts

@@ -0,0 +1,9 @@
+/**
+ * Preloaded (`bun --preload`) by `repo mutate` before Stryker. Bun's native `Error.prepareStackTrace` throws "First
+ * argument must be an Error object" on an Error-derived non-Error, which babel's stack rewriter and vite's
+ * follow-redirects reach while Stryker loads its vitest runner; with no hook, bun's default stack formatting runs.
+ * `cli/stryker-preload.test.ts` pins the bun bug: when it fails, delete this file and the `--preload` argument.
+ */
+Error.prepareStackTrace = undefined /* the lib types omit undefined; assigning it clears the native hook */ as never;
+
+export {};

package/cli/sync/agents/frontmatter.test.ts

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+import { describe, expect, it } from "vitest";
+import { emitYaml, finalize, parseDoc, type YamlValue } from "./frontmatter.ts";
+
+const GOLDEN = path.join(import.meta.dirname, "..", "fixtures", "golden");
+
+describe("parseDoc", () => {
+  it("splits frontmatter from a trimmed LF body", () => {
+    expect(parseDoc("a.md", "\uFEFF---\r\nname: x\r\n---\r\n\r\n  body\r\nline two\r\n\r\n")).toEqual({
+      data: { name: "x" },
+      body: "body\nline two",
+    });
+  });
+
+  it("reads YAML 1.2: yes stays a string", () => {
+    expect(parseDoc("a.md", "---\nflag: yes\nnum: 012\n---\n").data).toEqual({ flag: "yes", num: 12 });
+  });
+
+  it("drops null values at every level", () => {
+    const text = "---\na:\nb: 1\nc:\n  d: ~\n  e: 2\nf: [x, null]\n---\n";
+    expect(parseDoc("a.md", text).data).toEqual({ b: 1, c: { e: 2 }, f: ["x"] });
+  });
+
+  it("gives an empty mapping for an empty block", () => {
+    expect(parseDoc("a.md", "---\n---\nbody")).toEqual({ data: {}, body: "body" });
+  });
+
+  it("names the file when the frontmatter is missing", () => {
+    expect(() => parseDoc(".repo/rules/nofm.md", "# no fence\n")).toThrow(
+      new Error(".repo/rules/nofm.md: missing frontmatter (start the file with a --- block)"),
+    );
+  });
+
+  it("names the file and gives the parser message's first line when the YAML is broken", () => {
+    const yaml = "name: [bad";
+    let message = "";
+    try {
+      parse(yaml);
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    const firstLine = message.split("\n")[0]!.trim().replace(/:$/, "");
+    expect(firstLine).toMatch(/at line 1, column \d+$/);
+    expect(() => parseDoc(".repo/subagents/bad.md", `---\n${yaml}\n---\n`)).toThrow(
+      new Error(`.repo/subagents/bad.md: invalid frontmatter: ${firstLine}`),
+    );
+  });
+
+  it("keeps the invalid-frontmatter message on one line", () => {
+    expect(() => parseDoc("a.md", "---\nname: [bad\n---\n")).toThrow(/^a\.md: invalid frontmatter: [^\n]+$/);
+  });
+
+  it.each([
+    ["an unclosed block", "---\nname: x\n", "no closing --- line"],
+    ["a non-mapping", "---\n- x\n---\n", "expected a mapping"],
+  ])("rejects %s", (_label, text, why) => {
+    expect(() => parseDoc("a.md", text)).toThrow(new Error(`a.md: invalid frontmatter: ${why}`));
+  });
+});
+
+describe("emitYaml", () => {
+  const roundTrip = (entries: [string, YamlValue][], mode?: "claude") =>
+    expect(parse(emitYaml(entries, mode))).toEqual(Object.fromEntries(entries));
+
+  it("writes lists and nested maps in block style, in the order given", () => {
+    const entries: [string, YamlValue][] = [
+      ["name", "x"],
+      ["tools", ["Read", "Grep"]],
+      ["nested", { b: 1, a: true }],
+    ];
+    expect(emitYaml(entries)).toBe("name: x\ntools:\n  - Read\n  - Grep\nnested:\n  b: 1\n  a: true\n");
+    roundTrip(entries);
+  });
+
+  it("writes empty lists and maps in flow style", () => {
+    expect(
+      emitYaml([
+        ["a", []],
+        ["b", {}],
+      ]),
+    ).toBe("a: []\nb: {}\n");
+  });
+
+  it("drops nullish values at every level", () => {
+    expect(
+      emitYaml([
+        ["a", null],
+        ["b", undefined],
+        ["c", { d: null }],
+        ["e", ["x", null, undefined]],
+      ]),
+    ).toBe("c: {}\ne:\n  - x\n");
+  });
+
+  const ambiguous = [
+    "yes",
+    "No",
+    "y",
+    "on",
+    "true",
+    "null",
+    "~",
+    "012",
+    "1_000",
+    "1:20",
+    "0x1f",
+    "1e3",
+    ".5",
+    "2001-12-14",
+    "",
+    " lead",
+    "trail ",
+    "- a",
+    "-",
+    "a: b",
+    "a:",
+    "a #b",
+    "#a",
+    "[x]",
+    "{x}",
+    "@x",
+    "%x",
+    "`x",
+    "!x",
+    "&x",
+    "*x",
+    ">x",
+    "|x",
+    "'x",
+    '"x',
+    "---",
+    "--- [",
+  ];
+
+  it.each(ambiguous)("quotes %j and reads it back", (value) => {
+    expect(emitYaml([["k", value]])).toMatch(/^k: '/);
+    roundTrip([["k", value]]);
+  });
+
+  it.each(["a, b", "x[y]", "a:b", "a#b", "-a", "=x", "?x", "Agent(scout, explore, plan)", "grok-4.7", "it's 'quoted'"])(
+    "leaves %j bare by default",
+    (value) => {
+      expect(emitYaml([["k", value]])).toBe(`k: ${value}\n`);
+      roundTrip([["k", value]]);
+    },
+  );
+
+  it.each(["a, b", "x[y]", "{x", "a:b", "-a", "=x", "?x"])("quotes %j in claude mode", (value) => {
+    expect(emitYaml([["k", value]], "claude")).toBe(`k: '${value}'\n`);
+    roundTrip([["k", value]], "claude");
+  });
+
+  it("double-quotes strings with newlines or control characters", () => {
+    expect(emitYaml([["k", "a\nb\tc"]])).toBe('k: "a\\nb\\tc"\n');
+    roundTrip([["k", "a\nb\tc"]]);
+  });
+
+  it("quotes keys like values", () => {
+    roundTrip([
+      ["yes", "x"],
+      ["a: b", 1],
+    ]);
+    expect(emitYaml([["yes", "x"]])).toBe("'yes': x\n");
+  });
+
+  it("writes special numbers", () => {
+    roundTrip([
+      ["n", 1.5],
+      ["inf", Infinity],
+      ["ninf", -Infinity],
+    ]);
+    expect(parse(emitYaml([["nan", NaN]])).nan).toBeNaN();
+  });
+
+  const agentFiles = ["claude", "agents", "grok", "cursor"].flatMap((host) =>
+    fs.readdirSync(path.join(GOLDEN, `.${host}`, "agents")).map((name) => `.${host}/agents/${name}`),
+  );
+
+  it.each(agentFiles)("reproduces the frontmatter of golden %s", (rel) => {
+    const text = fs.readFileSync(path.join(GOLDEN, rel), "utf8");
+    const block = text.slice(4, text.indexOf("\n---\n", 4) + 1);
+    const mode = rel.startsWith(".claude/") ? "claude" : "default";
+    expect(emitYaml(Object.entries(parseDoc(rel, text).data) as [string, YamlValue][], mode)).toBe(block);
+  });
+});
+
+describe("finalize", () => {
+  it.each([
+    ["a\r\nb\rc", "a\nb\nc\n"],
+    ["a\n\n\n  ", "a\n"],
+    ["", "\n"],
+  ])("normalises %j", (text, want) => {
+    expect(finalize(text)).toBe(want);
+  });
+});

package/cli/sync/agents/frontmatter.ts

@@ -0,0 +1,140 @@
+/**
+ * Markdown-with-frontmatter in and out for the agent generators. Parsing is YAML 1.2 (`yes` stays a string);
+ * emitting covers the shapes agent files use: scalars, scalar lists as block sequences and nested maps.
+ */
+import { parse } from "yaml";
+
+/** A frontmatter document: the YAML mapping with nullish values removed, and the trimmed body. */
+export interface ParsedDoc {
+  data: Record<string, unknown>;
+  body: string;
+}
+
+type YamlScalar = string | number | boolean;
+/** `null` and `undefined` are dropped at every level, as rulesync did. */
+export type YamlValue = YamlScalar | readonly (YamlScalar | null | undefined)[] | YamlMap | null | undefined;
+export interface YamlMap {
+  readonly [key: string]: YamlValue;
+}
+
+/**
+ * How strings are quoted. `default` quotes only what YAML would misread. `claude` also quotes any string holding
+ * `,` `[` `]` `{` `}` or `:`, or starting with `-` `?` `=`, as the YAML 1.1 dumper behind the committed
+ * `.claude/agents` files did.
+ */
+export type YamlMode = "default" | "claude";
+
+const FENCE = "---";
+
+function toLf(text: string): string {
+  return text.replace(/\r\n?/g, "\n");
+}
+
+/** Parse `text` (the file at repo-relative POSIX `rel`); throws an Error whose message starts with `rel`. */
+export function parseDoc(rel: string, text: string): ParsedDoc {
+  const lines = toLf(text)
+    .replace(/^\uFEFF/, "")
+    .split("\n");
+  if (lines[0]?.trimEnd() !== FENCE) throw new Error(`${rel}: missing frontmatter (start the file with a --- block)`);
+  const close = lines.findIndex((line, i) => i > 0 && line.trimEnd() === FENCE);
+  if (close === -1) throw new Error(`${rel}: invalid frontmatter: no closing --- line`);
+  let raw: unknown;
+  try {
+    raw = parse(lines.slice(1, close).join("\n"));
+  } catch (error) {
+    // The first line already names the line and column; the rest is a source excerpt that would split the message.
+    const reason = (error as Error).message.split("\n")[0]!.trim().replace(/:$/, "");
+    throw new Error(`${rel}: invalid frontmatter: ${reason}`);
+  }
+  if (raw !== null && !isMap(raw)) throw new Error(`${rel}: invalid frontmatter: expected a mapping`);
+  return {
+    data: raw === null ? {} : dropNullish(raw),
+    body: lines
+      .slice(close + 1)
+      .join("\n")
+      .trim(),
+  };
+}
+
+function isMap(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function dropNullish(map: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(map)) {
+    if (value === null || value === undefined) continue;
+    out[key] = Array.isArray(value)
+      ? value.filter((item) => item !== null && item !== undefined)
+      : isMap(value)
+        ? dropNullish(value)
+        : value;
+  }
+  return out;
+}
+
+/** Block-style YAML for `entries` in the order given, ending in `\n`; `""` when every value is nullish. */
+export function emitYaml(entries: Iterable<readonly [string, YamlValue]>, mode: YamlMode = "default"): string {
+  return emitMap(entries, mode, "");
+}
+
+function emitMap(entries: Iterable<readonly [string, YamlValue]>, mode: YamlMode, indent: string): string {
+  let out = "";
+  for (const [key, value] of entries) {
+    if (value === null || value === undefined) continue;
+    const head = `${indent}${scalar(key, mode)}:`;
+    if (Array.isArray(value)) {
+      const items = (value as readonly (YamlScalar | null | undefined)[]).filter(
+        (item) => item !== null && item !== undefined,
+      );
+      out +=
+        items.length === 0
+          ? `${head} []\n`
+          : `${head}\n${items.map((item) => `${indent}  - ${scalar(item, mode)}\n`).join("")}`;
+    } else if (typeof value === "object") {
+      const body = emitMap(Object.entries(value as YamlMap), mode, `${indent}  `);
+      out += body === "" ? `${head} {}\n` : `${head}\n${body}`;
+    } else {
+      out += `${head} ${scalar(value as YamlScalar, mode)}\n`;
+    }
+  }
+  return out;
+}
+
+function scalar(value: YamlScalar, mode: YamlMode): string {
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "number") {
+    if (Number.isNaN(value)) return ".nan";
+    if (!Number.isFinite(value)) return value > 0 ? ".inf" : "-.inf";
+    return String(value);
+  }
+  // Newlines and control characters need escapes; a JSON string is a valid YAML double-quoted scalar.
+  if (/[\u0000-\u001f\u007f\u2028\u2029\uFEFF]/.test(value)) return JSON.stringify(value);
+  return needsQuotes(value, mode) ? `'${value.replaceAll("'", "''")}'` : value;
+}
+
+/** Words and numbers a YAML 1.1 reader types though YAML 1.2 reads them as strings. */
+const YAML_11_TYPED =
+  /^(?:[yYnN]|yes|Yes|YES|no|No|NO|on|On|ON|off|Off|OFF|[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+(?:\.[0-9_]*)?|[-+]?(?:0b[01_]+|0x[0-9a-fA-F_]+|0[0-7_]+|[0-9][0-9_]*(?:\.[0-9_]*)?(?:[eE][-+]?[0-9]+)?|\.[0-9_]+(?:[eE][-+]?[0-9]+)?)|[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}(?:[Tt ].*)?)$/;
+
+function needsQuotes(value: string, mode: YamlMode): boolean {
+  if (value === "" || value !== value.trim()) return true;
+  if (/^[,[\]{}#&*!|>'"%@`]/.test(value) || /^[-?:](?:\s|$)/.test(value)) return true;
+  if (/:(?:\s|$)/.test(value) || /\s#/.test(value)) return true;
+  if (mode === "claude" && (/[,[\]{}:]/.test(value) || /^[-?=]/.test(value))) return true;
+  if (YAML_11_TYPED.test(value)) return true;
+  return readsAsSomethingElse(value);
+}
+
+function readsAsSomethingElse(value: string): boolean {
+  try {
+    return parse(value) !== value;
+  } catch {
+    return true;
+  }
+}
+
+/** One file's final text: LF only, trailing whitespace trimmed, exactly one trailing `\n`. */
+export function finalize(text: string): string {
+  return `${toLf(text).trimEnd()}\n`;
+}