@hawkeyexl/manni 1.1.1 → 2.0.1

package/dist/cli.js

@@ -1,38 +1,67 @@
 #!/usr/bin/env node
 import {
+  STDIN_LINES_MARKER,
   buildProgram,
+  collect,
+  configOption,
+  explicitFalse,
   fail,
-  runIfMain
-} from "./chunk-DOQUHXK3.js";
+  readStdin,
+  reportConfig,
+  runIfMain,
+  splitList
+} from "./chunk-MV2T7XAW.js";
 import {
+  CiteError,
+  KeyError,
+  SEVERITIES,
+  SEVERITY_LIST,
+  isSeverity,
+  meetsSeverity,
+  renderCheckGithub,
+  renderCheckJson,
+  renderCheckPretty,
+  renderUpdateJson,
+  renderUpdatePretty,
+  runAdd,
+  runCheck,
+  runKeyRotate,
+  runKeySet,
+  runUpdate,
+  shortCommit,
+  shortPin,
+  shortSrc,
+  spellSource
+} from "./chunk-QLVNSAHR.js";
+import {
+  COMMON_FORMAT_LIST,
+  OMITTED_WHEN_CLEAN,
+  REPORT_FORMATS,
+  REPORT_FORMAT_LIST,
+  STDIN_TOKEN,
   ToolError,
   escapeWorkflowCommandMessage,
   escapeWorkflowCommandProperty,
   findConfigFile,
+  isMachineFormat,
+  isReportFormat,
+  notice,
   package_default,
   palette,
   programName,
   readConfigFile,
+  render,
   selectCollections,
-  shouldColor
-} from "./chunk-HYPDUKRU.js";
+  shouldColor,
+  terminalConfirm
+} from "./chunk-PDNSN5UJ.js";
 
 // src/cli.ts
-import { Command as Command2 } from "commander";
+import { Command as Command4 } from "commander";
 
 // src/a11y/cli.ts
 import { Command } from "commander";
 
-// src/shared/severity.ts
-var SEVERITIES = ["notice", "warning", "error"];
-var SEVERITY_LIST = SEVERITIES.join(" | ");
-function isSeverity(value) {
-  return SEVERITIES.includes(value);
-}
-function meetsSeverity(severity, min) {
-  return SEVERITIES.indexOf(severity) >= SEVERITIES.indexOf(min);
-}
-
 // src/a11y/types.ts
 var A11yError = class extends ToolError {
   constructor(message) {
@@ -350,7 +379,7 @@ var CHECK_DEFAULTS = Object.freeze({
   severity: "notice",
   timeout: 3e4
 });
-async function runCheck(opts, deps) {
+async function runCheck2(opts, deps) {
   const { analyzer } = deps;
   try {
     if (opts.urls.length === 0) {
@@ -716,7 +745,7 @@ var A11Y_FORMAT_LIST = A11Y_FORMATS.join(" | ");
 function isA11yFormat(value) {
   return A11Y_FORMATS.includes(value);
 }
-function render(format, run, opts) {
+function render2(format, run, opts) {
   switch (format) {
     case "pretty":
       return renderPretty(run, opts);
@@ -828,10 +857,10 @@ function truncateMiddle(text, room) {
 }
 
 // src/a11y/cli.ts
-function collect(value, prev) {
+function collect2(value, prev) {
   return prev.concat([value]);
 }
-function splitList(value) {
+function splitList2(value) {
   return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
 function resolveColor(program, stream) {
@@ -887,7 +916,7 @@ function buildProgram2() {
   ).option("-q, --quiet", "in pretty output, hide pages with no violations").option("--progress", "report progress on stderr (default: only on a terminal)").option("--no-progress", "never report progress").option(
     "--collection <name>",
     "configured collection to run over; repeatable",
-    collect,
+    collect2,
     []
   ).option("-c, --config <path>", "path to a manni config file").option("--no-config", "ignore any discovered config file").action(async (urls, options, command) => {
     let clearProgress = () => void 0;
@@ -912,20 +941,20 @@ function buildProgram2() {
       const parent = command.parent ?? command;
       const progress = resolveProgress(parent, options.progress);
       clearProgress = progress.clear;
-      const run = await runCheck(
+      const run = await runCheck2(
         {
           urls: seeds,
           crawl: typed("crawl") ? options.crawl : cfg.crawl ?? CHECK_DEFAULTS.crawl,
           // Typed flag > config key > no cap. There is no default to fall to.
           maxPages: maxPages ?? cfg.maxPages,
-          tags: options.tags !== void 0 ? splitList(options.tags) : cfg.tags ?? CHECK_DEFAULTS.tags,
+          tags: options.tags !== void 0 ? splitList2(options.tags) : cfg.tags ?? CHECK_DEFAULTS.tags,
           severity: typed("severity") ? severity : cfg.severity ?? CHECK_DEFAULTS.severity,
           timeout: typed("timeout") ? timeout : cfg.timeout ?? CHECK_DEFAULTS.timeout
         },
         { analyzer: createPlaywrightAnalyzer(), onProgress: progress.listener }
       );
       const color = resolveColor(parent, process.stdout);
-      const text = render(format, run, { color, quiet: Boolean(options.quiet) });
+      const text = render2(format, run, { color, quiet: Boolean(options.quiet) });
       if (text.length > 0 || format !== "github") {
         process.stdout.write(`${text}
 `);
@@ -939,13 +968,507 @@ function buildProgram2() {
   return program;
 }
 
-// src/cli.ts
+// src/cite/cli.ts
+import { Command as Command2, Option } from "commander";
+var JUNIT_CLASSNAME = "manni.cite";
+var UPDATE_FORMATS = ["pretty", "json"];
+function colorFor(command, isTTY, env) {
+  const noColor = colorOwner(command).opts().color === false;
+  return shouldColor({ noColor, isTTY, env });
+}
+function colorOwner(command) {
+  for (let c = command; c !== null; c = c.parent) {
+    if (c.options.some((o) => o.long === "--no-color")) return c;
+  }
+  return command;
+}
+function isUpdateFormat(value) {
+  return UPDATE_FORMATS.includes(value);
+}
+function splitPageArgument(arg) {
+  const text = arg.startsWith(STDIN_LINES_MARKER) ? `${STDIN_TOKEN}${arg.slice(STDIN_LINES_MARKER.length)}` : arg;
+  const m = /:([1-9][0-9]*)(?:-([1-9][0-9]*))?$/.exec(text);
+  const head = m === null ? text : text.slice(0, m.index);
+  if (m === null || head === "") return { page: arg };
+  const start = Number(m[1]);
+  const end = m[2] === void 0 ? start : Number(m[2]);
+  if (end < start) {
+    throw new CiteError(`Invalid range "${arg}": end line ${end} is before start line ${start}.`);
+  }
+  return { page: head, lines: { start, end } };
+}
+function spellAt(lines, noun = "line") {
+  return lines.start === lines.end ? `${noun} ${String(lines.start)}` : `${noun}s ${String(lines.start)}-${String(lines.end)}`;
+}
+function addMessage(result) {
+  const { citation, claimLines } = result;
+  const claim = citation.claim;
+  const name = citation.id ?? (claim === void 0 ? "a bare pin" : "an entry");
+  const src = shortSrc(spellSource(citation.source));
+  const commit = citation.source["commit-sha"];
+  const pin = `${src}, ${shortPin(citation.source.integrity)}, ${commit === void 0 ? "no commit" : shortCommit(commit)}`;
+  const where2 = result.manifest === void 0 ? "frontmatter" : `${result.manifest.file}:${String(result.manifest.line)}`;
+  const head = `${result.file}: added ${name} to ${where2}`;
+  if (result.markerLine !== void 0) {
+    const at = claimLines === void 0 ? "" : `, claim pinned at line ${String(claimLines.start)}`;
+    return `${head}; marker at line ${String(result.markerLine)}${at}`;
+  }
+  if (claim === void 0 || claimLines === void 0) {
+    return `${head} (source ${pin})`;
+  }
+  if (citation.quote === true) {
+    return `${head} (claim ${spellAt(claimLines, "line")}, a block that reproduces ${src})`;
+  }
+  return `${head} (claim at ${spellAt(claimLines)}, ${shortPin(claim.integrity)}; source ${pin})`;
+}
 function buildProgram3() {
+  const program = new Command2();
+  program.name("cite").description(
+    "Track citations from doc claims to source lines and check them for drift."
+  ).version(package_default.version, "-V, --version").option("--no-color", "disable colored output").showHelpAfterError("(add --help for usage)").exitOverride();
+  program.command("check").description("Check every citation in the given pages against its source").argument(
+    "[paths...]",
+    "files, directories, or globs to check (use - for stdin)"
+  ).option(
+    "--collection <name>",
+    "configured collection to run over; repeatable",
+    collect,
+    []
+  ).option("--ext <list>", "comma-separated extensions for directory walks").option("--exclude <glob>", "glob to exclude; repeatable", collect, []).option("--as <format>", "force an input format for every input").option(
+    "-f, --format <format>",
+    `output: ${REPORT_FORMATS.join(" | ")}`,
+    "pretty"
+  ).option("-c, --config <path>", "path to a manni config file").option("--no-config", "ignore any discovered config file").option("-q, --quiet", "in pretty output, hide current citations and clean files").option("--allow-empty", "treat zero matched files as success").option("--no-gitignore", "check files .gitignore covers").addOption(
+    new Option(
+      "--baseline [path]",
+      "compare against a baseline; fail only on findings not in it"
+    )
+  ).addOption(
+    new Option(
+      "--write-baseline [path]",
+      "record current findings as the baseline, then exit 0"
+    )
+  ).option("--no-baseline", "ignore a baseline configured by `baseline:`").option("--no-check-sources", "page-side rules only; every source status is skipped").option(
+    "--root <dir>",
+    "directory src: paths resolve from (default: cite.root from config, else the git root, else the current directory)"
+  ).option("--show-diff", "in pretty output, print the diff and commit subjects for changed").option("--reveal", "in pretty output, print the decrypted path beside an encrypted source").addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  manni cite check docs/                          # walk a directory",
+      "  manni cite check --collection guides             # one configured collection",
+      '  manni cite check "docs/**/*.md" -f github        # CI annotations',
+      "  manni cite check --show-diff docs/limits.md      # see what changed",
+      "  manni cite check --baseline                      # fail only on new findings",
+      "  cat page.md | manni cite check - --as markdown"
+    ].join("\n")
+  ).action(async (paths, options, command) => {
+    try {
+      const format = options.format;
+      if (!isReportFormat(format)) {
+        throw new CiteError(
+          `Unknown --format "${format}". Use ${REPORT_FORMAT_LIST}.`
+        );
+      }
+      const exts = options.ext ? splitList(options.ext) : void 0;
+      const stdinContent = paths.includes(STDIN_TOKEN) ? await readStdin() : void 0;
+      const cwd = process.cwd();
+      const run = await runCheck({
+        inputs: paths,
+        collection: options.collection,
+        exts,
+        exclude: options.exclude,
+        as: options.as,
+        ...configOption(options.config),
+        onConfigLoaded: reportConfig(!isMachineFormat(format), cwd),
+        stdinContent,
+        // `undefined` rather than `false` when absent, so config still wins.
+        allowEmpty: options.allowEmpty ? true : void 0,
+        respectGitignore: explicitFalse(options.gitignore),
+        onNotice: notice,
+        baseline: options.baseline,
+        writeBaseline: options.writeBaseline,
+        checkSources: explicitFalse(options.checkSources),
+        // Only so the run can say git is not there to give diffs; the diffs
+        // themselves are the pretty reporter's.
+        showDiff: options.showDiff ? true : void 0,
+        root: options.root
+      });
+      let text;
+      switch (format) {
+        case "pretty":
+          text = renderCheckPretty(run, {
+            color: colorFor(command, process.stdout.isTTY),
+            quiet: Boolean(options.quiet),
+            showDiff: Boolean(options.showDiff),
+            reveal: Boolean(options.reveal)
+          });
+          break;
+        case "json":
+          text = renderCheckJson(run);
+          break;
+        case "github":
+          text = renderCheckGithub(run);
+          break;
+        default:
+          text = render(format, run.results, run.summary, {
+            frame: run.frame,
+            classname: JUNIT_CLASSNAME,
+            onNotice: notice
+          });
+      }
+      if (text.length > 0 || !OMITTED_WHEN_CLEAN.has(format)) {
+        process.stdout.write(`${text}
+`);
+      }
+      process.exitCode = run.summary.failed > 0 ? 1 : 0;
+    } catch (err) {
+      fail(err);
+    }
+  });
+  program.command("add").description("Mint a citation for a source range and write it to a page").argument(
+    "<page>",
+    "the page to cite from, with the claim's lines: page:L or page:L1-L2 (use - for stdin, with --as)"
+  ).argument(
+    "<src>",
+    "path, path:L or path:L1-L2 relative to --root, or an encrypted ~source with the same line forms"
+  ).option("--id <id>", "kebab-case id, unique on the page; required with --marker").option("--marker", "write a cite <id> marker above the page lines and pin the text it anchors").option("--quote", "the page lines are a fenced block that reproduces the source").option(
+    "--encrypt",
+    "write source.file encrypted, with an hmac-sha256- pin; with no key, offer to create one (an available key encrypts without the flag)"
+  ).option("--no-commit-sha", "do not record HEAD").option("--dry-run", "print the diff; write nothing").option("--as <format>", "force the page format").option("--root <dir>", "directory source paths resolve from (as check)").option("-c, --config <path>", "path to a manni config file").option("--no-config", "ignore any discovered config file").addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  manni cite add docs/limits.md:9 lib/limits.ts:2 --id fetch-timeout",
+      "  manni cite add docs/limits.md:30 lib/limits.ts:8-12 --id timeouts --marker",
+      "  manni cite add docs/limits.md:14-18 lib/limits.ts:1-3 --quote",
+      "  manni cite add docs/limits.md lib/limits.ts --dry-run",
+      "  cat page.md | manni cite add -:9 lib/limits.ts:2 --as markdown > out.md"
+    ].join("\n")
+  ).action(async (pageArgument, src, options) => {
+    try {
+      const { page, lines } = splitPageArgument(pageArgument);
+      const usingStdin = page === STDIN_TOKEN;
+      const stdinContent = usingStdin ? await readStdin() : void 0;
+      const dryRun = Boolean(options.dryRun);
+      const cwd = process.cwd();
+      const result = await runAdd({
+        page,
+        pageLines: lines,
+        src,
+        id: options.id,
+        marker: options.marker ? true : void 0,
+        quote: options.quote ? true : void 0,
+        // `undefined` when absent, so the key decides: an available one
+        // encrypts without the flag.
+        encrypt: options.encrypt ? true : void 0,
+        commitSha: explicitFalse(options.commitSha),
+        dryRun,
+        as: options.as,
+        ...configOption(options.config),
+        // With `-` the page owns stdout; so does the diff under --dry-run.
+        onConfigLoaded: reportConfig(!usingStdin && !dryRun, cwd),
+        stdinContent,
+        root: options.root,
+        onNotice: notice,
+        // Only on a terminal: off one, a missing key is a refusal, not a
+        // question nobody can answer. With `-` stdin is the page, so no
+        // question is put either.
+        confirm: terminalConfirm()
+      });
+      const message = addMessage(result);
+      const diffs = [result.diff, result.manifest?.diff ?? ""].filter((d) => d.length > 0);
+      if (usingStdin) {
+        process.stdout.write(result.content);
+        if (dryRun) for (const diff of diffs) process.stderr.write(`${diff}
+`);
+        process.stderr.write(`${message}
+`);
+      } else if (dryRun) {
+        for (const diff of diffs) process.stdout.write(`${diff}
+`);
+        process.stderr.write(`${message}
+`);
+      } else {
+        process.stdout.write(`${message}
+`);
+      }
+      process.exitCode = 0;
+    } catch (err) {
+      fail(err);
+    }
+  });
+  program.command("update").description("Rewrite moved citations in place; with --accept, re-mint changed ones").argument(
+    "[paths...]",
+    "files, directories, or globs to update (use - for stdin)"
+  ).option(
+    "--collection <name>",
+    "configured collection to run over; repeatable",
+    collect,
+    []
+  ).option("--ext <list>", "comma-separated extensions for directory walks").option("--exclude <glob>", "glob to exclude; repeatable", collect, []).option("--as <format>", "force an input format for every input").option("-c, --config <path>", "path to a manni config file").option("--no-config", "ignore any discovered config file").option("--allow-empty", "treat zero matched files as success").option("--no-gitignore", "update files .gitignore covers").option("--no-check-sources", "refused: update needs the sources").option("--root <dir>", "directory src: paths resolve from (as check)").option("--accept", "re-mint changed and never-true entries at HEAD; prints old and new pins").option("--only <id>", "limit to entries with this id; repeatable", collect, []).option("--dry-run", "print the diffs; write nothing").option(
+    "-f, --format <format>",
+    `output: ${UPDATE_FORMATS.join(" | ")}`,
+    "pretty"
+  ).addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  manni cite update docs/                          # rewrite moved entries",
+      "  manni cite update --accept --only fetch-timeout docs/limits.md",
+      "  manni cite update --dry-run docs/               # see the diffs first"
+    ].join("\n")
+  ).action(async (paths, options, command) => {
+    try {
+      const format = options.format;
+      if (!isUpdateFormat(format)) {
+        throw new CiteError(
+          `Unknown --format "${format}". Use ${COMMON_FORMAT_LIST}.`
+        );
+      }
+      if (!options.checkSources) {
+        throw new CiteError(
+          "update needs the sources: drop --no-check-sources (or `checkSources: false`)."
+        );
+      }
+      const exts = options.ext ? splitList(options.ext) : void 0;
+      const usingStdin = paths.includes(STDIN_TOKEN);
+      const stdinContent = usingStdin ? await readStdin() : void 0;
+      const dryRun = Boolean(options.dryRun);
+      const pageToStdout = usingStdin && !dryRun;
+      const cwd = process.cwd();
+      const run = await runUpdate({
+        inputs: paths,
+        collection: options.collection,
+        exts,
+        exclude: options.exclude,
+        as: options.as,
+        ...configOption(options.config),
+        onConfigLoaded: reportConfig(format === "pretty" && !pageToStdout, cwd),
+        stdinContent,
+        allowEmpty: options.allowEmpty ? true : void 0,
+        respectGitignore: explicitFalse(options.gitignore),
+        onNotice: notice,
+        root: options.root,
+        accept: options.accept ? true : void 0,
+        only: options.only.length > 0 ? options.only : void 0,
+        dryRun
+      });
+      const text = format === "json" ? renderUpdateJson(run) : renderUpdatePretty(run, {
+        color: colorFor(command, process.stdout.isTTY),
+        // The diffs are the point of a dry run; a real run prints
+        // what it rewrote and leaves the file to say the rest.
+        showDiff: dryRun
+      });
+      const stdinPage = pageToStdout ? run.pages.find((page) => page.content !== void 0) : void 0;
+      if (stdinPage?.content !== void 0) {
+        process.stdout.write(stdinPage.content);
+        process.stderr.write(`${text}
+`);
+      } else {
+        process.stdout.write(`${text}
+`);
+      }
+      process.exitCode = run.exitCode;
+    } catch (err) {
+      fail(err);
+    }
+  });
+  return program;
+}
+
+// src/key/cli.ts
+import { Command as Command3 } from "commander";
+
+// src/key/reporters/json.ts
+function renderRotateJson(result) {
+  return JSON.stringify(
+    {
+      pages: result.pages,
+      manifests: result.manifests,
+      reencrypted: result.reencrypted,
+      skipped: result.skipped,
+      keyWritten: result.keyWritten
+    },
+    null,
+    2
+  );
+}
+
+// src/key/reporters/pretty.ts
+var BASELINE_NOTICE = "The citation baseline fingerprints id-less encrypted citations by their pin; re-record it with `manni cite check --write-baseline`.";
+var NARROWED = "Key not written: this run covered part of the family. Finish with a whole run under the same key: `manni key rotate --to <the same value>`.";
+var FROM_ENV = "Key not written: it comes from MANNI_ENCRYPTION_KEY. Update the secret to the value you passed.";
+var plural2 = (n, one, many = `${one}s`) => `${String(n)} ${n === 1 ? one : many}`;
+function setMessage(result) {
+  return result.dryRun ? `Would write encryptionKey to ${result.source}.` : `Encryption key written to ${result.source}.`;
+}
+function shortCiphertext(value) {
+  const colon = value.indexOf(":");
+  const token = colon === -1 ? value : value.slice(0, colon);
+  const suffix = colon === -1 ? "" : value.slice(colon);
+  return `${token.slice(0, 5)}\u2026${suffix}`;
+}
+function nameOf(row) {
+  if (row.kind === "metadata") return row.pointer;
+  if (row.id !== void 0) return row.id;
+  if (row.index !== void 0) return `/citations/${String(row.index)}`;
+  return `line ${String(row.line ?? 0)}`;
+}
+function closing(result) {
+  switch (result.outcome) {
+    case "written":
+      return result.configSource === void 0 ? void 0 : `Encryption key written to ${result.configSource}.`;
+    case "finished":
+      return void 0;
+    case "narrowed":
+      return NARROWED;
+    case "env":
+      return FROM_ENV;
+    case "skipped":
+      return result.skipped === 1 ? "Key not written: 1 value could not be re-encrypted. Fix it and rotate again." : `Key not written: ${String(result.skipped)} values could not be re-encrypted. Fix them and rotate again.`;
+    case "dry-run":
+      return "Dry run: nothing written.";
+  }
+}
+function renderRotatePretty(result, opts) {
+  const c = palette(opts.color);
+  const lines = [];
+  for (const page of result.pages) {
+    for (const row of page.rewritten) {
+      const gap = row.kind === "metadata" ? "  " : " ";
+      lines.push(
+        `${page.file}: ${nameOf(row)}  ${c.dim(shortCiphertext(row.from))}${gap}-> ${shortCiphertext(row.to)}`
+      );
+    }
+    for (const row of page.skipped) {
+      lines.push(`${page.file}: ${nameOf(row)}  ${c.red("skipped:")} ${row.message}`);
+    }
+  }
+  for (const manifest of result.manifests) {
+    for (const row of manifest.rewritten) {
+      lines.push(
+        `${manifest.file}: ${row.entry}${row.pointer}  ${c.dim(shortCiphertext(row.from))}  -> ${shortCiphertext(row.to)}`
+      );
+    }
+    for (const row of manifest.skipped) {
+      lines.push(
+        `${manifest.file}: ${row.entry}${row.pointer}  ${c.red("skipped:")} ${row.message}`
+      );
+    }
+  }
+  if (result.outcome === "finished" && result.configSource !== void 0) {
+    lines.push(`Finished the interrupted rotation in ${result.configSource}.`);
+  }
+  const files = result.pages.filter((page) => page.rewritten.length > 0).length + result.manifests.filter((manifest) => manifest.rewritten.length > 0).length;
+  lines.push(
+    `${plural2(result.reencrypted, "value")} re-encrypted in ${plural2(files, "file")}, ${String(result.skipped)} skipped`
+  );
+  const last = closing(result);
+  if (last !== void 0) lines.push(result.outcome === "skipped" ? c.red(last) : last);
+  if (result.baselineStale) lines.push(BASELINE_NOTICE);
+  return lines.join("\n");
+}
+
+// src/key/cli.ts
+var ROTATE_FORMATS = ["pretty", "json"];
+function isRotateFormat(value) {
+  return ROTATE_FORMATS.includes(value);
+}
+function buildProgram4() {
+  const program = new Command3();
+  program.name("key").description("Set and rotate the family key that encrypted values are encrypted with.").version(package_default.version, "-V, --version").option("--no-color", "disable colored output").showHelpAfterError("(add --help for usage)").exitOverride();
+  const color = () => shouldColor({ noColor: program.opts().color === false, isTTY: process.stdout.isTTY });
+  program.command("set").description("Write the family encryption key to manni.config.yaml; generate one when no value is given").argument("[value]", "the key, at least 32 hex or base64url characters (default: 64 random hex)").option(
+    "-c, --config <path>",
+    "the config file to write (default: the nearest manni.config.yaml, else a new one at the git root)"
+  ).option("--dry-run", "say what would be written; write nothing").addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  manni key set                          # generate 256 bits into manni.config.yaml",
+      "  manni key set --dry-run                # name the file, write nothing",
+      "  manni key set -c ops/manni.config.yaml 0123456789abcdef0123456789abcdef"
+    ].join("\n")
+  ).action(async (value, options) => {
+    try {
+      const result = await runKeySet({
+        value,
+        configPath: options.config,
+        dryRun: Boolean(options.dryRun),
+        onNotice: notice
+      });
+      process.stdout.write(`${setMessage(result)}
+`);
+      process.exitCode = 0;
+    } catch (err) {
+      fail(err);
+    }
+  });
+  program.command("rotate").description("Re-encrypt every encrypted value under a new key, then write the key").argument("[paths...]", "files, directories, or globs (default: every collection)").option(
+    "--to <value>",
+    "the new key (default: 64 random hex); required for a narrowed run and a key from MANNI_ENCRYPTION_KEY"
+  ).option("--collection <name>", "configured collection to run over; repeatable", collect, []).option("--ext <list>", "comma-separated extensions for directory walks").option("--exclude <glob>", "glob to exclude; repeatable", collect, []).option("--as <format>", "force an input format for every input").option("-c, --config <path>", "path to a manni config file").option("--allow-empty", "treat zero matched files as success").option("--no-gitignore", "include files .gitignore covers").option(
+    "--root <dir>",
+    "directory cited sources resolve from (default: cite.root from config, else the git root)"
+  ).option("--dry-run", "print what would change; write nothing").option("-f, --format <format>", `output: ${ROTATE_FORMATS.join(" | ")}`, "pretty").addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  manni key rotate                                   # every collection, then the key",
+      "  manni key rotate --dry-run                         # see every change first",
+      '  manni key rotate --collection site --to "$NEW_KEY" # part of the family',
+      '  MANNI_ENCRYPTION_KEY=\u2026 manni key rotate --to "$NEW_KEY"'
+    ].join("\n")
+  ).action(async (paths, options) => {
+    try {
+      const format = options.format;
+      if (!isRotateFormat(format)) {
+        throw new KeyError(`Unknown --format "${format}". Use ${COMMON_FORMAT_LIST}.`);
+      }
+      const result = await runKeyRotate({
+        inputs: paths,
+        collection: options.collection,
+        to: options.to,
+        exts: options.ext ? splitList(options.ext) : void 0,
+        exclude: options.exclude,
+        as: options.as,
+        configPath: options.config,
+        // `undefined` rather than `false` when absent.
+        allowEmpty: options.allowEmpty ? true : void 0,
+        respectGitignore: explicitFalse(options.gitignore),
+        root: options.root,
+        dryRun: Boolean(options.dryRun),
+        onNotice: notice
+      });
+      if (format === "json") {
+        process.stdout.write(`${renderRotateJson(result)}
+`);
+        if (result.baselineStale) notice(BASELINE_NOTICE);
+      } else {
+        process.stdout.write(`${renderRotatePretty(result, { color: color() })}
+`);
+      }
+      process.exitCode = result.exitCode;
+    } catch (err) {
+      fail(err);
+    }
+  });
+  return program;
+}
+
+// src/cli.ts
+function buildProgram5() {
   const meta = buildProgram().name("meta").description(
     "Validate, read, query and fill document metadata against JSON Schema"
   );
   const metaCommands = new Set(meta.commands.map((c) => c.name()));
-  const program = new Command2();
+  const program = new Command4();
   program.name("manni").description("Tools for documentation that is meant to be checked.").version(package_default.version, "-V, --version").showHelpAfterError("(add --help for usage)").exitOverride().configureOutput({
     outputError: (str, write) => {
       write(str);
@@ -965,10 +1488,18 @@ function buildProgram3() {
       "Crawl a site and check every page for accessibility violations with axe-core"
     )
   );
+  program.addCommand(
+    buildProgram3().name("cite").description(
+      "Track citations from doc claims to source lines and check them for drift"
+    )
+  );
+  program.addCommand(
+    buildProgram4().name("key").description("Set and rotate the family key that encrypted values are encrypted with.")
+  );
   return program;
 }
-runIfMain(import.meta.url, buildProgram3);
+runIfMain(import.meta.url, buildProgram5);
 export {
-  buildProgram3 as buildProgram
+  buildProgram5 as buildProgram
 };
 //# sourceMappingURL=cli.js.map