@opum-ai/lore 0.1.0 → 0.2.0

package/src/commands/replace.ts

@@ -1,320 +0,0 @@
-/**
- * commands/replace.ts — `lore replace <find> <replace> [--regex] [--in <glob>…] [--dry-run]`.
- *
- * The thin, side-effecting layer over the pure replace engine (cli-surface §replace): it parses the
- * command's own arguments, compiles the pattern **once** (so a bad pattern fails even when discovery
- * finds nothing), **discovers** the target markdown files (a default whole-bundle walk of `docs/`, or
- * the explicit `--in <glob>` set), reads their bytes, asks core to rewrite each — skipping every
- * lore-managed region (AC#1) — writes back the genuinely-changed files (unless `--dry-run`), renders a
- * per-file report, and returns the exit code. All file discovery and I/O live here; the
- * never-touch-managed-regions judgement lives in `core/replace.ts`.
- *
- * Discovery is hardened so a refactor can neither escape the bundle nor corrupt machine-owned files:
- * targets are `.md` only (a glob match on `mkdocs.yml` is left alone); a **symlink** is skipped (it
- * could resolve outside the repo, and `walkMarkdown` skips them too); files are de-duplicated by
- * **canonical identity** so one physical file reached two ways is rewritten once (never double-applied);
- * the fully-generated `log.md` is excluded (it is regenerated wholesale, so editing it is futile); and
- * an absolute `--in` glob resolves correctly. Reads and replacements for **all** files complete before
- * **any** write, so a bad pattern or an unreadable file aborts the run before it has changed a single
- * file on disk. Each individual write in that commit phase is itself atomic (LORE-116,
- * `writeFileAtomic`'s temp-file+rename discipline), so a crash or I/O error partway through a single
- * file's write can never leave that file truncated or half-written.
- *
- * A bad flag, an invalid/empty/zero-width pattern is a `usage` error (exit 2); an unreadable path an
- * I/O failure — both funnel through the router's one error seam like every command.
- */
-
-import { lstatSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { walkMarkdown } from "../core/bundle";
-import { compileReplacer, type Replacer } from "../core/replace";
-import { DOCS_DIR } from "../core/scaffold";
-import { EXIT_OK, LoreError, singleLine, stripAnsiAndControls, WarningCollector, type Writer } from "../errors";
-import { emit, type OutputContext, type Renderable } from "../output";
-import { optionValues, parseCommandArgs } from "./args";
-import { canonicalIdentity, readSource, toRepoRelative, withinRepo } from "./discover";
-import { writeFileAtomic } from "./fswrite";
-
-/** The reserved, fully git-derived file `lore` regenerates wholesale; editing it via `replace` is futile. */
-const GENERATED_FILE = "log.md";
-
-/** Options for {@link runReplace}; `root` and the streams are injectable for tests. */
-export interface ReplaceOptions {
-  /** The repo root the bundle (and any `--in` globs) resolve against. */
-  root: string;
-  /** The resolved output mode/color (from `output.ts`). */
-  output: OutputContext;
-  /** The command's normalized positional + flag tokens from Commander. */
-  args: readonly string[];
-  /** stdout sink; defaults to `process.stdout`. */
-  stdout?: Writer;
-  /** stderr sink for discovery advisories; defaults to `process.stderr`. */
-  stderr?: Writer;
-}
-
-/** The parsed form of `lore replace`'s arguments. */
-interface ReplaceArgs {
-  /** The find pattern (literal text, or a regex source under `--regex`). */
-  find: string;
-  /** The replacement (literal, or with `$1`/`$&` substitutions under `--regex`). */
-  replace: string;
-  /** `--regex`: treat `find` as a JavaScript regular expression. */
-  regex: boolean;
-  /** `--in <glob>` scopes (repeatable); empty means the whole `docs/` bundle. */
-  in: string[];
-  /** `--dry-run`: report what would change, write nothing. */
-  dryRun: boolean;
-}
-
-/** One discovered file: its repo-relative display path and the absolute path to read/write. */
-interface Target {
-  /** Repo-relative POSIX path, for the report. */
-  readonly display: string;
-  /** Absolute filesystem path (canonical), for reading and writing. */
-  readonly abs: string;
-}
-
-/** A planned write: a file whose bytes genuinely changed. */
-interface PlannedChange {
-  readonly display: string;
-  readonly abs: string;
-  readonly text: string;
-  readonly count: number;
-}
-
-/** One file's replacement tally, for the report. */
-interface FileChange {
-  /** Repo-relative POSIX path of the changed file. */
-  readonly path: string;
-  /** Matches replaced in that file (outside managed regions). */
-  readonly count: number;
-}
-
-/** The `replace.result` payload: the changed files and the run totals. */
-export interface ReplaceReport {
-  /** Per changed file, in ascending path order; files with no real change are omitted. */
-  readonly files: readonly FileChange[];
-  /** Total matches replaced across the bundle. */
-  readonly totalMatches: number;
-  /** How many files changed. */
-  readonly filesChanged: number;
-  /** How many `.md` files were examined. */
-  readonly filesScanned: number;
-  /** Whether this was a `--dry-run` (nothing was written). */
-  readonly dryRun: boolean;
-}
-
-/**
- * Run `lore replace`: parse the arguments, compile the pattern, discover and read the target markdown,
- * rewrite each outside its managed regions, write the genuinely-changed files (unless `--dry-run`),
- * emit the `replace.result`, and return `0`. A bad flag/positional or an invalid/empty/zero-width
- * pattern throws a `usage` {@link LoreError} (exit `2`); an unreadable bundle/path a
- * `not_found`/`denied`.
- */
-export function runReplace(options: ReplaceOptions): number {
-  const parsed = parseReplaceArgs(options.args);
-  // Compile (and validate) the pattern ONCE, before discovery — so an invalid/empty/zero-width pattern
-  // fails fast even when no file matches, instead of slipping through a per-file loop that never runs.
-  const replacer: Replacer = compileReplacer(parsed.find, parsed.replace, { regex: parsed.regex });
-
-  const advisories = new WarningCollector();
-  const targets = discoverFiles(options.root, parsed.in, advisories);
-
-  // Phase 1 — read + replace every target into a plan. No write happens until every file has been read
-  // and rewritten, so a read error or a no-match file can't leave the bundle half-rewritten.
-  const planned: PlannedChange[] = [];
-  for (const target of targets) {
-    const original = readSource(target.abs, target.display);
-    const { text, count } = replacer(original);
-    if (count === 0 || text === original) {
-      continue; // gate on a REAL byte change, so a no-op (e.g. find === replace) never churns a file
-    }
-    planned.push({ display: target.display, abs: target.abs, text, count });
-  }
-
-  // Phase 2 — commit the writes (unless dry-run). Each file goes through writeFileAtomic (LORE-116)
-  // rather than the plain writeFileOverwriting: a crash, kill, or I/O error (e.g. disk full) partway
-  // through a single file's write must never leave that target truncated or half-written — the same
-  // temp-file+rename discipline `lore sync` already relies on for the identical reason. This is
-  // per-file atomicity only, not a whole-run transaction: a failure partway through this loop still
-  // leaves earlier files in this run already committed (by design — there is no cross-file rollback
-  // here, matching `writeAllOrRollback`'s docstring, which notes that broader transactional rollback
-  // for `lore replace` is a separate, deferred concern) and the loop's own error propagates uncaught
-  // so the failure is never silently swallowed.
-  if (!parsed.dryRun) {
-    for (const change of planned) {
-      writeFileAtomic(change.abs, change.text, change.display);
-    }
-  }
-
-  const report: ReplaceReport = {
-    files: planned.map((c) => ({ path: c.display, count: c.count })),
-    totalMatches: planned.reduce((sum, c) => sum + c.count, 0),
-    filesChanged: planned.length,
-    filesScanned: targets.length,
-    dryRun: parsed.dryRun,
-  };
-  emit(reportRenderable(report), options.output, options.stdout);
-  advisories.flush({ color: options.output.color, stderr: options.stderr });
-  return EXIT_OK;
-}
-
-// ── Argument parsing ───────────────────────────────────────────────────────────
-
-/**
- * Parse `replace`'s tokens into its two positionals (`<find> <replace>`) and flags. The router has
- * already stripped lore's global flags, so a `--`-prefixed token here is a command flag: an
- * unrecognized one is a `usage` error. `--in` takes a value (inline `=` or the next token, which may
- * not itself be a flag), and a `--` ends option parsing so a `find`/`replace` may begin with `-`.
- */
-function parseReplaceArgs(args: readonly string[]): ReplaceArgs {
-  const parsed = parseCommandArgs(args, "replace");
-  const positionals = parsed.positionals;
-  const find = positionals[0];
-  if (find === undefined) {
-    throw usage("`lore replace` needs a find and a replace argument", 'run `lore replace "<find>" "<replace>"`');
-  }
-  const replace = positionals[1];
-  if (replace === undefined) {
-    throw usage(
-      "`lore replace` needs a replacement argument",
-      'pass the replacement text, e.g. `lore replace "old" "new"` (use "" to delete matches)',
-    );
-  }
-  if (positionals.length > 2) {
-    throw usage(
-      `unexpected argument "${positionals[2]}"`,
-      "pass exactly a find and a replace; quote values containing spaces, and scope with --in <glob>",
-    );
-  }
-  return {
-    find,
-    replace,
-    regex: parsed.flags.has("regex"),
-    in: [...optionValues(parsed, "in")],
-    dryRun: parsed.flags.has("dry-run"),
-  };
-}
-
-// ── File discovery ─────────────────────────────────────────────────────────────
-
-/**
- * Discover the `.md` files to rewrite as canonical {@link Target}s in ascending display order. With no
- * `--in` the target is the whole `docs/` bundle, walked the same way the loader does
- * ({@link walkMarkdown} — sorted, symlink-safe, `.md`-only). With `--in`, each pattern is expanded by
- * `Bun.Glob` relative to the repo root and filtered: `.md` only, no symlink (it could resolve outside
- * the repo, and `walkMarkdown` skips them too), inside the repo, never the reserved `log.md`. Both
- * paths de-duplicate by {@link canonicalIdentity}, so one physical file reached two ways (a symlink, a
- * case variant, or once directly and once via a walked directory) is rewritten exactly once.
- */
-function discoverFiles(root: string, patterns: readonly string[], warnings: WarningCollector): Target[] {
-  const seen = new Set<string>();
-  const targets: Target[] = [];
-  const add = (abs: string, display: string): void => {
-    const id = canonicalIdentity(abs);
-    if (seen.has(id)) {
-      return; // same physical file already queued
-    }
-    seen.add(id);
-    targets.push({ display, abs });
-  };
-
-  if (patterns.length === 0) {
-    const docsRoot = join(root, DOCS_DIR);
-    for (const rel of walkMarkdown(docsRoot, warnings)) {
-      if (basename(rel) === GENERATED_FILE) {
-        continue; // log.md is regenerated wholesale — never an author-editable target
-      }
-      add(join(docsRoot, rel), `${DOCS_DIR}/${rel}`);
-    }
-  } else {
-    for (const pattern of patterns) {
-      for (const match of new Bun.Glob(pattern).scanSync({ cwd: root, onlyFiles: true })) {
-        // `resolve` (not `join`): Bun.Glob returns a path relative to cwd for a relative pattern but an
-        // ABSOLUTE path for an absolute pattern — `resolve(root, abs)` returns it as-is rather than
-        // doubling `root` onto it (a plain `join` would mangle an absolute --in glob).
-        const abs = resolve(root, match);
-        if (!match.endsWith(".md")) {
-          continue; // replace edits the bundle's markdown only
-        }
-        if (basename(match) === GENERATED_FILE) {
-          warnings.add(`skipping "${match}": log.md is regenerated wholesale and is not editable via replace`);
-          continue;
-        }
-        if (isSymlink(abs)) {
-          warnings.add(`skipping symlink "${match}": symlinks are not followed (it may resolve outside the bundle)`);
-          continue;
-        }
-        if (!withinRepo(root, abs)) {
-          warnings.add(`skipping "${match}": outside the repo root`);
-          continue;
-        }
-        add(abs, toRepoRelative(root, abs));
-      }
-    }
-  }
-  return targets.sort((a, b) => (a.display < b.display ? -1 : a.display > b.display ? 1 : 0));
-}
-
-/** Whether the entry at `abs` is a symlink (a vanished/unstattable entry is treated as not-a-symlink; the read raises the real error). */
-function isSymlink(abs: string): boolean {
-  try {
-    return lstatSync(abs).isSymbolicLink();
-  } catch {
-    return false;
-  }
-}
-
-// ── Output ─────────────────────────────────────────────────────────────────────
-
-/** The per-result-type rendering bundle for `replace` (output.ts dispatches on the mode). */
-function reportRenderable(data: ReplaceReport): Renderable<ReplaceReport> {
-  return {
-    kind: "replace.result",
-    data,
-    pretty: (report) => render(report),
-    plain: (report) => render(report),
-  };
-}
-
-/**
- * One line per changed file, then a summary line. (No color: the report carries no severities.)
- * Each file's `path` is sanitized ({@link sanitizeField}) before interpolation — it is a discovered
- * display path derived from real filesystem entries, so a crafted/unusual filename could otherwise
- * smuggle an ANSI escape sequence or an embedded newline into the rendered report (LORE-229).
- */
-function render(data: ReplaceReport): string {
-  const verb = data.dryRun ? "would replace" : "replaced";
-  const lines = data.files.map((f) => `${verb} ${f.count} in ${sanitizeField(f.path)}`);
-  lines.push(summaryLine(data));
-  return lines.join("\n");
-}
-
-/**
- * Sanitize a discovered file path before it is interpolated into the plain/pretty report: collapse
- * it to one line ({@link singleLine}) and strip ANSI escape sequences plus residual C0/C1 control
- * bytes ({@link stripAnsiAndControls}) — mirrors `query.ts`'s `sanitizeField` (LORE-118), for the
- * same reason: an untrusted, filesystem-derived path can carry attacker-influenced bytes.
- */
-function sanitizeField(text: string): string {
-  return stripAnsiAndControls(singleLine(text));
-}
-
-/** The trailing summary: total matches, files changed of scanned, and a `(dry-run)` marker. */
-function summaryLine(data: ReplaceReport): string {
-  const head = `${data.totalMatches} ${plural(data.totalMatches, "match", "matches")} in ${data.filesChanged} of ${data.filesScanned} ${plural(data.filesScanned, "file")}`;
-  return data.dryRun ? `${head} (dry-run)` : head;
-}
-
-/** Pluralize a noun by count, with an optional explicit plural for irregulars. */
-function plural(count: number, noun: string, plural?: string): string {
-  if (count === 1) {
-    return noun;
-  }
-  return plural ?? `${noun}s`;
-}
-
-/** A `usage` {@link LoreError} (exit `2`) with an actionable hint. */
-function usage(message: string, hint: string): LoreError {
-  return new LoreError("usage", message, hint);
-}

package/src/commands/scaffold.ts

@@ -1,346 +0,0 @@
-/**
- * commands/scaffold.ts — `lore scaffold <target> [--force]`: generate a downstream documentation
- * consumer's config, additively and outside `docs/` (cli-surface §"Consumer scaffolding", ADR-0010).
- *
- * The thin, side-effecting layer over the pure {@link buildMkdocsScaffold} / {@link buildDocusaurusScaffold} /
- * {@link buildObsidianScaffold} (`core/consumer-scaffold.ts`): it resolves the repo root, the active profile, and a clock, asks core for the exact bytes, and
- * applies them via `fswrite.ts`'s shared {@link writeAllOrRollback}. Unlike `lore init` (which
- * silently skips an already-present file), scaffolding is **never-silent-clobber**: a planned file
- * whose on-disk bytes would differ from what this run would generate blocks the whole run with a
- * `conflict` error (exit 5) naming every such collision, and writes nothing — `--force` is required
- * to overwrite. But a planned file that already exists with **byte-identical** content is not a
- * collision at all (LORE-263): re-running `lore scaffold <target>` on an already-scaffolded,
- * untouched bundle is idempotent — exit `0`, nothing written, mirroring `lore sync`'s own
- * "0 files changed" no-op model — rather than making the user hand-edit the file or remember
- * `--force` just to re-assert a config nothing actually changed. The classification (via
- * `fswrite.ts`'s {@link classifyExistingFile}) is per-file, so a partially-recreated bundle (one
- * generated file present and unchanged, its sibling separately deleted) recreates only the missing
- * file rather than refusing the whole run. This is still all-or-nothing where it matters — the
- * plan-wide pre-flight below, backstopped by `writeAllOrRollback`'s own atomic per-file create and
- * rollback — so a partial *collision*, or a mid-run I/O failure (e.g. a read-only `docs/`), can
- * never leave one scaffolded file refreshed and its sibling stale.
- *
- * `mkdocs`'s `docs/tags.md` stamps a `timestamp` into its own frontmatter (a real wall-clock read
- * by default — see {@link ScaffoldOptions.clock}), which would otherwise defeat the idempotent
- * byte-compare above on every real (non-test) bare re-run: two runs a second apart regenerate
- * different bytes purely because time moved forward, even though the user touched nothing, so
- * `classifyExistingFile` would report "differs" and the run would still hard-error. A bare
- * (non `--force`) `mkdocs` run avoids that by reusing the on-disk `docs/tags.md`'s own `timestamp`
- * field (via {@link preservedTagsTimestamp}) instead of a fresh `clock()` read, so an otherwise
- * untouched bundle compares byte-identical regardless of how much wall-clock time has passed.
- * `--force` is unaffected — it always stamps a fresh timestamp, since its whole point is to
- * regenerate the file.
- *
- * `mkdocs`, `docusaurus`, and `obsidian` are implemented; any other target string is a `usage`
- * error (exit 2).
- */
-
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { tryReadFrontmatter } from "../core/concept";
-import {
-  buildDocusaurusScaffold,
-  buildMkdocsScaffold,
-  buildObsidianScaffold,
-  type ConsumerScaffoldFile,
-  type ConsumerScaffoldOptions,
-  type ConsumerScaffoldPlan,
-  TAGS_INDEX_REL_PATH,
-} from "../core/consumer-scaffold";
-import { loadProfile } from "../core/profile";
-import { EXIT_OK, LoreError, type Writer } from "../errors";
-import { emit, type OutputContext, type Renderable } from "../output";
-import { parseCommandArgs, usage } from "./args";
-import { classifyExistingFile, writeAllOrRollback } from "./fswrite";
-
-/** Options for {@link runScaffold}; `root`, `clock`, and the stream are injectable for tests. */
-export interface ScaffoldOptions {
-  /** The repo root to scaffold into. */
-  root: string;
-  /** The resolved output mode/color (from `output.ts`). */
-  output: OutputContext;
-  /** The command's normalized positional + flag tokens from Commander. */
-  args: readonly string[];
-  /** stdout sink; defaults to `process.stdout`. */
-  stdout?: Writer;
-  /**
-   * Clock seam for `docs/tags.md`'s timestamp; defaults to the real wall clock. Only actually
-   * consulted for a fresh stamp on a `--force` run, or on a bare run with no usable on-disk
-   * `docs/tags.md` timestamp to preserve — see {@link preservedTagsTimestamp}.
-   */
-  clock?: () => Date;
-}
-
-/** One file the scaffold wrote (or, under `--force`, overwrote). */
-export interface ScaffoldResultFile {
-  /** Repo-relative POSIX path. */
-  readonly path: string;
-  /** Whether this run created the file fresh or overwrote a pre-existing one (`--force` only). */
-  readonly action: "created" | "updated";
-}
-
-/** The result of a `lore scaffold` run. */
-export interface ScaffoldResult {
-  /** The target that was scaffolded (`"mkdocs"`, `"docusaurus"`, or `"obsidian"`). */
-  readonly target: string;
-  /** Whether `--force` was passed. */
-  readonly force: boolean;
-  /**
-   * Every file this run actually wrote, in scaffold order. A planned file already on disk with
-   * byte-identical content is never included here (LORE-263) — it was left untouched, not written —
-   * so an idempotent no-op re-run (every planned file already matches) reports an empty array here,
-   * exactly like `lore sync`'s own "0 files changed".
-   */
-  readonly files: readonly ScaffoldResultFile[];
-  /** Extra guidance lines to print after the summary (empty unless the target's plan carries any — see {@link ConsumerScaffoldPlan.notes}). */
-  readonly notes: readonly string[];
-}
-
-/**
- * Every implemented target's pure plan builder — the single source of truth for which targets
- * `lore scaffold` can actually build. {@link TARGETS} is *derived* from this map's keys, so a
- * target can never be accepted by argument validation without a registered builder to route to —
- * the failure mode a hand-written per-target `if`/ternary chain invites the moment a third target
- * is added.
- */
-const BUILDERS: Record<string, (options: ConsumerScaffoldOptions) => ConsumerScaffoldPlan> = {
-  mkdocs: buildMkdocsScaffold,
-  docusaurus: buildDocusaurusScaffold,
-  obsidian: buildObsidianScaffold,
-};
-
-/** The consumer targets `lore scaffold` recognizes as valid (derived from {@link BUILDERS}'s own keys). */
-export const TARGETS = new Set(Object.keys(BUILDERS));
-
-/** The validated arguments {@link applyScaffold} needs — `root`/`target`/`force` plus an injectable clock. */
-export interface ApplyScaffoldOptions {
-  /** The repo root to scaffold into. */
-  root: string;
-  /** One of {@link TARGETS} (`"mkdocs"`, `"docusaurus"`, `"obsidian"`). */
-  target: string;
-  /** `--force`: overwrite an existing generated config, skipping the collision preflight. */
-  force: boolean;
-  /** Clock seam for `docs/tags.md`'s timestamp; defaults to the real wall clock. */
-  clock?: () => Date;
-}
-
-/**
- * Build `target`'s plan, then — unless `force` — classify every planned file against what's already
- * on disk (LORE-263) and write it: the pure side-effecting core of `lore scaffold`, extracted
- * (LORE-260) so `lore init`'s wizard/flags can fold a downstream-consumer scaffold into one
- * onboarding run without going through `runScaffold`'s own arg-parsing/emit (which would print a
- * second, separate envelope onto the SAME stdout `lore init` owns — the `--json` contract requires
- * stdout be exclusively `init`'s own envelope, cli-contract §4).
- *
- * - any planned file whose on-disk bytes DIFFER from what this run would generate, or a
- *   structural directory blocker, refuses the whole run with a `conflict` error (exit `5`) naming
- *   every such collision and pointing at `--force`, writing nothing;
- * - otherwise, only the planned files that are genuinely ABSENT are written — a planned file
- *   already on disk with byte-identical content is left untouched, so a bare re-run of an
- *   unchanged bundle writes nothing at all and still exits `0` (idempotent no-op).
- *
- * `force` skips this classification entirely and overwrites every planned file, unchanged from
- * before. `target` must already be validated against {@link TARGETS} — an unregistered target throws
- * an internal `Error`, not a `usage` {@link LoreError} (the caller owns argument validation).
- */
-export function applyScaffold(options: ApplyScaffoldOptions): ScaffoldResult {
-  const { root, target, force } = options;
-  const clock = options.clock ?? (() => new Date());
-  // Only mkdocs's builder reads `profile` (to decide docs/tags.md's $schema modeline) — loading
-  // it unconditionally for every target would make `lore scaffold docusaurus` fail on a malformed
-  // .lore/profile.toml/json it never reads, contradicting ConsumerScaffoldOptions.profile's own
-  // "unused by buildDocusaurusScaffold" contract.
-  const profile = target === "mkdocs" ? loadProfile({ root }) : undefined;
-  const build = BUILDERS[target];
-  if (!build) {
-    // Callers validate `target` against TARGETS (derived from BUILDERS' own keys) before calling —
-    // this can only fire if that invariant is ever broken.
-    throw new Error(`internal: no builder registered for target "${target}"`);
-  }
-  // A bare mkdocs run reuses docs/tags.md's own on-disk timestamp (when there's one to preserve)
-  // instead of always stamping a fresh clock() read — see the module docstring and
-  // preservedTagsTimestamp's own doc for why this is load-bearing for LORE-263's idempotency
-  // guarantee. --force always wants a fresh stamp (it's regenerating the file outright), and
-  // docusaurus/obsidian ignore `timestamp` entirely, so neither needs this.
-  const timestamp = target === "mkdocs" && !force ? preservedTagsTimestamp(root, clock) : clock().toISOString();
-  const plan = build({
-    timestamp,
-    siteName: basename(resolve(root)),
-    profile,
-  });
-
-  // Under --force every planned file is (re)written, exactly as before LORE-263; under a bare
-  // run it narrows to only the files actually missing (below) once the collision check clears.
-  let filesToWrite: readonly ConsumerScaffoldFile[] = plan.files;
-
-  if (!force) {
-    const blockedDirs = plan.dirs.filter((dir) => {
-      const abs = join(root, dir);
-      return existsSync(abs) && !statSync(abs).isDirectory();
-    });
-    // Per-file, not per-plan: classifyExistingFile tells "absent" (needs creating), "unchanged"
-    // (already matches — leave it alone, not a collision) and "differs" (a real user edit — a
-    // collision) apart, rather than the old plain-existence check that treated every already-there
-    // file as a collision regardless of its content.
-    const statuses = plan.files.map((file) => ({
-      file,
-      status: classifyExistingFile(join(root, file.path), file.contents),
-    }));
-    const differingFiles = statuses.filter((s) => s.status === "differs").map((s) => s.file.path);
-    const collisions = [...blockedDirs, ...differingFiles];
-    if (collisions.length > 0) {
-      throw new LoreError(
-        "conflict",
-        `${target} config already exists: ${collisions.join(", ")}`,
-        conflictHint(blockedDirs.length > 0, differingFiles.length > 0),
-        { target, paths: collisions },
-      );
-    }
-    filesToWrite = statuses.filter((s) => s.status === "missing").map((s) => s.file);
-  }
-
-  const files = writeAllOrRollback(root, plan.dirs, filesToWrite, { force });
-
-  return { target, force, files, notes: plan.notes ?? [] };
-}
-
-/**
- * Run `lore scaffold <target>`: the thin CLI layer over {@link applyScaffold} — parse the arguments,
- * apply the scaffold, render the result, and return the exit code. An unknown target, or a bad
- * flag/extra argument, throws a `usage` {@link LoreError} (exit `2`) before {@link applyScaffold}
- * ever runs.
- */
-export function runScaffold(options: ScaffoldOptions): number {
-  const parsed = parseScaffoldArgs(options.args);
-  const result = applyScaffold({
-    root: options.root,
-    target: parsed.target,
-    force: parsed.force,
-    clock: options.clock,
-  });
-  emit(scaffoldRenderable(result), options.output, options.stdout);
-  return EXIT_OK;
-}
-
-/**
- * The timestamp a bare (non `--force`) `lore scaffold mkdocs` run stamps into `docs/tags.md`'s
- * regenerated frontmatter (LORE-263 follow-up): the on-disk file's own `timestamp` field, when
- * there's one to reuse, rather than always a fresh `clock()` read. Without this, an otherwise
- * completely untouched `docs/tags.md` would regenerate different bytes on every real re-run
- * (the timestamp always advances with the wall clock) even though nothing the user controls
- * changed, so `classifyExistingFile` would report "differs" and the run would hard-error exactly
- * the way idempotent-when-unchanged is supposed to prevent. This only decides which timestamp
- * string goes into the freshly rebuilt plan bytes — the actual byte comparison against what's on
- * disk still happens afterward via {@link classifyExistingFile}, so a file that differs for any
- * OTHER reason (a hand-edited title, body, or `$schema` modeline) is still correctly classified
- * "differs" and still blocks the run.
- *
- * Reads via the shared {@link tryReadFrontmatter} (frontmatter mapping only, no schema
- * validation) rather than the full `parseConcept`, since a file that's otherwise a byte-identical
- * regenerate is exactly the case this must handle, and schema validation is an orthogonal
- * concern. Falls back to `clock().toISOString()` — the timestamp a fresh scaffold has always
- * used — whenever there's nothing usable to reuse: `docs/tags.md` is absent or unreadable, its
- * YAML frontmatter doesn't parse at all (a genuinely malformed file must still flow through to
- * the normal "differs" collision path with *some* deterministic timestamp, not fail this whole
- * command), or its `timestamp` field isn't present as a string.
- */
-function preservedTagsTimestamp(root: string, clock: () => Date): string {
-  const fresh = () => clock().toISOString();
-  let raw: string;
-  try {
-    raw = readFileSync(join(root, TAGS_INDEX_REL_PATH), "utf8");
-  } catch {
-    return fresh(); // absent, or unreadable -- nothing on disk to preserve
-  }
-  let frontmatter: Record<string, unknown> | null;
-  try {
-    frontmatter = tryReadFrontmatter(TAGS_INDEX_REL_PATH, raw);
-  } catch {
-    return fresh(); // unparseable YAML -- let the normal "differs" collision path handle the file itself
-  }
-  const timestamp = frontmatter?.timestamp;
-  return typeof timestamp === "string" ? timestamp : fresh();
-}
-
-/**
- * Build the preflight `conflict` error's remedy hint, differentiated by which kind(s) of
- * collision were found. A structural directory blocker — a plain (non-directory) file occupying
- * a path the plan needs to be a directory — is NOT fixed by `--force`: under `--force` this same
- * preflight is skipped entirely and the run reaches `writeAllOrRollback` -> `ensureDir`
- * (fswrite.ts) -> `mkdirSync(dir, { recursive: true })`, which throws `EEXIST` on the same
- * non-directory entry, remapped by `ioError` to a second `conflict` (fswrite.ts's own
- * `conflictError`). So the hint must never tell the user `--force` will overwrite a dir-blocker —
- * only removing/renaming the blocking entry does. A planned file whose on-disk bytes DIFFER from
- * what this run would generate (LORE-263 — a byte-identical match is never a collision at all, see
- * {@link classifyExistingFile}) is genuinely fixed by `--force` (writeAllOrRollback overwrites it
- * in place), so that remedy is preserved whenever at least one such file collision is present.
- */
-function conflictHint(hasDirBlocker: boolean, hasFileCollision: boolean): string {
-  if (hasDirBlocker && hasFileCollision) {
-    return "pass --force to overwrite the existing file(s); separately, remove or rename the non-directory entry blocking the planned directory (--force cannot fix that one)";
-  }
-  if (hasDirBlocker) {
-    return "remove or rename the non-directory entry that is blocking the planned directory, then re-run";
-  }
-  return "pass --force to overwrite, or remove the existing file(s) first";
-}
-
-// ── Argument parsing ───────────────────────────────────────────────────────────
-
-/** The parsed form of `lore scaffold`'s arguments. */
-interface ScaffoldArgs {
-  /** The validated, implemented target (`"mkdocs"` or `"docusaurus"` today). */
-  target: string;
-  /** `--force`: overwrite an existing generated config. */
-  force: boolean;
-}
-
-/**
- * Parse `scaffold`'s tokens into the `<target>` positional and `--force`, via the shared
- * shared Commander-backed parser every no-value-flag command uses. An unknown flag, an
- * extra positional, or a missing target is a `usage` error.
- */
-function parseScaffoldArgs(args: readonly string[]): ScaffoldArgs {
-  const { positionals, flags } = parseCommandArgs(args, "scaffold");
-
-  const target = positionals[0];
-  if (target === undefined) {
-    throw usage(
-      "`lore scaffold` needs a target",
-      "pass a target, e.g. `lore scaffold mkdocs` (mkdocs | docusaurus | obsidian)",
-    );
-  }
-  if (positionals.length > 1) {
-    throw usage(`unexpected argument "${positionals[1]}"`, "run `lore scaffold <target> [--force]`");
-  }
-  if (!TARGETS.has(target)) {
-    throw usage(`unknown scaffold target "${target}"`, "valid targets are mkdocs, docusaurus, obsidian");
-  }
-  return { target, force: flags.has("force") };
-}
-
-// ── Output ─────────────────────────────────────────────────────────────────────
-
-/** The per-result-type rendering bundle for `scaffold` (output.ts dispatches on the mode). */
-function scaffoldRenderable(data: ScaffoldResult): Renderable<ScaffoldResult> {
-  return { kind: "scaffold.result", data, pretty: render, plain: render };
-}
-
-/**
- * One `<action> <path>` line per file, then a one-line summary, then any target-specific guidance
- * notes. A bare (non `--force`) re-run where every planned file already matched what would be
- * generated (LORE-263) writes nothing at all — `files.length === 0` only happens in that idempotent
- * case, since a `--force` run always (re)writes the whole, non-empty plan — so that case gets a
- * distinct "nothing to do" line instead of reading as "scaffolded ... (0 files)", mirroring `lore
- * sync`'s own "0 files changed" no-op summary.
- */
-function render(data: ScaffoldResult): string {
-  const lines = data.files.map((file) => `${file.action} ${file.path}`);
-  lines.push(
-    data.files.length === 0
-      ? `${data.target} config already up to date — nothing to do`
-      : `scaffolded ${data.target} config (${data.files.length} file${data.files.length === 1 ? "" : "s"})`,
-  );
-  lines.push(...data.notes);
-  return lines.join("\n");
-}