@infinitedusky/indusk-mcp 1.1.1 → 1.1.3

package/dist/bin/commands/init.js

@@ -176,7 +176,12 @@ export async function init(projectRoot, options = {}) {
     console.info("\n[Hooks]");
     const hooksSource = join(packageRoot, "hooks");
     const hooksTarget = join(projectRoot, ".claude/hooks");
-    const hookFiles = ["check-gates.js", "gate-reminder.js", "validate-impl-structure.js"];
+    const hookFiles = [
+        "check-gates.js",
+        "gate-reminder.js",
+        "validate-impl-structure.js",
+        "check-catchup.js",
+    ];
     if (existsSync(hooksSource)) {
         mkdirSync(hooksTarget, { recursive: true });
         for (const file of hookFiles) {
@@ -202,6 +207,7 @@ export async function init(projectRoot, options = {}) {
                 hooks: [
                     { type: "command", command: "node .claude/hooks/check-gates.js" },
                     { type: "command", command: "node .claude/hooks/validate-impl-structure.js" },
+                    { type: "command", command: "node .claude/hooks/check-catchup.js" },
                 ],
             },
         ],
@@ -221,7 +227,8 @@ export async function init(projectRoot, options = {}) {
             // Check if our hook is already present
             const hasOurHook = existingEntries.some((e) => e.hooks?.some((h) => h.command?.includes("check-gates") ||
                 h.command?.includes("gate-reminder") ||
-                h.command?.includes("validate-impl")));
+                h.command?.includes("validate-impl") ||
+                h.command?.includes("check-catchup")));
             if (!hasOurHook || force) {
                 // Remove old entries if force, then add
                 if (force) {

package/dist/tools/graph-tools.js

@@ -6,22 +6,58 @@ function cgcPath() {
     const paths = [join(process.env.HOME ?? "", ".local/bin/cgc"), "/usr/local/bin/cgc"];
     return paths.find((p) => existsSync(p)) ?? null;
 }
-function runCgc(args, projectRoot) {
+function getFalkorHost() {
+    if (process.env.FALKORDB_HOST)
+        return process.env.FALKORDB_HOST;
+    // Try OrbStack hostname first, fall back to localhost
+    try {
+        execSync("ping -c 1 -W 1 falkordb.orb.local", {
+            stdio: ["ignore", "ignore", "ignore"],
+            timeout: 2000,
+        });
+        return "falkordb.orb.local";
+    }
+    catch {
+        return "localhost";
+    }
+}
+function checkFalkorConnection(host) {
+    try {
+        // Fast TCP check — try to connect to Redis port
+        execSync(`node -e "const s=require('net').connect(6379,'${host}');s.setTimeout(2000);s.on('connect',()=>{s.end();process.exit(0)});s.on('error',()=>process.exit(1));s.on('timeout',()=>process.exit(1))"`, { timeout: 3000, stdio: ["ignore", "ignore", "ignore"] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function runCgc(args, projectRoot, options) {
     const cgc = cgcPath();
     if (!cgc) {
         return JSON.stringify({ error: "CGC not installed — run: pipx install codegraphcontext" });
     }
+    const host = getFalkorHost();
+    const timeout = options?.timeout ?? 15000;
+    // Fast pre-check: is FalkorDB reachable?
+    if (!options?.skipConnectionCheck && !checkFalkorConnection(host)) {
+        return JSON.stringify({
+            error: `FalkorDB not reachable at ${host}:6379. Is the container running? Try: docker start falkordb`,
+            host,
+            suggestion: host === "localhost"
+                ? "OrbStack not detected. If using OrbStack, ensure it's running."
+                : "Try: docker start falkordb — or check if OrbStack is running.",
+        });
+    }
     try {
         return execSync(`${cgc} ${args}`, {
             encoding: "utf-8",
-            timeout: 60000,
+            timeout,
             stdio: ["ignore", "pipe", "pipe"],
             cwd: projectRoot,
             env: {
                 ...process.env,
                 DATABASE_TYPE: "falkordb-remote",
-                FALKORDB_HOST: process.env.FALKORDB_HOST ?? "falkordb.orb.local",
-                FALKORDB_PORT: process.env.FALKORDB_PORT ?? "6379",
+                FALKORDB_HOST: host,
                 FALKORDB_GRAPH_NAME: process.env.FALKORDB_GRAPH_NAME ?? basename(projectRoot),
             },
         }).trim();
@@ -38,10 +74,16 @@ export function indexProject(projectRoot) {
     if (!cgc) {
         return { success: false, output: "CGC not installed — run: pipx install codegraphcontext" };
     }
+    const host = getFalkorHost();
+    if (!checkFalkorConnection(host)) {
+        return {
+            success: false,
+            output: `FalkorDB not reachable at ${host}:6379. Is the container running? Try: docker start falkordb`,
+        };
+    }
     const graphName = process.env.FALKORDB_GRAPH_NAME ?? basename(projectRoot);
+    const hasIgnore = existsSync(join(projectRoot, ".cgcignore"));
     try {
-        // Check if .cgcignore exists
-        const hasIgnore = existsSync(join(projectRoot, ".cgcignore"));
         const output = execSync(`${cgc} index ${projectRoot}`, {
             encoding: "utf-8",
             timeout: 120000,
@@ -49,8 +91,7 @@ export function indexProject(projectRoot) {
             env: {
                 ...process.env,
                 DATABASE_TYPE: "falkordb-remote",
-                FALKORDB_HOST: process.env.FALKORDB_HOST ?? "falkordb.orb.local",
-                FALKORDB_PORT: process.env.FALKORDB_PORT ?? "6379",
+                FALKORDB_HOST: host,
                 FALKORDB_GRAPH_NAME: graphName,
             },
         }).trim();
@@ -268,4 +309,141 @@ export function registerGraphTools(server, projectRoot) {
             content: [{ type: "text", text: output }],
         };
     });
+    server.registerTool("graph_ensure", {
+        description: "Validate and fix the entire code graph stack: FalkorDB container, CGC connection, repo indexing. Call this during catchup or when graph tools fail. Attempts auto-repair for common issues.",
+    }, async () => {
+        const steps = [];
+        // 1. Check CGC installed
+        const cgc = cgcPath();
+        if (!cgc) {
+            steps.push({
+                step: "cgc-installed",
+                status: "error",
+                detail: "CGC not installed — run: pipx install codegraphcontext",
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ steps }, null, 2) }],
+                isError: true,
+            };
+        }
+        steps.push({ step: "cgc-installed", status: "ok", detail: cgc });
+        // 2. Check FalkorDB container exists and is running
+        try {
+            const status = execSync("docker ps --filter name=falkordb --format '{{.Status}}'", {
+                encoding: "utf-8",
+                timeout: 5000,
+                stdio: ["ignore", "pipe", "pipe"],
+            }).trim();
+            if (status) {
+                steps.push({ step: "falkordb-container", status: "ok", detail: status });
+            }
+            else {
+                // Container exists but not running — try to start
+                try {
+                    execSync("docker start falkordb", {
+                        timeout: 10000,
+                        stdio: ["ignore", "pipe", "pipe"],
+                    });
+                    steps.push({
+                        step: "falkordb-container",
+                        status: "fixed",
+                        detail: "Started existing container",
+                    });
+                }
+                catch {
+                    // Container doesn't exist — create it
+                    try {
+                        execSync("docker run -d --name falkordb --restart unless-stopped -v falkordb-global:/var/lib/falkordb/data falkordb/falkordb:latest", { timeout: 30000, stdio: ["ignore", "pipe", "pipe"] });
+                        steps.push({
+                            step: "falkordb-container",
+                            status: "fixed",
+                            detail: "Created new container",
+                        });
+                    }
+                    catch (e) {
+                        const err = e;
+                        steps.push({
+                            step: "falkordb-container",
+                            status: "error",
+                            detail: err.message ?? "Failed to create container",
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            steps.push({
+                step: "falkordb-container",
+                status: "error",
+                detail: "Docker not available — is OrbStack running?",
+            });
+        }
+        // 3. Check connectivity
+        const host = getFalkorHost();
+        if (checkFalkorConnection(host)) {
+            steps.push({
+                step: "falkordb-connection",
+                status: "ok",
+                detail: `Connected to ${host}:6379`,
+            });
+        }
+        else {
+            // Wait a moment if we just started the container
+            const justStarted = steps.some((s) => s.step === "falkordb-container" && s.status === "fixed");
+            if (justStarted) {
+                await new Promise((r) => setTimeout(r, 3000));
+                if (checkFalkorConnection(host)) {
+                    steps.push({
+                        step: "falkordb-connection",
+                        status: "ok",
+                        detail: `Connected to ${host}:6379 (after wait)`,
+                    });
+                }
+                else {
+                    steps.push({
+                        step: "falkordb-connection",
+                        status: "error",
+                        detail: `Cannot connect to ${host}:6379`,
+                    });
+                }
+            }
+            else {
+                steps.push({
+                    step: "falkordb-connection",
+                    status: "error",
+                    detail: `Cannot connect to ${host}:6379`,
+                });
+            }
+        }
+        // 4. Check if repo is indexed
+        if (steps.every((s) => s.status !== "error")) {
+            const listOutput = runCgc("list", projectRoot, { skipConnectionCheck: true });
+            if (listOutput.includes(projectRoot) || listOutput.includes(basename(projectRoot))) {
+                steps.push({ step: "repo-indexed", status: "ok", detail: "Repository is indexed" });
+            }
+            else {
+                steps.push({
+                    step: "repo-indexed",
+                    status: "error",
+                    detail: "Repository not indexed — call index_project to index",
+                });
+            }
+        }
+        const hasErrors = steps.some((s) => s.status === "error");
+        const hasFixed = steps.some((s) => s.status === "fixed");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        healthy: !hasErrors,
+                        autoRepaired: hasFixed,
+                        host,
+                        steps,
+                    }, null, 2),
+                },
+            ],
+            isError: hasErrors,
+        };
+    });
 }

package/extensions/falkordb/manifest.json

@@ -6,6 +6,10 @@
 			{
 				"name": "falkordb-container",
 				"command": "docker ps --filter name=falkordb --format '{{.Status}}'"
+			},
+			{
+				"name": "falkordb-connection",
+				"command": "node -e \"const s=require('net').connect(6379,process.env.FALKORDB_HOST||'falkordb.orb.local');s.setTimeout(3000);s.on('connect',()=>{console.log('connected');s.end();process.exit(0)});s.on('error',e=>{console.error(e.message);process.exit(1)});s.on('timeout',()=>{console.error('timeout');process.exit(1)})\""
 			}
 		],
 		"env_vars": {

package/hooks/check-catchup.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook: blocks Edit/Write on project files until /catchup is complete.
+ *
+ * Reads .claude/handoff.md and checks that all Catchup Status boxes are checked.
+ * Allows edits TO the handoff file itself (so catchup can check off boxes).
+ * Allows edits if no handoff file exists (first session, no enforcement).
+ *
+ * Exit 0 = allow
+ * Exit 2 = block (stderr sent to agent)
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8"));
+const toolInput = input.tool_input ?? {};
+const filePath = toolInput.file_path ?? "";
+
+// Find project root by looking for .claude/ directory
+function findProjectRoot() {
+	let dir = process.cwd();
+	for (let i = 0; i < 10; i++) {
+		if (existsSync(join(dir, ".claude"))) return dir;
+		const parent = resolve(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return process.cwd();
+}
+
+const projectRoot = findProjectRoot();
+const handoffPath = join(projectRoot, ".claude", "handoff.md");
+
+// Allow if no handoff exists (first session or handoff not yet created)
+if (!existsSync(handoffPath)) {
+	process.exit(0);
+}
+
+// Always allow edits to the handoff file itself (catchup needs to check boxes)
+if (filePath.endsWith("handoff.md")) {
+	process.exit(0);
+}
+
+// Read the handoff and check catchup status
+const content = readFileSync(handoffPath, "utf-8");
+
+// Look for the Catchup Status section
+const statusMatch = content.match(/## Catchup Status\n([\s\S]*?)(?:\n##|\n$|$)/);
+if (!statusMatch) {
+	// No catchup status section — allow (handoff was written before this feature)
+	process.exit(0);
+}
+
+const statusSection = statusMatch[1];
+const unchecked = [];
+const checkboxes = statusSection.matchAll(/- \[( |x)\] (\w+)/g);
+
+for (const match of checkboxes) {
+	if (match[1] === " ") {
+		unchecked.push(match[2]);
+	}
+}
+
+if (unchecked.length === 0) {
+	// All boxes checked — catchup is complete
+	process.exit(0);
+}
+
+// Block the edit
+process.stderr.write(
+	`Catchup incomplete. Run /catchup before editing project files.\n` +
+		`Missing steps: ${unchecked.join(", ")}\n` +
+		`The handoff file (.claude/handoff.md) has unchecked catchup boxes. ` +
+		`Complete each /catchup step to check them off.`,
+);
+process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.1.1",
+	"version": "1.1.3",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/catchup.md

@@ -16,14 +16,20 @@ Check if `.claude/handoff.md` exists. If it does, read it first — this is the
 
 If the handoff exists, present a brief summary to the user: "Last session was working on X, stopped at Y. Ready to pick up there?"
 
-If no handoff exists, skip to step 2.
+**After reading, edit the handoff to check off:** `- [x] handoff`
+
+If no handoff exists, create one with all catchup status boxes unchecked, then check off handoff.
 
 ### 2. Read Lessons
 Call `list_lessons`. Read every lesson. These are rules learned from past mistakes — not suggestions. Internalize them before touching any code.
 
+**After reading, edit the handoff to check off:** `- [x] lessons`
+
 ### 3. Check Infrastructure
 Call `check_health`. Verify FalkorDB and CGC are running. If unhealthy, tell the user what's down and how to fix it.
 
+**After checking, edit the handoff to check off:** `- [x] health`
+
 ### 4. Read Project Context
 Call `get_context` to read CLAUDE.md. This contains:
 - **Architecture** — what the project is, how it's structured
@@ -34,12 +40,16 @@ Call `get_context` to read CLAUDE.md. This contains:
 
 Read it fully. Don't skim.
 
+**After reading, edit the handoff to check off:** `- [x] context`
+
 ### 5. Check Active Plans
 Call `list_plans`. This shows every plan and its status. Pay attention to:
 - Plans with status `in-progress` — these are actively being worked on
 - The current phase of each active plan — this is where `/work` will pick up
 - Dependencies between plans — don't start a blocked plan
 
+**After checking, edit the handoff to check off:** `- [x] plans`
+
 ### 6. Review Skills and Extensions
 Call `extensions_status` to see what extensions are enabled and their capabilities.
 
@@ -51,8 +61,12 @@ Then read all installed skill files in `.claude/skills/*/SKILL.md`. These define
 
 Understand what each skill does and when to use it. You should be able to answer: "What slash commands are available and what do they do?"
 
+**After reviewing, edit the handoff to check off:** `- [x] skills` and `- [x] extensions`
+
 ### 7. Check Code Graph
-Call `get_repository_stats` to understand the codebase size and structure. This gives you a sense of what's indexed and queryable. If it fails, the CGC extension may not be enabled or FalkorDB may be down — check_health will have flagged this.
+Call `graph_ensure` to validate the entire code graph stack: FalkorDB container, CGC connection, repo indexing. This tool auto-repairs common issues (starts stopped containers, detects the right host). If it reports errors it couldn't fix, tell the user what's wrong and how to fix it. If the repo isn't indexed, call `index_project`.
+
+**After checking, edit the handoff to check off:** `- [x] graph`
 
 ### 8. Summarize
 

package/skills/handoff.md

@@ -32,6 +32,16 @@ Create or overwrite `.claude/handoff.md` with:
 
 ## Watch Out For
 {Gotchas the next agent should know. "The FalkorDB graph needs reindexing." "The hooks aren't published yet — version 1.0.3 has them." "Don't touch init.ts until the extension system PR is merged."}
+
+## Catchup Status
+- [ ] handoff
+- [ ] lessons
+- [ ] skills
+- [ ] health
+- [ ] context
+- [ ] plans
+- [ ] extensions
+- [ ] graph
 ```
 
 ## When to Write a Handoff
@@ -48,3 +58,4 @@ Create or overwrite `.claude/handoff.md` with:
 - **Decisions that aren't saved anywhere else MUST go here.** They'll be lost otherwise.
 - **Overwrite the previous handoff.** There's only one — the most recent session's. Old handoffs are consumed by /catchup and don't need to persist.
 - **Keep it short.** This isn't a retrospective. It's a sticky note for the next person.
+- **Always include the Catchup Status section** with all boxes unchecked. This is enforced by a hook — the next session cannot edit or write code until `/catchup` checks off every box. Each step in catchup marks its box when completed.