@codyswann/lisa 2.24.0 → 2.25.1

package/plugins/lisa-wiki/schema/lisa-wiki-config.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://codyswann.github.io/lisa/schema/lisa-wiki-config.schema.json",
+  "title": "lisa-wiki project config",
+  "description": "Per-project behavioral config for the lisa-wiki plugin. Lives at wiki/lisa-wiki.config.json. The plugin's validate-config script enforces these constraints dependency-free; this schema is the authoritative spec and powers editor tooling.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schemaVersion", "org", "mode", "wikiRoot", "categories"],
+  "properties": {
+    "schemaVersion": { "type": "string", "description": "Config schema version (semver)." },
+    "org": { "type": "string", "description": "Owning organization / project name." },
+    "displayName": { "type": "string", "description": "Human-facing wiki name." },
+    "purpose": { "type": "string", "description": "One paragraph: what this wiki is for. Asked by /setup; rendered into the contract + start-here; feeds /onboard-me." },
+    "mode": { "enum": ["embedded", "wrapper", "standalone", "subdir"], "description": "Repository model." },
+    "wikiRoot": { "type": "string", "default": "wiki", "description": "Path to the wiki root, relative to repo root." },
+    "frontmatter": { "type": "boolean", "default": true, "description": "Whether new/touched pages require YAML frontmatter." },
+    "categories": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Synthesis category directories." },
+    "sources": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "layout": { "enum": ["by-system", "by-category"], "default": "by-system" },
+        "buckets": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "git": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "prPerIngestion": { "type": "boolean" },
+        "autoMerge": { "type": "boolean" },
+        "targetBranch": { "type": "string" },
+        "branchPrefix": { "type": "string" }
+      }
+    },
+    "sensitivity": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "default": { "enum": ["public", "internal", "confidential", "restricted"] }
+      }
+    },
+    "sourceRetention": { "enum": ["raw-ok", "sanitized-note-only", "metadata-only", "external-pointer-only"] },
+    "readme": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "mode": { "enum": ["rich", "stub", "preserve"], "default": "rich" } }
+    },
+    "documentation": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "absorb": { "type": "boolean", "default": true },
+        "keepInPlace": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "onboarding": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": { "allowAudienceNote": { "type": "boolean", "default": false } }
+    },
+    "connectors": {
+      "type": "object",
+      "description": "Map of connector name -> connector config.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["sideEffects"],
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "sideEffects": { "enum": ["read-only-ingest", "repo-write", "external-write"] }
+        }
+      }
+    },
+    "customConnectors": {
+      "type": "array",
+      "description": "Explicit allowlist of project-authored front-door ingest skills (generated by /add-ingest). No auto-discovery.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["name", "skill", "sourceSystem", "sideEffects"],
+        "properties": {
+          "name": { "type": "string" },
+          "skill": { "type": "string" },
+          "sourceSystem": { "type": "string" },
+          "stateFile": { "type": "string" },
+          "sideEffects": { "enum": ["read-only-ingest", "repo-write", "external-write"] }
+        }
+      }
+    },
+    "staff": {
+      "type": "array",
+      "description": "Digital-staff roles. Each generates a wiki/staff/<id>.md doc page + dual-runtime subagents.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["id", "role"],
+        "properties": {
+          "id": { "type": "string" },
+          "role": { "type": "string" },
+          "expertise": { "type": "string" },
+          "owns": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "categories": { "type": "array", "items": { "type": "string" } },
+              "connectors": { "type": "array", "items": { "type": "string" } },
+              "skills": { "type": "array", "items": { "type": "string" } }
+            }
+          },
+          "sensitivity": { "enum": ["public", "internal", "confidential", "restricted"] }
+        }
+      }
+    },
+    "contaminationTerms": { "type": "array", "items": { "type": "string" }, "description": "Cross-tenant terms scanned for before every commit." }
+  }
+}

package/plugins/lisa-wiki/schema/wiki-structure.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://codyswann.github.io/lisa/schema/wiki-structure.schema.json",
+  "title": "lisa-wiki canonical structure manifest",
+  "description": "The canonical folder structure of a lisa-wiki. This manifest is the intended single source of truth for structure conformance, consumed by lint-wiki and validate-config as of M1 (structure enforcement) and by render-contract; in M0 it is the published spec. All paths are relative to config.wikiRoot unless noted. It is a descriptive manifest (not a JSON-Schema validation of a document); validators interpret these fields.",
+  "manifestVersion": "1.0.0",
+  "requiredFiles": [
+    "lisa-wiki.config.json",
+    "index.md",
+    "log.md",
+    "start-here.md",
+    "schema/llm-wiki-contract.md"
+  ],
+  "requiredDirs": ["schema", "sources", "state"],
+  "optionalDirs": ["staff", "documentation"],
+  "categoryDirs": {
+    "default": [
+      "concepts",
+      "entities",
+      "decisions",
+      "architecture",
+      "requirements",
+      "playbooks",
+      "open-questions",
+      "projects"
+    ],
+    "note": "A project may declare additional categories in config.categories (e.g. claims, comparisons, finance, sales)."
+  },
+  "sourcesLayout": {
+    "by-system": "sources/<system>/   (e.g. sources/jira/, sources/git/, sources/slack/)",
+    "by-category": "sources/<bucket>/  (e.g. sources/primary/, sources/secondary/)"
+  },
+  "stateLayout": "state/<system>/*.json",
+  "reportPath": "state/migration/doctor-report.json",
+  "generatedArtifacts": {
+    "claudeRoleAgents": ".claude/agents/<id>.md   (repo root, not under wikiRoot)",
+    "codexRoleAgents": ".codex/agents/<id>.toml   (repo root, not under wikiRoot)",
+    "frontDoorSkills": ".claude|.agents/skills/lisa-wiki-local-*"
+  },
+  "keepInPlaceDefault": [
+    "LICENSE*",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "NOTICE*",
+    "SUPPORT.md",
+    "GOVERNANCE.md",
+    ".github/**"
+  ]
+}

package/plugins/lisa-wiki/scripts/_wiki-lib.mjs

@@ -0,0 +1,185 @@
+/**
+ * _wiki-lib.mjs — shared, dependency-free helpers for the lisa-wiki validators
+ * (lint-wiki, diff-guard, rewrite-refs, verify-migration). Node built-ins only,
+ * so the scripts stay portable to any downstream repo that installs the plugin.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+/** Read and parse a JSON file, or return undefined if missing/invalid. */
+export function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Resolve the plugin root from a script in scripts/ (parent of scripts/). */
+export function pluginRootFrom(scriptDir) {
+  return path.dirname(scriptDir);
+}
+
+/** Load the project config (wiki/lisa-wiki.config.json by default). */
+export function loadConfig(configPath) {
+  const resolved = path.resolve(configPath ?? "wiki/lisa-wiki.config.json");
+  const config = readJsonSafe(resolved);
+  return { config, configPath: resolved };
+}
+
+/** Load the canonical structure manifest shipped with the plugin. */
+export function loadStructure(pluginRoot) {
+  return readJsonSafe(
+    path.join(pluginRoot, "schema", "wiki-structure.schema.json")
+  );
+}
+
+/** Recursively list files under dir matching an optional extension filter. */
+export function walkFiles(dir, { ext } = {}) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === ".git" || entry.name === "node_modules") continue;
+        stack.push(full);
+      } else if (entry.isFile()) {
+        if (!ext || full.endsWith(ext)) out.push(full);
+      }
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Minimal frontmatter detector. Returns whether a leading `--- ... ---` block
+ * exists and the top-level keys it declares (enough to check required fields;
+ * NOT a full YAML parser).
+ */
+export function parseFrontmatter(text) {
+  const lines = text.split("\n");
+  if (lines[0].trim() !== "---") return { has: false, keys: [], body: text };
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === "---") {
+      closeIdx = i;
+      break;
+    }
+  }
+  if (closeIdx === -1) return { has: false, keys: [], body: text };
+  const keys = [];
+  for (let i = 1; i < closeIdx; i += 1) {
+    const m = lines[i].match(/^([A-Za-z][\w-]*):/);
+    if (m) keys.push(m[1]);
+  }
+  const body = lines.slice(closeIdx + 1).join("\n");
+  return { has: true, keys, body };
+}
+
+/**
+ * Extract internal markdown link targets ([txt](target)) — excludes external
+ * (http/https/mailto), anchors, and template tokens. Anchors are stripped.
+ */
+export function extractMarkdownLinks(text) {
+  const targets = [];
+  const re = /\[[^\]]*\]\(([^)]+)\)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    let target = m[1].trim();
+    if (!target || target.startsWith("#")) continue;
+    if (target.includes("{{") || target.includes("<") || target.includes(">"))
+      continue; // template token / placeholder / angle-bracket autolink
+    target = target.split(/\s+/)[0]; // drop optional link title: (url "title")
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target) || target.startsWith("mailto:"))
+      continue;
+    target = target.split("#")[0].trim();
+    if (target) targets.push(target);
+  }
+  return targets;
+}
+
+/** Extract plain-text `Source: <path>.md` citations that look like wiki paths. */
+export function extractCitations(text) {
+  const cites = [];
+  const re = /Source:\s*([^\s)]+\.md)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const c = m[1];
+    if (c.includes("{{") || c.includes("<") || c.includes(">")) continue; // template token / placeholder example
+    cites.push(c);
+  }
+  return cites;
+}
+
+/** Convert a tiny glob (supporting ** and *) to a RegExp anchored full-match. */
+export function globToRegExp(glob) {
+  let re = "^";
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        re += ".*";
+        i += 1;
+        if (glob[i + 1] === "/") i += 1; // consume trailing slash of **/
+      } else {
+        re += "[^/]*";
+      }
+    } else if ("\\^$+?.()|[]{}".includes(c)) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+  re += "$";
+  return new RegExp(re);
+}
+
+/** Secret-detection patterns (kept minimal + high-signal). */
+export const SECRET_PATTERNS = [
+  { name: "Slack token", re: /xox[pbar]-[A-Za-z0-9-]{10,}/ },
+  { name: "AWS access key", re: /AKIA[0-9A-Z]{16}/ },
+  {
+    name: "private key header",
+    re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/,
+  },
+  { name: "bearer token", re: /bearer\s+[A-Za-z0-9._-]{20,}/i },
+  {
+    name: "client secret assignment",
+    re: /client_secret["'\s:=]+[A-Za-z0-9._-]{16,}/i,
+  },
+];
+
+/** Text-ish file extensions allowed inside a wiki (others flagged as binaries). */
+export const TEXT_EXTS = new Set([
+  ".md",
+  ".mdx",
+  ".json",
+  ".jsonl",
+  ".txt",
+  ".yml",
+  ".yaml",
+  ".toml",
+  ".csv",
+  ".tsv",
+  ".svg",
+  ".gitkeep",
+]);
+
+/** Severity-tagged result accumulator. */
+export function makeReport() {
+  const items = [];
+  return {
+    add(group, id, status, message, file) {
+      items.push({ group, id, status, message, ...(file ? { file } : {}) });
+    },
+    items,
+  };
+}

package/plugins/lisa-wiki/scripts/diff-guard.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * diff-guard.mjs — enforce a connector's touched-file boundary. Dependency-free
+ * (git + Node built-ins).
+ *
+ * Run AFTER a connector returns and BEFORE the kernel synthesizes: a connector may
+ * write ONLY its declared source-note path(s) and run-metadata. Any repo change
+ * outside the allowed globs is a hard failure (this is what makes "source-note only"
+ * enforceable, not aspirational). Writes outside the repo (e.g. external-write to a
+ * remote system) are not git-visible and so are not policed here.
+ *
+ * The change set ALWAYS includes untracked files (connectors create new files), so a
+ * stray new file can never bypass the guard. `--base <ref>` additionally unions a
+ * committed range. Paths are read NUL-safe to handle renames/quoting.
+ *
+ * Usage: node diff-guard.mjs --allow <glob> [--allow <glob>...] [--base <ref>]
+ * Exit 0 = all changes within allowed globs, 1 = out-of-bounds change (or git error).
+ */
+import { execFileSync } from "node:child_process";
+import { globToRegExp } from "./_wiki-lib.mjs";
+
+function fail(msg) {
+  console.error(`✗ ${msg}`);
+  process.exit(1);
+}
+
+const argv = process.argv.slice(2);
+const allows = [];
+let base;
+for (let i = 0; i < argv.length; i += 1) {
+  const a = argv[i];
+  if (a === "--allow") {
+    const v = argv[i + 1];
+    if (!v || v.startsWith("--")) fail("--allow requires a glob argument");
+    allows.push(v);
+    i += 1;
+  } else if (a === "--base") {
+    const v = argv[i + 1];
+    if (!v || v.startsWith("--")) fail("--base requires a ref argument");
+    base = v;
+    i += 1;
+  } else {
+    fail(`unknown argument: ${a}`);
+  }
+}
+
+if (allows.length === 0) {
+  fail(
+    "diff-guard requires at least one --allow <glob> (the connector's permitted paths)"
+  );
+}
+
+function git(args) {
+  return execFileSync("git", args, { encoding: "utf8" });
+}
+
+let repoRoot;
+try {
+  repoRoot = git(["rev-parse", "--show-toplevel"]).trim();
+} catch {
+  fail("not inside a git repository");
+}
+const inRepo = args => ["-C", repoRoot, ...args];
+
+// Working-tree change set, NUL-safe, including untracked files. Renames/copies
+// (status starts with R/C) emit the destination then the source as separate NUL
+// records — include both so neither side can slip outside the allow-list.
+function workingTreePaths() {
+  const out = git(
+    inRepo(["status", "--porcelain=v1", "-z", "--untracked-files=all"])
+  );
+  const records = out.split("\0");
+  const paths = [];
+  for (let i = 0; i < records.length; i += 1) {
+    const rec = records[i];
+    if (!rec) continue;
+    const status = rec.slice(0, 2);
+    const p = rec.slice(3);
+    if (p) paths.push(p);
+    if (status[0] === "R" || status[0] === "C") {
+      i += 1;
+      if (records[i]) paths.push(records[i]);
+    }
+  }
+  return paths;
+}
+
+let changed = [];
+try {
+  changed = workingTreePaths();
+  if (base) {
+    changed = changed.concat(
+      git(inRepo(["diff", "--name-only", "-z", base])).split("\0")
+    );
+  }
+} catch (e) {
+  fail(`git failed: ${e.message}`);
+}
+
+changed = [...new Set(changed.map(s => s.trim()).filter(Boolean))];
+const matchers = allows.map(globToRegExp);
+const isAllowed = p => matchers.some(re => re.test(p));
+const violations = changed.filter(p => !isAllowed(p));
+
+if (violations.length > 0) {
+  console.error(
+    `✗ diff-guard: ${violations.length} change(s) outside the allowed connector paths:`
+  );
+  for (const v of violations) console.error(`  - ${v}`);
+  console.error(`  allowed: ${allows.join(", ")}`);
+  process.exit(1);
+}
+
+console.log(
+  `✓ diff-guard: ${changed.length} change(s) all within allowed paths (${allows.join(", ")}).`
+);

package/plugins/lisa-wiki/scripts/ingest-git.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * ingest-git.mjs — git/PR-history connector. Dependency-free (git + optional gh).
+ * Read-only: it never checks out, fetches, or mutates the target repo.
+ *
+ * Writes a sanitized, dated source note under <source-dir> summarizing commits (and
+ * merged PRs, if `gh` is available) since the cursor, and emits a PROPOSED next cursor
+ * to --emit-meta. It does NOT advance final state — the kernel does that after
+ * verification (per the §7 connector contract).
+ *
+ * Usage:
+ *   node ingest-git.mjs --repo <path> [--slug <name>] [--config <p>]
+ *     [--source-dir <dir>] [--state <file>] [--emit-meta <file>]
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { readJsonSafe, SECRET_PATTERNS } 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 slug = opt("--slug", path.basename(repo));
+const githubRepo = opt("--github-repo"); // owner/repo for PR history (else inferred via gh)
+const fileSlug = slug.replace(/[^A-Za-z0-9_.-]+/g, "-"); // safe for filenames
+const sourceDir = path.resolve(opt("--source-dir", "wiki/sources/git"));
+const statePath = opt("--state");
+const emitMeta = opt("--emit-meta");
+
+const fail = m => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+const git = args =>
+  execFileSync("git", ["-C", repo, ...args], { encoding: "utf8" }).trim();
+const tryGit = args => {
+  try {
+    return git(args);
+  } catch {
+    return "";
+  }
+};
+const commitExists = c => {
+  try {
+    execFileSync("git", ["-C", repo, "cat-file", "-e", `${c}^{commit}`], {
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+const redact = t =>
+  SECRET_PATTERNS.reduce(
+    (acc, { re }) => acc.replace(new RegExp(re, "g"), "[REDACTED]"),
+    t
+  );
+
+if (
+  !fs.existsSync(path.join(repo, ".git")) &&
+  !tryGit(["rev-parse", "--is-inside-work-tree"])
+) {
+  fail(`not a git repository: ${repo}`);
+}
+
+const cursor = statePath ? (readJsonSafe(statePath)?.cursor ?? {}) : {};
+const lastCommit = cursor.lastCommit;
+const head = tryGit(["rev-parse", "HEAD"]);
+if (!head) fail("could not resolve HEAD (empty repo?)");
+if (lastCommit && !commitExists(lastCommit)) {
+  fail(
+    `cursor commit ${lastCommit} not found in ${repo}; refusing to silently re-window from HEAD`
+  );
+}
+
+const range = lastCommit ? `${lastCommit}..HEAD` : "HEAD";
+const logLines = tryGit([
+  "log",
+  range,
+  "--pretty=format:%h\t%ad\t%s",
+  "--date=short",
+])
+  .split("\n")
+  .filter(Boolean);
+const totalCommits = Number(tryGit(["rev-list", "--count", "HEAD"]) || "0");
+
+// merged PRs via gh (optional, read-only); resolve the GitHub repo explicitly
+let lastPr = cursor.lastPr ?? null;
+let prSummary = "(no GitHub repo resolved — PR history skipped)";
+let ghRepo = githubRepo;
+if (!ghRepo) {
+  try {
+    ghRepo = execFileSync(
+      "gh",
+      ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
+      { cwd: repo, encoding: "utf8" }
+    ).trim();
+  } catch {
+    ghRepo = "";
+  }
+}
+if (ghRepo) {
+  try {
+    const prs = JSON.parse(
+      execFileSync(
+        "gh",
+        [
+          "pr",
+          "list",
+          "--repo",
+          ghRepo,
+          "--state",
+          "merged",
+          "--limit",
+          "20",
+          "--json",
+          "number,title,mergedAt",
+        ],
+        { cwd: repo, encoding: "utf8" }
+      )
+    );
+    if (prs.length) {
+      lastPr = prs[0].number;
+      prSummary = `${prs.length} recent merged PR(s) in ${ghRepo}; latest #${prs[0].number} "${prs[0].title}"`;
+    } else {
+      prSummary = `no merged PRs found in ${ghRepo}`;
+    }
+  } catch {
+    prSummary = `(gh pr list failed for ${ghRepo} — PR history skipped)`;
+  }
+}
+
+const date = new Date().toISOString().slice(0, 10);
+const newCommits = logLines.length;
+const notePath = path.join(sourceDir, `${date}-${fileSlug}-git.md`);
+const note = `---
+type: source
+created: ${date}
+updated: ${date}
+related: []
+sources: []
+source_system: git
+project: ${slug}
+---
+
+# git history — ${slug} (${date})
+
+- Repo: \`${repo}\`
+- HEAD: \`${head}\`
+- Total commits on HEAD: ${totalCommits}
+- New commits since last ingest${lastCommit ? ` (\`${lastCommit}\`)` : " (first run)"}: ${newCommits}
+- Merged PRs: ${prSummary}
+
+## New commits
+${
+  newCommits
+    ? logLines
+        .slice(0, 200)
+        .map(l => `- ${l.replace(/\t/g, " · ")}`)
+        .join("\n")
+    : "_(none)_"
+}
+`;
+
+fs.mkdirSync(sourceDir, { recursive: true });
+fs.writeFileSync(notePath, redact(note));
+
+const meta = {
+  connector: "git",
+  profile: slug,
+  ranAt: new Date().toISOString(),
+  proposedCursor: { lastCommit: head, lastPr },
+  sourceNotes: [path.relative(process.cwd(), notePath)],
+};
+if (emitMeta) {
+  fs.mkdirSync(path.dirname(emitMeta), { recursive: true });
+  fs.writeFileSync(emitMeta, `${JSON.stringify(meta, null, 2)}\n`);
+}
+
+console.log(
+  `✓ git connector: ${newCommits} new commit(s) → ${path.relative(process.cwd(), notePath)}`
+);
+if (emitMeta)
+  console.log(
+    `  proposed cursor → ${path.relative(process.cwd(), emitMeta)} (kernel advances final state after verification)`
+  );