@ctxr/skill-llm-wiki 1.0.1 → 1.0.2

package/scripts/lib/json-envelope.mjs

@@ -0,0 +1,190 @@
+// json-envelope.mjs — shared JSON stdout shape for consumer-facing
+// operational subcommands that use the envelope (validate, init,
+// heal, rollback). Those commands emit exactly one envelope object
+// on stdout; no surrounding prose, no multiple envelopes per
+// invocation. stderr stays free-form for logs.
+//
+// Probe-style commands — `contract --json` and `where --json` —
+// intentionally return their own non-envelope JSON shapes because
+// they pre-date the envelope contract and have stable consumer
+// schemas of their own (skill-llm-wiki/contract/v1 and
+// skill-llm-wiki/where/v1).
+//
+// Consumers validate the `schema` discriminator as their first
+// check. See guide/consumers/recipes/post-write-heal.md and
+// recipes/ci-gate.md for canonical parsing patterns.
+//
+// Envelope shape (format_version 1):
+//   {
+//     "schema": "skill-llm-wiki/v1",
+//     "command": "validate",
+//     "target": "/abs/path" | null,
+//     "verdict": "ok" | "fixable" | "needs-rebuild" | "broken"
+//              | "built" | "extended" | "healed" | "initialised"
+//              | "aborted" | "ambiguous",
+//     "exit": <integer>,
+//     "diagnostics": [
+//       { "code": "IDX-01", "severity": "warning", "path": "...", "message": "..." }
+//     ],
+//     "artifacts": { "created": [...], "modified": [...], "deleted": [...] },
+//     "timing_ms": <integer>,
+//     "next": null | { "command": "skill-llm-wiki", "args": ["fix", "/wiki", "--json"] }
+//   }
+//
+// `next` is present only when the subcommand wants to hand the
+// consumer a machine-readable follow-up command (init emits the
+// build invocation; heal emits the fix or rebuild invocation).
+// Consumers that receive `verdict: "fixable"` / `"needs-rebuild"`
+// should invoke `next.command` with `next.args` rather than parse
+// the `NEXT-01` info diagnostic's free-text message.
+
+export const ENVELOPE_SCHEMA = "skill-llm-wiki/v1";
+
+// Every known verdict string. Consumers can switch on these without
+// fearing a surprise value; adding a new verdict is a format_version
+// bump.
+export const VERDICTS = Object.freeze([
+  "ok",
+  "fixable",
+  "needs-rebuild",
+  "broken",
+  "built",
+  "extended",
+  "healed",
+  "initialised",
+  "aborted",
+  "ambiguous",
+]);
+
+// Diagnostic severity levels. Consumers gate their CI on `error`.
+export const SEVERITIES = Object.freeze(["error", "warning", "info"]);
+
+// Build an envelope from a minimal set of inputs. Missing artifact
+// buckets default to empty arrays so consumers never have to
+// defensively check for undefined.
+//
+// `next` is an optional structured hint for consumers that also
+// carries a human-readable form in an info diagnostic. It is the
+// machine-readable sibling of the NEXT-01 diagnostic consumers may
+// still parse today.
+export function makeEnvelope({
+  command,
+  target = null,
+  verdict,
+  exit,
+  diagnostics = [],
+  artifacts = {},
+  timing_ms = 0,
+  next = null,
+} = {}) {
+  if (!command || typeof command !== "string") {
+    throw new Error("makeEnvelope: command is required");
+  }
+  if (!verdict || typeof verdict !== "string") {
+    throw new Error("makeEnvelope: verdict is required");
+  }
+  if (!VERDICTS.includes(verdict)) {
+    throw new Error(
+      `makeEnvelope: unknown verdict "${verdict}". Known: ${VERDICTS.join(", ")}`,
+    );
+  }
+  if (!Number.isInteger(exit)) {
+    throw new Error("makeEnvelope: exit must be an integer");
+  }
+  const envelope = {
+    schema: ENVELOPE_SCHEMA,
+    command,
+    target,
+    verdict,
+    exit,
+    diagnostics: Array.isArray(diagnostics) ? diagnostics : [],
+    artifacts: {
+      created: artifacts.created ?? [],
+      modified: artifacts.modified ?? [],
+      deleted: artifacts.deleted ?? [],
+    },
+    timing_ms: Number.isInteger(timing_ms) ? timing_ms : 0,
+  };
+  if (next !== null) {
+    if (
+      typeof next !== "object" ||
+      typeof next.command !== "string" ||
+      !Array.isArray(next.args)
+    ) {
+      throw new Error(
+        "makeEnvelope: next must be { command: string, args: string[] } or null",
+      );
+    }
+    envelope.next = { command: next.command, args: next.args.slice() };
+  }
+  return envelope;
+}
+
+// Shared error-envelope builder used by consumer subcommands that
+// need to surface a structured failure without reinventing the
+// envelope shape. Verdict defaults to "ambiguous" (the canonical
+// error verdict) and exit defaults to 2 (validation / ambiguity per
+// the skill-wide scheme). Usage-error callers pass exit=1 explicitly.
+export function makeErrorEnvelope({
+  command,
+  code,
+  message,
+  target = null,
+  verdict = "ambiguous",
+  exit = 2,
+} = {}) {
+  if (!command || typeof command !== "string") {
+    throw new Error("makeErrorEnvelope: command is required");
+  }
+  if (!code || typeof code !== "string") {
+    throw new Error("makeErrorEnvelope: code is required");
+  }
+  return makeEnvelope({
+    command,
+    target,
+    verdict,
+    exit,
+    diagnostics: [
+      { code, severity: "error", path: target, message: message ?? "" },
+    ],
+  });
+}
+
+// Write an envelope to stdout as one line of JSON followed by a
+// newline. Single-line output is easier to pipe through `jq` and
+// also to `grep`-assert in test harnesses.
+export function writeEnvelope(envelope, stream = process.stdout) {
+  stream.write(JSON.stringify(envelope) + "\n");
+}
+
+// Detect whether --json or --json-errors (legacy alias) was passed.
+// Returns true on the first positive match. `--json-errors`
+// predates the envelope; we accept it as an alias rather than
+// deprecating it loudly, because every existing consumer passes it
+// to get structured intent errors.
+//
+// Only the bare flag forms are supported. `--json=1` / `--json=true`
+// are NOT accepted: the skill's shared arg parser (parseSubArgv)
+// rejects inline values on boolean flags, and hasJsonFlag would
+// otherwise diverge from that contract and silently accept an
+// argument shape that build/extend/rebuild/... reject.
+export function hasJsonFlag(args) {
+  if (!Array.isArray(args)) return false;
+  for (const tok of args) {
+    if (typeof tok !== "string") continue;
+    if (tok === "--json" || tok === "--json-errors") return true;
+  }
+  return false;
+}
+
+// Convert a validate-style finding (code, severity, target, message)
+// into a diagnostic object in the envelope's canonical shape. Shared
+// so consumers see the same field names everywhere.
+export function findingToDiagnostic(finding) {
+  return {
+    code: finding.code ?? "UNKNOWN",
+    severity: finding.severity ?? "info",
+    path: finding.target ?? null,
+    message: finding.message ?? "",
+  };
+}

package/scripts/lib/templates.mjs

@@ -0,0 +1,78 @@
+// templates.mjs — discovery + metadata for the shipped layout
+// templates under <SKILL_ROOT>/templates/*.llmwiki.layout.yaml.
+//
+// Feature 1 (this module) exposes the list and paths. Feature 2
+// (init) uses them to seed a consumer's topic wiki with one command.
+// Consumers can also copy templates by hand via `skill-llm-wiki
+// where --json` + templates_dir.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { SKILL_ROOT } from "./where.mjs";
+
+const TEMPLATES_DIR = join(SKILL_ROOT, "templates");
+const TEMPLATE_SUFFIX = ".llmwiki.layout.yaml";
+
+// Metadata layer ON TOP of the template files. Keeps the per-template
+// YAML focused on the layout contract itself while the "what kind of
+// topic am I?" mapping lives in code. A template whose name isn't
+// listed here is still usable, just not recommended via the CLI's
+// `--kind` short-hand.
+const TEMPLATE_META = {
+  reports: { kind: "dated", description: "Generated reports filed by day." },
+  sessions: { kind: "dated", description: "Daily session logs filed by day." },
+  regressions: { kind: "dated", description: "Regression notes filed by month." },
+  plans: { kind: "dated", description: "Plans filed by day, with subject subfolders for families." },
+  runbooks: { kind: "subject", description: "Runbooks grouped by subject." },
+  adrs: { kind: "subject", description: "Architecture decision records, numbered by subject." },
+};
+
+export function templatesDir() {
+  return TEMPLATES_DIR;
+}
+
+// Return a map of template name (e.g. "reports") -> { path, kind,
+// description }. Only templates that actually exist on disk are
+// returned — package.json `files` ships the templates/ dir, but a
+// broken install or an older skill version may lack a given file.
+export function listTemplates() {
+  if (!existsSync(TEMPLATES_DIR)) return {};
+  const out = {};
+  for (const entry of readdirSync(TEMPLATES_DIR)) {
+    if (!entry.endsWith(TEMPLATE_SUFFIX)) continue;
+    const name = entry.slice(0, -TEMPLATE_SUFFIX.length);
+    const abs = join(TEMPLATES_DIR, entry);
+    try {
+      if (!statSync(abs).isFile()) continue;
+    } catch {
+      continue;
+    }
+    const meta = TEMPLATE_META[name] ?? {
+      kind: "unknown",
+      description: "",
+    };
+    out[name] = { path: abs, kind: meta.kind, description: meta.description };
+  }
+  return out;
+}
+
+export function getTemplate(name) {
+  const all = listTemplates();
+  return all[name] ?? null;
+}
+
+export function readTemplate(name) {
+  const t = getTemplate(name);
+  if (!t) return null;
+  return readFileSync(t.path, "utf8");
+}
+
+// Returns the canonical default template name for a given --kind.
+// Consumers who don't want to name a specific template can pass
+// --kind and get a sensible default (dated -> reports, subject ->
+// runbooks).
+export function defaultTemplateForKind(kind) {
+  if (kind === "dated") return "reports";
+  if (kind === "subject") return "runbooks";
+  return null;
+}

package/scripts/lib/where.mjs

@@ -0,0 +1,71 @@
+// where.mjs — canonical "where am I installed?" report.
+//
+// Consumers need a reliable way to resolve the skill's install path
+// without hard-coding `~/.claude/skills/...` or duplicating the
+// @ctxr/kit path list. `skill-llm-wiki where` answers:
+//   - where is the skill root?
+//   - where is SKILL.md?
+//   - where is the templates/ directory?
+//   - where is the scripts/testkit/ directory?
+//   - what are the current package and format versions?
+//
+// Safe to invoke before the runtime-dep preflight resolves; uses
+// only node:fs + node:path + node:url. No gray-matter, no transformers.
+
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { FORMAT_VERSION } from "./contract.mjs";
+
+// `where.mjs` lives at <SKILL_ROOT>/scripts/lib/where.mjs. The skill
+// root is two directories up. Exported so other lib / testkit
+// modules that need the skill root import this single source of
+// truth (contract.mjs, templates.mjs, cli-run.mjs).
+export const SKILL_ROOT = dirname(
+  dirname(dirname(fileURLToPath(import.meta.url))),
+);
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(SKILL_ROOT, "package.json"), "utf8"),
+    );
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function pathIfExists(p) {
+  return existsSync(p) ? p : null;
+}
+
+export function getWhere() {
+  return {
+    schema: "skill-llm-wiki/where/v1",
+    skill_root: SKILL_ROOT,
+    skill_md: join(SKILL_ROOT, "SKILL.md"),
+    cli: join(SKILL_ROOT, "scripts", "cli.mjs"),
+    guide_dir: join(SKILL_ROOT, "guide"),
+    templates_dir: pathIfExists(join(SKILL_ROOT, "templates")),
+    testkit_dir: pathIfExists(join(SKILL_ROOT, "scripts", "testkit")),
+    package_version: readPackageVersion(),
+    format_version: FORMAT_VERSION,
+  };
+}
+
+// Human-readable summary. Absolute paths, one per line, aligned so
+// operators can eyeball things without parsing JSON.
+export function renderWhereText(info) {
+  const lines = [
+    `skill_root:       ${info.skill_root}`,
+    `skill_md:         ${info.skill_md}`,
+    `cli:              ${info.cli}`,
+    `guide_dir:        ${info.guide_dir}`,
+    `templates_dir:    ${info.templates_dir ?? "<not shipped>"}`,
+    `testkit_dir:      ${info.testkit_dir ?? "<not shipped>"}`,
+    `package_version:  ${info.package_version}`,
+    `format_version:   ${info.format_version}`,
+  ];
+  return lines.join("\n") + "\n";
+}

package/scripts/testkit/assert-frontmatter.mjs

@@ -0,0 +1,171 @@
+// assert-frontmatter.mjs — testkit helper: read a leaf, parse its
+// frontmatter block, assert expected fields match.
+//
+// Deliberately lightweight: does not import gray-matter. The
+// opening `---` fence, body, and closing `---` fence pattern the
+// skill emits is stable enough that a ~10-line parser is the right
+// shape for a testkit. Tolerates both LF and CRLF line endings so
+// consumer tests running on Windows runners don't see spurious
+// parse failures.
+//
+// Zero runtime deps; pure Node built-ins.
+
+import { readFileSync } from "node:fs";
+
+// Both fences match CRLF and LF: git on Windows checks repos out
+// with native line endings by default. Capture group on FM_START is
+// the length of the consumed fence so the caller can slice past it.
+const FM_START = /^---(\r?\n)/;
+const FM_END = /\r?\n---(\r?\n|$)/;
+
+// Parse a leaf's frontmatter block into a flat key: string-ish
+// object. Only the shallow YAML shape the skill emits is
+// supported. For full YAML-as-data consumers should use gray-matter
+// in their own test code; this helper is for sanity checks.
+export function readLeafFrontmatter(absLeafPath) {
+  const raw = readFileSync(absLeafPath, "utf8");
+  const startMatch = FM_START.exec(raw);
+  if (!startMatch) {
+    throw new Error(
+      `readLeafFrontmatter: ${absLeafPath} has no frontmatter block`,
+    );
+  }
+  const afterFirst = raw.slice(startMatch[0].length);
+  const endMatch = FM_END.exec(afterFirst);
+  if (!endMatch) {
+    throw new Error(
+      `readLeafFrontmatter: ${absLeafPath} has an unterminated frontmatter block`,
+    );
+  }
+  const block = afterFirst.slice(0, endMatch.index);
+  const data = {};
+  // A "pending key" is a top-level key with an empty RHS whose
+  // type isn't yet decided. The first indented continuation line
+  // picks: `- x` → list, `subkey: v` → map. Once decided, further
+  // continuations at the same indent extend the same container.
+  let pendingKey = null;
+  let pendingIndent = -1;
+  let pendingKind = null; // null | "list" | "map"
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const indent = line.length - line.trimStart().length;
+    const trimmed = line.trimStart();
+
+    // Continuation: line is indented past the open key.
+    if (pendingKey !== null && indent > pendingIndent) {
+      const listMatch = /^-\s*(.*)$/.exec(trimmed);
+      if (listMatch && (pendingKind === null || pendingKind === "list")) {
+        if (pendingKind === null) {
+          data[pendingKey] = [];
+          pendingKind = "list";
+        }
+        data[pendingKey].push(unquote(listMatch[1].trim()));
+        continue;
+      }
+      const nestedKv = /^([a-z_][a-z0-9_]*)\s*:\s*(.*)$/i.exec(trimmed);
+      if (nestedKv && (pendingKind === null || pendingKind === "map")) {
+        if (pendingKind === null) {
+          data[pendingKey] = {};
+          pendingKind = "map";
+        }
+        data[pendingKey][nestedKv[1]] = unquote(nestedKv[2].trim());
+        continue;
+      }
+      // Fall through: unknown continuation shape, ignore.
+      continue;
+    }
+
+    // New top-level key ends any open container.
+    const kv = /^([a-z_][a-z0-9_]*)\s*:\s*(.*)$/i.exec(line);
+    if (!kv) continue;
+    pendingKey = null;
+    pendingIndent = -1;
+    pendingKind = null;
+    const key = kv[1];
+    const val = kv[2].trim();
+    if (val === "") {
+      // Empty RHS: open a pending key; the first continuation
+      // picks list vs map. Default to an empty object until
+      // decided — consumers that assert a key exists without
+      // inspecting its type still pass.
+      data[key] = {};
+      pendingKey = key;
+      pendingIndent = indent;
+      pendingKind = null;
+    } else if (val === "[]") {
+      data[key] = [];
+    } else if (val.startsWith("[") && val.endsWith("]")) {
+      data[key] = val
+        .slice(1, -1)
+        .split(",")
+        .map((s) => unquote(s.trim()))
+        .filter(Boolean);
+    } else {
+      data[key] = unquote(val);
+    }
+  }
+  return data;
+}
+
+function unquote(s) {
+  if (
+    (s.startsWith('"') && s.endsWith('"')) ||
+    (s.startsWith("'") && s.endsWith("'"))
+  ) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+// Compare actual frontmatter to an expected subset. Only fields
+// named in `expected` are checked; extra fields in the leaf are
+// allowed. Arrays compare element-wise as strings; objects compare
+// each expected key shallowly (string-equality) so consumers can
+// write `{ source: { origin: "file", path: "foo.md" } }` against
+// the skill's canonical frontmatter shape.
+//
+// Throws an Error when any mismatch is found. Returns the parsed
+// frontmatter object on success.
+export function assertFrontmatterShape(absLeafPath, expected) {
+  const data = readLeafFrontmatter(absLeafPath);
+  const mismatches = [];
+  for (const [key, want] of Object.entries(expected ?? {})) {
+    const got = data[key];
+    if (Array.isArray(want)) {
+      if (!Array.isArray(got)) {
+        mismatches.push(`${key}: expected array, got ${JSON.stringify(got)}`);
+        continue;
+      }
+      if (got.length !== want.length || got.some((v, i) => String(v) !== String(want[i]))) {
+        mismatches.push(
+          `${key}: expected [${want.join(", ")}], got [${got.join(", ")}]`,
+        );
+      }
+      continue;
+    }
+    if (want !== null && typeof want === "object") {
+      if (got === null || typeof got !== "object" || Array.isArray(got)) {
+        mismatches.push(`${key}: expected object, got ${JSON.stringify(got)}`);
+        continue;
+      }
+      for (const [subKey, subWant] of Object.entries(want)) {
+        if (String(got[subKey]) !== String(subWant)) {
+          mismatches.push(
+            `${key}.${subKey}: expected ${JSON.stringify(subWant)}, got ${JSON.stringify(got[subKey])}`,
+          );
+        }
+      }
+      continue;
+    }
+    if (String(got) !== String(want)) {
+      mismatches.push(`${key}: expected ${JSON.stringify(want)}, got ${JSON.stringify(got)}`);
+    }
+  }
+  if (mismatches.length > 0) {
+    throw new Error(
+      `assertFrontmatterShape failed for ${absLeafPath}:\n  - ` +
+        mismatches.join("\n  - "),
+    );
+  }
+  return data;
+}

package/scripts/testkit/cli-run.mjs

@@ -0,0 +1,95 @@
+// cli-run.mjs — testkit helper: spawn the skill CLI as a child
+// process, capture stdout/stderr/exitCode, optionally parse the
+// --json envelope. Consumers use this in their test suites to drive
+// the skill without re-implementing the spawn ceremony.
+//
+// Zero runtime deps; pure Node built-ins.
+
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { SKILL_ROOT } from "../lib/where.mjs";
+import { hasJsonFlag } from "../lib/json-envelope.mjs";
+
+export const CLI_PATH = join(SKILL_ROOT, "scripts", "cli.mjs");
+
+// Run the skill CLI with `args`. Returns an object of:
+//   { status, stdout, stderr, envelope, error }
+//
+// `envelope` is only populated when `args` includes `--json` or
+// `--json-errors` AND the stdout parses as JSON. On parse failure it
+// is `null` and the caller can inspect `stdout` directly.
+//
+// `error` is populated when the child process could not be spawned
+// at all (ENOENT, EACCES, EPERM). When it is set, `status` will be
+// `null` (spawnSync's convention) and the `error` field carries the
+// Node errno. Consumers writing cross-platform tests need to see
+// this to distinguish "CLI ran and exited with status X" from "CLI
+// never ran".
+//
+// Note on environment: when `env` is supplied, the testkit forwards
+// the parent process environment too (object-spread with the
+// override). This is intentional for local test convenience; CI
+// harnesses writing untrusted fixtures should scrub `process.env`
+// before calling.
+export function runCli(args, { cwd, env } = {}) {
+  const resolvedArgs = Array.isArray(args) ? args : [];
+  const r = spawnSync(process.execPath, [CLI_PATH, ...resolvedArgs], {
+    encoding: "utf8",
+    cwd: cwd ?? process.cwd(),
+    env: env ? { ...process.env, ...env } : process.env,
+  });
+  const wantJson = hasJsonFlag(resolvedArgs);
+  let envelope = null;
+  if (wantJson && r.stdout) {
+    // Two output shapes exist. Envelope subcommands (validate, init,
+    // heal) emit a single-line JSON object. contract/where emit
+    // pretty-printed JSON spanning multiple lines. Try parsing the
+    // full stdout first; if that fails, fall back to the last
+    // JSON-like line (handles envelope output that may be preceded
+    // by progress lines).
+    const full = r.stdout.trim();
+    try {
+      envelope = JSON.parse(full);
+    } catch {
+      const lines = full.split("\n");
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line.startsWith("{")) continue;
+        try {
+          envelope = JSON.parse(line);
+          break;
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+  return {
+    status: r.status,
+    stdout: r.stdout,
+    stderr: r.stderr,
+    envelope,
+    error: r.error ?? null,
+  };
+}
+
+// Convenience: assert a clean run, throw on non-zero exit with the
+// stderr attached so the consumer's test output is useful. When the
+// child failed to spawn at all (ENOENT/EACCES), surface that
+// explicitly rather than saying "exited null".
+export function runCliOk(args, opts) {
+  const r = runCli(args, opts);
+  const argString = Array.isArray(args) ? args.join(" ") : "";
+  if (r.error) {
+    throw new Error(
+      `runCliOk: failed to spawn skill-llm-wiki ${argString}: ` +
+        `${r.error.code ?? "unknown"} — ${r.error.message}`,
+    );
+  }
+  if (r.status !== 0) {
+    throw new Error(
+      `runCliOk: skill-llm-wiki ${argString} exited ${r.status}:\n${r.stderr}`,
+    );
+  }
+  return r;
+}