@ctxr/skill-llm-wiki 1.0.1

package/scripts/lib/interactive.mjs

@@ -0,0 +1,99 @@
+// interactive.mjs — TTY-gated prompt helpers.
+//
+// The "ask, don't guess" rule from methodology section 9.4.3 has two
+// enforcement layers: intent.mjs refuses ambiguous CLI invocations; this
+// module handles interactive prompts for things that genuinely need a
+// runtime yes/no (migration confirmation, Tier 1 install, --review
+// checkpoints in Phase 7).
+//
+// Non-interactive mode is the default for CI, hooks, and any pipeline
+// where stdin is not a TTY. Detection prefers explicit flags over
+// heuristics, in this order:
+//
+//   1. `LLM_WIKI_NO_PROMPT=1` (env var)            → never prompt
+//   2. `--no-prompt` (CLI flag, surfaced via opts) → never prompt
+//   3. `process.stdin.isTTY === false`             → never prompt
+//   4. otherwise                                    → prompt
+//
+// When prompting is disabled, every prompt helper throws a
+// `NonInteractiveError` that the caller is expected to surface as a
+// structured CLI error. The caller chooses whether to exit, fall through,
+// or translate into a different behaviour (Tier 1 install's silent
+// fallthrough is the canonical example).
+
+import { createInterface } from "node:readline";
+
+export class NonInteractiveError extends Error {
+  constructor(question) {
+    super(
+      `skill-llm-wiki: cannot prompt "${question}" in non-interactive mode`,
+    );
+    this.name = "NonInteractiveError";
+    this.question = question;
+  }
+}
+
+export function isInteractive(opts = {}) {
+  if (process.env.LLM_WIKI_NO_PROMPT === "1") return false;
+  if (opts.noPrompt) return false;
+  if (opts.forceInteractive) return true; // tests
+  // `process.stdin.isTTY` is `true` on a TTY, `undefined` on a pipe.
+  // Boolean() handles both: pipes become false, TTYs become true.
+  return Boolean(process.stdin && process.stdin.isTTY);
+}
+
+// Basic y/n prompt with a configurable default. Returns a boolean.
+// Throws NonInteractiveError when prompts are disabled.
+export async function confirm(question, opts = {}) {
+  if (!isInteractive(opts)) {
+    throw new NonInteractiveError(question);
+  }
+  const def = opts.default === undefined ? true : Boolean(opts.default);
+  const suffix = def ? " [Y/n] " : " [y/N] ";
+  const answer = await readLine(question + suffix);
+  if (answer === "") return def;
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+// Free-form text prompt with an optional default value.
+export async function ask(question, opts = {}) {
+  if (!isInteractive(opts)) {
+    throw new NonInteractiveError(question);
+  }
+  const suffix = opts.default ? ` [${opts.default}] ` : " ";
+  const answer = await readLine(question + suffix);
+  if (answer === "" && opts.default !== undefined) return opts.default;
+  return answer.trim();
+}
+
+// Multiple-choice prompt. Returns the chosen option's `value`.
+export async function choose(question, options, opts = {}) {
+  if (!isInteractive(opts)) {
+    throw new NonInteractiveError(question);
+  }
+  const lines = [question];
+  for (let i = 0; i < options.length; i++) {
+    lines.push(`  ${i + 1}. ${options[i].label}`);
+  }
+  lines.push(`Choose 1-${options.length}: `);
+  while (true) {
+    const answer = await readLine(lines.join("\n"));
+    const idx = Number.parseInt(answer.trim(), 10);
+    if (Number.isInteger(idx) && idx >= 1 && idx <= options.length) {
+      return options[idx - 1].value;
+    }
+    process.stderr.write(
+      `skill-llm-wiki: please enter a number between 1 and ${options.length}\n`,
+    );
+  }
+}
+
+function readLine(prompt) {
+  return new Promise((resolvePromise) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolvePromise(answer);
+    });
+  });
+}

package/scripts/lib/migrate.mjs

@@ -0,0 +1,126 @@
+// migrate.mjs — move a legacy `<source>.llmwiki.v<N>/` wiki into the new
+// `<source>.wiki/` sibling layout with a private git repo and an op-log
+// entry recording the migration lineage.
+//
+// Atomicity guarantees:
+//   1. The legacy folder is read-only to this module — never mutated,
+//      byte-identical before and after (success OR failure).
+//   2. The destination is cleaned up on ANY exception between mkdirSync
+//      and the final commit. The user never has to manually rm a
+//      half-built sibling before retrying.
+//   3. If the destination existed before this call (the caller should
+//      have refused via intent.mjs's INT-01 check, but defence in depth),
+//      we never touch it on failure — we only nuke directories this
+//      call created.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { appendOpLog } from "./history.mjs";
+import { ensureWikiGitignore } from "./gitignore.mjs";
+import {
+  gitCommit,
+  gitHeadSha,
+  gitInit,
+  gitRunChecked,
+  gitTag,
+} from "./git.mjs";
+
+// Match legacy folder names of the form `<anything>.llmwiki.v<digits>`
+// and extract the version integer. Returns null for non-matching inputs.
+function parseLegacyVersion(legacyPath) {
+  const m = /\.llmwiki\.v(\d+)$/.exec(basename(legacyPath));
+  return m ? Number(m[1]) : null;
+}
+
+// Build the default migration destination for a legacy wiki.
+// `<parent>/<base>.llmwiki.v3` → `<parent>/<base>.wiki`.
+export function defaultMigrationTarget(legacyPath) {
+  const parent = dirname(legacyPath);
+  const name = basename(legacyPath);
+  const cleanName = name.replace(/\.llmwiki\.v\d+$/, "");
+  return join(parent, `${cleanName}.wiki`);
+}
+
+// Migrate a legacy wiki. Parameters:
+//   legacyPath    absolute path to `<source>.llmwiki.v<N>/`
+//   newWikiPath   absolute path to the new sibling destination
+//   opts.opId     op-id string for the migration (caller-supplied so the
+//                 surrounding CLI can correlate with its op-log record)
+//
+// Returns { opId, version, sha } on success.
+// Throws if legacyPath is not a legacy wiki, or if newWikiPath already
+// exists (collision resolution is the caller's job).
+export function migrateLegacyWiki(legacyPath, newWikiPath, opts = {}) {
+  const version = parseLegacyVersion(legacyPath);
+  if (version === null) {
+    throw new Error(
+      `migrate: ${legacyPath} does not match the legacy .llmwiki.v<N> naming convention`,
+    );
+  }
+  if (!existsSync(legacyPath)) {
+    throw new Error(`migrate: legacy wiki ${legacyPath} does not exist`);
+  }
+  if (existsSync(newWikiPath)) {
+    throw new Error(
+      `migrate: destination ${newWikiPath} already exists; pick a new target or remove it first`,
+    );
+  }
+  if (!opts.opId || typeof opts.opId !== "string") {
+    throw new Error("migrate: opts.opId is required");
+  }
+  // The destination must not pre-exist. We check and throw here — AFTER
+  // this point, any directory at `newWikiPath` was created by this
+  // specific call, so failure-cleanup can rmSync it unconditionally
+  // without fear of destroying an unrelated pre-existing directory.
+  if (existsSync(newWikiPath)) {
+    throw new Error(
+      `migrate: destination ${newWikiPath} already exists; pick a new target or remove it first`,
+    );
+  }
+  try {
+    mkdirSync(newWikiPath, { recursive: true });
+    // Copy everything except the legacy sibling's own cruft. The legacy
+    // layout never had a `.llmwiki/` subdir of its own, so a full recursive
+    // copy is safe. `errorOnExist: false` is the default; explicit for clarity.
+    for (const entry of readdirSync(legacyPath, { withFileTypes: true })) {
+      cpSync(join(legacyPath, entry.name), join(newWikiPath, entry.name), {
+        recursive: true,
+        errorOnExist: false,
+        force: false,
+        preserveTimestamps: true,
+      });
+    }
+    // Initialise the private git repo, stage everything, commit.
+    gitInit(newWikiPath);
+    ensureWikiGitignore(newWikiPath);
+    gitRunChecked(newWikiPath, ["add", "-A"]);
+    gitCommit(newWikiPath, `migrate from legacy .llmwiki.v${version}`);
+    const tagName = `op/${opts.opId}`;
+    gitTag(newWikiPath, tagName, "HEAD");
+    const sha = gitHeadSha(newWikiPath);
+    appendOpLog(newWikiPath, {
+      op_id: opts.opId,
+      operation: "migrate",
+      layout_mode: "sibling",
+      started: new Date().toISOString(),
+      finished: new Date().toISOString(),
+      base_commit: "legacy",
+      final_commit: sha || "",
+      summary: `migrated from ${legacyPath} (v${version})`,
+    });
+    return { opId: opts.opId, version, sha };
+  } catch (err) {
+    // Atomic-rollback: remove the half-built destination so the user
+    // can retry cleanly. Safe to do unconditionally because the
+    // pre-existence check above guarantees this call is the one that
+    // created `newWikiPath`.
+    try {
+      rmSync(newWikiPath, { recursive: true, force: true });
+    } catch {
+      /* best effort — surface the original error anyway */
+    }
+    throw err;
+  }
+}
+
+export { parseLegacyVersion };

package/scripts/lib/nest-applier.mjs

@@ -0,0 +1,260 @@
+// nest-applier.mjs — the applying NEST operator.
+//
+// Given a cluster proposal (set of sibling leaves all under the
+// same parent directory) and a resolved slug (from Tier 2), move
+// the leaves into a new subdirectory `<parent>/<slug>/`, rewrite
+// each moved leaf's `parents[]` to point at the new parent, and
+// bootstrap a minimal `index.md` stub in the new subdirectory.
+// The parent index.md is NOT touched here — the caller re-runs
+// `rebuildAllIndices` in its phase so the parent's entries[] is
+// regenerated with the new subcategory replacing the moved leaves.
+//
+// Preconditions enforced here:
+//
+//   1. The resolved slug is a valid kebab-case directory name.
+//   2. All leaves share the same parent directory.
+//   3. The new subdirectory does not already exist.
+//   4. None of the leaf target paths collide with existing files.
+//
+// On any precondition failure the function throws BEFORE touching
+// the filesystem, so the phase's rollback guarantees (pre-op
+// snapshot → reset on exception) remain byte-exact.
+//
+// We do NOT touch the private git here. The caller's phase
+// pipeline `git add -A && git commit` after the applier runs is
+// what records the change.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { parseFrontmatter, renderFrontmatter } from "./frontmatter.mjs";
+
+const SLUG_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+export function validateSlug(slug) {
+  if (typeof slug !== "string") return false;
+  return SLUG_RE.test(slug);
+}
+
+// Resolve a slug that won't collide with a member leaf's id or with a
+// non-member sibling in the same parent directory. The observed
+// collision case (v0.4.1 novel-corpus run): Tier 2's propose_structure
+// response picked slug="security" for a cluster whose members included
+// a leaf with id="security", so after apply both the new subcategory's
+// stub index.md AND the moved leaf carried id="security" — DUP-ID at
+// validate time, forcing a full pipeline rollback. Pre-resolving here
+// auto-suffixes the slug (deterministically: `-group`, then `-group-N`)
+// until it's non-colliding, letting the NEST land on the first try.
+// Non-collision slugs are returned unchanged; invalid slugs are left
+// alone so applyNest's own validation can reject them with its usual
+// error message.
+export function resolveNestSlug(slug, proposal) {
+  if (!validateSlug(slug)) return slug;
+  if (
+    !proposal ||
+    !Array.isArray(proposal.leaves) ||
+    proposal.leaves.length === 0
+  ) {
+    return slug;
+  }
+  const forbidden = collectForbiddenIds(proposal);
+  if (!forbidden.has(slug)) return slug;
+  // Try "-group" first (the natural human reading: "the group of X
+  // leaves"); fall back to numeric suffixes starting at -group-2
+  // because "-group" itself already occupies the slot that would
+  // otherwise be "-group-1". If the base slug is so long that
+  // "${slug}-group" overflows the 64-char SLUG_RE cap, short-circuit:
+  // all numeric candidates share the same prefix and will fail
+  // validation identically, so there's no point spinning the loop.
+  // Returning the original (colliding) slug propagates the failure
+  // to applyNest, which throws a clear "target subcategory already
+  // exists" error — strictly better than a silent spin.
+  const primary = `${slug}-group`;
+  if (!validateSlug(primary)) return slug;
+  if (!forbidden.has(primary)) return primary;
+  for (let i = 2; i < 100; i++) {
+    const candidate = `${slug}-group-${i}`;
+    if (!forbidden.has(candidate)) return candidate;
+  }
+  return slug;
+}
+
+function collectForbiddenIds(proposal) {
+  const forbidden = new Set();
+  for (const leaf of proposal.leaves) {
+    if (leaf?.data?.id) forbidden.add(leaf.data.id);
+  }
+  const parentDir = dirname(proposal.leaves[0].path);
+  const memberPaths = new Set(proposal.leaves.map((l) => l.path));
+  let entries;
+  try {
+    entries = readdirSync(parentDir, { withFileTypes: true });
+  } catch {
+    return forbidden;
+  }
+  for (const entry of entries) {
+    // Skip the parent's own index.md: its id is the parent's basename
+    // (i.e., the parent directory name), not something the new
+    // subcategory could collide with. Parent-name collisions — where
+    // the slug equals the parent dir's name — are a separate case that
+    // applyNest itself rejects via its existsSync(targetDir) check.
+    if (entry.name === "index.md") continue;
+    const entryPath = join(parentDir, entry.name);
+    if (memberPaths.has(entryPath)) continue;
+    if (entry.isDirectory()) {
+      forbidden.add(entry.name);
+      continue;
+    }
+    if (!entry.name.endsWith(".md")) continue;
+    try {
+      const raw = readFileSync(entryPath, "utf8");
+      const { data } = parseFrontmatter(raw, entryPath);
+      if (data?.id) forbidden.add(data.id);
+    } catch {
+      /* skip unreadable siblings */
+    }
+  }
+  return forbidden;
+}
+
+export function applyNest(wikiRoot, proposal, slug, opts = {}) {
+  void wikiRoot;
+  void opts;
+  if (!proposal || !Array.isArray(proposal.leaves) || proposal.leaves.length < 2) {
+    throw new Error("nest-applier: proposal must carry at least 2 leaves");
+  }
+  if (!validateSlug(slug)) {
+    throw new Error(
+      `nest-applier: invalid slug "${slug}" (must match /^[a-z][a-z0-9-]{0,63}$/)`,
+    );
+  }
+  const parentDirs = new Set(proposal.leaves.map((l) => dirname(l.path)));
+  if (parentDirs.size !== 1) {
+    throw new Error(
+      `nest-applier: leaves belong to ${parentDirs.size} different parent dirs — cannot NEST across parents in one step`,
+    );
+  }
+  const parentDir = parentDirs.values().next().value;
+  const targetDir = join(parentDir, slug);
+  if (existsSync(targetDir)) {
+    throw new Error(
+      `nest-applier: target subcategory ${targetDir} already exists`,
+    );
+  }
+
+  // Precompute target paths and check for collisions BEFORE any
+  // filesystem mutation.
+  const moves = [];
+  for (const leaf of proposal.leaves) {
+    const targetPath = join(targetDir, basename(leaf.path));
+    if (existsSync(targetPath)) {
+      throw new Error(
+        `nest-applier: target leaf path ${targetPath} already exists`,
+      );
+    }
+    moves.push({ from: leaf.path, to: targetPath, leaf });
+  }
+
+  // Create the target directory and move each leaf into it,
+  // rewriting the parents[] field as we go. We use `renameSync`
+  // rather than a raw move so the private git sees the rename
+  // as a proper content-preserving move on the next `git add`.
+  mkdirSync(targetDir, { recursive: true });
+  for (const move of moves) {
+    const raw = readFileSync(move.from, "utf8");
+    const { data, body } = parseFrontmatter(raw, move.from);
+    // Rewrite parents[] to point at the new subcategory's
+    // index.md. The methodology says parents[] uses POSIX-relative
+    // paths; for a leaf at `<parent>/<slug>/foo.md`, the direct
+    // parent index.md lives at `<parent>/<slug>/index.md`, which
+    // is `index.md` relative to the leaf itself.
+    data.parents = ["index.md"];
+    writeFileSync(move.to, renderFrontmatter(data, body), "utf8");
+    // Unlink the old location. The new file has already been
+    // written, so this is a destructive move but at the same
+    // level as the rollback guarantee (which resets the working
+    // tree to the pre-op snapshot on any exception upstream).
+    rmSync(move.from, { force: true });
+  }
+
+  // Bootstrap an index.md stub in the new subcategory. The stub is
+  // minimal: `id`, `type`, `depth_role`, `focus` (from the Tier 2
+  // cluster purpose, with a placeholder fallback), any shared tags
+  // and shared_covers that the cluster members have in common, and
+  // the `parents[]` / `generator` marker that the subsequent
+  // `rebuildAllIndices` pass fills in. No `activation_defaults`
+  // aggregation: routing is semantic now — Claude decides descent
+  // from `focus` and `shared_covers` rather than from a literal
+  // keyword/tag union. Per-leaf `activation` blocks stay on the
+  // leaves as optional semantic hints (see SKILL.md "Routing into
+  // guide.wiki/").
+  const sharedTags = intersectTags(proposal.leaves.map((l) => l.data.tags || []));
+  const sharedCovers = intersectCovers(proposal.leaves.map((l) => l.data.covers || []));
+  const purpose = typeof proposal.purpose === "string" ? proposal.purpose.trim() : "";
+  const stubData = {
+    id: slug,
+    type: "index",
+    depth_role: "subcategory",
+    focus: purpose || `subtree under ${slug}`,
+  };
+  if (sharedTags.length > 0) stubData.tags = sharedTags;
+  if (sharedCovers.length > 0) {
+    stubData.shared_covers = sharedCovers;
+  }
+  const stubBody =
+    "\n<!-- BEGIN AUTO-GENERATED NAVIGATION -->\n\n" +
+    "<!-- END AUTO-GENERATED NAVIGATION -->\n\n" +
+    "<!-- BEGIN AUTHORED ORIENTATION -->\n\n" +
+    "<!-- END AUTHORED ORIENTATION -->\n";
+  const stubPath = join(targetDir, "index.md");
+  writeFileSync(stubPath, renderFrontmatter(stubData, stubBody), "utf8");
+
+  return {
+    target_dir: targetDir,
+    moved: moves.map((m) => ({ from: m.from, to: m.to })),
+    stub: stubPath,
+    shared_tags: sharedTags,
+    shared_covers: sharedCovers,
+  };
+}
+
+function intersectTags(lists) {
+  if (lists.length === 0) return [];
+  const first = new Set(lists[0]);
+  const out = [];
+  for (const t of first) {
+    if (lists.every((l) => l.includes(t))) out.push(t);
+  }
+  return out.sort();
+}
+
+// Deterministic intersection of cover strings across cluster
+// members. Case-sensitive string equality. Result is sorted so
+// stub bodies are byte-deterministic across rebuilds.
+function intersectCovers(lists) {
+  if (lists.length === 0) return [];
+  if (lists.length === 1) return [];
+  const first = new Set(lists[0]);
+  const out = [];
+  for (const item of first) {
+    if (lists.every((l) => l.includes(item))) out.push(item);
+  }
+  return out.sort();
+}
+
+// Historical note: an `aggregateActivation(leaves)` helper used to
+// live here. It unioned `activation.keyword_matches`,
+// `activation.tag_matches`, `tags[]`, and `activation.escalation_from`
+// across cluster members into a single `activation_defaults` block
+// for the new subcategory stub. That block was the old literal-
+// routing substrate — the router's deterministic descent rule was an
+// AND-filter on `activation_defaults.tag_matches ∩ profile.tags`.
+// The rule has been removed in favour of semantic routing (Claude
+// matches on the stub's `focus` + `shared_covers`), so the helper
+// has no callers and was deleted.