@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/commands/init/command.ts

@@ -0,0 +1,238 @@
+/**
+ * `untangle init` as the CLI shell sees it.
+ *
+ * This is the ONLY file of the command that knows about argv, exit codes and
+ * a terminal. Everything else (`run.ts` and below) is a library over ports,
+ * which is why the whole detection pipeline is testable without a process,
+ * without a network and without `node:fs`.
+ */
+
+import path from "node:path";
+
+import { boolFlag, enumFlag, stringFlag, type FlagSpecs, type ParsedArgs } from "../../cli/args.js";
+import type { Command, CommandContext } from "../../cli/command.js";
+import { EXIT, UsageError } from "../../cli/exit.js";
+import { line, note, processIo } from "../../cli/io.js";
+
+import { formatTextReport } from "./report.js";
+import { CONFIG_FILE_NAME, runInit, type InitDepsV1, type InitOptionsV1 } from "./run.js";
+import { createWizardTerminal } from "./wizard-terminal.js";
+import { runInitWizard, type InitWizardDepsV1 } from "./wizard.js";
+
+const FLAGS: FlagSpecs = {
+  interactive: {
+    kind: "boolean",
+    describe: "Guided terminal setup. --no-interactive keeps the scriptable config-only workflow.",
+    defaultLabel: "automatic only on an interactive terminal, text output and online mode",
+  },
+  root: {
+    kind: "string",
+    placeholder: "PATH",
+    describe: `Project directory where ${CONFIG_FILE_NAME} is written.`,
+    defaultLabel: "current directory",
+  },
+  force: {
+    kind: "boolean",
+    describe: `Overwrite an existing ${CONFIG_FILE_NAME}.`,
+  },
+  "dry-run": {
+    kind: "boolean",
+    describe: "Preview what would be created. Writes nothing.",
+  },
+  offline: {
+    kind: "boolean",
+    describe: "No network probes; local LanceDB setup remains available.",
+  },
+  storage: {
+    kind: "string",
+    placeholder: "lancedb|qdrant",
+    describe:
+      "Search storage backend. LanceDB keeps the index in the project without a service; Qdrant is an explicit opt-in.",
+    defaultLabel: "lancedb for new projects; existing explicit backend is preserved",
+  },
+  "embedding-model": {
+    kind: "string",
+    placeholder: "NAME",
+    describe: "Select a specific embedding model instead of automatic discovery.",
+    defaultLabel: "largest context window",
+  },
+  vision: {
+    kind: "string",
+    placeholder: "PATH",
+    describe: "Vision for local document inspection; path relative to the project directory.",
+  },
+  spec: {
+    kind: "string",
+    placeholder: "PATH",
+    describe:
+      "Specification for local document inspection; path relative to the project directory.",
+  },
+  "feature-map": {
+    kind: "string",
+    placeholder: "PATH",
+    describe:
+      "Declared feature map for local evidence inspection; relative to the project directory.",
+    defaultLabel: "untangle.features.json",
+  },
+  format: {
+    kind: "string",
+    placeholder: "text|json",
+    describe: "Output format. `json` contains all findings, including the skip ledger.",
+    defaultLabel: "text",
+  },
+};
+
+/** argv → options. Rejects the ambiguous call rather than picking a winner. */
+export function initOptionsFrom(args: ParsedArgs, cwd: string): InitOptionsV1 {
+  if (args.positionals.length > 1) {
+    throw new UsageError(
+      `init accepts at most one path; received ${String(args.positionals.length)}.`,
+      "untangle init [PATH]",
+    );
+  }
+  const positional = args.positionals[0];
+  const flagRoot = stringFlag(args, "root");
+  if (positional !== undefined && flagRoot !== undefined) {
+    throw new UsageError(
+      "Specify the path as either an argument or --root, not both.",
+      "untangle init /path/to/project",
+    );
+  }
+  const preferredModel = stringFlag(args, "embedding-model");
+  const visionPath = stringFlag(args, "vision");
+  const specPath = stringFlag(args, "spec");
+  const featureManifestPath = stringFlag(args, "feature-map");
+  const storageBackend =
+    args.flags["storage"] === undefined
+      ? undefined
+      : enumFlag(args, "storage", ["lancedb", "qdrant"] as const, "lancedb");
+  return {
+    root: path.resolve(cwd, flagRoot ?? positional ?? "."),
+    force: boolFlag(args, "force"),
+    dryRun: boolFlag(args, "dry-run"),
+    offline: boolFlag(args, "offline"),
+    ...(storageBackend === undefined ? {} : { storageBackend }),
+    ...(preferredModel === undefined ? {} : { preferredModel }),
+    ...(visionPath === undefined ? {} : { visionPath }),
+    ...(specPath === undefined ? {} : { specPath }),
+    ...(featureManifestPath === undefined ? {} : { featureManifestPath }),
+  };
+}
+
+/**
+ * Builds the command. `deps` exists so a test can hand in an in-memory file
+ * system and a probe that answers nothing; production calls it with none.
+ */
+export interface InitCommandDepsV1 extends InitDepsV1 {
+  wizard?: Partial<InitWizardDepsV1>;
+}
+
+export function createInitCommand(deps: InitCommandDepsV1 = {}): Command {
+  return {
+    spec: {
+      name: "init",
+      implementedBy: "commands/init/index.js",
+      summary: "Discover a project and write a commented untangle.toml",
+      usage:
+        "untangle init [PATH] [--interactive|--no-interactive] [--storage=lancedb|qdrant] [--vision=PATH] [--spec=PATH] [--feature-map=PATH] [--force] [--dry-run] [--offline]",
+      details: [
+        "On a terminal, guided setup previews configuration, optional local search/analyzer installation and a local feature/code map. No file, download or service is changed before the final selection. Preparing recipes and executing the displayed setup are separate choices. Prompts stay on stderr. Escape and Ctrl-C cancel; raw terminal mode is restored before external tools run.",
+        "Pipes, agents, --format=json, --dry-run, --offline and --no-interactive retain config-only behavior. Explicit --interactive requires a terminal and cannot be combined with JSON or dry-run. Explicit offline interactive setup may prepare local files but cannot download or start tools.",
+        `Discovers project languages weighted by lines, identifying parsed and search-only languages; monorepo topology across workspace packages and container services; an available embedding provider with its reported model, vector width and context window; an available vector store; and .gitignore rules plus defaults.`,
+        `Writes a ${CONFIG_FILE_NAME} with comments explaining each value's evidence. Omitted values come from product defaults; the file includes only decisions made by init.`,
+        "New projects use embedded LanceDB at .untangle/index/lancedb. No Docker or Qdrant probe is needed. Select --storage=qdrant for an owned or explicitly configured server. Missing Ollama is not an error; local offline indexing remains available.",
+        "Vision and specification are inspected locally through filenames, readability, hashes and document references. --vision and --spec select sources relative to the project directory. The review draft confirms neither features nor ownership and does not claim semantic conformance.",
+        "A supplied --feature-map, or untangle.features.json when present, makes declared features, code/test evidence, ownership declarations and feature complexity visible. No tests are executed and semantic conformance is not independently proven. Noninteractive init writes no visual map; confirmed guided setup may save a separate HTML/JSON snapshot. No ownership or implementation is confirmed automatically.",
+        "Spec-driven setup can inspect detected local Spec Kit or OpenSpec artifacts when no explicit feature manifest was chosen. Only final confirmation saves a source-bound proposed manifest under .untangle/sdd/ and uses it for this setup's feature report/map. Existing declarations are preserved. No framework commands or tests run; imported features remain planned/proposed without invented owners. The same connector is available through `untangle product connect [auto|spec-kit|openspec]`.",
+        "Discovery reads service information with GET and probes /api/embed with a small POST. Noninteractive init does not start or modify foreign services. A foreign vector store's usual default port is deliberately not probed (spec.md §3.2); set UNTANGLE_QDRANT_URL to select it explicitly. Only a confirmed interactive tool selection can install/start prepared owned services.",
+        "A second identical run changes nothing. If an existing file differs, init displays line-by-line differences and preserves it unless --force is explicit.",
+      ],
+      flags: FLAGS,
+      examples: [
+        "untangle init",
+        "untangle init --interactive",
+        "untangle init --no-interactive --offline",
+        "untangle init /path/to/another/project --dry-run",
+        "untangle init --offline --force",
+        "untangle init --format=json",
+        "untangle init /path/to/project --vision=docs/vision.md --spec=docs/requirements.md",
+      ],
+      exitCodes: [
+        [EXIT.ok, `${CONFIG_FILE_NAME} written or already current.`],
+        [
+          EXIT.operational,
+          "An existing file differs and was preserved (use --force), or the generated configuration would be invalid.",
+        ],
+        [EXIT.usage, "Invalid arguments."],
+      ],
+    },
+
+    async run(ctx: CommandContext, args: ParsedArgs): Promise<number> {
+      const format = enumFlag(args, "format", ["text", "json"] as const, "text");
+      const options = initOptionsFrom(args, ctx.cwd);
+      const explicit = args.flags["interactive"];
+      if (explicit === true && (format === "json" || options.dryRun))
+        throw new UsageError(
+          "--interactive cannot be combined with --format=json or --dry-run.",
+          "Use --no-interactive for a machine-readable or write-free preview.",
+        );
+      const automatic =
+        explicit === undefined &&
+        ctx.io === processIo &&
+        process.stdin.isTTY === true &&
+        process.stderr.isTTY === true &&
+        !ctx.env["CI"] &&
+        format === "text" &&
+        !options.dryRun &&
+        !options.offline;
+      const { wizard, ...ports } = deps;
+      const initDeps = {
+        env: ctx.env,
+        signal: ctx.signal,
+        ...ports,
+      };
+      let result;
+      if (explicit === true || automatic) {
+        if (
+          wizard?.terminal === undefined &&
+          (process.stdin.isTTY !== true || process.stderr.isTTY !== true)
+        )
+          throw new UsageError(
+            "--interactive requires a terminal on stdin and stderr.",
+            "Use `untangle init --no-interactive` in a pipe or coding agent.",
+          );
+        const terminal =
+          wizard?.terminal ??
+          createWizardTerminal({ write: (text) => ctx.io.err(text), signal: ctx.signal });
+        if (
+          !terminal.interactive ||
+          (wizard?.terminal === undefined && process.stderr.isTTY !== true)
+        )
+          throw new UsageError(
+            "--interactive requires a terminal on stdin and stderr.",
+            "Use `untangle init --no-interactive` in a pipe or coding agent.",
+          );
+        const completed = await runInitWizard(ctx, options, initDeps, { ...wizard, terminal });
+        if (completed.result === null) return completed.exitCode;
+        result = completed.result;
+        if (completed.exitCode !== result.exitCode) return completed.exitCode;
+      } else result = await runInit(options, initDeps);
+
+      if (format === "json") {
+        line(ctx.io, JSON.stringify(result, null, 2));
+        return result.exitCode;
+      }
+
+      // The path goes to stdout — it is the payload of this command, the one
+      // thing a script would pipe. Everything else is diagnosis (cli/io.ts).
+      line(ctx.io, result.configPath);
+      for (const reportLine of formatTextReport(result)) {
+        note(ctx.io, reportLine);
+      }
+      return result.exitCode;
+    },
+  };
+}
+
+/** The command with production ports. */
+export const initCommand: Command = createInitCommand();

package/src/commands/init/config-draft.ts

@@ -0,0 +1,235 @@
+/**
+ * Turning findings into a configuration.
+ *
+ * The shape written to disk is `UntangleConfigV1` from
+ * `@untangle-code/config` — not a private CLI dialect — and it is checked with
+ * that package's own validator before a byte reaches the file system. A first
+ * command that writes a configuration the rest of the product then rejects is
+ * a first command that has failed.
+ *
+ * WHICH SECTIONS GET WRITTEN: only the ones `init` actually DECIDED something
+ * about. Everything else is left to the product defaults, because a file that
+ * restates two hundred defaults verbatim tells the reader nothing about what
+ * was chosen. `defaultsFor` records the values that stay defaulted so the
+ * renderer can name them in prose instead.
+ */
+
+import {
+  DEFAULT_EMBEDDING_CONFIG,
+  DEFAULT_INDEX_CONFIG,
+  PRODUCT_DEFAULT_CONFIG,
+  mergeConfigLayers,
+  validateEffectiveConfig,
+} from "@untangle-code/config";
+import type { RawConfigLayer } from "@untangle-code/config";
+import { sha256Hex, sortByCodepoints } from "@untangle-code/domain";
+
+import type { ProjectFindingsV1 } from "./types.js";
+
+/** The sub-sections `init` fills in, without the `| undefined` of the optional slot. */
+type QdrantSection = NonNullable<RawConfigLayer["qdrant"]>;
+type EmbeddingSection = NonNullable<RawConfigLayer["embeddings"]>;
+
+export interface ConfigDraftV1 {
+  /** Exactly what `init` decided — the layer that ends up in the file. */
+  layer: RawConfigLayer;
+  /** Validator warnings over the layer merged onto the product defaults. */
+  warnings: string[];
+  /** Validator errors. Non-empty means the file is NOT written. */
+  errors: string[];
+}
+
+/**
+ * Derives a project id from a directory name.
+ *
+ * Lowercase, non-alphanumerics collapsed to `-`, trimmed. A name that reduces
+ * to nothing (a directory called `...`) falls back to `project`, because an
+ * empty id would fail validation and an id derived from something random
+ * would not be reproducible.
+ */
+export function deriveProjectId(directoryName: string): string {
+  const slug = directoryName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+  return slug.length === 0 ? "project" : slug;
+}
+
+export function buildConfigDraft(findings: ProjectFindingsV1): ConfigDraftV1 {
+  const contextArtifacts = productContextArtifacts(findings);
+  const layer: RawConfigLayer = {
+    schemaVersion: 1,
+    projectId: findings.projectId,
+    repositories: [
+      {
+        id: findings.projectId,
+        // Relative to this configuration file — spec.md §4.3 allows exactly
+        // that, and a relative path keeps the file portable between checkouts.
+        path: ".",
+        label: findings.projectId,
+        exclude: sortByCodepoints([
+          ...findings.ignore.defaultExcludes,
+          ...findings.ignore.additionalExcludes,
+        ]),
+      },
+    ],
+    ...(findings.storage?.backend === "lancedb"
+      ? {
+          storage: {
+            backend: "lancedb" as const,
+            ...(findings.storage.path === undefined ? {} : { path: findings.storage.path }),
+          },
+        }
+      : { storage: { backend: "qdrant" as const }, qdrant: buildQdrantSection(findings) }),
+    embeddings: buildEmbeddingSection(findings),
+    index: {
+      // The only index knob `init` moves: a project whose sources are wider
+      // than the default ceiling would otherwise lose them silently.
+      maxFileSizeMb: DEFAULT_INDEX_CONFIG.maxFileSizeMb,
+      watch: DEFAULT_INDEX_CONFIG.watch,
+    },
+    graph: {
+      // Both levels of the topology feed the graph; a single-package project
+      // gets the same setting, it simply has less to draw.
+      enabled: true,
+    },
+    telemetry: { enabled: false },
+    ...(contextArtifacts.length === 0 ? {} : { contextArtifacts }),
+  };
+
+  const merged = mergeConfigLayers<Record<string, unknown>>([PRODUCT_DEFAULT_CONFIG, layer]);
+  const validation = validateEffectiveConfig(merged);
+  return {
+    layer,
+    warnings: [
+      ...validation.warnings.map((issue) => `${issue.path}: ${issue.message}`),
+      ...(findings.storage?.configurationWarnings ?? []),
+      ...(findings.storage?.directoryStatus === "not-directory" ||
+      findings.storage?.directoryStatus === "unreadable"
+        ? [
+            `Local storage ${findings.storage.directory}: ${findings.storage.directoryStatus}${findings.storage.detail === undefined ? "" : ` (${findings.storage.detail})`}. Indexing cannot use this path.`,
+          ]
+        : []),
+    ],
+    errors: validation.errors.map((issue) => `${issue.path}: ${issue.message} [${issue.code}]`),
+  };
+}
+
+function productContextArtifacts(
+  findings: ProjectFindingsV1,
+): NonNullable<RawConfigLayer["contextArtifacts"]> {
+  const descriptions = {
+    vision: "Provisional vision",
+    specification: "Provisional specification",
+    product: "Provisional product description",
+  };
+  return (findings.productContext?.sources ?? [])
+    .filter((source) => source.selected && source.status === "readable")
+    .map((source) => ({
+      name: `product-${source.role}-${sha256Hex(source.path).slice(0, 12)}`,
+      path: `./${source.path}`,
+      description: `${descriptions[source.role]}; local document inspection, features and ownership remain unconfirmed.`,
+      type: "markdown",
+    }));
+}
+
+/**
+ * Qdrant: `external` only when an endpoint actually answered. Otherwise
+ * `managed` with no URL — the mode that says "start your own instance", which
+ * is the correct answer both when nothing is running and when the only thing
+ * running is somebody else's (spec.md §3.2).
+ */
+function buildQdrantSection(findings: ProjectFindingsV1): QdrantSection {
+  if (findings.storage?.qdrantMode !== undefined) {
+    return {
+      mode: findings.storage.qdrantMode,
+      ...(findings.storage.qdrantUrl === undefined ? {} : { url: findings.storage.qdrantUrl }),
+      collectionPrefix: collectionPrefixFor(findings),
+    };
+  }
+  if (findings.qdrant.outcome === "reachable" && findings.qdrant.url !== undefined) {
+    return {
+      mode: "external",
+      url: findings.qdrant.url,
+      collectionPrefix: collectionPrefixFor(findings),
+    };
+  }
+  return { mode: "managed", collectionPrefix: collectionPrefixFor(findings) };
+}
+
+/** `untangle_<projectId>_` — keeps two projects on one instance from colliding. */
+export function collectionPrefixFor(findings: ProjectFindingsV1): string {
+  return `untangle_${findings.projectId.replace(/-/gu, "_")}_`;
+}
+
+/**
+ * Embeddings: when a provider answered, the model AND its vector width and
+ * context window are taken from what the provider reported about itself. When
+ * none answered, the product default profile stands and `mode` stays `auto`,
+ * so the next run can still discover a provider without the user editing
+ * anything.
+ */
+function buildEmbeddingSection(findings: ProjectFindingsV1): EmbeddingSection {
+  const chosen = findings.ollama.chosenModel;
+  if (findings.ollama.outcome !== "reachable" || chosen === undefined) {
+    return {
+      provider: "ollama",
+      mode: "auto",
+      model: DEFAULT_EMBEDDING_CONFIG.model,
+      dimensions: DEFAULT_EMBEDDING_CONFIG.dimensions,
+      contextLength: DEFAULT_EMBEDDING_CONFIG.contextLength,
+    };
+  }
+  return {
+    provider: "ollama",
+    mode: "external",
+    url: findings.ollama.url,
+    model: chosen.name,
+    dimensions: chosen.dimensions ?? DEFAULT_EMBEDDING_CONFIG.dimensions,
+    contextLength: chosen.contextLength ?? DEFAULT_EMBEDDING_CONFIG.contextLength,
+  };
+}
+
+/**
+ * The single next step.
+ *
+ * EXACTLY ONE, in a fixed priority order, because a first command that ends
+ * in a list of five things is a first command the user closes. The order is
+ * "what blocks the next command first": no embedding provider blocks
+ * indexing; no model blocks it too; no vector store blocks it; otherwise
+ * nothing blocks it and the step is to index.
+ */
+export function nextStepFor(findings: ProjectFindingsV1): string {
+  if (findings.storage?.backend === "lancedb") {
+    if (
+      findings.storage.directoryStatus === "not-directory" ||
+      findings.storage.directoryStatus === "unreadable"
+    )
+      return `Local storage path ${JSON.stringify(findings.storage.directory)} is ${findings.storage.directoryStatus}. Next step: choose an accessible directory with UNTANGLE_LANCEDB_PATH and rerun \`untangle init\`.`;
+    if (findings.ollama.outcome !== "reachable" || findings.ollama.chosenModel === undefined)
+      return "Local LanceDB storage needs no service. Next step: `untangle index --embedder=offline` (local vectors without semantic embeddings).";
+  }
+  if (findings.ollama.outcome !== "reachable") {
+    return `No embedding provider at ${findings.ollama.url}. Next step: start \`ollama serve\` and rerun \`untangle init\`.`;
+  }
+  if (findings.ollama.chosenModel === undefined) {
+    return `${findings.ollama.url} is running but reports no embedding model. Next step: \`ollama pull ${DEFAULT_EMBEDDING_CONFIG.model}\`.`;
+  }
+  if (findings.storage?.backend !== "lancedb" && findings.qdrant.outcome !== "reachable") {
+    if (findings.storage?.qdrantMode === "external")
+      return `The selected Qdrant server ${JSON.stringify(findings.storage.qdrantUrl)} is unreachable. Next step: check that server's URL and availability, then rerun \`untangle doctor\`.`;
+    return "No vector store is reachable. Next step: start an owned instance with `docker run -d --name untangle-qdrant -p 16333:6333 -v untangle-qdrant-data:/qdrant/storage qdrant/qdrant`, then run `untangle index`.";
+  }
+  // WP-228: Der Anbieter laeuft, das Modell ist da, der Speicher steht — und
+  // trotzdem kann nicht indiziert werden, weil der Endpunkt, den der
+  // Indexlauf benutzt, nicht antwortet. Das ist ein eigener Fall und
+  // verdient einen eigenen naechsten Schritt; „alles vorhanden" waere hier
+  // schlicht falsch.
+  if (findings.ollama.embedProbe.outcome === "timeout") {
+    return `${findings.ollama.url} responds on /api/tags, but /api/embed did not respond within ${String(findings.ollama.embedProbe.timeoutMs)} ms, so embeddings are unavailable. Next step: \`untangle index --embedder=offline\` (local vectors without semantics).`;
+  }
+  if (findings.ollama.embedProbe.outcome === "failed") {
+    return `${findings.ollama.url} is running, but /api/embed failed (${findings.ollama.embedProbe.detail ?? "no details"}). Next step: \`untangle index --embedder=offline\` (local vectors without semantics).`;
+  }
+  return "Everything is available. Next step: `untangle index`.";
+}

package/src/commands/init/diff.ts

@@ -0,0 +1,117 @@
+/**
+ * Idempotency: what a second run would change.
+ *
+ * `init` compares the RENDERED text against the file on disk rather than
+ * parsing the file back into a config object. That is a deliberate choice and
+ * it buys three things at once:
+ *
+ * - it needs no TOML parser, so there is no second grammar to keep in step
+ *   with the writer;
+ * - it notices changes the user made BY HAND, including in the comments,
+ *   which a value-level comparison would call "identical";
+ * - it is only meaningful because `renderUntangleToml` is pure and carries no
+ *   clock — otherwise every run would differ and the check would be theatre.
+ *
+ * The comparison is a line diff, so the report says which lines would be
+ * added and which lost, not merely "the file differs".
+ */
+
+import type { ConfigChangeV1 } from "./types.js";
+
+/** Above this line count the diff degrades to a set comparison (see `diffLines`). */
+const LCS_LINE_BUDGET = 2_000;
+
+/** Splits into lines, dropping the single trailing empty element of a final newline. */
+export function toLines(text: string): string[] {
+  const lines = text.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines;
+}
+
+/**
+ * Line diff, longest-common-subsequence based.
+ *
+ * The dynamic-programming table is O(n·m); both sides are a configuration
+ * file, so that is a few hundred by a few hundred. Above `LCS_LINE_BUDGET`
+ * the function falls back to a multiset comparison — less precise about
+ * ORDER, but still exact about which lines appear on only one side, and it
+ * cannot be made to allocate gigabytes by a pathological input.
+ */
+export function diffLines(before: readonly string[], after: readonly string[]): ConfigChangeV1[] {
+  if (before.length > LCS_LINE_BUDGET || after.length > LCS_LINE_BUDGET) {
+    return multisetDiff(before, after);
+  }
+
+  const rows = before.length;
+  const columns = after.length;
+  // table[i][j] = length of the LCS of before[i…] and after[j…]
+  const table: number[][] = Array.from({ length: rows + 1 }, () =>
+    new Array<number>(columns + 1).fill(0),
+  );
+  for (let i = rows - 1; i >= 0; i -= 1) {
+    const row = table[i] as number[];
+    const nextRow = table[i + 1] as number[];
+    for (let j = columns - 1; j >= 0; j -= 1) {
+      row[j] =
+        before[i] === after[j]
+          ? (nextRow[j + 1] as number) + 1
+          : Math.max(nextRow[j] as number, row[j + 1] as number);
+    }
+  }
+
+  const changes: ConfigChangeV1[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < rows && j < columns) {
+    if (before[i] === after[j]) {
+      i += 1;
+      j += 1;
+      continue;
+    }
+    const row = table[i] as number[];
+    const nextRow = table[i + 1] as number[];
+    if ((nextRow[j] as number) >= (row[j + 1] as number)) {
+      changes.push({ kind: "removed", line: (before[i] as string).trimEnd() });
+      i += 1;
+    } else {
+      changes.push({ kind: "added", line: (after[j] as string).trimEnd() });
+      j += 1;
+    }
+  }
+  for (; i < rows; i += 1) {
+    changes.push({ kind: "removed", line: (before[i] as string).trimEnd() });
+  }
+  for (; j < columns; j += 1) {
+    changes.push({ kind: "added", line: (after[j] as string).trimEnd() });
+  }
+  return changes;
+}
+
+function multisetDiff(before: readonly string[], after: readonly string[]): ConfigChangeV1[] {
+  const counts = new Map<string, number>();
+  for (const line of before) {
+    counts.set(line, (counts.get(line) ?? 0) + 1);
+  }
+  const changes: ConfigChangeV1[] = [];
+  for (const line of after) {
+    const remaining = counts.get(line) ?? 0;
+    if (remaining > 0) {
+      counts.set(line, remaining - 1);
+    } else {
+      changes.push({ kind: "added", line: line.trimEnd() });
+    }
+  }
+  for (const [line, remaining] of counts) {
+    for (let index = 0; index < remaining; index += 1) {
+      changes.push({ kind: "removed", line: line.trimEnd() });
+    }
+  }
+  return changes;
+}
+
+/** True when the file on disk already IS what `init` would write. */
+export function isUnchanged(existing: string, rendered: string): boolean {
+  return existing === rendered;
+}