@ctxr/skill-llm-wiki 1.0.1 → 1.0.2

package/scripts/lib/contract.mjs

@@ -0,0 +1,229 @@
+// contract.mjs — stable, machine-readable description of what this
+// skill speaks to consumers. The single source of truth for the
+// skill's format + CLI surface version.
+//
+// Consumers (other skills, agents, CI jobs) invoke
+// `node scripts/cli.mjs contract --json` and assert
+// `format_version >= <their required>` rather than drift-testing
+// against SKILL.md prose. Bump FORMAT_VERSION on any breaking change
+// to: leaf frontmatter schema, layout-contract grammar, CLI wire
+// protocol, or exit-code meanings. Additive changes do not bump.
+//
+// The shape returned by `getContract()` is documented in
+// guide/consumers/recipes/format-gate.md.
+
+import { readFileSync } from "node:fs";
+
+// ─── Version constants ──────────────────────────────────────────────
+// `FORMAT_VERSION` is an integer. Bumps are breaking changes to the
+// consumer-visible contract. Start at 1.
+export const FORMAT_VERSION = 1;
+
+// `MIN_CONSUMER_FORMAT_VERSION` is the oldest consumer-declared
+// format_version this skill still speaks to. A consumer whose
+// `required_format_version` is below this refuses to run; a consumer
+// whose `required_format_version` is between this and FORMAT_VERSION
+// runs unchanged. Bumps here signal a deprecation window closing.
+export const MIN_CONSUMER_FORMAT_VERSION = 1;
+
+// ─── Canonical shape ────────────────────────────────────────────────
+
+// Leaf + index frontmatter fields the skill reads and writes.
+// Mirrors scripts/lib/draft.mjs AUTHORED_LEAF_FIELDS for leaves
+// and scripts/lib/indices.mjs / scripts/lib/validate.mjs for
+// indices. Enums here are the canonical values the skill's own
+// code emits and validate.mjs accepts; consumers authoring their
+// own frontmatter must pick from these.
+const FRONTMATTER_SCHEMA = {
+  leaf: {
+    required: ["id", "type", "depth_role", "focus", "parents", "source"],
+    fields: {
+      id: { kind: "string", description: "Unique leaf identifier; derived from source path." },
+      // Leaves are `primary` by default; `overlay` is a dedicated
+      // type that carries a smaller body budget (see validate.mjs
+      // SIZE-CAP) and mandates overlay_targets[].
+      type: { kind: "enum", values: ["primary", "overlay"] },
+      // Leaves only ever carry depth_role "leaf". Indices have
+      // their own depth_role vocabulary (see index.depth_role
+      // below).
+      depth_role: { kind: "enum", values: ["leaf"] },
+      focus: { kind: "string", description: "One-line subject of the leaf." },
+      covers: { kind: "string[]", description: "Sub-topics or H2 headings." },
+      parents: { kind: "string[]", description: "Relative paths to parent index.md files (e.g. [index.md] or [../index.md])." },
+      tags: { kind: "string[]" },
+      source: {
+        kind: "object",
+        fields: {
+          origin: { kind: "enum", values: ["file", "synthetic"] },
+          path: { kind: "string", description: "POSIX-relative path from the source root." },
+          hash: { kind: "string", description: "SHA-256 of the source content." },
+        },
+      },
+      activation: { kind: "object", description: "Routing hints: keyword_matches, tag_matches, etc." },
+      domains: { kind: "string[]" },
+      aliases: { kind: "string[]" },
+      shared_covers: { kind: "string[]" },
+      // Only present (and required) when type === "overlay".
+      overlay_targets: { kind: "string[]" },
+      links: { kind: "string[]" },
+    },
+  },
+  index: {
+    required: ["id", "type", "depth_role", "focus"],
+    fields: {
+      id: { kind: "string", description: "Must match the containing directory's basename." },
+      type: { kind: "enum", values: ["index"] },
+      // `category` is the root index of a wiki; `subcategory` is
+      // any nested index. There is no `root` or `branch` role in
+      // the canonical shape; the skill refuses those.
+      depth_role: { kind: "enum", values: ["category", "subcategory"] },
+      focus: { kind: "string", description: "One-line subject of this branch." },
+      depth: { kind: "integer", description: "0 for root category, 1+ for subcategories." },
+      parents: { kind: "string[]", description: "Empty at the root; [../index.md] for nested." },
+      children: { kind: "string[]", description: "Relative paths to nested index files." },
+      entries: { kind: "object[]", description: "Per-leaf summaries (id, file, type, focus, tags)." },
+      shared_covers: { kind: "string[]", description: "Inherited by this branch's leaves." },
+      orientation: { kind: "string", description: "Authored guidance block; preserved across rebuilds." },
+      rebuild_command: { kind: "string" },
+      // Skill-generated marker; validate rejects a wiki root
+      // whose root index.md lacks it.
+      generator: { kind: "string", description: "e.g. \"skill-llm-wiki/v1\"; required on the root index." },
+    },
+  },
+};
+
+// Dynamic-subdirs template tokens supported inside
+// `.llmwiki.layout.yaml` under `layout[].dynamic_subdirs.template`.
+const LAYOUT_TOKENS = [
+  { token: "{yyyy}", description: "4-digit year." },
+  { token: "{mm}", description: "2-digit month." },
+  { token: "{dd}", description: "2-digit day of month." },
+  { token: "{slug}", description: "Leaf slug derived from source filename." },
+];
+
+// Exit code contract. Mirrors the banner in cli.mjs printUsage().
+// Listed here so consumers have a single machine-readable source.
+const EXIT_CODES = {
+  0: "ok",
+  1: "usage error",
+  2: "validation or ambiguity error",
+  3: "resolve-wiki miss",
+  4: "Node.js too old",
+  5: "git missing or too old",
+  6: "wiki corrupt",
+  7: "NEEDS_TIER2 — suspend and resume; not a failure",
+  8: "DEPS_MISSING — required runtime dep missing",
+};
+
+// Top-level subcommands consumers are expected to invoke. Low-level
+// helpers (`ingest`, `draft-leaf`, etc.) are deliberately omitted
+// from the contract: they are internal tools, subject to change
+// without a format_version bump. Keep this list in sync with
+// cli.mjs printUsage() top-level operations.
+// Keep this table in sync with scripts/cli.mjs. A drift test in
+// tests/unit/contract.test.mjs asserts every flag listed here is
+// actually accepted by the CLI's shared parser or one of the
+// per-subcommand handlers. `SUBCOMMANDS[*].flags` lists canonical
+// consumer-surface flags only; legacy aliases accepted by the CLI
+// (for example `--json-errors` as an alias of `--json`) are
+// deliberately omitted so consumers standardise on the current
+// flag form.
+const SUBCOMMANDS = {
+  build: {
+    positionals: ["source"],
+    flags: [
+      "--layout-mode",
+      "--target",
+      "--quality-mode",
+      "--no-prompt",
+      "--accept-dirty",
+      "--accept-foreign-target",
+      "--json",
+    ],
+  },
+  extend: {
+    positionals: ["wiki"],
+    flags: ["--quality-mode", "--no-prompt", "--json"],
+  },
+  validate: { positionals: ["wiki"], flags: ["--json"] },
+  rebuild: {
+    positionals: ["wiki"],
+    flags: ["--quality-mode", "--review", "--no-prompt", "--json"],
+  },
+  fix: { positionals: ["wiki"], flags: ["--json"] },
+  join: {
+    positionals: ["wiki-a", "wiki-b"],
+    flags: ["--target", "--canonical", "--json"],
+  },
+  rollback: { positionals: ["wiki"], flags: ["--to", "--json"] },
+  init: {
+    positionals: ["topic"],
+    flags: ["--kind", "--template", "--force", "--json"],
+  },
+  heal: { positionals: ["wiki"], flags: ["--dry-run", "--json"] },
+  where: { positionals: [], flags: ["--json"] },
+  contract: { positionals: [], flags: ["--json"] },
+  "testkit-stub": { positionals: [], flags: ["--at", "--layout"] },
+};
+
+// Envelope schema that --json stdout follows across every command.
+// Full JSON Schema lives in scripts/lib/json-envelope.mjs (Feature
+// 5). Consumers gate on the `schema` discriminator.
+const ENVELOPE_SCHEMA = {
+  schema: "skill-llm-wiki/v1",
+  fields: {
+    schema: { kind: "string", const: "skill-llm-wiki/v1" },
+    command: { kind: "string" },
+    target: { kind: "string|null" },
+    verdict: { kind: "string" },
+    exit: { kind: "integer" },
+    diagnostics: { kind: "object[]" },
+    artifacts: { kind: "object" },
+    timing_ms: { kind: "integer" },
+    // `next` is optional: present only when the subcommand wants
+    // to hand the consumer a machine-readable follow-up command
+    // (init emits `{command:"skill-llm-wiki", args:["build",...]}`,
+    // heal emits the fix/rebuild invocation). When absent, the
+    // consumer has nothing to run.
+    next: { kind: "object|null", fields: { command: "string", args: "string[]" } },
+  },
+};
+
+// ─── Assembly ───────────────────────────────────────────────────────
+
+function packageVersion() {
+  try {
+    const pkgUrl = new URL("../../package.json", import.meta.url);
+    return JSON.parse(readFileSync(pkgUrl, "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+export function getContract() {
+  return {
+    schema: "skill-llm-wiki/contract/v1",
+    format_version: FORMAT_VERSION,
+    min_consumer_format_version: MIN_CONSUMER_FORMAT_VERSION,
+    package_version: packageVersion(),
+    frontmatter_schema: FRONTMATTER_SCHEMA,
+    layout_tokens: LAYOUT_TOKENS,
+    subcommands: SUBCOMMANDS,
+    envelope_schema: ENVELOPE_SCHEMA,
+    exit_codes: EXIT_CODES,
+  };
+}
+
+// Human-readable summary. Used when `contract` is invoked without
+// --json. Keep it short: anyone who wants detail takes --json.
+export function renderContractText(contract) {
+  const lines = [];
+  lines.push(`skill-llm-wiki contract`);
+  lines.push(`  package_version: ${contract.package_version}`);
+  lines.push(`  format_version: ${contract.format_version}`);
+  lines.push(`  min_consumer_format_version: ${contract.min_consumer_format_version}`);
+  lines.push(`  subcommands: ${Object.keys(contract.subcommands).join(", ")}`);
+  lines.push(`  layout_tokens: ${contract.layout_tokens.map((t) => t.token).join(" ")}`);
+  lines.push(`  envelope: ${contract.envelope_schema.schema}`);
+  return lines.join("\n") + "\n";
+}

package/scripts/lib/heal.mjs

@@ -0,0 +1,162 @@
+// heal.mjs — classify validate findings and name the next command.
+//
+// `skill-llm-wiki heal <wiki>` runs validate internally, then maps
+// the findings to one of five verdicts:
+//
+//   ok            → nothing to do
+//   fixable       → `skill-llm-wiki fix <wiki>` will resolve it
+//   needs-rebuild → `skill-llm-wiki rebuild <wiki>` is required
+//   broken        → the wiki is corrupt; manual intervention needed
+//   ambiguous     → validate itself failed before producing findings
+//
+// The consumer invokes the recommended command as a separate step.
+// Heal does not run fix/rebuild directly: doing so pulls in the
+// orchestrator's error surface (Tier 2 exits, validation rollback,
+// non-interactive refusal) that a classify-only shape deliberately
+// avoids. A follow-up can add --apply once that error-mapping is
+// proven.
+//
+// The classification table below is the public contract: consumers
+// who want to pre-classify findings themselves (e.g. for a CI dash)
+// can import FINDING_ACTIONS.
+
+import { validateWiki } from "./validate.mjs";
+
+// Map every known finding code to the minimum action that resolves
+// it. Ranked from cheapest ("none") to most invasive ("manual"):
+//
+//   none    → a warning; no mutating step required
+//   fix     → `skill-llm-wiki fix` is sufficient
+//   rebuild → `skill-llm-wiki rebuild` is required
+//   manual  → the wiki is broken in a way the skill cannot self-heal
+export const FINDING_ACTIONS = Object.freeze({
+  // Wiki substrate / git:
+  "WIKI-01": "manual", // not a valid wiki root
+  "GIT-01": "manual", // private git is broken / divergent
+
+  // Content loss:
+  "LOSS-01": "rebuild", // source bytes not accounted for in target
+
+  // Parse / malformed frontmatter:
+  PARSE: "manual", // cannot parse YAML; user must edit
+
+  // Frontmatter field issues — fix regenerates most of these:
+  "MISSING-FIELD": "fix",
+  "DUP-ID": "rebuild",
+  "ALIAS-COLLIDES-ID": "fix",
+  "ID-MISMATCH-DIR": "rebuild",
+  "ID-MISMATCH-FILE": "rebuild",
+  "DEPTH-ROLE": "rebuild",
+  "PARENTS-REQUIRED": "rebuild",
+  "PARENT-CONTRACT": "rebuild",
+  "DANGLING-LINK": "fix",
+  "DANGLING-OVERLAY": "fix",
+
+  // Size cap is a warning surface only:
+  "SIZE-CAP": "none",
+});
+
+// Priority ranking: if any finding maps to a higher-priority action,
+// that action wins for the whole wiki.
+const PRIORITY = Object.freeze({ none: 0, fix: 1, rebuild: 2, manual: 3 });
+
+// Verdict that corresponds to each action tier. Keeps the four
+// tables (FINDING_ACTIONS, PRIORITY, NEXT_COMMAND_BY_ACTION,
+// VERDICT_BY_ACTION) in parallel so adding a new action tier means
+// adding one row in each.
+const VERDICT_BY_ACTION = Object.freeze({
+  none: "ok",
+  fix: "fixable",
+  rebuild: "needs-rebuild",
+  manual: "broken",
+});
+
+function actionFor(code) {
+  return FINDING_ACTIONS[code] ?? "rebuild";
+}
+
+// Core routing. Pure: call validateWiki separately if you want to
+// avoid re-validating.
+export function classifyFindings(findings) {
+  const actions = new Set();
+  for (const f of findings) {
+    // Warnings never trigger a mutating verdict — they're advisory.
+    if (f.severity !== "error") continue;
+    actions.add(actionFor(f.code));
+  }
+  if (actions.size === 0) {
+    return { action: "none", verdict: "ok" };
+  }
+  let best = "none";
+  for (const a of actions) {
+    if (PRIORITY[a] > PRIORITY[best]) best = a;
+  }
+  return { action: best, verdict: VERDICT_BY_ACTION[best] };
+}
+
+// Full heal run against a wiki path. Returns an object the CLI
+// wraps into an envelope.
+export function runHeal(wikiPath) {
+  let findings;
+  try {
+    findings = validateWiki(wikiPath);
+  } catch (err) {
+    return {
+      target: wikiPath,
+      verdict: "ambiguous",
+      action: "manual",
+      findings: [],
+      error: err.message,
+      next_command: null,
+    };
+  }
+  const { action, verdict } = classifyFindings(findings);
+  const next_command = buildNextCommand(action, wikiPath);
+  return {
+    target: wikiPath,
+    verdict,
+    action,
+    findings,
+    error: null,
+    next_command,
+  };
+}
+
+// Map every action to the CLI invocation that resolves it. A map
+// rather than an if/else chain keeps the action vocabulary in one
+// place next to FINDING_ACTIONS / PRIORITY / VERDICT_BY_ACTION. To
+// add a new action tier, add a row here; anything else falls back
+// to `null` (no auto-step).
+const NEXT_COMMAND_BY_ACTION = Object.freeze({
+  none: null,
+  fix: (wikiPath) => ["skill-llm-wiki", "fix", wikiPath, "--json"],
+  rebuild: (wikiPath) => ["skill-llm-wiki", "rebuild", wikiPath, "--json"],
+  manual: null,
+});
+
+function buildNextCommand(action, wikiPath) {
+  const builder = NEXT_COMMAND_BY_ACTION[action];
+  if (typeof builder !== "function") return null;
+  return builder(wikiPath);
+}
+
+// Human-readable rendering of a runHeal result. Lives here so the
+// text and JSON output of heal stay under the same roof and cannot
+// drift. Mirrors the renderContractText / renderInitText pattern.
+export function renderHealText(result) {
+  const lines = [`heal: ${result.verdict} (${result.action})`];
+  for (const f of result.findings) {
+    const tag =
+      f.severity === "error"
+        ? "ERR "
+        : f.severity === "warning"
+          ? "WARN"
+          : "INFO";
+    lines.push(`  [${tag}] ${f.code}  ${f.target}`);
+    lines.push(`         ${f.message}`);
+  }
+  if (result.next_command) {
+    lines.push(`  next: ${result.next_command.join(" ")}`);
+  }
+  return lines.join("\n") + "\n";
+}

package/scripts/lib/init.mjs

@@ -0,0 +1,210 @@
+// init.mjs — seed a topic directory with a shipped layout contract.
+//
+// `skill-llm-wiki init <topic> --kind dated|subject [--template <name>] [--force]`
+//
+// Removes the cp + edit + build-flag dance every consumer reinvents.
+// Seeds the contract file and returns a structured envelope telling
+// the consumer the exact build command to run next. Auto-build is
+// intentionally not included here: running build internally pulls in
+// the full orchestrator error surface (Tier 2 exits, validation
+// rollback, non-interactive refusal). A follow-up can add a --build
+// flag once the error-mapping story is proven out.
+//
+// Behaviour:
+//   1. Resolve topic path relative to cwd; create parent dirs if needed.
+//   2. Refuse if topic exists as a file, not a directory.
+//   3. Select template: explicit --template wins; otherwise
+//      defaultTemplateForKind.
+//   4. Refuse if <topic>/.llmwiki.layout.yaml already exists, unless
+//      --force.
+//   5. Copy the template's body to <topic>/.llmwiki.layout.yaml.
+//   6. Return a structured result; the CLI wraps it in the envelope.
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve as pathResolve } from "node:path";
+import {
+  defaultTemplateForKind,
+  getTemplate,
+  listTemplates,
+} from "./templates.mjs";
+
+const CONTRACT_FILENAME = ".llmwiki.layout.yaml";
+
+// Walk UP from `absTopic` to the first existing ancestor and
+// lstat it. Refuse if that ancestor is a symbolic link. This
+// catches the attack where a pre-existing symlink on the path to
+// absTopic would let `mkdirSync(recursive: true)` follow it and
+// create directories outside the user's intended tree.
+//
+// Non-existent segments need no check — mkdir creates them fresh.
+// Segments ABOVE the first existing ancestor are user-environment
+// territory (including OS symlinks like macOS's /var), not our
+// concern, and walking into them would produce false positives.
+function refuseSymlinkOnExistingAncestor(absTopic) {
+  let cursor = absTopic;
+  while (!existsSync(cursor)) {
+    const parent = dirname(cursor);
+    if (parent === cursor) return; // reached filesystem root, no anchor
+    cursor = parent;
+  }
+  const st = lstatSync(cursor);
+  if (st.isSymbolicLink()) {
+    throw new InitError(
+      "INIT-08",
+      `init: ${cursor} is a symbolic link on the path to ${absTopic}; refusing to write through it. Remove or resolve the symlink explicitly before initialising.`,
+    );
+  }
+}
+
+export class InitError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function runInit({
+  topic,
+  kind = null,
+  template = null,
+  force = false,
+  cwd = process.cwd(),
+} = {}) {
+  if (!topic || typeof topic !== "string") {
+    throw new InitError("INIT-01", "init requires a <topic> path");
+  }
+  const absTopic = pathResolve(cwd, topic);
+
+  // Pick the template.
+  let templateName = template;
+  if (!templateName) {
+    if (!kind) {
+      throw new InitError(
+        "INIT-02",
+        "init requires either --template <name> or --kind <dated|subject>",
+      );
+    }
+    templateName = defaultTemplateForKind(kind);
+    if (!templateName) {
+      throw new InitError(
+        "INIT-03",
+        `init: unknown --kind "${kind}". Accepted: dated, subject.`,
+      );
+    }
+  }
+  const tmpl = getTemplate(templateName);
+  if (!tmpl) {
+    const available = Object.keys(listTemplates()).join(", ");
+    throw new InitError(
+      "INIT-04",
+      `init: template "${templateName}" not found. Available: ${available}`,
+    );
+  }
+  // If the caller supplied both --kind and --template, check that
+  // they're compatible so we catch "`--kind dated --template runbooks`"
+  // before the consumer is surprised by a dated mis-shape.
+  if (kind && tmpl.kind !== "unknown" && tmpl.kind !== kind) {
+    throw new InitError(
+      "INIT-05",
+      `init: template "${templateName}" is kind=${tmpl.kind}, but --kind ${kind} was requested.`,
+    );
+  }
+
+  // Refuse to write through a pre-existing symlink in the topic
+  // path. Two shapes to catch:
+  //   (a) absTopic itself is a symbolic link — covered by the
+  //       existing-path branch below.
+  //   (b) an intermediate segment on the way to absTopic is a
+  //       symlink (e.g. `<parent>/sub -> /etc/` before init runs).
+  //       `mkdirSync(recursive: true)` would follow it and create
+  //       directories outside the user's intended topic tree.
+  //
+  // Algorithm: walk UP from absTopic until we find the first
+  // existing ancestor (the "anchor"), then lstat it. If the
+  // anchor is a symlink, refuse. Segments that do NOT yet exist
+  // are safe — mkdir creates them fresh. We deliberately do NOT
+  // walk past the anchor upward: OS-level symlinks above the
+  // user-chosen path (macOS's /var → /private/var on tmpdirs)
+  // would false-positive and block every test.
+  refuseSymlinkOnExistingAncestor(absTopic);
+
+  if (existsSync(absTopic)) {
+    const st = lstatSync(absTopic);
+    if (!st.isDirectory()) {
+      throw new InitError(
+        "INIT-06",
+        `init: ${absTopic} exists but is not a directory.`,
+      );
+    }
+  } else {
+    mkdirSync(absTopic, { recursive: true });
+  }
+
+  const contractPath = join(absTopic, CONTRACT_FILENAME);
+  // Same symlink guard for the contract file itself. An attacker
+  // who controls the topic directory could plant a symlink at
+  // <topic>/.llmwiki.layout.yaml pointing anywhere; without lstat
+  // we'd follow it on writeFileSync.
+  if (existsSync(contractPath)) {
+    const cst = lstatSync(contractPath);
+    if (cst.isSymbolicLink()) {
+      throw new InitError(
+        "INIT-08",
+        `init: ${contractPath} is a symbolic link; refusing to overwrite through it.`,
+      );
+    }
+  }
+  const alreadyPresent = existsSync(contractPath);
+  if (alreadyPresent && !force) {
+    throw new InitError(
+      "INIT-07",
+      `init: ${CONTRACT_FILENAME} already exists at ${absTopic}. Pass --force to overwrite, or use \`skill-llm-wiki rebuild\` to reconcile against the existing contract.`,
+    );
+  }
+
+  const body = readFileSync(tmpl.path, "utf8");
+  writeFileSync(contractPath, body, "utf8");
+
+  // The next step for the consumer. Passed back so the CLI can
+  // include it in the envelope both as a structured `next` field
+  // and as a human-readable NEXT-01 info diagnostic.
+  const buildCommand = [
+    "skill-llm-wiki",
+    "build",
+    absTopic,
+    "--layout-mode",
+    "hosted",
+    "--target",
+    absTopic,
+    "--json",
+  ];
+
+  return {
+    topic: absTopic,
+    template: templateName,
+    kind: tmpl.kind,
+    contract_path: contractPath,
+    overwrote: alreadyPresent,
+    build_command: buildCommand,
+    next: { command: buildCommand[0], args: buildCommand.slice(1) },
+  };
+}
+
+// Human-readable rendering of a runInit result. Lives here (not in
+// cli.mjs) so the text and JSON output of init stay under the same
+// roof and cannot drift. Mirrors the renderContractText /
+// renderWhereText pattern.
+export function renderInitText(result) {
+  return (
+    `init: seeded ${result.contract_path}\n` +
+    `  template: ${result.template} (kind=${result.kind})\n` +
+    (result.overwrote ? `  overwrote existing contract\n` : "") +
+    `  next: ${result.build_command.join(" ")}\n`
+  );
+}