@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-wiki-devin/scripts/ensure-gitignore.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * ensure-gitignore.mjs — merge the lisa-wiki gitignore block into the project's
+ * `.gitignore`, idempotently. Dependency-free.
+ *
+ * The block is delimited by `# BEGIN: AI GUARDRAILS WIKI` and
+ * `# END: AI GUARDRAILS WIKI` markers (see templates/wrapper-gitignore.txt).
+ * Behavior matches the base lisa plugin's copy-contents strategy
+ * (src/strategies/copy-contents.ts):
+ *
+ *   - If the file is missing, create it with just the block.
+ *   - If the block markers exist, replace the block in place.
+ *   - If the markers don't exist, append the block to the end (preserving a
+ *     trailing newline).
+ *
+ * Patterns outside the marker block are NEVER touched. Re-running produces no
+ * spurious diff once the file is in sync.
+ *
+ * Usage: node ensure-gitignore.mjs [--cwd <project-dir>] [--dry-run]
+ *   default cwd: process.cwd()
+ *   --dry-run    prints the proposed merge result to stdout instead of writing
+ *
+ * Exit code 0 = ok (file was created, updated, or already in sync).
+ * Exit code 1 = error (e.g. template missing).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BEGIN_MARKER = "# BEGIN: AI GUARDRAILS WIKI";
+const END_MARKER = "# END: AI GUARDRAILS WIKI";
+
+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",
+  "wrapper-gitignore.txt"
+);
+
+const argv = process.argv.slice(2);
+const cwdIndex = argv.indexOf("--cwd");
+const projectDir =
+  cwdIndex !== -1 && argv[cwdIndex + 1]
+    ? path.resolve(argv[cwdIndex + 1])
+    : process.cwd();
+const dryRun = argv.includes("--dry-run");
+
+if (!fs.existsSync(templatePath)) {
+  fail(`template not found: ${templatePath}`);
+}
+
+const templateRaw = fs.readFileSync(templatePath, "utf8");
+const block = extractBlock(templateRaw);
+if (!block) {
+  fail(
+    `template at ${templatePath} does not contain the expected marker pair (${BEGIN_MARKER} / ${END_MARKER})`
+  );
+}
+
+const gitignorePath = path.join(projectDir, ".gitignore");
+const existing = fs.existsSync(gitignorePath)
+  ? fs.readFileSync(gitignorePath, "utf8")
+  : null;
+
+const merged = mergeBlock(existing, block);
+
+if (existing !== null && merged === existing) {
+  console.log(`✓ .gitignore already in sync (${gitignorePath})`);
+  process.exit(0);
+}
+
+if (dryRun) {
+  process.stdout.write(merged);
+  process.exit(0);
+}
+
+fs.writeFileSync(gitignorePath, merged);
+const verb = existing === null ? "created" : "updated";
+console.log(`✓ ${verb} ${gitignorePath}`);
+process.exit(0);
+
+/**
+ * Pull the block (markers included) out of arbitrary text. Returns null when
+ * the marker pair is missing or out of order.
+ */
+function extractBlock(text) {
+  const startIdx = text.indexOf(BEGIN_MARKER);
+  if (startIdx === -1) return null;
+  const endStart = text.indexOf(END_MARKER, startIdx + BEGIN_MARKER.length);
+  if (endStart === -1) return null;
+  const endIdx = endStart + END_MARKER.length;
+  return text.slice(startIdx, endIdx);
+}
+
+/**
+ * Merge a freshly-rendered block into the destination file content.
+ *   - existing === null → return the block alone (file will be created)
+ *   - existing has the markers → replace the block in place
+ *   - existing lacks the markers → append the block at the end
+ * Always normalizes to exactly one trailing newline.
+ */
+function mergeBlock(existing, freshBlock) {
+  if (existing === null) {
+    return `${freshBlock.trimEnd()}\n`;
+  }
+
+  const startIdx = existing.indexOf(BEGIN_MARKER);
+  if (startIdx !== -1) {
+    const endStart = existing.indexOf(
+      END_MARKER,
+      startIdx + BEGIN_MARKER.length
+    );
+    if (endStart !== -1) {
+      const endIdx = endStart + END_MARKER.length;
+      const before = existing.slice(0, startIdx);
+      const after = existing.slice(endIdx);
+      const trimmedAfter = after.startsWith("\n") ? after : `\n${after}`;
+      return `${before}${freshBlock.trimEnd()}${trimmedAfter}`;
+    }
+  }
+
+  // No marker pair in the destination — append.
+  const base = existing.endsWith("\n") ? existing : `${existing}\n`;
+  return `${base}\n${freshBlock.trimEnd()}\n`;
+}

package/plugins/lisa-wiki-devin/scripts/ensure-wiki.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * ensure-wiki.mjs — resolve the project's wiki root, mirroring/refreshing a
+ * remote wiki when one is configured. Dependency-free (Node built-ins only),
+ * so it stays portable to any downstream repo that installs the plugin.
+ *
+ * This is the single resolver that `lisa-wiki-query` and `lisa-wiki-ingest`
+ * call as step 0 so they never hardcode `wiki/` and never have to know whether
+ * the wiki is local or remote. The mode decision lives HERE, not in the skills:
+ *
+ *   - LOCAL  — the wiki lives on the local filesystem (the common case). Resolve
+ *              the wiki root, in precedence order, from `wiki.source.path`, else
+ *              `wikiRoot` in `wiki/lisa-wiki.config.json`, else `wiki`. No
+ *              network, a no-op. `wiki.source.path` is just the explicit form of
+ *              what the convention resolves implicitly.
+ *   - REMOTE — `.lisa.config.json` declares `wiki.source.url`. Maintain a
+ *              gitignored mirror of that repo and return the wiki root inside
+ *              it. Clone-if-missing, fetch+fast-forward when stale (TTL), and
+ *              tolerate being offline (proceed with the existing mirror + warn).
+ *
+ * `url` (remote) and `path` (local) are the two shapes of `wiki.source`; `url`
+ * takes precedence if both are somehow present.
+ *
+ * Config (consumer repo `.lisa.config.json`, with `.lisa.config.local.json`
+ * overriding per the config-resolution rule):
+ *
+ *   "wiki": {
+ *     "source": {
+ *       // LOCAL shape — optional; defaults to the in-repo `wiki/` convention:
+ *       "path":       "wiki",            // local wiki root, relative to repo root
+ *       // REMOTE shape (instead of path):
+ *       "url":        "git@github.com:org/wiki.git",  // present => REMOTE mode
+ *       "ref":        "main",            // default: remote HEAD / "main"
+ *       "mirrorPath": ".lisa/wiki",      // default; always gitignored
+ *       "subdir":     "wiki"             // optional: wiki root within the repo
+ *     },
+ *     "ttlSeconds": 300                  // skip the fetch if synced more recently
+ *   }
+ *
+ * Usage: node ensure-wiki.mjs [--cwd <dir>] [--json] [--ttl <seconds>] [--offline]
+ *   --cwd      project dir to resolve config/mirror against (default cwd)
+ *   --json     emit {mode, wikiRoot, mirrored, fetched, stale, offline} on stdout
+ *   --ttl      override ttlSeconds (0 = always fetch)
+ *   --offline  never touch the network; use whatever is already on disk
+ *
+ * Output: the resolved absolute wiki root is the LAST line on stdout (so a
+ * caller can `WIKI_ROOT=$(node ensure-wiki.mjs | tail -1)`). All human-facing
+ * progress goes to stderr. Exit 0 = a usable wiki root was resolved; 1 = not.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import { boundedChildOutput } from "./lib/bounded-child.mjs";
+
+const GITIGNORE_BEGIN = "# BEGIN: AI GUARDRAILS WIKI MIRROR";
+const GITIGNORE_END = "# END: AI GUARDRAILS WIKI MIRROR";
+const DEFAULT_MIRROR = ".lisa/wiki";
+const DEFAULT_TTL_SECONDS = 300;
+
+function log(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+function fail(msg) {
+  log(`✗ ${msg}`);
+  process.exit(1);
+}
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+function git(args, cwd) {
+  return boundedChildOutput("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  }).trim();
+}
+
+// ── args ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+function flagValue(name) {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] ? argv[i + 1] : undefined;
+}
+const projectDir = path.resolve(flagValue("--cwd") ?? process.cwd());
+const asJson = argv.includes("--json");
+const offline = argv.includes("--offline");
+const ttlOverride = flagValue("--ttl");
+
+// ── resolve the wiki source from .lisa.config.json (+ .local override) ────────
+const committed =
+  readJsonSafe(path.join(projectDir, ".lisa.config.json")) ?? {};
+const local =
+  readJsonSafe(path.join(projectDir, ".lisa.config.local.json")) ?? {};
+const wikiCfg = { ...committed.wiki, ...local.wiki };
+const source = {
+  ...committed.wiki?.source,
+  ...local.wiki?.source,
+};
+const ttlSeconds = Number(
+  ttlOverride ?? wikiCfg.ttlSeconds ?? DEFAULT_TTL_SECONDS
+);
+
+if (source.url !== undefined && typeof source.url !== "string") {
+  fail("`wiki.source.url` in .lisa.config.json must be a string");
+}
+if (source.path !== undefined && typeof source.path !== "string") {
+  fail("`wiki.source.path` in .lisa.config.json must be a string");
+}
+
+function emit(result) {
+  if (asJson) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else process.stdout.write(`${result.wikiRoot}\n`);
+  process.exit(0);
+}
+
+// ── LOCAL mode (no remote clone) ───────────────────────────────────────────────
+// The wiki lives on the local filesystem. Its root is, in precedence order:
+//   1. `wiki.source.path` — explicit override in .lisa.config.json
+//   2. `wikiRoot` from wiki/lisa-wiki.config.json — the in-repo convention
+//   3. `wiki` — the default
+// No network, a no-op resolve. `wiki.source.path` is just the explicit form of
+// the same thing the convention resolves implicitly.
+if (!source.url) {
+  const wikiRoot = path.resolve(
+    projectDir,
+    source.path ??
+      readJsonSafe(path.join(projectDir, "wiki", "lisa-wiki.config.json"))
+        ?.wikiRoot ??
+      "wiki"
+  );
+  if (!fs.existsSync(path.join(wikiRoot, "index.md"))) {
+    log(
+      `⚠ no index.md under ${wikiRoot} — check wiki.source.path, or run /lisa-wiki:setup if the wiki is not scaffolded yet`
+    );
+  }
+  log(`✓ local wiki: ${wikiRoot}`);
+  emit({
+    mode: "local",
+    wikiRoot,
+    mirrored: false,
+    fetched: false,
+    stale: false,
+    offline,
+  });
+}
+
+// ── REMOTE mode ───────────────────────────────────────────────────────────────
+const mirrorPath = path.resolve(
+  projectDir,
+  source.mirrorPath ?? DEFAULT_MIRROR
+);
+const ref = source.ref || "";
+ensureGitignored(projectDir, source.mirrorPath ?? DEFAULT_MIRROR);
+
+const isClone = fs.existsSync(path.join(mirrorPath, ".git"));
+let fetched = false;
+let stale = false;
+
+if (!isClone) {
+  if (offline) fail(`offline and no mirror present at ${mirrorPath}`);
+  log(`↧ cloning wiki ${source.url} → ${mirrorPath}`);
+  try {
+    fs.mkdirSync(path.dirname(mirrorPath), { recursive: true });
+    const cloneArgs = ["clone", "--depth", "1"];
+    if (ref) cloneArgs.push("--branch", ref);
+    cloneArgs.push(source.url, mirrorPath);
+    git(cloneArgs, projectDir);
+    fetched = true;
+    stampSync(mirrorPath);
+  } catch (e) {
+    fail(`clone failed: ${String(e.message ?? e).split("\n")[0]}`);
+  }
+} else if (offline) {
+  log("• offline — using existing mirror without fetching");
+  stale = true;
+} else if (isFresh(mirrorPath, ttlSeconds)) {
+  log(`• mirror synced < ${ttlSeconds}s ago — skipping fetch`);
+} else {
+  // Stale: fetch and hard-reset. The mirror is a read-only working copy of the
+  // canonical wiki — never edited in place — so resetting to the remote ref is
+  // safe and keeps it byte-identical to upstream.
+  try {
+    const branch =
+      ref || git(["rev-parse", "--abbrev-ref", "HEAD"], mirrorPath);
+    log(`↻ refreshing wiki mirror (${branch})`);
+    git(["fetch", "--depth", "1", "origin", branch], mirrorPath);
+    git(["reset", "--hard", `origin/${branch}`], mirrorPath);
+    fetched = true;
+    stampSync(mirrorPath);
+  } catch (e) {
+    // Offline-tolerant: a fetch failure must not block work when we already
+    // have a usable (if stale) copy on disk.
+    log(
+      `⚠ refresh failed (${String(e.message ?? e).split("\n")[0]}) — using stale mirror`
+    );
+    stale = true;
+  }
+}
+
+const wikiRoot = resolveWikiRootInMirror(mirrorPath, source.subdir);
+if (!fs.existsSync(path.join(wikiRoot, "index.md"))) {
+  log(
+    `⚠ no index.md under ${wikiRoot} — check wiki.source.subdir / the wiki repo layout`
+  );
+}
+log(`✓ remote wiki mirror: ${wikiRoot}`);
+emit({ mode: "remote", wikiRoot, mirrored: true, fetched, stale, offline });
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/** Locate the wiki content root inside a cloned wiki repo. */
+function resolveWikiRootInMirror(mirror, subdir) {
+  if (subdir) return path.resolve(mirror, subdir);
+  if (fs.existsSync(path.join(mirror, "wiki", "index.md")))
+    return path.join(mirror, "wiki");
+  return mirror; // dedicated wiki repo with content at its root
+}
+
+/** TTL stamp lives under .git so it is never part of the wiki content. */
+function stampPath(mirror) {
+  return path.join(mirror, ".git", "lisa-wiki-sync");
+}
+function stampSync(mirror) {
+  try {
+    fs.writeFileSync(stampPath(mirror), String(Date.now()));
+  } catch {
+    /* best-effort */
+  }
+}
+function isFresh(mirror, ttl) {
+  if (ttl <= 0) return false;
+  let last = NaN;
+  try {
+    last = Number(fs.readFileSync(stampPath(mirror), "utf8"));
+  } catch {
+    return false;
+  }
+  if (!Number.isFinite(last)) return false;
+  return Date.now() - last < ttl * 1000;
+}
+
+/** Idempotently keep the mirror path out of version control. */
+function ensureGitignored(dir, relPath) {
+  const gitignorePath = path.join(dir, ".gitignore");
+  const line = `/${relPath.replace(/^\/+/, "").replace(/\/+$/, "")}/`;
+  const block = `${GITIGNORE_BEGIN}\n# Remote wiki mirror — gitignored working copy, managed by ensure-wiki.\n${line}\n${GITIGNORE_END}`;
+  const existing = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, "utf8")
+    : null;
+  if (existing && existing.includes(line)) return; // already ignored (any block)
+  const start = existing?.indexOf(GITIGNORE_BEGIN) ?? -1;
+  let merged;
+  if (existing === null) {
+    merged = `${block}\n`;
+  } else if (start !== -1) {
+    const end = existing.indexOf(GITIGNORE_END, start) + GITIGNORE_END.length;
+    merged = `${existing.slice(0, start)}${block}${existing.slice(end)}`;
+  } else {
+    const base = existing.endsWith("\n") ? existing : `${existing}\n`;
+    merged = `${base}\n${block}\n`;
+  }
+  fs.writeFileSync(gitignorePath, merged);
+  log(`✓ ensured ${line} is gitignored`);
+}

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

@@ -0,0 +1,198 @@
+#!/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 { readJsonSafe, writeSanitizedSourceNote } from "./_wiki-lib.mjs";
+
+import {
+  boundedChildOutput,
+  rethrowIfChildTimeout,
+} from "./lib/bounded-child.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 =>
+  boundedChildOutput("git", ["-C", repo, ...args], { encoding: "utf8" }).trim();
+const tryGit = args => {
+  try {
+    return git(args);
+  } catch {
+    // probe-direction: neutral — this is wiki ingestion; the empty string becomes
+    // an empty section of a source note and gates nothing.
+    return "";
+  }
+};
+const commitExists = c => {
+  try {
+    boundedChildOutput("git", ["-C", repo, "cat-file", "-e", `${c}^{commit}`], {
+      stdio: "ignore",
+    });
+    return true;
+  } catch (error) {
+    // `false` is a verdict of "absent", not an admission of ignorance.
+    rethrowIfChildTimeout(error);
+    return false;
+  }
+};
+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 = boundedChildOutput(
+      "gh",
+      ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
+      { cwd: repo, encoding: "utf8" }
+    ).trim();
+  } catch {
+    ghRepo = "";
+  }
+}
+if (ghRepo) {
+  try {
+    const prs = JSON.parse(
+      boundedChildOutput(
+        "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)_"
+}
+`;
+
+const safety = writeSanitizedSourceNote(notePath, note, {
+  sourceId: path.relative(process.cwd(), notePath),
+  sourceSystem: "git",
+  project: slug,
+});
+
+const meta = {
+  connector: "git",
+  profile: slug,
+  ranAt: new Date().toISOString(),
+  proposedCursor: { lastCommit: head, lastPr },
+  sourceNotes: [path.relative(process.cwd(), notePath)],
+  safety: {
+    reviewRequired: safety.reviewRequired,
+    findings: safety.findings,
+  },
+};
+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)`
+  );