@ctxr/skill-llm-wiki 1.0.1

package/scripts/lib/paths.mjs

@@ -0,0 +1,197 @@
+// Sibling-versioned output directory conventions.
+//
+// For any user source `./docs`, a wiki lives at `./docs.llmwiki.v<N>/` and
+// the current version is tracked via a plaintext file `./docs.llmwiki.current`
+// containing a single line `v<N>`. Rollback is `echo v2 > docs.llmwiki.current`.
+//
+// Every operation that produces structural change writes a new vN+1 and then
+// atomically flips the current pointer on successful commit. The previous
+// version stays on disk until the user explicitly prunes.
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+const VERSION_RE = /^v(\d+)$/;
+
+// Marker written into the root index.md frontmatter by this skill. The hook
+// will ONLY react on directories whose root index carries this marker —
+// folders that merely happen to match the `*.llmwiki.vN` naming pattern are
+// ignored. Bump the version suffix (v1 → v2) when the wiki format changes
+// in a way that would confuse older hook code.
+export const WIKI_GENERATOR_MARKER = "skill-llm-wiki/v1";
+
+export function wikiBaseName(sourcePath) {
+  return basename(resolve(sourcePath));
+}
+
+export function siblingRoot(sourcePath) {
+  return dirname(resolve(sourcePath));
+}
+
+// The default sibling target for any source is `<source>.wiki` — NOT
+// `<source>.llmwiki.v1`. History lives in the private git repo inside
+// the wiki directory (see Phase 1 `snapshot.mjs`), so we never need
+// version-numbered folder names. Trailing slashes on the source path
+// are normalised away by `resolve`.
+//
+// Examples:
+//   defaultSiblingPath("./docs")       → "/abs/cwd/docs.wiki"
+//   defaultSiblingPath("./docs/")      → "/abs/cwd/docs.wiki"
+//   defaultSiblingPath("/tmp/fluffy")  → "/tmp/fluffy.wiki"
+//   defaultSiblingPath(".")            → "/abs/cwd.wiki"   (basename of cwd)
+export function defaultSiblingPath(sourcePath) {
+  const base = wikiBaseName(sourcePath);
+  return join(siblingRoot(sourcePath), `${base}.wiki`);
+}
+
+export function currentPointerPath(sourcePath) {
+  const base = wikiBaseName(sourcePath);
+  return join(siblingRoot(sourcePath), `${base}.llmwiki.current`);
+}
+
+export function versionDir(sourcePath, version) {
+  const base = wikiBaseName(sourcePath);
+  const tag = typeof version === "number" ? `v${version}` : version;
+  return join(siblingRoot(sourcePath), `${base}.llmwiki.${tag}`);
+}
+
+// Return all existing `<base>.llmwiki.v<N>` directories sorted ascending by N.
+export function listVersions(sourcePath) {
+  const base = wikiBaseName(sourcePath);
+  const parent = siblingRoot(sourcePath);
+  if (!existsSync(parent)) return [];
+  const prefix = `${base}.llmwiki.`;
+  const out = [];
+  for (const name of readdirSync(parent)) {
+    if (!name.startsWith(prefix)) continue;
+    const tag = name.slice(prefix.length);
+    const m = VERSION_RE.exec(tag);
+    if (!m) continue;
+    const full = join(parent, name);
+    try {
+      if (statSync(full).isDirectory()) {
+        out.push({ version: Number(m[1]), tag, path: full });
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  out.sort((a, b) => a.version - b.version);
+  return out;
+}
+
+export function readCurrentPointer(sourcePath) {
+  const p = currentPointerPath(sourcePath);
+  if (!existsSync(p)) return null;
+  const raw = readFileSync(p, "utf8").trim();
+  const m = VERSION_RE.exec(raw);
+  if (!m) return null;
+  return { tag: raw, version: Number(m[1]), path: versionDir(sourcePath, raw) };
+}
+
+export function writeCurrentPointer(sourcePath, versionTag) {
+  const p = currentPointerPath(sourcePath);
+  writeFileSync(p, `${versionTag}\n`, "utf8");
+}
+
+// Resolve the "live" wiki for a source, preferring the current-pointer,
+// falling back to the highest existing version, or null if none exist.
+export function resolveLiveWiki(sourcePath) {
+  const pointer = readCurrentPointer(sourcePath);
+  if (pointer && existsSync(pointer.path)) return pointer;
+  const versions = listVersions(sourcePath);
+  if (versions.length === 0) return null;
+  const latest = versions[versions.length - 1];
+  return { tag: latest.tag, version: latest.version, path: latest.path };
+}
+
+export function nextVersionTag(sourcePath) {
+  const versions = listVersions(sourcePath);
+  const next = versions.length === 0 ? 1 : versions[versions.length - 1].version + 1;
+  return `v${next}`;
+}
+
+export function workDir(wikiPath) {
+  return join(wikiPath, ".work");
+}
+
+export function shapeDir(wikiPath) {
+  return join(wikiPath, ".shape");
+}
+
+// A directory is a wiki root iff:
+//   (a) it contains an `index.md`
+//   (b) that `index.md`'s frontmatter declares `generator: skill-llm-wiki/v<N>`
+//   (c) AND AT LEAST ONE of:
+//       - it has a `.llmwiki/git/HEAD` file (new default — private-git managed)
+//       - its name matches `*.llmwiki.v<N>` (legacy sibling-versioned mode)
+//       - it has a `.llmwiki.layout.yaml` file at its root (hosted mode)
+//
+// The generator marker (b) is the core safety check — it positively
+// identifies a directory the skill itself built. Private-git presence
+// (c-top) is the recognition the new default sibling layout `<source>.wiki/`
+// relies on. Name matching (c-middle) keeps old sibling-versioned wikis
+// recognisable during auto-migration. Layout contract presence (c-bottom)
+// handles hosted-mode targets with arbitrary names like `./memory/`.
+//
+// Phase 1 only adds the private-git branch; Phase 2's migrate.mjs uses it
+// to decide whether a target is already managed.
+export function isWikiRoot(dirPath) {
+  const indexMd = join(dirPath, "index.md");
+  if (!existsSync(indexMd)) return false;
+
+  const base = basename(dirPath);
+  const hasPrivateGit = existsSync(join(dirPath, ".llmwiki", "git", "HEAD"));
+  const hasVersionedName = /\.llmwiki\.v\d+$/.test(base);
+  const hasLayoutContract = existsSync(join(dirPath, ".llmwiki.layout.yaml"));
+
+  // Must satisfy at least one structural recognition rule.
+  if (!hasPrivateGit && !hasVersionedName && !hasLayoutContract) return false;
+
+  // Frontmatter probe: cheap, bounded, no YAML parse required for the
+  // marker check — we just look for the line within the fence.
+  try {
+    const raw = readFileSync(indexMd, "utf8");
+    return hasGeneratorMarker(raw);
+  } catch {
+    return false;
+  }
+}
+
+// Cheap existence check used by Phase 2's intent resolution to detect
+// "this folder is already a skill-managed wiki" without parsing index.md.
+// Unlike isWikiRoot, this returns true even when the directory has a
+// private git repo but no index.md yet (partially-initialised state).
+export function hasPrivateGit(dirPath) {
+  return existsSync(join(dirPath, ".llmwiki", "git", "HEAD"));
+}
+
+// Legacy format detection — a folder whose basename matches `*.llmwiki.v<N>`.
+// Used by Phase 2's auto-migration to prompt the user before operating on
+// a legacy wiki. Intentionally lightweight: no filesystem reads beyond the
+// basename, no frontmatter probe.
+export function isLegacyVersionedWiki(dirPath) {
+  return /\.llmwiki\.v\d+$/.test(basename(dirPath));
+}
+
+function hasGeneratorMarker(raw) {
+  if (!raw.startsWith("---\n")) return false;
+  const end = raw.indexOf("\n---\n", 4);
+  if (end === -1) return false;
+  const fm = raw.slice(4, end);
+  // Accept `generator: skill-llm-wiki/v1` with or without quotes.
+  return /^\s*generator:\s*['"]?skill-llm-wiki\/v\d+['"]?\s*$/m.test(fm);
+}
+
+// Walk upward from `startPath` to find the nearest wiki root. Returns the
+// absolute path to the wiki root, or null if the starting path is not
+// inside a skill-managed wiki.
+export function findEnclosingWiki(startPath) {
+  let cur = resolve(startPath);
+  while (true) {
+    if (isWikiRoot(cur)) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}

package/scripts/lib/preflight.mjs

@@ -0,0 +1,213 @@
+// preflight.mjs — centralized runtime checks invoked from cli.mjs and
+// any long-running phase that wants defence-in-depth against a broken
+// environment.
+//
+// Exit codes (kept consistent with cli.mjs):
+//   4 — Node too old / missing
+//   5 — git missing / too old
+//   6 — wiki present but corrupt (git fsck failed)
+//   8 — required runtime dependency missing (DEPS_MISSING)
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { BASE_ISOLATION_ENV, gitFsck } from "./git.mjs";
+
+export const REQUIRED_NODE_MAJOR = 18;
+export const REQUIRED_GIT_MAJOR = 2;
+export const REQUIRED_GIT_MINOR = 25;
+
+// The runtime dependencies that MUST be resolvable from `skillRoot` for
+// any operation to run. Both are declared in package.json `dependencies`
+// (not devDependencies) and are pulled in by `npm install` automatically.
+// `gray-matter` is required to parse authored frontmatter in source files;
+// `@xenova/transformers` powers the local Tier 1 embeddings model used
+// during operator-convergence. The list is exported so tests can verify
+// the contract without re-declaring the names.
+export const REQUIRED_RUNTIME_DEPS = ["gray-matter", "@xenova/transformers"];
+
+// Parse `vX.Y.Z` → { major, minor }. Returns null on malformed input.
+function parseNodeVersion(raw) {
+  const m = /^v(\d+)\.(\d+)/.exec(raw);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]) };
+}
+
+// Parse `git version 2.25.1 (Apple Git-133)` → { major, minor }.
+function parseGitVersion(raw) {
+  const m = /git version (\d+)\.(\d+)/.exec(raw);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]) };
+}
+
+// Returns { ok: true } on success, otherwise { ok: false, message, exitCode }.
+export function preflightNode() {
+  const raw = (process && process.version) || "";
+  const v = parseNodeVersion(raw);
+  if (!v || v.major < REQUIRED_NODE_MAJOR) {
+    return {
+      ok: false,
+      exitCode: 4,
+      message:
+        `skill-llm-wiki: Node.js ${raw || "<unknown>"} is below the required ` +
+        `minimum (v${REQUIRED_NODE_MAJOR}.0.0).\n` +
+        "Please upgrade Node.js and retry. See SKILL.md " +
+        "'Preflight: verify Node.js is installed' for platform-specific " +
+        "install instructions.\n",
+    };
+  }
+  return { ok: true, version: v };
+}
+
+// Returns { ok: true, version } when git is present and new enough, otherwise
+// { ok: false, exitCode, message }. Spawns `git --version` with an isolated
+// env so a user with GIT_* env vars set cannot redirect it. Reuses
+// BASE_ISOLATION_ENV from git.mjs so this preflight probe and the main
+// subprocess path stay in lockstep (including the Windows NUL override).
+// The parent `process.env` is filtered to drop every `GIT_*` / `SSH_ASKPASS`
+// key before the isolation block is applied, matching `buildGitEnv` (D3).
+function preflightGitEnv() {
+  const out = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith("GIT_")) continue;
+    if (k === "SSH_ASKPASS") continue;
+    out[k] = v;
+  }
+  return { ...out, ...BASE_ISOLATION_ENV };
+}
+
+export function preflightGit() {
+  const result = spawnSync("git", ["--version"], {
+    encoding: "utf8",
+    env: preflightGitEnv(),
+  });
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      exitCode: 5,
+      message:
+        "skill-llm-wiki: `git` binary not found on PATH.\n" +
+        `Please install Git >= ${REQUIRED_GIT_MAJOR}.${REQUIRED_GIT_MINOR}.\n` +
+        "macOS:    brew install git\n" +
+        "Debian:   sudo apt-get install git\n" +
+        "Fedora:   sudo dnf install git\n" +
+        "Windows:  https://git-scm.com/download/win\n",
+    };
+  }
+  const raw = (result.stdout || "").trim();
+  const v = parseGitVersion(raw);
+  if (!v) {
+    return {
+      ok: false,
+      exitCode: 5,
+      message: `skill-llm-wiki: unable to parse git version from "${raw}"\n`,
+    };
+  }
+  if (
+    v.major < REQUIRED_GIT_MAJOR ||
+    (v.major === REQUIRED_GIT_MAJOR && v.minor < REQUIRED_GIT_MINOR)
+  ) {
+    return {
+      ok: false,
+      exitCode: 5,
+      message:
+        `skill-llm-wiki: Git ${v.major}.${v.minor} is below the required minimum ` +
+        `(${REQUIRED_GIT_MAJOR}.${REQUIRED_GIT_MINOR}).\n` +
+        "Please upgrade git and retry.\n",
+    };
+  }
+  return { ok: true, version: v };
+}
+
+// Optional check: when pointed at an existing wiki, run git fsck inside
+// the private repo to catch object corruption early. If `.llmwiki/git/`
+// does not exist, this is a no-op success — the wiki predates git tracking.
+export function preflightWiki(wikiRoot) {
+  if (!existsSync(join(wikiRoot, ".llmwiki", "git", "HEAD"))) {
+    return { ok: true, reason: "no-private-git" };
+  }
+  const r = gitFsck(wikiRoot);
+  if (!r.ok) {
+    return {
+      ok: false,
+      exitCode: 6,
+      message:
+        `skill-llm-wiki: private git repo at ${wikiRoot}/.llmwiki/git/ ` +
+        `failed integrity check:\n${r.stderr.trim() || r.stdout.trim()}\n`,
+    };
+  }
+  return { ok: true };
+}
+
+// Verify that the skill's required runtime dependencies are installed and
+// resolvable from `skillRoot`. Uses createRequire anchored at the skill's
+// own package.json so the resolution honours the skill's local
+// node_modules — not the caller's. This matters when the skill is loaded
+// from a vendored install path or a non-standard layout where the parent
+// process's resolution roots wouldn't see the deps.
+//
+// Tests can pass a custom `deps` array to inject a non-existent package
+// name; production callers should always rely on the default
+// REQUIRED_RUNTIME_DEPS list.
+//
+// Returns `{ ok: true, missing: [] }` on success or
+// `{ ok: false, missing: [...], exitCode: 8, message }` on failure. The
+// failure shape mirrors preflightNode/preflightGit so cli.mjs can treat
+// it uniformly.
+export function preflightDependencies(skillRoot, deps = REQUIRED_RUNTIME_DEPS) {
+  const missing = [];
+  let require;
+  try {
+    require = createRequire(join(skillRoot, "package.json"));
+  } catch (err) {
+    return {
+      ok: false,
+      exitCode: 8,
+      missing: deps.slice(),
+      message:
+        `skill-llm-wiki: cannot anchor dependency resolution at ${skillRoot}: ` +
+        `${err && err.message ? err.message : String(err)}\n`,
+    };
+  }
+  for (const dep of deps) {
+    try {
+      require.resolve(dep);
+    } catch {
+      missing.push(dep);
+    }
+  }
+  if (missing.length === 0) {
+    return { ok: true, missing: [] };
+  }
+  const list = missing.map((d) => `  - ${d}`).join("\n");
+  return {
+    ok: false,
+    exitCode: 8,
+    missing,
+    message:
+      "skill-llm-wiki: required runtime dependencies are missing:\n" +
+      list +
+      "\n" +
+      "Run `npm install` in the skill directory to install them, or see " +
+      "guide/ux/preflight.md Case E.\n",
+  };
+}
+
+// Run the mandatory Node + Git preflight and exit on failure. Intended to
+// be called once at CLI startup. Split into a helper so phase-level code
+// can call it mid-operation if it wants extra paranoia.
+export function preflightOrExit({ requireGit = true } = {}) {
+  const n = preflightNode();
+  if (!n.ok) {
+    process.stderr.write(n.message);
+    process.exit(n.exitCode);
+  }
+  if (requireGit) {
+    const g = preflightGit();
+    if (!g.ok) {
+      process.stderr.write(g.message);
+      process.exit(g.exitCode);
+    }
+  }
+}