@infinitedusky/indusk-mcp 1.10.2 → 1.11.0

package/dist/bin/cli.js

@@ -131,6 +131,93 @@ infra
     const { infraStatus } = await import("./commands/infra.js");
     await infraStatus();
 });
+const graph = program
+    .command("graph")
+    .description("Manage the semantic graph (sync, rebuild, status)");
+graph
+    .command("sync")
+    .description("Sync CGC structural data into the semantic graph")
+    .action(async () => {
+    const { basename } = await import("node:path");
+    const { CgcAdapter } = await import("../lib/semantic-graph/adapters/cgc.js");
+    const { LogWriter } = await import("../lib/semantic-graph/log-writer.js");
+    const { getLogPath } = await import("../lib/semantic-graph/paths.js");
+    const { SemanticGraphClient } = await import("../lib/semantic-graph/runtime-client.js");
+    const { runSync } = await import("../lib/semantic-graph/sync-engine.js");
+    const projectRoot = process.cwd();
+    const projectName = basename(projectRoot);
+    const adapter = new CgcAdapter();
+    const logWriter = new LogWriter(getLogPath(projectRoot));
+    const client = new SemanticGraphClient(projectName);
+    await client.ensureConnection();
+    console.info("Syncing semantic graph...");
+    const result = await runSync(adapter, projectRoot, logWriter, client);
+    await client.close();
+    console.info(`Created: ${result.created}, Moved: ${result.moved}, Tombstoned: ${result.tombstoned}, Edges: ${result.edges_attached}, Unchanged: ${result.unchanged}`);
+    console.info(`Duration: ${result.duration_ms}ms`);
+});
+graph
+    .command("rebuild")
+    .description("Clear and rebuild the semantic graph runtime from the event log")
+    .action(async () => {
+    const { basename } = await import("node:path");
+    const { getLogPath } = await import("../lib/semantic-graph/paths.js");
+    const { replay } = await import("../lib/semantic-graph/replay.js");
+    const { SemanticGraphClient } = await import("../lib/semantic-graph/runtime-client.js");
+    const projectRoot = process.cwd();
+    const projectName = basename(projectRoot);
+    const logPath = getLogPath(projectRoot);
+    const client = new SemanticGraphClient(projectName);
+    await client.ensureConnection();
+    console.info("Clearing runtime...");
+    await client.clearGraph();
+    await client.close();
+    const freshClient = new SemanticGraphClient(projectName);
+    await freshClient.ensureConnection();
+    console.info("Replaying log...");
+    const result = await replay(logPath, freshClient);
+    await freshClient.close();
+    console.info(`Total: ${result.total}, Applied: ${result.applied}, Skipped: ${result.skipped}, Errors: ${result.errors}`);
+});
+graph
+    .command("status")
+    .description("Show semantic graph status")
+    .action(async () => {
+    const { basename } = await import("node:path");
+    const { existsSync, statSync } = await import("node:fs");
+    const { getLogPath } = await import("../lib/semantic-graph/paths.js");
+    const { readAllEvents } = await import("../lib/semantic-graph/log-reader.js");
+    const { SemanticGraphClient } = await import("../lib/semantic-graph/runtime-client.js");
+    const projectRoot = process.cwd();
+    const projectName = basename(projectRoot);
+    const logPath = getLogPath(projectRoot);
+    console.info(`Project: ${projectName}`);
+    console.info(`Log: ${logPath}`);
+    if (existsSync(logPath)) {
+        const stat = statSync(logPath);
+        const events = await readAllEvents(logPath);
+        console.info(`  Events: ${events.length}`);
+        console.info(`  Size: ${(stat.size / 1024).toFixed(1)}KB`);
+        const lastSync = [...events].reverse().find((e) => e.type === "sync.completed");
+        if (lastSync) {
+            console.info(`  Last sync: ${lastSync.ts}`);
+        }
+    }
+    else {
+        console.info("  (no log file — run 'indusk graph sync' first)");
+    }
+    try {
+        const client = new SemanticGraphClient(projectName);
+        await client.ensureConnection();
+        const anchors = await client.countAnchors();
+        const edges = await client.countEdges();
+        await client.close();
+        console.info(`Runtime: ${anchors} anchors, ${edges} edges`);
+    }
+    catch {
+        console.info("Runtime: FalkorDB not available");
+    }
+});
 program
     .command("pr-clean")
     .description("Strip InDusk settings overlay before a PR")
@@ -147,6 +234,40 @@ program
     applyOverlay(process.cwd());
     console.info("Re-applied InDusk overlay to .claude/settings.json");
 });
+program
+    .command("install <names...>")
+    .description("Install extensions (shorthand for extensions enable / add)")
+    .option("--from <source>", "Source for third-party extension (npm:pkg, github:user/repo, URL, or path)")
+    .action(async (names, opts) => {
+    if (opts.from) {
+        const { extensionsAdd } = await import("./commands/extensions.js");
+        await extensionsAdd(process.cwd(), names[0], opts.from);
+    }
+    else {
+        const { extensionsEnable } = await import("./commands/extensions.js");
+        await extensionsEnable(process.cwd(), names);
+    }
+});
+const eval_ = program.command("eval").description("Context evaluation and quality scoring");
+eval_
+    .command("summary")
+    .description("Aggregate eval scores and trends")
+    .option("--mode <mode>", "Filter by mode (eval, baseline)")
+    .option("--since <date>", "Show results since date")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { evalSummary } = await import("./commands/eval.js");
+    await evalSummary(process.cwd(), opts);
+});
+eval_
+    .command("baseline")
+    .description("Run baseline evaluation with vanilla agent")
+    .requiredOption("--task <path>", "Path to task prompt file")
+    .option("--keep", "Keep baseline worktree after eval")
+    .action(async (opts) => {
+    const { evalBaseline } = await import("./commands/eval.js");
+    await evalBaseline(process.cwd(), opts);
+});
 program
     .command("serve")
     .description("Start the MCP server (used by Claude Code via .mcp.json)")

package/dist/bin/commands/eval.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CLI commands for the eval system.
+ *
+ * `indusk eval summary` — aggregate scores and trends
+ * `indusk eval baseline` — run baseline evaluation with vanilla agent
+ */
+export declare function evalSummary(projectRoot: string, opts: {
+    mode?: string;
+    since?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function evalBaseline(projectRoot: string, opts: {
+    task: string;
+    keep?: boolean;
+}): Promise<void>;

package/dist/bin/commands/eval.js

@@ -0,0 +1,225 @@
+/**
+ * CLI commands for the eval system.
+ *
+ * `indusk eval summary` — aggregate scores and trends
+ * `indusk eval baseline` — run baseline evaluation with vanilla agent
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readAllEntries } from "../../lib/eval/log-reader.js";
+import { isScorecard } from "../../lib/eval/types.js";
+function getEvalLogPath(projectRoot) {
+    return join(projectRoot, ".indusk", "eval", "results.log");
+}
+export async function evalSummary(projectRoot, opts) {
+    const logPath = getEvalLogPath(projectRoot);
+    if (!existsSync(logPath)) {
+        console.info("No eval results yet. Results appear after jj describe triggers the eval hook.");
+        return;
+    }
+    const filterOpts = {};
+    if (opts.mode === "eval" || opts.mode === "baseline")
+        filterOpts.mode = opts.mode;
+    if (opts.since)
+        filterOpts.since = new Date(opts.since);
+    const entries = await readAllEntries(logPath, filterOpts);
+    const scorecards = entries.filter(isScorecard);
+    const errors = entries.filter((e) => !isScorecard(e));
+    if (entries.length === 0) {
+        console.info("No eval results match the filter criteria.");
+        return;
+    }
+    if (opts.json) {
+        console.info(JSON.stringify({ scorecards, errors, summary: computeSummary(scorecards) }, null, 2));
+        return;
+    }
+    // Text output
+    const summary = computeSummary(scorecards);
+    console.info(`\n📊 Eval Summary`);
+    console.info(`${"─".repeat(50)}`);
+    console.info(`Total evaluations: ${entries.length} (${scorecards.length} scorecards, ${errors.length} errors)`);
+    if (scorecards.length > 0) {
+        console.info(`\nMode breakdown:`);
+        console.info(`  eval:     ${summary.evalCount}`);
+        console.info(`  baseline: ${summary.baselineCount}`);
+        console.info(`\nPer-question pass rates:`);
+        for (const [id, rate] of Object.entries(summary.passRates)) {
+            const bar = "█".repeat(Math.round(rate * 20)) + "░".repeat(20 - Math.round(rate * 20));
+            console.info(`  ${id.padEnd(20)} ${bar} ${(rate * 100).toFixed(0)}%`);
+        }
+        console.info(`\nGraphiti writes: ${summary.totalGraphitiWrites}`);
+        if (summary.evalCount >= 10) {
+            console.info(`\nTrend (last 10 vs previous 10):`);
+            for (const [id, delta] of Object.entries(summary.trend)) {
+                const arrow = delta > 0 ? "↑" : delta < 0 ? "↓" : "→";
+                console.info(`  ${id.padEnd(20)} ${arrow} ${delta > 0 ? "+" : ""}${(delta * 100).toFixed(0)}%`);
+            }
+        }
+    }
+    console.info("");
+}
+function computeSummary(scorecards) {
+    const evalCards = scorecards.filter((s) => s.mode === "eval");
+    const baselineCards = scorecards.filter((s) => s.mode === "baseline");
+    // Pass rates per question
+    const passRates = {};
+    const questionCounts = {};
+    for (const card of scorecards) {
+        for (const q of card.questions) {
+            if (!questionCounts[q.id])
+                questionCounts[q.id] = { pass: 0, total: 0 };
+            questionCounts[q.id].total++;
+            if (q.answer === "yes")
+                questionCounts[q.id].pass++;
+        }
+    }
+    for (const [id, counts] of Object.entries(questionCounts)) {
+        passRates[id] = counts.total > 0 ? counts.pass / counts.total : 0;
+    }
+    // Trend: compare last 10 eval scorecards vs previous 10
+    const trend = {};
+    if (evalCards.length >= 10) {
+        const recent = evalCards.slice(-10);
+        const previous = evalCards.slice(-20, -10);
+        if (previous.length >= 5) {
+            const recentRates = computePassRates(recent);
+            const previousRates = computePassRates(previous);
+            for (const id of Object.keys(recentRates)) {
+                trend[id] = (recentRates[id] ?? 0) - (previousRates[id] ?? 0);
+            }
+        }
+    }
+    return {
+        evalCount: evalCards.length,
+        baselineCount: baselineCards.length,
+        passRates,
+        totalGraphitiWrites: scorecards.reduce((sum, s) => sum + s.graphitiWrites, 0),
+        trend,
+    };
+}
+function computePassRates(cards) {
+    const counts = {};
+    for (const card of cards) {
+        for (const q of card.questions) {
+            if (!counts[q.id])
+                counts[q.id] = { pass: 0, total: 0 };
+            counts[q.id].total++;
+            if (q.answer === "yes")
+                counts[q.id].pass++;
+        }
+    }
+    const rates = {};
+    for (const [id, c] of Object.entries(counts)) {
+        rates[id] = c.total > 0 ? c.pass / c.total : 0;
+    }
+    return rates;
+}
+export async function evalBaseline(projectRoot, opts) {
+    const { execSync, spawnSync } = await import("node:child_process");
+    const { rmSync, writeFileSync } = await import("node:fs");
+    const { basename } = await import("node:path");
+    const taskPath = opts.task;
+    if (!existsSync(taskPath)) {
+        console.error(`Task file not found: ${taskPath}`);
+        process.exit(1);
+    }
+    const { readFileSync } = await import("node:fs");
+    const taskPrompt = readFileSync(taskPath, "utf-8");
+    const taskName = basename(taskPath, ".md").replace(/\s+/g, "-");
+    const worktreePath = join(projectRoot, ".indusk", "eval", "baseline-worktree");
+    console.info("Setting up baseline worktree...");
+    // Create worktree from current HEAD
+    try {
+        execSync(`git worktree add "${worktreePath}" HEAD --detach`, {
+            cwd: projectRoot,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        // Worktree may already exist
+        if (existsSync(worktreePath)) {
+            console.info("Baseline worktree already exists, reusing...");
+        }
+        else {
+            console.error("Failed to create baseline worktree");
+            process.exit(1);
+        }
+    }
+    // Strip the worktree for vanilla agent
+    console.info("Stripping worktree for baseline agent...");
+    const skillsPath = join(worktreePath, ".claude", "skills");
+    if (existsSync(skillsPath)) {
+        rmSync(skillsPath, { recursive: true, force: true });
+    }
+    // Write minimal CLAUDE.md
+    const projectName = basename(projectRoot);
+    writeFileSync(join(worktreePath, "CLAUDE.md"), `# ${projectName}\n\nThis is a software project. No special instructions.\n`);
+    // Write empty .mcp.json
+    writeFileSync(join(worktreePath, ".mcp.json"), JSON.stringify({ mcpServers: {} }, null, 2));
+    console.info(`Running baseline agent with task: ${taskName}...`);
+    // Spawn vanilla claude --print in the baseline worktree
+    const result = spawnSync("claude", ["--print", "--model", "opus", taskPrompt], {
+        cwd: worktreePath,
+        stdio: "inherit",
+        timeout: 10 * 60 * 1000, // 10 minutes
+        env: { ...process.env },
+    });
+    if (result.status !== 0) {
+        console.error(`Baseline agent exited with code ${result.status}`);
+    }
+    // Commit the baseline work
+    console.info("Committing baseline work...");
+    try {
+        execSync("jj new", { cwd: worktreePath, stdio: "pipe" });
+        execSync(`jj describe -m "baseline: ${taskName}"`, { cwd: worktreePath, stdio: "pipe" });
+    }
+    catch {
+        console.info("Note: jj commit may have failed — evaluating current state anyway");
+    }
+    // Run the smart evaluator against the baseline
+    console.info("Running smart evaluator against baseline...");
+    const { runJudgeSync } = await import("../../lib/eval/judge-runner.js");
+    let changeId;
+    try {
+        changeId = execSync("jj log -r @ --no-graph -T change_id", {
+            cwd: worktreePath,
+            encoding: "utf8",
+        }).trim();
+    }
+    catch {
+        changeId = "baseline-unknown";
+    }
+    const evalResult = await runJudgeSync({
+        projectRoot: worktreePath,
+        changeId,
+        transcriptPath: "(baseline — no transcript)",
+        mode: "baseline",
+    });
+    if ("error" in evalResult) {
+        console.error(`Eval failed: ${evalResult.message}`);
+    }
+    else {
+        console.info(`\nBaseline scorecard for ${taskName}:`);
+        console.info(`  Summary: ${evalResult.summary}`);
+        for (const q of evalResult.questions) {
+            const icon = q.answer === "yes" ? "✓" : q.answer === "no" ? "✗" : "~";
+            console.info(`  ${icon} ${q.id}: ${q.finding}`);
+        }
+    }
+    // Cleanup
+    if (!opts.keep) {
+        console.info("Cleaning up baseline worktree...");
+        try {
+            execSync(`git worktree remove "${worktreePath}" --force`, {
+                cwd: projectRoot,
+                stdio: "pipe",
+            });
+        }
+        catch {
+            console.info("Note: worktree cleanup may need manual removal");
+        }
+    }
+    else {
+        console.info(`Baseline worktree kept at: ${worktreePath}`);
+    }
+}

package/dist/bin/commands/init.d.ts

@@ -1,3 +1,4 @@
+export declare function ensureGitignore(projectRoot: string): void;
 export interface InitOptions {
     force?: boolean;
     local?: boolean;

package/dist/bin/commands/init.js

@@ -17,22 +17,34 @@ function run(cmd, options) {
         return "";
     }
 }
-function ensureGitignore(projectRoot) {
+/** Paths that should be gitignored in ALL modes (full + local). */
+const GITIGNORE_ENTRIES = [
+    { comment: "# MCP config (contains auth tokens)", pattern: ".mcp.json" },
+    { comment: "# Session-specific handoff (not project knowledge)", pattern: ".claude/handoff.md" },
+    { comment: "# Semantic graph event log (large, local-only)", pattern: ".indusk/graph/" },
+    { comment: "# Eval results (local-only)", pattern: ".indusk/eval/" },
+    { comment: "# Extension manifests are package-owned; env files contain secrets", pattern: ".indusk/extensions/" },
+];
+const GITIGNORE_MARKER = "# InDusk managed";
+export function ensureGitignore(projectRoot) {
     const gitignorePath = join(projectRoot, ".gitignore");
-    const entries = ["# MCP config (contains auth tokens)", ".mcp.json"];
-    if (existsSync(gitignorePath)) {
-        const content = readFileSync(gitignorePath, "utf-8");
-        if (content.includes(".mcp.json")) {
-            console.info("  skip: .gitignore (.mcp.json already ignored)");
-            return;
-        }
-        writeFileSync(gitignorePath, `${content.trimEnd()}\n\n${entries.join("\n")}\n`);
-        console.info("  updated: .gitignore (added .mcp.json)");
-    }
-    else {
-        writeFileSync(gitignorePath, `${entries.join("\n")}\n`);
-        console.info("  create: .gitignore (with .mcp.json)");
+    const content = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+    // Collect entries that are missing from the current .gitignore
+    const missing = GITIGNORE_ENTRIES.filter((e) => !content.includes(e.pattern));
+    if (missing.length === 0) {
+        console.info("  skip: .gitignore (all InDusk entries present)");
+        return;
     }
+    // Build the block to append
+    const block = [
+        "",
+        GITIGNORE_MARKER,
+        ...missing.flatMap((e) => [e.comment, e.pattern]),
+        "",
+    ].join("\n");
+    writeFileSync(gitignorePath, `${content.trimEnd()}${block}`);
+    const verb = content.length > 0 ? "updated" : "created";
+    console.info(`  ${verb}: .gitignore (added ${missing.map((e) => e.pattern).join(", ")})`);
 }
 function createCgcIgnore(projectRoot) {
     const ignorePath = join(projectRoot, ".cgcignore");

package/dist/bin/commands/update.js

@@ -323,7 +323,11 @@ export async function update(projectRoot) {
     catch {
         console.info("  could not check third-party extensions");
     }
-    // 8. Respect local mode: re-apply overlay, refresh excludes
+    // 8. Ensure .gitignore has all required entries
+    console.info("\n[Git Ignores]\n");
+    const { ensureGitignore } = await import("./init.js");
+    ensureGitignore(projectRoot);
+    // 9. Respect local mode: re-apply overlay, refresh excludes
     const { readConfig } = await import("../../lib/config.js");
     const config = readConfig(projectRoot);
     if (config?.mode === "local") {

package/dist/lib/config.d.ts

@@ -44,12 +44,28 @@ export declare function getConfigPath(projectRoot: string): string;
 export declare function readConfig(projectRoot: string): InduskConfig | null;
 export declare function writeConfig(projectRoot: string, config: InduskConfig): void;
 export declare function getPlanningDir(projectRoot: string): string;
+/**
+ * Sanitize a string into a valid Graphiti group id.
+ *
+ * Graphiti uses RediSearch under the hood, which treats `-` as a token separator.
+ * A query like `chitin-sportsbook` parses as "find chitin, exclude sportsbook" and
+ * fails with `Syntax error at offset N near chitin`. Anything that isn't
+ * `[A-Za-z0-9_]` gets replaced with `_`. Multiple separators collapse to one.
+ *
+ * Examples:
+ *   "chitin-sportsbook" → "chitin_sportsbook"
+ *   "my.cool.project"   → "my_cool_project"
+ *   "@scope/pkg"        → "scope_pkg"
+ *   "indusk_already_ok" → "indusk_already_ok" (no change)
+ */
+export declare function sanitizeGroupId(raw: string): string;
 /**
  * Get the Graphiti group id for project-specific episodes.
  *
  * Resolution order:
- *   1. .indusk/config.json `graphiti.groupId` if set
- *   2. Project directory basename
+ *   1. .indusk/config.json `graphiti.groupId` if set (used as-is, not sanitized —
+ *      explicit overrides are trusted; if you set a hyphenated id, that's on you)
+ *   2. Sanitized project directory basename (`-` → `_`, etc., for RediSearch safety)
  *
  * Use `[getProjectGroupId(root), "shared"]` as the default group_ids list when
  * searching Graphiti — this gives both project-scoped and cross-project knowledge.

package/dist/lib/config.js

@@ -26,12 +26,30 @@ export function getPlanningDir(projectRoot) {
     // Default to new path (will be created by init)
     return newPath;
 }
+/**
+ * Sanitize a string into a valid Graphiti group id.
+ *
+ * Graphiti uses RediSearch under the hood, which treats `-` as a token separator.
+ * A query like `chitin-sportsbook` parses as "find chitin, exclude sportsbook" and
+ * fails with `Syntax error at offset N near chitin`. Anything that isn't
+ * `[A-Za-z0-9_]` gets replaced with `_`. Multiple separators collapse to one.
+ *
+ * Examples:
+ *   "chitin-sportsbook" → "chitin_sportsbook"
+ *   "my.cool.project"   → "my_cool_project"
+ *   "@scope/pkg"        → "scope_pkg"
+ *   "indusk_already_ok" → "indusk_already_ok" (no change)
+ */
+export function sanitizeGroupId(raw) {
+    return raw.replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+}
 /**
  * Get the Graphiti group id for project-specific episodes.
  *
  * Resolution order:
- *   1. .indusk/config.json `graphiti.groupId` if set
- *   2. Project directory basename
+ *   1. .indusk/config.json `graphiti.groupId` if set (used as-is, not sanitized —
+ *      explicit overrides are trusted; if you set a hyphenated id, that's on you)
+ *   2. Sanitized project directory basename (`-` → `_`, etc., for RediSearch safety)
  *
  * Use `[getProjectGroupId(root), "shared"]` as the default group_ids list when
  * searching Graphiti — this gives both project-scoped and cross-project knowledge.
@@ -40,7 +58,7 @@ export function getProjectGroupId(projectRoot) {
     const config = readConfig(projectRoot);
     if (config?.graphiti?.groupId)
         return config.graphiti.groupId;
-    return basename(projectRoot);
+    return sanitizeGroupId(basename(projectRoot));
 }
 /**
  * Whether the OTel gate should fire for this project.

package/dist/lib/eval/judge-runner.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Judge runner — spawns a background `claude --print` process that evaluates
+ * a commit and writes results to the eval log.
+ *
+ * The judge is a detached child process so the calling hook can exit immediately.
+ * Results appear asynchronously in `.indusk/eval/results.log`.
+ */
+import type { EvalErrorEntry, EvalScorecard } from "./types.js";
+export interface JudgeRunOptions {
+    projectRoot: string;
+    changeId: string;
+    transcriptPath: string;
+    mode: "eval" | "baseline";
+    evalEndpoint?: string;
+}
+/**
+ * Run the judge as a detached background process.
+ *
+ * Spawns `claude --print` with the judge prompt and allowed tools whitelist.
+ * Collects stdout, parses the scorecard JSON, and appends to the eval log.
+ * If anything fails, logs an error entry instead of silently dropping.
+ */
+export declare function runJudgeBackground(opts: JudgeRunOptions): void;
+/**
+ * Run the judge synchronously (for testing and manual invocation).
+ * Returns the scorecard or error entry.
+ */
+export declare function runJudgeSync(opts: JudgeRunOptions): Promise<EvalScorecard | EvalErrorEntry>;