wicked-brain 0.9.2 → 0.11.0

package/server/lib/detect-mode.mjs

@@ -0,0 +1,233 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const CODE_MANIFESTS = [
+  "package.json",
+  "pyproject.toml",
+  "requirements.txt",
+  "Pipfile",
+  "go.mod",
+  "Cargo.toml",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "Gemfile",
+  "composer.json",
+  "mix.exs",
+  "deno.json",
+  "bun.lockb",
+];
+
+const CONTENT_MANIFESTS = [
+  "mkdocs.yml",
+  "mkdocs.yaml",
+  "_config.yml",
+  "hugo.toml",
+  "hugo.yaml",
+  "book.toml",
+  "docusaurus.config.js",
+  "docusaurus.config.ts",
+  "docusaurus.config.mjs",
+  "astro.config.mjs",
+  "astro.config.ts",
+  ".vitepress",
+  "antora.yml",
+];
+
+const CODE_DIRS = ["src", "lib", "server", "cmd", "internal", "pkg", "app"];
+const CONTENT_DIRS = ["content", "posts", "chapters", "handbook", "policies", "articles"];
+
+const CODE_EXTS = new Set([
+  ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+  ".py", ".pyi",
+  ".go", ".rs",
+  ".java", ".kt", ".kts", ".scala", ".groovy",
+  ".rb", ".php", ".ex", ".exs",
+  ".c", ".h", ".cpp", ".hpp", ".cc", ".cxx",
+  ".cs", ".fs", ".vb",
+  ".swift", ".m", ".mm",
+  ".sh", ".bash", ".zsh", ".fish",
+  ".lua", ".r",
+]);
+
+const PROSE_EXTS = new Set([
+  ".md", ".mdx", ".markdown",
+  ".adoc", ".asciidoc",
+  ".rst",
+  ".txt",
+  ".tex",
+  ".org",
+]);
+
+const SKIP_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", "out",
+  ".venv", "venv", "env", "__pycache__",
+  ".next", ".nuxt", ".svelte-kit", ".cache",
+  "target", "bin", "obj",
+  "archive", "vendor",
+  ".wicked-brain",
+]);
+
+/**
+ * Pure classifier. Takes shallow scan inputs, returns mode verdict.
+ */
+export function classifyRepo({ manifests = [], dirs = [], codeFileCount = 0, proseFileCount = 0 }) {
+  let codeScore = 0;
+  let contentScore = 0;
+  const reasons = [];
+
+  for (const m of manifests) {
+    if (CODE_MANIFESTS.includes(m)) {
+      codeScore += 10;
+      reasons.push(`+10 code manifest: ${m}`);
+    }
+    if (CONTENT_MANIFESTS.includes(m)) {
+      contentScore += 10;
+      reasons.push(`+10 content manifest: ${m}`);
+    }
+  }
+
+  for (const d of dirs) {
+    if (CODE_DIRS.includes(d)) {
+      codeScore += 5;
+      reasons.push(`+5 code dir: ${d}/`);
+    }
+    if (CONTENT_DIRS.includes(d)) {
+      contentScore += 5;
+      reasons.push(`+5 content dir: ${d}/`);
+    }
+  }
+
+  const total = codeFileCount + proseFileCount;
+  const MIN_SAMPLE = 5;
+  if (total >= MIN_SAMPLE) {
+    const codeRatio = codeFileCount / total;
+    const proseRatio = proseFileCount / total;
+    const codeBoost = Math.round(codeRatio * 20);
+    const contentBoost = Math.round(proseRatio * 20);
+    if (codeBoost > 0) {
+      codeScore += codeBoost;
+      reasons.push(`+${codeBoost} code_ratio=${codeRatio.toFixed(2)} (${codeFileCount}/${total})`);
+    }
+    if (contentBoost > 0) {
+      contentScore += contentBoost;
+      reasons.push(`+${contentBoost} prose_ratio=${proseRatio.toFixed(2)} (${proseFileCount}/${total})`);
+    }
+  } else if (total > 0) {
+    reasons.push(`ratio skipped: sample too small (${total} < ${MIN_SAMPLE})`);
+  }
+
+  let mode;
+  if (codeScore >= 15 && contentScore < 10) mode = "code";
+  else if (contentScore >= 15 && codeScore < 10) mode = "content";
+  else if (codeScore >= 10 && contentScore >= 10) mode = "mixed";
+  else mode = "unknown";
+
+  return {
+    mode,
+    score: { code: codeScore, content: contentScore },
+    reasons,
+  };
+}
+
+/**
+ * Default paths for the wiki root, given a detection result.
+ *
+ * Honors the discovery contract's convention-fallback order for an already-
+ * present wiki tree: `wiki/` → `docs/wiki/` → default `wiki/`. That way a
+ * repo that already has `docs/wiki/` (common when `docs/` is contributor-
+ * facing) is detected correctly and mode.json points at the right place.
+ */
+export function defaultWikiRoots({ mode }, { hasWikiDir, hasDocsWikiDir, hasDocsDir }) {
+  const wikiRoot = hasWikiDir
+    ? "wiki"
+    : hasDocsWikiDir
+      ? "docs/wiki"
+      : "wiki";
+  if (mode === "mixed") {
+    return {
+      wiki_root: wikiRoot,
+      content_root: hasDocsDir ? "docs" : "content",
+    };
+  }
+  if (mode === "content") {
+    return {
+      wiki_root: wikiRoot,
+      content_root: hasDocsDir ? "docs" : "content",
+    };
+  }
+  return {
+    wiki_root: wikiRoot,
+    content_root: null,
+  };
+}
+
+/**
+ * I/O wrapper: scans a repo root with caps, then classifies.
+ */
+export async function detectRepoMode(repoRoot, { maxFiles = 10000, maxDepth = 6 } = {}) {
+  const absRoot = path.resolve(repoRoot);
+  const topLevel = await readDirSafe(absRoot);
+
+  const manifests = topLevel.filter((e) => e.isFile).map((e) => e.name);
+  const dirs = topLevel.filter((e) => e.isDir && !SKIP_DIRS.has(e.name)).map((e) => e.name);
+
+  let codeFileCount = 0;
+  let proseFileCount = 0;
+  let visited = 0;
+  const queue = dirs.map((d) => ({ rel: d, depth: 1 }));
+
+  while (queue.length > 0 && visited < maxFiles) {
+    const { rel, depth } = queue.shift();
+    if (depth > maxDepth) continue;
+    const abs = path.join(absRoot, rel);
+    const entries = await readDirSafe(abs);
+    for (const e of entries) {
+      if (visited >= maxFiles) break;
+      if (e.isDir) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        queue.push({ rel: path.join(rel, e.name), depth: depth + 1 });
+      } else if (e.isFile) {
+        visited += 1;
+        const ext = path.extname(e.name).toLowerCase();
+        if (CODE_EXTS.has(ext)) codeFileCount += 1;
+        else if (PROSE_EXTS.has(ext)) proseFileCount += 1;
+      }
+    }
+  }
+
+  const result = classifyRepo({ manifests, dirs, codeFileCount, proseFileCount });
+  const hasWikiDir = dirs.includes("wiki");
+  const hasDocsDir = dirs.includes("docs");
+  // Check for a pre-existing `docs/wiki/` tree — this is the "contributor-
+  // facing docs/" case where the wiki has been nested by convention.
+  let hasDocsWikiDir = false;
+  if (hasDocsDir) {
+    try {
+      const docsEntries = await fs.readdir(path.join(absRoot, "docs"), { withFileTypes: true });
+      hasDocsWikiDir = docsEntries.some((e) => e.isDirectory() && e.name === "wiki");
+    } catch {
+      // directory unreadable — treat as absent
+    }
+  }
+  const roots = defaultWikiRoots(result, { hasWikiDir, hasDocsWikiDir, hasDocsDir });
+
+  return {
+    ...result,
+    ...roots,
+    scanned: { files: visited, capped: visited >= maxFiles },
+  };
+}
+
+async function readDirSafe(dir) {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.map((e) => ({
+      name: e.name,
+      isDir: e.isDirectory(),
+      isFile: e.isFile(),
+    }));
+  } catch {
+    return [];
+  }
+}

package/server/lib/frontmatter.mjs

@@ -0,0 +1,204 @@
+/**
+ * Minimal YAML-subset frontmatter parser.
+ *
+ * Supports the exact shape wicked-brain wiki pages use. Does NOT support
+ * nested objects, multi-line string folding, anchors, tags, or other full
+ * YAML features. If those are ever needed, switch to the `yaml` npm package
+ * rather than expanding this.
+ *
+ * Supported value forms:
+ *   key: value                   → string (quotes stripped)
+ *   key: "value with :"          → quoted string
+ *   key: true / false            → boolean
+ *   key: 42                      → number
+ *   key: 2026-04-17              → date (kept as string for portability)
+ *   key: [a, b, "c, d"]          → inline array of scalars
+ *   key:
+ *     - a
+ *     - b                        → block array of scalars
+ *
+ * Lines starting with `#` are treated as comments and ignored. Leading and
+ * trailing whitespace on each line is stripped.
+ */
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Split raw content into { frontmatter, body }.
+ * If no frontmatter fence is present, returns { frontmatter: null, body: content }.
+ */
+export function extractFrontmatter(content) {
+  if (typeof content !== "string") return { frontmatter: null, body: "" };
+  const m = content.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: null, body: content };
+  return { frontmatter: m[1], body: m[2] };
+}
+
+/**
+ * Parse a frontmatter block into a flat object. Returns {} on null/empty input.
+ * Throws on clearly malformed input (unclosed block array, duplicate key).
+ */
+export function parseFrontmatterBlock(block) {
+  if (!block) return {};
+  const lines = block.split(/\r?\n/);
+  const data = {};
+  let i = 0;
+  while (i < lines.length) {
+    const rawLine = lines[i];
+    const line = rawLine.trimEnd();
+    i++;
+    if (line.length === 0) continue;
+    if (/^\s*#/.test(line)) continue;
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("-")) {
+      throw new Error(`unexpected list item at top level: ${rawLine}`);
+    }
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx < 0) {
+      throw new Error(`expected 'key: value' but got: ${rawLine}`);
+    }
+    const key = trimmed.slice(0, colonIdx).trim();
+    const rest = trimmed.slice(colonIdx + 1).trim();
+    if (Object.prototype.hasOwnProperty.call(data, key)) {
+      throw new Error(`duplicate key: ${key}`);
+    }
+    if (rest.length === 0) {
+      const { array, consumed } = readBlockArray(lines, i);
+      data[key] = array;
+      i += consumed;
+      continue;
+    }
+    data[key] = parseScalarOrInlineArray(rest);
+  }
+  return data;
+}
+
+/**
+ * Parse content into { data, body }. Convenience wrapper for the common case.
+ */
+export function parseFrontmatter(content) {
+  const { frontmatter, body } = extractFrontmatter(content);
+  const data = parseFrontmatterBlock(frontmatter);
+  return { data, body };
+}
+
+/**
+ * Get a field value from parsed data. Returns null if missing.
+ * Exists primarily so callers can be explicit about "missing" vs "false/0/''".
+ */
+export function getField(data, name) {
+  if (data == null || !Object.prototype.hasOwnProperty.call(data, name)) return null;
+  return data[name];
+}
+
+/**
+ * Serialize a flat object back to a frontmatter block. Inverse of
+ * parseFrontmatterBlock for the supported subset. Arrays are emitted inline
+ * when short, block form when any element contains a comma or the total
+ * length exceeds 60 chars. Booleans/numbers pass through; strings are quoted
+ * only when necessary (contain : # [ ] , or leading/trailing whitespace).
+ */
+export function serializeFrontmatterBlock(data) {
+  if (!data || typeof data !== "object") return "";
+  const out = [];
+  for (const [key, value] of Object.entries(data)) {
+    if (Array.isArray(value)) {
+      const inline = `[${value.map((v) => formatScalar(v)).join(", ")}]`;
+      if (value.length === 0) {
+        out.push(`${key}: []`);
+      } else if (inline.length <= 60 && !value.some((v) => typeof v === "string" && v.includes(","))) {
+        out.push(`${key}: ${inline}`);
+      } else {
+        out.push(`${key}:`);
+        for (const v of value) out.push(`  - ${formatScalar(v)}`);
+      }
+    } else {
+      out.push(`${key}: ${formatScalar(value)}`);
+    }
+  }
+  return out.join("\n");
+}
+
+// --- internals ---
+
+function readBlockArray(lines, startIdx) {
+  const items = [];
+  let i = startIdx;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim().length === 0) {
+      i++;
+      continue;
+    }
+    const m = line.match(/^\s+-\s+(.*)$/);
+    if (!m) break;
+    items.push(parseScalarOrInlineArray(m[1].trim()));
+    i++;
+  }
+  return { array: items, consumed: i - startIdx };
+}
+
+function parseScalarOrInlineArray(raw) {
+  if (raw.length === 0) return "";
+  if (raw.startsWith("[")) {
+    if (!raw.endsWith("]")) {
+      throw new Error(`unterminated inline array: ${raw}`);
+    }
+    const inner = raw.slice(1, -1).trim();
+    if (inner.length === 0) return [];
+    return splitInlineArray(inner).map(parseScalar);
+  }
+  return parseScalar(raw);
+}
+
+function splitInlineArray(inner) {
+  const out = [];
+  let buf = "";
+  let inQuote = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (inQuote) {
+      buf += ch;
+      if (ch === inQuote) inQuote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inQuote = ch;
+      buf += ch;
+      continue;
+    }
+    if (ch === ",") {
+      out.push(buf.trim());
+      buf = "";
+      continue;
+    }
+    buf += ch;
+  }
+  if (buf.trim().length > 0) out.push(buf.trim());
+  return out;
+}
+
+function parseScalar(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return "";
+  if (/^".*"$/.test(trimmed) || /^'.*'$/.test(trimmed)) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null" || trimmed === "~") return null;
+  if (/^-?\d+$/.test(trimmed)) return Number(trimmed);
+  if (/^-?\d+\.\d+$/.test(trimmed)) return Number(trimmed);
+  // Dates kept as strings — downstream often wants the original form.
+  return trimmed;
+}
+
+function formatScalar(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  const s = String(value);
+  if (s.length === 0) return '""';
+  if (/[:#\[\],]/.test(s) || /^\s|\s$/.test(s)) return `"${s.replace(/"/g, '\\"')}"`;
+  return s;
+}

package/server/lib/gen-contract-api.mjs

@@ -0,0 +1,178 @@
+/**
+ * Contract API generator.
+ *
+ * Reads the `const actions = {...}` object literal in wicked-brain-server.mjs
+ * and produces:
+ *   - A structured JSON manifest of every action (name, implementation, notes)
+ *   - A markdown page with a stable H2 taxonomy and symbol-named anchors
+ *
+ * Pure functions — no I/O. The CLI glue (scripts/gen-wiki.mjs) reads the
+ * source, calls the extractor, and writes the outputs.
+ *
+ * The extractor is intentionally text-based, not AST-based: the file we
+ * target is disciplined (one object literal, one handler per line after the
+ * `=>`). If the shape changes, this extractor breaks loudly with a failing
+ * test rather than silently producing stale output.
+ */
+
+const ACTIONS_BLOCK_RE = /const\s+actions\s*=\s*\{\s*\n([\s\S]*?)\n\};/;
+const ACTION_LINE_RE = /^\s*(?:"([^"]+)"|([a-zA-Z_][a-zA-Z0-9_-]*))\s*:\s*(async\s+)?\(([^)]*)\)\s*=>/;
+const DB_CALL_RE = /\bdb\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/g;
+const LSP_CALL_RE = /\blsp\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/g;
+
+/**
+ * Extract actions from the server source. Returns an array in source order.
+ */
+export function extractActions(source) {
+  const block = source.match(ACTIONS_BLOCK_RE);
+  if (!block) {
+    throw new Error("Could not find `const actions = {...}` block");
+  }
+  const body = block[1];
+  const lines = body.split("\n");
+  const actions = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const m = line.match(ACTION_LINE_RE);
+    if (!m) { i++; continue; }
+    const name = m[1] ?? m[2];
+    const isAsync = Boolean(m[3]);
+    const paramsSig = m[4].trim();
+    // Collect the handler body (rest of this line + following lines until a
+    // line that looks like another action or closes the object).
+    const handlerLines = [line];
+    i++;
+    while (i < lines.length) {
+      const next = lines[i];
+      if (ACTION_LINE_RE.test(next)) break;
+      handlerLines.push(next);
+      i++;
+    }
+    const handlerText = handlerLines.join("\n");
+    const impls = collectImplCalls(handlerText);
+    actions.push({
+      name,
+      async: isAsync,
+      params: parseParamUses(paramsSig, handlerText),
+      impls,
+    });
+  }
+  return actions;
+}
+
+/**
+ * Render a contract-api.md page from the extracted actions.
+ * Declares canonical_for: [CONTRACT-API] so it's the single source.
+ */
+export function renderContractApi({ actions, generatedAt, sourcePath }) {
+  const lines = [];
+  lines.push("---");
+  lines.push("status: published");
+  lines.push("canonical_for: [CONTRACT-API]");
+  lines.push("references: []");
+  lines.push(`owner: core`);
+  lines.push(`last_reviewed: ${generatedAt}`);
+  lines.push("generated: true");
+  lines.push(`source: ${sourcePath}`);
+  lines.push("---");
+  lines.push("");
+  lines.push("# Contract: `POST /api`");
+  lines.push("");
+  lines.push("Single endpoint, action-dispatched. Body shape:");
+  lines.push("");
+  lines.push("```json");
+  lines.push('{ "action": "<name>", "params": { ... } }');
+  lines.push("```");
+  lines.push("");
+  lines.push(
+    "This page is **generated** from the server source. Do not hand-edit — "
+    + "changes will be overwritten on the next `npm run gen:wiki`. The truth "
+    + `lives at \`${sourcePath}\`; update that, then regenerate.`,
+  );
+  lines.push("");
+  lines.push("## Actions");
+  lines.push("");
+  lines.push("| Action | Params referenced | Implementation |");
+  lines.push("|---|---|---|");
+  for (const a of actions) {
+    const params = a.params.length ? a.params.map((p) => `\`${p}\``).join(", ") : "—";
+    const impls = a.impls.length
+      ? a.impls.map((i) => `\`${i.target}#${i.method}\``).join(", ")
+      : "—";
+    lines.push(`| \`${a.name}\` | ${params} | ${impls} |`);
+  }
+  lines.push("");
+  lines.push("## Per-action anchors");
+  lines.push("");
+  for (const a of actions) {
+    lines.push(`### \`${a.name}\``);
+    lines.push("");
+    if (a.impls.length) {
+      for (const impl of a.impls) {
+        lines.push(`- Implementation: \`${impl.target}#${impl.method}\``);
+      }
+    } else {
+      lines.push("- Implementation: inline in the action handler (no single delegate).");
+    }
+    if (a.params.length) {
+      lines.push(`- Params referenced: ${a.params.map((p) => `\`${p}\``).join(", ")}`);
+    }
+    if (a.async) lines.push("- Async handler.");
+    lines.push("");
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Produce the structured manifest used by tests and machine consumers.
+ */
+export function renderActionsJson({ actions, generatedAt, sourcePath }) {
+  return {
+    generated_at: generatedAt,
+    source: sourcePath,
+    canonical_id: "CONTRACT-API",
+    count: actions.length,
+    actions,
+  };
+}
+
+// --- internals ---
+
+function collectImplCalls(text) {
+  const out = [];
+  const seen = new Set();
+  DB_CALL_RE.lastIndex = 0;
+  let m;
+  while ((m = DB_CALL_RE.exec(text)) !== null) {
+    const key = `db:${m[1]}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ target: "server/lib/sqlite-search.mjs", method: m[1] });
+  }
+  LSP_CALL_RE.lastIndex = 0;
+  while ((m = LSP_CALL_RE.exec(text)) !== null) {
+    const key = `lsp:${m[1]}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ target: "server/lib/lsp-client.mjs", method: m[1] });
+  }
+  return out;
+}
+
+function parseParamUses(paramsSig, handlerText) {
+  if (paramsSig.length === 0) return [];
+  // paramsSig is typically `p` — find `p.xxx` references in the body.
+  const name = paramsSig.replace(/[={}:[\]].*$/, "").trim().split(/\s|,/)[0];
+  if (!name || /[^a-zA-Z_]/.test(name)) return [];
+  const re = new RegExp(`\\b${name}\\.([a-zA-Z_][a-zA-Z0-9_]*)`, "g");
+  const out = [];
+  const seen = new Set();
+  let m;
+  while ((m = re.exec(handlerText)) !== null) {
+    if (seen.has(m[1])) continue;
+    seen.add(m[1]);
+    out.push(m[1]);
+  }
+  return out;
+}