@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-wiki-devin/scripts/validate-config.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * validate-config.mjs — dependency-free validator for wiki/lisa-wiki.config.json.
+ *
+ * Enforces the constraints described in schema/lisa-wiki-config.schema.json without
+ * requiring a JSON-Schema runtime, so it is portable to any downstream repo that
+ * installs the lisa-wiki plugin (no ajv / node_modules assumptions).
+ *
+ * Usage: node validate-config.mjs [path-to-config]
+ *   default path: wiki/lisa-wiki.config.json (relative to cwd)
+ * Exit code 0 = valid, 1 = invalid or unreadable.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const MODES = ["embedded", "wrapper", "standalone", "subdir"];
+const SIDE_EFFECTS = ["read-only-ingest", "repo-write", "external-write"];
+const RETENTION = [
+  "raw-ok",
+  "sanitized-note-only",
+  "metadata-only",
+  "external-pointer-only",
+];
+const SENSITIVITY = ["public", "internal", "confidential", "restricted"];
+const REDACTION_ENTITIES = [
+  "api_key",
+  "bank_account",
+  "credit_card",
+  "oauth_token",
+  "password",
+  "private_key",
+  "routing_number",
+  "ssn",
+];
+const REDACTION_SCANNERS = ["builtin", "gitleaks", "presidio"];
+const SOURCE_LAYOUT = ["by-system", "by-category"];
+const README_MODE = ["rich", "stub", "preserve"];
+
+const configPath = path.resolve(
+  process.argv[2] ?? "wiki/lisa-wiki.config.json"
+);
+const errors = [];
+const err = msg => errors.push(msg);
+
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every(x => typeof x === "string");
+}
+function checkEnum(value, allowed, label) {
+  if (value !== undefined && !allowed.includes(value)) {
+    err(`${label}: "${String(value)}" is not one of ${allowed.join(" | ")}`);
+  }
+}
+function checkType(value, type, label) {
+  if (value !== undefined && typeof value !== type) {
+    err(
+      `${label}: expected ${type}, got ${Array.isArray(value) ? "array" : typeof value}`
+    );
+  }
+}
+function checkKnownKeys(object, allowed, label) {
+  if (!isObject(object)) return;
+  for (const key of Object.keys(object)) {
+    if (!allowed.includes(key)) {
+      err(`${label}.${key}: unknown field`);
+    }
+  }
+}
+
+if (!fs.existsSync(configPath)) {
+  console.error(`✗ config not found: ${configPath}`);
+  process.exit(1);
+}
+
+let config;
+try {
+  config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+} catch (e) {
+  console.error(`✗ config is not valid JSON: ${e.message}`);
+  process.exit(1);
+}
+
+if (!isObject(config)) {
+  console.error("✗ config must be a JSON object");
+  process.exit(1);
+}
+
+// Required
+for (const key of ["schemaVersion", "org", "mode", "wikiRoot", "categories"]) {
+  if (config[key] === undefined) err(`missing required field: ${key}`);
+}
+checkType(config.schemaVersion, "string", "schemaVersion");
+checkType(config.org, "string", "org");
+checkType(config.displayName, "string", "displayName");
+checkType(config.purpose, "string", "purpose");
+checkEnum(config.mode, MODES, "mode");
+checkType(config.wikiRoot, "string", "wikiRoot");
+if (
+  typeof config.wikiRoot === "string" &&
+  (path.isAbsolute(config.wikiRoot) ||
+    config.wikiRoot.split(/[\\/]/).includes(".."))
+) {
+  err(
+    'wikiRoot: must be a relative path inside the repo (no absolute paths, no ".." traversal)'
+  );
+}
+checkType(config.frontmatter, "boolean", "frontmatter");
+if (
+  config.categories !== undefined &&
+  !(isStringArray(config.categories) && config.categories.length > 0)
+) {
+  err("categories: must be a non-empty array of strings");
+}
+checkEnum(config.sourceRetention, RETENTION, "sourceRetention");
+checkType(config.contaminationTerms, "object", "contaminationTerms");
+if (
+  config.contaminationTerms !== undefined &&
+  !isStringArray(config.contaminationTerms)
+) {
+  err("contaminationTerms: must be an array of strings");
+}
+
+if (config.sources !== undefined) {
+  if (!isObject(config.sources)) err("sources: must be an object");
+  else checkEnum(config.sources.layout, SOURCE_LAYOUT, "sources.layout");
+}
+if (config.git !== undefined) {
+  if (!isObject(config.git)) err("git: must be an object");
+  else {
+    checkType(config.git.prPerIngestion, "boolean", "git.prPerIngestion");
+    checkType(config.git.autoMerge, "boolean", "git.autoMerge");
+    checkType(config.git.targetBranch, "string", "git.targetBranch");
+    checkType(config.git.branchPrefix, "string", "git.branchPrefix");
+  }
+}
+if (config.readme !== undefined) {
+  if (!isObject(config.readme)) err("readme: must be an object");
+  else checkEnum(config.readme.mode, README_MODE, "readme.mode");
+}
+if (config.sensitivity !== undefined) {
+  if (!isObject(config.sensitivity)) err("sensitivity: must be an object");
+  else {
+    checkKnownKeys(
+      config.sensitivity,
+      ["enabled", "default", "redaction"],
+      "sensitivity"
+    );
+    checkType(config.sensitivity.enabled, "boolean", "sensitivity.enabled");
+    checkEnum(config.sensitivity.default, SENSITIVITY, "sensitivity.default");
+    if (config.sensitivity.redaction !== undefined) {
+      if (!isObject(config.sensitivity.redaction)) {
+        err("sensitivity.redaction: must be an object");
+      } else {
+        const redaction = config.sensitivity.redaction;
+        checkKnownKeys(
+          redaction,
+          [
+            "enabled",
+            "scanners",
+            "failClosed",
+            "requireReview",
+            "allowedEntities",
+            "blockedEntities",
+          ],
+          "sensitivity.redaction"
+        );
+        checkType(
+          redaction.enabled,
+          "boolean",
+          "sensitivity.redaction.enabled"
+        );
+        checkType(
+          redaction.failClosed,
+          "boolean",
+          "sensitivity.redaction.failClosed"
+        );
+        checkType(
+          redaction.requireReview,
+          "boolean",
+          "sensitivity.redaction.requireReview"
+        );
+        if (
+          redaction.scanners !== undefined &&
+          !(isStringArray(redaction.scanners) && redaction.scanners.length > 0)
+        ) {
+          err(
+            "sensitivity.redaction.scanners: must be a non-empty array of strings"
+          );
+        }
+        const scanners = isStringArray(redaction.scanners)
+          ? redaction.scanners
+          : [];
+        for (const scanner of scanners) {
+          checkEnum(
+            scanner,
+            REDACTION_SCANNERS,
+            "sensitivity.redaction.scanners[]"
+          );
+        }
+        for (const key of ["allowedEntities", "blockedEntities"]) {
+          if (redaction[key] !== undefined && !isStringArray(redaction[key])) {
+            err(`sensitivity.redaction.${key}: must be an array of strings`);
+          }
+          const entities = isStringArray(redaction[key]) ? redaction[key] : [];
+          for (const entity of entities) {
+            checkEnum(
+              entity,
+              REDACTION_ENTITIES,
+              `sensitivity.redaction.${key}[]`
+            );
+          }
+        }
+      }
+    }
+  }
+}
+if (config.documentation !== undefined) {
+  if (!isObject(config.documentation)) err("documentation: must be an object");
+  else {
+    checkType(config.documentation.absorb, "boolean", "documentation.absorb");
+    if (
+      config.documentation.keepInPlace !== undefined &&
+      !isStringArray(config.documentation.keepInPlace)
+    ) {
+      err("documentation.keepInPlace: must be an array of strings");
+    }
+  }
+}
+if (config.onboarding !== undefined) {
+  if (!isObject(config.onboarding)) err("onboarding: must be an object");
+  else
+    checkType(
+      config.onboarding.allowAudienceNote,
+      "boolean",
+      "onboarding.allowAudienceNote"
+    );
+}
+
+if (config.connectors !== undefined) {
+  if (!isObject(config.connectors))
+    err("connectors: must be an object (name -> connector config)");
+  else {
+    for (const [name, c] of Object.entries(config.connectors)) {
+      if (!isObject(c)) {
+        err(`connectors.${name}: must be an object`);
+        continue;
+      }
+      checkType(c.enabled, "boolean", `connectors.${name}.enabled`);
+      if (c.sideEffects === undefined) {
+        err(
+          `connectors.${name}: missing required field "sideEffects" (every connector must declare its side-effect class so full ingest can skip external-write)`
+        );
+      } else {
+        checkEnum(
+          c.sideEffects,
+          SIDE_EFFECTS,
+          `connectors.${name}.sideEffects`
+        );
+      }
+    }
+  }
+}
+
+if (config.customConnectors !== undefined) {
+  if (!Array.isArray(config.customConnectors))
+    err("customConnectors: must be an array");
+  else {
+    config.customConnectors.forEach((c, i) => {
+      if (!isObject(c)) {
+        err(`customConnectors[${i}]: must be an object`);
+        return;
+      }
+      for (const k of ["name", "skill", "sourceSystem", "sideEffects"]) {
+        if (c[k] === undefined)
+          err(`customConnectors[${i}]: missing required field "${k}"`);
+      }
+      checkEnum(
+        c.sideEffects,
+        SIDE_EFFECTS,
+        `customConnectors[${i}].sideEffects`
+      );
+    });
+  }
+}
+
+if (config.staff !== undefined) {
+  if (!Array.isArray(config.staff)) err("staff: must be an array");
+  else {
+    config.staff.forEach((s, i) => {
+      if (!isObject(s)) {
+        err(`staff[${i}]: must be an object`);
+        return;
+      }
+      for (const k of ["id", "role"]) {
+        if (s[k] === undefined)
+          err(`staff[${i}]: missing required field "${k}"`);
+      }
+      checkEnum(s.sensitivity, SENSITIVITY, `staff[${i}].sensitivity`);
+      if (s.owns !== undefined) {
+        if (!isObject(s.owns)) err(`staff[${i}].owns: must be an object`);
+        else {
+          for (const ok of ["categories", "connectors", "skills"]) {
+            if (s.owns[ok] !== undefined && !isStringArray(s.owns[ok])) {
+              err(`staff[${i}].owns.${ok}: must be an array of strings`);
+            }
+          }
+        }
+      }
+    });
+  }
+}
+
+if (errors.length > 0) {
+  console.error(`✗ ${path.relative(process.cwd(), configPath)} is invalid:`);
+  for (const e of errors) console.error(`  - ${e}`);
+  process.exit(1);
+}
+
+console.log(`✓ ${path.relative(process.cwd(), configPath)} is valid.`);

package/plugins/lisa-wiki-devin/scripts/verify-migration.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * verify-migration.mjs — the deterministic half of /doctor. Dependency-free.
+ *
+ * Composes validate-config + lint-wiki into a grouped report and writes
+ * <wikiRoot>/state/migration/doctor-report.json with an overall verdict. Groups D
+ * (runtime surfaces) and E (functional smoke) are SKIPPED here — the lisa-wiki-doctor
+ * SKILL performs those and merges its results.
+ *
+ * Usage: node verify-migration.mjs [--wiki <root>] [--config <path>] [--migration]
+ * Exit 0 = READY or READY_WITH_WARNINGS, 1 = NOT_READY.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./_wiki-lib.mjs";
+
+import { boundedChild } from "./lib/bounded-child.mjs";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const opt = n => {
+  const i = argv.indexOf(n);
+  return i !== -1 ? argv[i + 1] : undefined;
+};
+const migration = argv.includes("--migration");
+const configPath = opt("--config");
+const { config } = loadConfig(configPath);
+const wikiRoot = path.resolve(opt("--wiki") ?? config?.wikiRoot ?? "wiki");
+
+const groups = { A: [], B: [], C: [], D: [], E: [], F: [], G: [] };
+const add = (g, id, status, message) => groups[g].push({ id, status, message });
+
+function runNode(script, args) {
+  const res = boundedChild("node", [path.join(scriptDir, script), ...args], {
+    encoding: "utf8",
+  });
+  return {
+    status: res.status ?? 1,
+    stdout: res.stdout ?? "",
+    stderr: (res.stderr ?? "") + (res.error ? `\n${res.error.message}` : ""),
+  };
+}
+
+// --- A. structure & config ------------------------------------------------
+const vc = runNode("validate-config.mjs", [
+  configPath ?? path.join(wikiRoot, "lisa-wiki.config.json"),
+]);
+add(
+  "A",
+  "config-valid",
+  vc.status === 0 ? "PASS" : "FAIL",
+  vc.status === 0
+    ? "config validates"
+    : `config invalid: ${(vc.stderr || vc.stdout).trim().split("\n").slice(0, 6).join("; ")}`
+);
+add(
+  "A",
+  "schema-version",
+  config?.schemaVersion ? "PASS" : "FAIL",
+  config?.schemaVersion
+    ? `schemaVersion ${config.schemaVersion}`
+    : "schemaVersion missing"
+);
+add(
+  "A",
+  "readme-mode",
+  config?.readme?.mode ? "PASS" : "WARN",
+  config?.readme?.mode
+    ? `readme.mode ${config.readme.mode}`
+    : "readme.mode not recorded (asked by /setup)"
+);
+add(
+  "A",
+  "purpose",
+  config?.purpose ? "PASS" : "WARN",
+  config?.purpose
+    ? "purpose set"
+    : "purpose not set (asked by /setup; feeds onboarding + contract)"
+);
+
+// --- A/B. lint (structure -> A, everything else -> B) ---------------------
+const lint = runNode("lint-wiki.mjs", [
+  "--wiki",
+  wikiRoot,
+  ...(configPath ? ["--config", configPath] : []),
+  "--json",
+]);
+let lintReport;
+try {
+  lintReport = JSON.parse(lint.stdout);
+} catch {
+  add(
+    "B",
+    "lint-run",
+    "FAIL",
+    `lint-wiki did not produce JSON: ${(lint.stderr || lint.stdout).trim().slice(0, 200)}`
+  );
+}
+if (lintReport) {
+  const structureItems = lintReport.items.filter(i => i.group === "structure");
+  const otherItems = lintReport.items.filter(i => i.group !== "structure");
+  if (structureItems.length === 0)
+    add("A", "structure", "PASS", "structure conforms to the manifest");
+  for (const i of structureItems)
+    add(
+      "A",
+      `structure:${i.group}`,
+      i.status,
+      `${i.message}${i.file ? ` (${i.file})` : ""}`
+    );
+  if (otherItems.length === 0)
+    add("B", "integrity", "PASS", "no integrity/safety findings");
+  for (const i of otherItems)
+    add(
+      "B",
+      `${i.group}`,
+      i.status,
+      `${i.message}${i.file ? ` (${i.file})` : ""}`
+    );
+}
+
+// --- C/D/E/F/G: deterministic-light + delegated to the doctor skill --------
+add(
+  "C",
+  "no-loss",
+  "SKIP",
+  "no-loss/parity needs the migration manifest from /migrate; dangling-link check is covered in B"
+);
+add(
+  "D",
+  "runtime",
+  "SKIP",
+  "runtime surfaces (commands/skills/subagents/MCP) verified by the lisa-wiki-doctor skill"
+);
+add(
+  "E",
+  "smoke",
+  "SKIP",
+  "functional smoke tests (ingest/query/lint/onboard) performed by the lisa-wiki-doctor skill"
+);
+add(
+  "F",
+  "mode",
+  config?.mode ? "PASS" : "FAIL",
+  config?.mode ? `mode: ${config.mode}; wikiRoot resolves` : "mode not set"
+);
+add(
+  "G",
+  "git-ci-dist",
+  "SKIP",
+  "git/CI/distribution checks performed by the lisa-wiki-doctor skill and CI"
+);
+
+// --- verdict --------------------------------------------------------------
+const all = Object.values(groups).flat();
+const isBlockingWarn = (item, group) =>
+  migration && (group === "A" || group === "B") && item.status === "WARN";
+let verdict = "READY";
+if (all.some(i => i.status === "FAIL")) verdict = "NOT_READY";
+else if (
+  Object.entries(groups).some(([g, items]) =>
+    items.some(i => isBlockingWarn(i, g))
+  )
+)
+  verdict = "NOT_READY";
+else if (all.some(i => i.status === "WARN")) verdict = "READY_WITH_WARNINGS";
+
+const reportObj = {
+  tool: "verify-migration",
+  deterministic: true,
+  wikiRoot: path.relative(process.cwd(), wikiRoot) || ".",
+  mode: config?.mode ?? null,
+  migration,
+  generatedAt: new Date().toISOString(),
+  verdict,
+  subset: "deterministic",
+  note: "Deterministic subset only. Groups C (no-loss/parity), D (runtime surfaces), E (functional smoke), and G (git/CI/distribution) are completed by the lisa-wiki-doctor skill, which merges its results into this report.",
+  groups,
+};
+
+const outPath = path.join(wikiRoot, "state", "migration", "doctor-report.json");
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+fs.writeFileSync(outPath, `${JSON.stringify(reportObj, null, 2)}\n`);
+
+const counts = all.reduce(
+  (acc, i) => ((acc[i.status] = (acc[i.status] ?? 0) + 1), acc),
+  {}
+);
+console.log(
+  // INFO is listed so a finding this tool deliberately does not judge is still
+  // counted somewhere. Omitting it would make a reported finding invisible in
+  // the one line most readers stop at.
+  `verdict: ${verdict}  (${["PASS", "INFO", "WARN", "FAIL", "SKIP"].map(s => `${counts[s] ?? 0} ${s}`).join(", ")})`
+);
+console.log(`report → ${path.relative(process.cwd(), outPath)}`);
+console.log(
+  "  (deterministic subset — C/D/E/G completed by the /doctor skill)"
+);
+for (const i of all.filter(i => i.status === "FAIL" || i.status === "WARN")) {
+  console.log(`  ${i.status === "FAIL" ? "✗" : "⚠"} [${i.id}] ${i.message}`);
+}
+process.exit(verdict === "NOT_READY" ? 1 : 0);

package/plugins/lisa-wiki-devin/scripts/verify-wiki-safety.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Pre-commit safety gate for generated wiki output.
+ *
+ * Scans only explicit wiki paths, or current git changes under the configured
+ * wiki root when no paths are passed. Reports safe metadata only.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./_wiki-lib.mjs";
+import { scanWikiGeneratedFiles } from "./wiki-safety.mjs";
+
+import {
+  boundedChildOutput,
+  rethrowIfChildTimeout,
+} from "./lib/bounded-child.mjs";
+
+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 repeated = name => {
+  const values = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === name && argv[i + 1]) values.push(argv[i + 1]);
+  }
+  return values;
+};
+
+const { config } = loadConfig(opt("--config"));
+const wikiRoot = path.resolve(opt("--wiki") ?? config?.wikiRoot ?? "wiki");
+const asJson = flag("--json");
+const scanner = opt("--scanner") ?? "builtin";
+
+function commandExists(command) {
+  try {
+    boundedChildOutput("sh", ["-c", `command -v ${command}`], {
+      stdio: "ignore",
+    });
+    return true;
+  } catch (error) {
+    // "I could not check whether the tool exists" is not "the tool is
+    // absent" — and absent silently downgrades the scan to the builtin.
+    rethrowIfChildTimeout(error);
+    return false;
+  }
+}
+
+function gitChangedPaths() {
+  let out = "";
+  try {
+    out = boundedChildOutput("git", ["status", "--porcelain=v1", "-z"], {
+      encoding: "utf8",
+    });
+  } catch (error) {
+    // An empty change set means this safety check inspects NOTHING and
+    // passes. A busy machine would clear the wiki without reading it.
+    rethrowIfChildTimeout(error);
+    return [];
+  }
+  const entries = out.split("\0").filter(Boolean);
+  const paths = [];
+  for (let i = 0; i < entries.length; i += 1) {
+    const entry = entries[i];
+    const status = entry.slice(0, 2);
+    const file = entry.slice(3);
+    if (!file || status.includes("D")) continue;
+    paths.push(file);
+    if (status[0] === "R" || status[0] === "C") i += 1;
+  }
+  return paths;
+}
+
+const explicitPaths = repeated("--path");
+const files = explicitPaths.length > 0 ? explicitPaths : gitChangedPaths();
+
+const externalScanner =
+  scanner === "gitleaks" || scanner === "trufflehog" ? scanner : undefined;
+const externalScannerMissing =
+  externalScanner !== undefined && !commandExists(externalScanner);
+
+const result = scanWikiGeneratedFiles(files, {
+  fsModule: fs,
+  pathModule: path,
+  wikiRoot,
+});
+
+const finalResult = {
+  ...result,
+  scanner: {
+    selected: scanner,
+    externalAvailable: externalScanner ? !externalScannerMissing : undefined,
+  },
+  ok: result.ok && !externalScannerMissing,
+  errors: [
+    ...result.errors,
+    ...(externalScannerMissing
+      ? [
+          {
+            file: path.relative(process.cwd(), wikiRoot) || ".",
+            message: `${externalScanner} scanner selected but unavailable`,
+          },
+        ]
+      : []),
+  ],
+};
+
+if (asJson) {
+  console.log(JSON.stringify(finalResult, null, 2));
+} else {
+  for (const finding of finalResult.findings) {
+    console.log(
+      `x [wiki-safety] possible ${finding.entityType} (${finding.confidence}) in ${finding.sourceId}; count=${finding.count}`
+    );
+  }
+  for (const error of finalResult.errors) {
+    console.log(`x [wiki-safety] ${error.message} (${error.file})`);
+  }
+  console.log(
+    `\n${finalResult.findings.length} finding${finalResult.findings.length === 1 ? "" : "s"}, ${finalResult.errors.length} error${finalResult.errors.length === 1 ? "" : "s"} across ${finalResult.scanned.length} wiki file${finalResult.scanned.length === 1 ? "" : "s"} — ${finalResult.ok ? "OK" : "BLOCKING"}`
+  );
+}
+
+process.exitCode = finalResult.ok ? 0 : 1;