@codyswann/lisa 2.24.0 → 2.25.1

package/plugins/src/wiki/scripts/lint-wiki.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+/**
+ * lint-wiki.mjs — deterministic, dependency-free integrity checker for a lisa-wiki.
+ *
+ * Read-only: it reports findings, it never modifies the wiki. Default mode is
+ * "warning" (exit 1 only on FAIL items); `--strict` (hard-enforcement) also fails
+ * on WARN items.
+ *
+ * Usage: node lint-wiki.mjs [--wiki <wikiRoot>] [--config <path>] [--strict] [--json]
+ * Exit 0 = clean (for the active mode), 1 = blocking findings.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  loadConfig,
+  loadStructure,
+  pluginRootFrom,
+  walkFiles,
+  parseFrontmatter,
+  extractMarkdownLinks,
+  extractCitations,
+  SECRET_PATTERNS,
+  TEXT_EXTS,
+  makeReport,
+} from "./_wiki-lib.mjs";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = pluginRootFrom(scriptDir);
+
+const argv = process.argv.slice(2);
+const flag = name => argv.includes(name);
+const opt = name => {
+  const i = argv.indexOf(name);
+  return i !== -1 ? argv[i + 1] : undefined;
+};
+const strict = flag("--strict");
+const asJson = flag("--json");
+
+const { config } = loadConfig(opt("--config"));
+const structure = loadStructure(pluginRoot) ?? {};
+const wikiRoot = path.resolve(opt("--wiki") ?? config?.wikiRoot ?? "wiki");
+const report = makeReport();
+
+if (!config) {
+  report.add(
+    "config",
+    "not-loaded",
+    "WARN",
+    "config not found/invalid; using structure-manifest defaults"
+  );
+}
+
+if (!fs.existsSync(wikiRoot)) {
+  console.error(`✗ wiki root not found: ${wikiRoot}`);
+  process.exit(1);
+}
+
+const rel = p => path.relative(process.cwd(), p);
+const wrel = p => path.relative(wikiRoot, p);
+const categories = config?.categories ?? structure.categoryDirs?.default ?? [];
+const frontmatterRequired = config?.frontmatter !== false;
+
+const allMd = walkFiles(wikiRoot, { ext: ".md" });
+const allFiles = walkFiles(wikiRoot);
+const exists = p => fs.existsSync(p);
+const isUnder = (p, dir) => {
+  const r = path.relative(path.join(wikiRoot, dir), p);
+  return r !== "" && !r.startsWith("..") && !path.isAbsolute(r);
+};
+const isSynthesisPage = p => categories.some(c => isUnder(p, c));
+const isSourceNote = p => isUnder(p, "sources");
+
+// --- A. structure conformance ---------------------------------------------
+for (const f of structure.requiredFiles ?? []) {
+  report.add(
+    "structure",
+    `required-file:${f}`,
+    exists(path.join(wikiRoot, f)) ? "PASS" : "FAIL",
+    exists(path.join(wikiRoot, f))
+      ? `present: ${f}`
+      : `missing required file: ${f}`
+  );
+}
+for (const d of structure.requiredDirs ?? []) {
+  const ok =
+    fs.existsSync(path.join(wikiRoot, d)) &&
+    fs.statSync(path.join(wikiRoot, d)).isDirectory();
+  report.add(
+    "structure",
+    `required-dir:${d}`,
+    ok ? "PASS" : "FAIL",
+    ok ? `present: ${d}/` : `missing required dir: ${d}/`
+  );
+}
+
+// --- B. frontmatter on synthesis pages + source notes ---------------------
+if (frontmatterRequired) {
+  for (const f of allMd) {
+    if (!isSynthesisPage(f) && !isSourceNote(f)) continue;
+    const fm = parseFrontmatter(fs.readFileSync(f, "utf8"));
+    if (!fm.has) {
+      report.add("frontmatter", "missing", "WARN", `no frontmatter`, wrel(f));
+    } else {
+      const missing = ["type", "created", "updated"].filter(
+        k => !fm.keys.includes(k)
+      );
+      if (missing.length) {
+        report.add(
+          "frontmatter",
+          "incomplete",
+          "WARN",
+          `frontmatter missing keys: ${missing.join(", ")}`,
+          wrel(f)
+        );
+      }
+    }
+  }
+}
+
+// --- C/D. links: index coverage, broken links, citations ------------------
+const indexPath = path.join(wikiRoot, "index.md");
+const indexText = exists(indexPath) ? fs.readFileSync(indexPath, "utf8") : "";
+const indexTargets = new Set(
+  extractMarkdownLinks(indexText).map(t => path.resolve(wikiRoot, t))
+);
+// dangling index links
+for (const t of indexTargets) {
+  if (t.endsWith(".md") && !exists(t)) {
+    report.add(
+      "links",
+      "index-dangling",
+      "FAIL",
+      `index links to a missing page: ${wrel(t)}`,
+      "index.md"
+    );
+  }
+}
+// pages missing from index
+for (const f of allMd) {
+  if (!isSynthesisPage(f)) continue;
+  if (!indexTargets.has(f)) {
+    report.add(
+      "index",
+      "page-missing",
+      "WARN",
+      `synthesis page not linked from index.md`,
+      wrel(f)
+    );
+  }
+}
+// broken internal links + citations across all md; build link graph for orphans.
+// A link resolves if it exists relative to the file, OR as a wiki-root-relative /
+// repo-root-relative / "wiki/"-prefixed form (reduces false positives).
+const wikiBase = path.basename(wikiRoot);
+const linkResolution = (f, target) => {
+  const primary = path.resolve(path.dirname(f), target);
+  const stripped = target
+    .replace(/^\/+/, "")
+    .replace(new RegExp(`^${wikiBase}/`), "");
+  const cands = [
+    primary,
+    path.resolve(wikiRoot, target),
+    path.resolve(wikiRoot, "..", target),
+    path.resolve(wikiRoot, stripped),
+  ];
+  return { primary, hit: cands.find(exists) };
+};
+const linkedTo = new Set();
+for (const f of allMd) {
+  const text = fs.readFileSync(f, "utf8");
+  for (const target of extractMarkdownLinks(text)) {
+    const { primary, hit } = linkResolution(f, target);
+    if (target.endsWith(".md") || primary.endsWith(".md")) {
+      linkedTo.add(hit ?? primary);
+      if (!hit) {
+        report.add(
+          "links",
+          "broken",
+          "FAIL",
+          `broken link → ${target}`,
+          wrel(f)
+        );
+      }
+    } else if (!hit) {
+      report.add(
+        "links",
+        "broken-asset",
+        "WARN",
+        `link to missing path → ${target}`,
+        wrel(f)
+      );
+    }
+  }
+  for (const cite of extractCitations(text)) {
+    const candidates = [
+      path.resolve(wikiRoot, cite),
+      path.resolve(wikiRoot, "..", cite),
+      path.resolve(path.dirname(f), cite),
+    ];
+    if (!candidates.some(exists)) {
+      report.add(
+        "links",
+        "citation-unresolved",
+        "WARN",
+        `citation path not found → ${cite}`,
+        wrel(f)
+      );
+    }
+  }
+}
+
+// --- E. orphan pages ------------------------------------------------------
+for (const f of allMd) {
+  if (!isSynthesisPage(f)) continue;
+  if (!indexTargets.has(f) && !linkedTo.has(f)) {
+    report.add(
+      "orphans",
+      "orphan",
+      "WARN",
+      `page is unreferenced (not in index, not linked)`,
+      wrel(f)
+    );
+  }
+}
+
+// --- F. log non-empty -----------------------------------------------------
+const logPath = path.join(wikiRoot, "log.md");
+if (exists(logPath)) {
+  // Accept the canonical table row (| YYYY-MM-DD | ...) AND the legacy heading
+  // formats (## YYYY-MM-DD or ## [YYYY-MM-DD]) tolerated during migration.
+  const rows = fs
+    .readFileSync(logPath, "utf8")
+    .split("\n")
+    .filter(
+      l =>
+        /^\|\s*\d{4}-\d{2}-\d{2}\s*\|/.test(l) ||
+        /^##\s*\[?\d{4}-\d{2}-\d{2}/.test(l)
+    );
+  report.add(
+    "log",
+    "non-empty",
+    rows.length > 0 ? "PASS" : "WARN",
+    rows.length > 0
+      ? `${rows.length} log entr${rows.length === 1 ? "y" : "ies"}`
+      : "log.md has no dated entries"
+  );
+}
+
+// --- G. secret + contamination + binaries ---------------------------------
+const terms = (config?.contaminationTerms ?? []).filter(Boolean);
+for (const f of allFiles) {
+  const ext = path.extname(f);
+  if (!TEXT_EXTS.has(ext) && path.basename(f) !== ".gitkeep") {
+    report.add(
+      "binaries",
+      "stray",
+      "WARN",
+      `non-text file under wiki`,
+      wrel(f)
+    );
+    continue;
+  }
+  let text;
+  try {
+    text = fs.readFileSync(f, "utf8");
+  } catch {
+    continue;
+  }
+  for (const { name, re } of SECRET_PATTERNS) {
+    if (re.test(text))
+      report.add("secrets", "leak", "FAIL", `possible ${name}`, wrel(f));
+  }
+  // The config file legitimately lists the contamination terms it scans for; don't flag it.
+  if (path.basename(f) !== "lisa-wiki.config.json") {
+    for (const term of terms) {
+      if (text.toLowerCase().includes(term.toLowerCase())) {
+        report.add(
+          "contamination",
+          "term",
+          "FAIL",
+          `contamination term "${term}"`,
+          wrel(f)
+        );
+      }
+    }
+  }
+}
+
+// --- output + verdict -----------------------------------------------------
+const fails = report.items.filter(i => i.status === "FAIL");
+const warns = report.items.filter(i => i.status === "WARN");
+const blocking = strict ? fails.length + warns.length : fails.length;
+
+if (asJson) {
+  console.log(
+    JSON.stringify(
+      {
+        wikiRoot: rel(wikiRoot),
+        strict,
+        fails: fails.length,
+        warns: warns.length,
+        items: report.items.filter(i => i.status !== "PASS"),
+      },
+      null,
+      2
+    )
+  );
+} else {
+  for (const i of report.items.filter(i => i.status !== "PASS")) {
+    console.log(
+      `${i.status === "FAIL" ? "✗" : "⚠"} [${i.group}] ${i.message}${i.file ? ` (${i.file})` : ""}`
+    );
+  }
+  console.log(
+    `\n${fails.length} fail, ${warns.length} warn${strict ? " (strict: warnings block)" : ""} — ${blocking === 0 ? "OK" : "BLOCKING"}`
+  );
+}
+
+process.exit(blocking === 0 ? 0 : 1);

package/plugins/src/wiki/scripts/mcp-doctor.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * mcp-doctor.mjs — inspect-and-report MCP wiring for the wiki's MCP connectors.
+ * Dependency-free. Print-only: it never edits .mcp.json / .codex/config.toml or any
+ * auth file — it reports PASS/MISSING and prints setup snippets for the user to apply.
+ *
+ * Usage: node mcp-doctor.mjs [--config <p>] [--repo <dir>]
+ * Exit 0 always (advisory). Used by /setup --doctor and /doctor group D.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./_wiki-lib.mjs";
+
+const argv = process.argv.slice(2);
+const opt = (n, d) => {
+  const i = argv.indexOf(n);
+  return i !== -1 ? argv[i + 1] : d;
+};
+const repo = path.resolve(opt("--repo", "."));
+const { config } = loadConfig(opt("--config"));
+
+// Connectors that require an MCP server, and the server name to look for.
+const MCP_CONNECTORS = {
+  jira: "atlassian",
+  confluence: "atlassian",
+  notion: "notion",
+};
+
+const mcpJsonPath = path.join(repo, ".mcp.json");
+const codexTomlPath = path.join(repo, ".codex", "config.toml");
+const mcpJson = fs.existsSync(mcpJsonPath)
+  ? fs.readFileSync(mcpJsonPath, "utf8")
+  : "";
+const codexToml = fs.existsSync(codexTomlPath)
+  ? fs.readFileSync(codexTomlPath, "utf8")
+  : "";
+
+const enabled = Object.entries(config?.connectors ?? {}).filter(
+  ([name, c]) => c?.enabled && name in MCP_CONNECTORS
+);
+
+if (enabled.length === 0) {
+  console.log(
+    "mcp-doctor: no MCP-backed connectors enabled — nothing to check."
+  );
+  process.exit(0);
+}
+
+let missing = 0;
+for (const [name] of enabled) {
+  const server = MCP_CONNECTORS[name];
+  const inClaude = mcpJson.includes(`"${server}"`);
+  const inCodex = codexToml.includes(`[mcp_servers.${server}]`);
+  const status = inClaude || inCodex ? "PASS" : "MISSING";
+  if (status === "MISSING") missing += 1;
+  console.log(
+    `${status === "PASS" ? "✓" : "⚠"} ${name} → MCP server "${server}": Claude=${inClaude ? "yes" : "no"} Codex=${inCodex ? "yes" : "no"}`
+  );
+  if (status === "MISSING") {
+    console.log(
+      `    Add to .mcp.json:        { "mcpServers": { "${server}": { ... } } }`
+    );
+    console.log(`    Add to .codex/config.toml: [mcp_servers.${server}]`);
+    console.log(
+      `    Then authenticate per the ${server} MCP instructions (project-owned auth).`
+    );
+  }
+}
+
+console.log(
+  `\nmcp-doctor: ${enabled.length - missing}/${enabled.length} MCP connector(s) wired${missing ? ` — ${missing} MISSING (connector disabled until wired)` : ""}.`
+);

package/plugins/src/wiki/scripts/render-contract.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * render-contract.mjs — render the repo-local contract snapshot from the plugin
+ * template + the project's config. Dependency-free.
+ *
+ * The plugin owns the canonical contract template (templates/llm-wiki-contract.md);
+ * this script materializes wiki/schema/llm-wiki-contract.md so the wiki stays
+ * readable/maintainable even without the plugin installed. The kernelVersion is
+ * read from the built plugin manifest and stamped into the snapshot.
+ *
+ * Usage: node render-contract.mjs [path-to-config] [--out <path>]
+ *   default config: wiki/lisa-wiki.config.json (relative to cwd)
+ *   default out:    <wikiRoot>/schema/llm-wiki-contract.md
+ * Exit code 0 = rendered, 1 = error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function fail(msg) {
+  console.error(`✗ ${msg}`);
+  process.exit(1);
+}
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.dirname(scriptDir);
+const templatePath = path.join(pluginRoot, "templates", "llm-wiki-contract.md");
+const manifestPath = path.join(pluginRoot, ".claude-plugin", "plugin.json");
+
+const argv = process.argv.slice(2);
+const outFlagIdx = argv.indexOf("--out");
+let outOverride;
+if (outFlagIdx !== -1) {
+  outOverride = argv[outFlagIdx + 1];
+  if (!outOverride || outOverride.startsWith("--"))
+    fail("--out requires a path argument");
+}
+const configArg = argv.find(
+  (a, i) => !a.startsWith("--") && i !== outFlagIdx + 1
+);
+const configPath = path.resolve(configArg ?? "wiki/lisa-wiki.config.json");
+
+if (!fs.existsSync(templatePath))
+  fail(`contract template missing: ${templatePath}`);
+if (!fs.existsSync(configPath)) fail(`config not found: ${configPath}`);
+
+let config;
+try {
+  config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+} catch (e) {
+  fail(`config is not valid JSON: ${e.message}`);
+}
+
+let kernelVersion = "0.0.0";
+try {
+  kernelVersion =
+    JSON.parse(fs.readFileSync(manifestPath, "utf8")).version ?? kernelVersion;
+} catch {
+  // manifest may be absent in the src tree before build; leave default.
+}
+
+const enabledConnectors = Object.entries(config.connectors ?? {})
+  .filter(([, c]) => c && c.enabled)
+  .map(([name]) => name);
+
+const subs = {
+  org: config.org ?? "",
+  displayName: config.displayName ?? config.org ?? "LLM Wiki",
+  purpose: config.purpose ?? "(purpose not set — run /setup to define it)",
+  mode: config.mode ?? "",
+  wikiRoot: config.wikiRoot ?? "wiki",
+  kernelVersion,
+  schemaVersion: config.schemaVersion ?? "",
+  categories: (config.categories ?? []).join(", "),
+  connectors: enabledConnectors.length
+    ? enabledConnectors.join(", ")
+    : "(none enabled)",
+  sourceLayout: config.sources?.layout ?? "by-system",
+  sourceRetention: config.sourceRetention ?? "sanitized-note-only",
+  sensitivityDefault: config.sensitivity?.default ?? "internal",
+  prPolicy: config.git?.prPerIngestion
+    ? `PR per ingestion to ${config.git?.targetBranch ?? "main"}${config.git?.autoMerge ? " (auto-merge)" : ""}`
+    : "no PR per ingestion",
+  readmeMode: config.readme?.mode ?? "rich",
+  generatedDate: new Date().toISOString().slice(0, 10),
+};
+
+let rendered = fs.readFileSync(templatePath, "utf8");
+rendered = rendered.replace(/\{\{(\w+)\}\}/g, (match, key) =>
+  key in subs ? String(subs[key]) : match
+);
+
+const leftover = [
+  ...new Set([...rendered.matchAll(/\{\{(\w+)\}\}/g)].map(m => m[1])),
+];
+if (leftover.length) {
+  fail(`unresolved template tokens in contract: ${leftover.join(", ")}`);
+}
+
+const outPath = path.resolve(
+  outOverride ?? path.join(subs.wikiRoot, "schema", "llm-wiki-contract.md")
+);
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+fs.writeFileSync(outPath, rendered);
+console.log(
+  `✓ rendered contract → ${path.relative(process.cwd(), outPath)} (kernelVersion ${kernelVersion})`
+);

package/plugins/src/wiki/scripts/rewrite-refs.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * rewrite-refs.mjs — deterministically fix wiki references after files have moved.
+ * Dependency-free. Assumes the files are ALREADY moved (e.g. by absorb-docs/migrate
+ * via `git mv`); this script only repairs references and verifies no dangling links.
+ *
+ * It correctly handles both directions:
+ *   - a moved file's relative links to unmoved targets (re-based to its new location),
+ *   - unmoved files' relative links to moved targets,
+ *   - moved → moved,
+ *   - plain-text `Source: <path>` citations (wiki-root-relative).
+ *
+ * Usage:
+ *   node rewrite-refs.mjs --wiki <root> --move <oldPath>:<newPath> [--move ...] [--check]
+ *   paths are resolved relative to CWD; --check verifies only (no writes).
+ * Exit 0 = rewritten/clean, 1 = dangling links remain (or bad args).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { walkFiles, extractMarkdownLinks } from "./_wiki-lib.mjs";
+
+const argv = process.argv.slice(2);
+const check = argv.includes("--check");
+const wikiArgIdx = argv.indexOf("--wiki");
+if (
+  wikiArgIdx !== -1 &&
+  (!argv[wikiArgIdx + 1] || argv[wikiArgIdx + 1].startsWith("--"))
+) {
+  console.error("✗ --wiki requires a path argument");
+  process.exit(1);
+}
+const wikiRoot = path.resolve(
+  wikiArgIdx !== -1 ? argv[wikiArgIdx + 1] : "wiki"
+);
+const moves = [];
+for (let i = 0; i < argv.length; i += 1) {
+  if (argv[i] === "--move") {
+    const spec = argv[i + 1] ?? "";
+    const sep = spec.lastIndexOf(":");
+    if (sep === -1) {
+      console.error(`✗ bad --move "${spec}" (expected old:new)`);
+      process.exit(1);
+    }
+    moves.push([
+      path.resolve(spec.slice(0, sep)),
+      path.resolve(spec.slice(sep + 1)),
+    ]);
+    i += 1;
+  }
+}
+
+const moveMap = new Map(moves); // oldAbs -> newAbs
+const newToOld = new Map(moves.map(([o, n]) => [n, o])); // newAbs -> oldAbs
+const currentLocation = abs => moveMap.get(abs) ?? abs;
+const toPosix = p => p.split(path.sep).join("/");
+
+const isExternal = t =>
+  !t ||
+  t.startsWith("#") ||
+  /^[a-z][a-z0-9+.-]*:\/\//i.test(t) ||
+  t.startsWith("mailto:") ||
+  t.includes("{{") ||
+  t.includes("<") ||
+  t.includes(">");
+
+let rewriteCount = 0;
+const mdFiles = walkFiles(wikiRoot, { ext: ".md" });
+
+for (const file of mdFiles) {
+  const oldOfFile = newToOld.get(file) ?? file; // where this file's links were authored relative to
+  const authorBase = path.dirname(oldOfFile);
+  const curDir = path.dirname(file);
+  const original = fs.readFileSync(file, "utf8");
+
+  // 1) markdown links
+  let updated = original.replace(
+    /(\]\()([^)]+)(\))/g,
+    (whole, open, target, close) => {
+      // split off an optional markdown link title: (url "title") — preserve it
+      const tm = target.match(/^(\S+)(\s[\s\S]*)?$/);
+      if (!tm) return whole;
+      const urlAnchor = tm[1];
+      const title = tm[2] ?? "";
+      if (isExternal(urlAnchor)) return whole;
+      const [pathPart, anchor] = urlAnchor.split("#");
+      const resolvedFromAuthor = path.resolve(authorBase, pathPart);
+      const correctAbs = currentLocation(resolvedFromAuthor);
+      let nextRel = toPosix(path.relative(curDir, correctAbs));
+      if (!nextRel.startsWith(".")) nextRel = `./${nextRel}`;
+      const nextUrl = anchor !== undefined ? `${nextRel}#${anchor}` : nextRel;
+      const nextTarget = `${nextUrl}${title}`;
+      return nextTarget === target ? whole : `${open}${nextTarget}${close}`;
+    }
+  );
+
+  // 2) plain-text citations: Source: <wiki-root-relative path>
+  updated = updated.replace(
+    /(Source:\s*)([^\s)]+\.md)/g,
+    (whole, pre, cite) => {
+      if (cite.includes("{{") || cite.includes("<")) return whole;
+      // citations are wiki-root-relative (or repo-relative); map via moveMap if they point to a moved file
+      const candidates = [
+        path.resolve(wikiRoot, cite),
+        path.resolve(wikiRoot, "..", cite),
+      ];
+      const hit = candidates.find(c => moveMap.has(c));
+      if (!hit) return whole;
+      const nextAbs = moveMap.get(hit);
+      const nextCite = toPosix(path.relative(wikiRoot, nextAbs));
+      return `${pre}${nextCite}`;
+    }
+  );
+
+  if (updated !== original) {
+    rewriteCount += 1;
+    if (!check) fs.writeFileSync(file, updated);
+  }
+}
+
+// verification: no dangling internal .md links remain (at current locations)
+const dangling = [];
+for (const file of mdFiles) {
+  const text = fs.readFileSync(file, "utf8");
+  for (const target of extractMarkdownLinks(text)) {
+    const resolved = path.resolve(path.dirname(file), target);
+    if (resolved.endsWith(".md") && !fs.existsSync(resolved)) {
+      dangling.push(`${toPosix(path.relative(wikiRoot, file))} → ${target}`);
+    }
+  }
+}
+
+if (dangling.length > 0) {
+  console.error(
+    `✗ ${dangling.length} dangling internal link(s) ${check ? "found" : "remain after rewrite"}:`
+  );
+  for (const d of dangling) console.error(`  - ${d}`);
+  process.exit(1);
+}
+
+console.log(
+  check
+    ? `✓ no dangling internal links (${mdFiles.length} files checked).`
+    : `✓ rewrote refs in ${rewriteCount} file(s); no dangling internal links remain.`
+);