@codyswann/lisa 2.23.2 → 2.25.0

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.`
+);

package/plugins/src/wiki/scripts/slack_oauth_user.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Run a local Slack OAuth flow for a user token.
+
+This helper intentionally requests user scopes, not bot scopes. It stores the
+OAuth response in an ignored local file by default; do not commit that file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import secrets
+import stat
+import sys
+import urllib.parse
+import urllib.request
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+
+DEFAULT_SCOPES = ",".join(
+    [
+        "channels:read",
+        "channels:history",
+        "groups:read",
+        "groups:history",
+        "users:read",
+        "files:read",
+    ]
+)
+
+
+class OAuthHandler(BaseHTTPRequestHandler):
+    server: "OAuthServer"
+
+    def log_message(self, fmt: str, *args: object) -> None:
+        return
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        params = urllib.parse.parse_qs(parsed.query)
+        state = params.get("state", [""])[0]
+        code = params.get("code", [""])[0]
+        error = params.get("error", [""])[0]
+
+        if error:
+            self.server.error = error
+            self._respond(400, f"Slack OAuth failed: {error}")
+            return
+
+        if state != self.server.expected_state:
+            self.server.error = "state_mismatch"
+            self._respond(400, "Slack OAuth failed: state mismatch.")
+            return
+
+        if not code:
+            self.server.error = "missing_code"
+            self._respond(400, "Slack OAuth failed: missing code.")
+            return
+
+        self.server.code = code
+        self._respond(200, "Slack OAuth complete. You can return to the terminal.")
+
+    def _respond(self, status: int, body: str) -> None:
+        data = body.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+
+class OAuthServer(HTTPServer):
+    expected_state: str
+    code: str | None
+    error: str | None
+
+
+def exchange_code(
+    *,
+    client_id: str,
+    client_secret: str,
+    code: str,
+    redirect_uri: str,
+) -> dict:
+    body = urllib.parse.urlencode(
+        {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+        }
+    ).encode("utf-8")
+    basic = base64.b64encode(f"{client_id}:{client_secret}".encode("utf-8")).decode("ascii")
+    request = urllib.request.Request(
+        "https://slack.com/api/oauth.v2.access",
+        data=body,
+        headers={
+            "Authorization": f"Basic {basic}",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=30) as response:
+        payload = json.loads(response.read().decode("utf-8"))
+    if not payload.get("ok"):
+        raise RuntimeError(f"Slack token exchange failed: {payload}")
+    return payload
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--client-id", default=os.environ.get("SLACK_CLIENT_ID"))
+    parser.add_argument("--client-secret", default=os.environ.get("SLACK_CLIENT_SECRET"))
+    parser.add_argument("--redirect-uri", default="http://localhost:8765/slack/oauth/callback")
+    parser.add_argument("--scopes", default=os.environ.get("SLACK_USER_SCOPES", DEFAULT_SCOPES))
+    parser.add_argument("--output", default=".secrets/slack-user-token.json")
+    parser.add_argument("--no-open", action="store_true", help="Print the URL without opening a browser.")
+    args = parser.parse_args()
+
+    if not args.client_id or not args.client_secret:
+        parser.error("Provide --client-id/--client-secret or SLACK_CLIENT_ID/SLACK_CLIENT_SECRET.")
+
+    redirect = urllib.parse.urlparse(args.redirect_uri)
+    if redirect.hostname not in {"localhost", "127.0.0.1"}:
+        parser.error("This helper only starts a localhost callback server.")
+
+    state = secrets.token_urlsafe(32)
+    query = urllib.parse.urlencode(
+        {
+            "client_id": args.client_id,
+            "user_scope": args.scopes,
+            "redirect_uri": args.redirect_uri,
+            "state": state,
+        }
+    )
+    authorize_url = f"https://slack.com/oauth/v2/authorize?{query}"
+
+    server = OAuthServer((redirect.hostname or "localhost", redirect.port or 80), OAuthHandler)
+    server.expected_state = state
+    server.code = None
+    server.error = None
+
+    print("Open this URL to authorize Slack user-token access:")
+    print(authorize_url)
+    if not args.no_open:
+        webbrowser.open(authorize_url)
+
+    while server.code is None and server.error is None:
+        server.handle_request()
+
+    if server.error:
+        print(f"OAuth failed: {server.error}", file=sys.stderr)
+        return 1
+
+    payload = exchange_code(
+        client_id=args.client_id,
+        client_secret=args.client_secret,
+        code=server.code or "",
+        redirect_uri=args.redirect_uri,
+    )
+
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    output.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+    team = payload.get("team") or {}
+    print(f"Saved Slack OAuth response to {output}")
+    print(f"Team: {team.get('name') or team.get('id') or 'unknown'}")
+    print("Use it with: python3 scripts/ingest_slack_channel.py --token-file " + str(output) + " --channel '#channel-name'")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())