@infinitedusky/indusk-mcp 0.6.0 → 0.6.2

package/dist/bin/cli.js

@@ -16,12 +16,14 @@ program
     .option("-f, --force", "Overwrite existing files (except CLAUDE.md and planning/)")
     .option("--skills <list>", "Comma-separated domain skills to install (e.g., nextjs,tailwind)")
     .option("--no-domain-skills", "Skip domain skill detection and installation")
+    .option("--no-index", "Skip code graph indexing")
     .action(async (opts) => {
     const { init } = await import("./commands/init.js");
     await init(process.cwd(), {
         force: opts.force ?? false,
         skills: opts.skills,
         noDomainSkills: opts.domainSkills === false,
+        noIndex: opts.index === false,
     });
 });
 program

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

@@ -2,5 +2,6 @@ export interface InitOptions {
     force?: boolean;
     skills?: string;
     noDomainSkills?: boolean;
+    noIndex?: boolean;
 }
 export declare function init(projectRoot: string, options?: InitOptions): Promise<void>;

package/dist/bin/commands/init.js

@@ -119,7 +119,7 @@ function detectDomainSkills(projectRoot) {
     return detections;
 }
 export async function init(projectRoot, options = {}) {
-    const { force = false, skills, noDomainSkills = false } = options;
+    const { force = false, skills, noDomainSkills = false, noIndex = false } = options;
     const projectName = basename(projectRoot);
     console.info(`Initializing InDusk dev system...${force ? " (--force)" : ""}\n`);
     // 1. Copy skills
@@ -371,7 +371,11 @@ export async function init(projectRoot, options = {}) {
     }
     const cgcInstalled = checkCGC();
     // 9. Auto-index the codebase into the graph
-    if (dockerAvailable && cgcInstalled) {
+    if (noIndex) {
+        console.info("\n[Code Graph]");
+        console.info("  skipped (--no-index)");
+    }
+    else if (dockerAvailable && cgcInstalled) {
         console.info("\n[Code Graph]");
         console.info("  indexing: scanning codebase...");
         const { indexProject } = await import("../../tools/graph-tools.js");

package/hooks/check-gates.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook: blocks phase transitions in impl.md when gates are incomplete.
+ *
+ * Exit 0 = allow the edit
+ * Exit 2 = block the edit (stderr sent to agent as feedback)
+ */
+
+import { readFileSync } from "node:fs";
+
+// Read hook input from stdin
+let input = "";
+for await (const chunk of process.stdin) {
+	input += chunk;
+}
+
+const event = JSON.parse(input);
+const toolInput = event.tool_input ?? {};
+
+// Determine file path based on tool type
+const filePath = toolInput.file_path ?? "";
+
+// Fast path: not an impl.md file
+if (!filePath.endsWith("/impl.md") && !filePath.endsWith("\\impl.md")) {
+	process.exit(0);
+}
+
+// Check for skip-gates escape hatch
+const newContent = toolInput.new_string ?? toolInput.content ?? "";
+if (newContent.includes("<!-- skip-gates -->")) {
+	process.exit(0);
+}
+
+// Detect checkbox transition: - [ ] → - [x]
+const oldContent = toolInput.old_string ?? "";
+
+// For Edit tool: check if old_string has unchecked and new_string has checked
+// For Write tool: we need to compare with the file on disk
+let hasCheckboxTransition = false;
+
+if (event.tool_name === "Edit" && oldContent && newContent) {
+	const oldUnchecked = (oldContent.match(/- \[ \]/g) || []).length;
+	const newUnchecked = (newContent.match(/- \[ \]/g) || []).length;
+	const oldChecked = (oldContent.match(/- \[x\]/g) || []).length;
+	const newChecked = (newContent.match(/- \[x\]/g) || []).length;
+	hasCheckboxTransition = newChecked > oldChecked || newUnchecked < oldUnchecked;
+} else if (event.tool_name === "Write") {
+	// For Write, compare with file on disk
+	try {
+		const diskContent = readFileSync(filePath, "utf-8");
+		const diskChecked = (diskContent.match(/- \[x\]/g) || []).length;
+		const writeChecked = (newContent.match(/- \[x\]/g) || []).length;
+		hasCheckboxTransition = writeChecked > diskChecked;
+	} catch {
+		// File doesn't exist yet — new impl, allow
+		process.exit(0);
+	}
+}
+
+if (!hasCheckboxTransition) {
+	process.exit(0);
+}
+
+// Parse the impl file to understand phase structure
+// Read the full file to get current state, then apply the edit mentally
+let fullContent;
+try {
+	fullContent = readFileSync(filePath, "utf-8");
+} catch {
+	process.exit(0);
+}
+
+// For Edit, apply the edit to get the new full content
+let newFullContent;
+if (event.tool_name === "Edit" && oldContent) {
+	newFullContent = fullContent.replace(oldContent, newContent);
+} else if (event.tool_name === "Write") {
+	newFullContent = newContent;
+} else {
+	process.exit(0);
+}
+
+// Parse phases from the NEW content (after edit) and OLD content (before edit)
+function parsePhases(content) {
+	// Strip frontmatter
+	const fmMatch = content.match(/^---\n[\s\S]*?\n---\n/);
+	const body = fmMatch ? content.slice(fmMatch[0].length) : content;
+
+	const lines = body.split("\n");
+	const phases = [];
+	let currentPhase = null;
+	let currentGateType = "implementation";
+
+	for (const line of lines) {
+		const phaseMatch = line.match(/^###\s+Phase\s+(\d+)[:\s]+(.*)/);
+		if (phaseMatch) {
+			if (currentPhase) phases.push(currentPhase);
+			currentPhase = {
+				number: parseInt(phaseMatch[1], 10),
+				name: phaseMatch[2].trim(),
+				items: [],
+			};
+			currentGateType = "implementation";
+			continue;
+		}
+
+		const gateMatch = line.match(/^####\s+Phase\s+\d+\s+(Verification|Context|Document)\b/);
+		if (gateMatch) {
+			currentGateType = gateMatch[1].toLowerCase();
+			continue;
+		}
+
+		// Forward intelligence — skip
+		if (line.match(/^####\s+Phase\s+\d+\s+Forward Intelligence\b/)) {
+			currentGateType = "_fi";
+			continue;
+		}
+
+		if (currentPhase && currentGateType !== "_fi") {
+			const itemMatch = line.match(/^-\s+\[([ x])\]\s+(.*)/);
+			if (itemMatch) {
+				currentPhase.items.push({
+					checked: itemMatch[1] === "x",
+					text: itemMatch[2].trim(),
+					gate: currentGateType,
+				});
+			}
+		}
+	}
+	if (currentPhase) phases.push(currentPhase);
+	return phases;
+}
+
+const oldPhases = parsePhases(fullContent);
+const newPhases = parsePhases(newFullContent);
+
+// Find which items were just checked (were unchecked before, checked now)
+const newlyChecked = [];
+for (let pi = 0; pi < newPhases.length; pi++) {
+	const newPhase = newPhases[pi];
+	const oldPhase = oldPhases[pi];
+	if (!oldPhase) continue;
+
+	for (let ii = 0; ii < newPhase.items.length; ii++) {
+		const newItem = newPhase.items[ii];
+		const oldItem = oldPhase.items[ii];
+		if (!oldItem) continue;
+
+		if (newItem.checked && !oldItem.checked) {
+			newlyChecked.push({
+				phase: newPhase.number,
+				phaseName: newPhase.name,
+				text: newItem.text,
+				gate: newItem.gate,
+			});
+		}
+	}
+}
+
+if (newlyChecked.length === 0) {
+	process.exit(0);
+}
+
+// For each newly checked item: if it's an implementation item,
+// check that all PREVIOUS phases have complete gates
+for (const item of newlyChecked) {
+	// Checking gate items is always allowed
+	if (item.gate !== "implementation") continue;
+
+	// Check all phases before this item's phase
+	for (const phase of oldPhases) {
+		if (phase.number >= item.phase) break;
+
+		const uncheckedGates = phase.items.filter(
+			(i) =>
+				!i.checked && (i.gate === "verification" || i.gate === "context" || i.gate === "document"),
+		);
+
+		if (uncheckedGates.length > 0) {
+			const missing = uncheckedGates.map((i) => `  [${i.gate}] ${i.text}`).join("\n");
+			process.stderr.write(
+				`Phase ${item.phase} blocked: complete Phase ${phase.number} gates first:\n${missing}\n`,
+			);
+			process.exit(2);
+		}
+	}
+}
+
+// All checks passed
+process.exit(0);

package/hooks/gate-reminder.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook: nudges the agent to call advance_plan when a phase is complete.
+ *
+ * This hook is advisory — it cannot block. It outputs a reminder message
+ * that appears in the conversation as additional context.
+ */
+
+import { readFileSync } from "node:fs";
+
+// Read hook input from stdin
+let input = "";
+for await (const chunk of process.stdin) {
+	input += chunk;
+}
+
+const event = JSON.parse(input);
+const toolInput = event.tool_input ?? {};
+const filePath = toolInput.file_path ?? "";
+
+// Fast path: not an impl.md file
+if (!filePath.endsWith("/impl.md") && !filePath.endsWith("\\impl.md")) {
+	process.exit(0);
+}
+
+// Read the impl file (post-edit state)
+let content;
+try {
+	content = readFileSync(filePath, "utf-8");
+} catch {
+	process.exit(0);
+}
+
+// Parse phases
+function parsePhases(text) {
+	const fmMatch = text.match(/^---\n[\s\S]*?\n---\n/);
+	const body = fmMatch ? text.slice(fmMatch[0].length) : text;
+
+	const lines = body.split("\n");
+	const phases = [];
+	let currentPhase = null;
+	let currentGateType = "implementation";
+
+	for (const line of lines) {
+		const phaseMatch = line.match(/^###\s+Phase\s+(\d+)[:\s]+(.*)/);
+		if (phaseMatch) {
+			if (currentPhase) phases.push(currentPhase);
+			currentPhase = {
+				number: parseInt(phaseMatch[1], 10),
+				name: phaseMatch[2].trim(),
+				items: [],
+			};
+			currentGateType = "implementation";
+			continue;
+		}
+
+		const gateMatch = line.match(/^####\s+Phase\s+\d+\s+(Verification|Context|Document)\b/);
+		if (gateMatch) {
+			currentGateType = gateMatch[1].toLowerCase();
+			continue;
+		}
+
+		if (line.match(/^####\s+Phase\s+\d+\s+Forward Intelligence\b/)) {
+			currentGateType = "_fi";
+			continue;
+		}
+
+		if (currentPhase && currentGateType !== "_fi") {
+			const itemMatch = line.match(/^-\s+\[([ x])\]\s+(.*)/);
+			if (itemMatch) {
+				currentPhase.items.push({
+					checked: itemMatch[1] === "x",
+					gate: currentGateType,
+				});
+			}
+		}
+	}
+	if (currentPhase) phases.push(currentPhase);
+	return phases;
+}
+
+const phases = parsePhases(content);
+
+// Find the first phase that just became fully complete
+// (all items checked, including gates)
+for (const phase of phases) {
+	const allChecked = phase.items.every((i) => i.checked);
+	if (!allChecked) continue;
+
+	// Check if the next phase has any unchecked items (meaning work hasn't started there yet)
+	const nextPhase = phases.find((p) => p.number === phase.number + 1);
+	if (nextPhase) {
+		const nextHasUnchecked = nextPhase.items.some((i) => !i.checked);
+		if (nextHasUnchecked) {
+			// This phase is complete and next phase hasn't started
+			const result = {
+				hookSpecificOutput: {
+					hookEventName: "PostToolUse",
+				},
+			};
+			// Output reminder as JSON to stdout
+			console.log(JSON.stringify(result));
+			console.error(
+				`Phase ${phase.number} (${phase.name}) is fully complete. Call advance_plan to validate gates before starting Phase ${nextPhase.number}.`,
+			);
+			process.exit(0);
+		}
+	}
+}
+
+process.exit(0);

package/lessons/community/community-check-existing-packages.md

@@ -0,0 +1,9 @@
+# Search for official packages before building custom
+
+Before building any integration, SDK wrapper, or utility:
+
+1. Check if an official package exists (npm, PyPI, crates.io)
+2. Check if a well-maintained community package exists
+3. Only build custom if nothing exists AND the need is truly unique
+
+Official implementations are battle-tested, maintained, and handle edge cases you haven't thought of. Custom implementations create tech debt and break in production.

package/lessons/community/community-explicit-errors.md

@@ -0,0 +1,10 @@
+# Let errors propagate visibly
+
+Don't silently swallow errors with empty catch blocks or fallback returns. Every `catch {}` is a future mystery bug.
+
+If you catch an error, either:
+- Re-throw it with context: `throw new Error("Failed to parse config", { cause: err })`
+- Log it meaningfully and return an explicit failure value
+- Handle it completely (not just suppress it)
+
+Silent failures compound. One swallowed error leads to wrong data, which leads to wrong behavior three layers up.

package/lessons/community/community-index-after-setup.md

@@ -0,0 +1,5 @@
+# Auto-index during setup, not as a separate step
+
+When setting up infrastructure that requires indexing, scanning, or initial data loading — do it as part of the setup command, not as a "next step" the user has to remember.
+
+Every manual step between "install" and "working" is a step where someone gets stuck. If the tool needs an index to function, build the index during init.

package/lessons/community/community-no-fallback-values.md

@@ -0,0 +1,7 @@
+# Never use fallback values where a value is expected
+
+When a value should exist, don't provide a default. Let it fail visibly.
+
+`process.env.DATABASE_URL ?? "localhost"` hides the fact that the env var is missing. The app runs, connects to the wrong database, and you debug for an hour.
+
+If a value is required, assert its existence. If it's truly optional, make that explicit in the type.

package/lessons/community/community-no-mock-databases.md

@@ -0,0 +1,12 @@
+# Don't mock the database in integration tests
+
+Mocked tests pass. Production breaks. The mock doesn't know about:
+- Migration changes
+- Constraint violations
+- Query performance
+- Transaction behavior
+- Type coercion differences
+
+Use a real database instance for integration tests. Docker makes this trivial. The extra seconds are worth the confidence.
+
+Unit tests can mock external calls. Integration tests should hit real infrastructure.

package/lessons/community/community-one-concern-per-change.md

@@ -0,0 +1,7 @@
+# One concern per change
+
+Each commit, PR, or change should address one thing. Not two. Not "while I'm in here."
+
+Mixed changes make review harder, reverts riskier, and git blame useless. If you notice something unrelated while working, note it and address it separately.
+
+The exception: if the unrelated fix is a one-line typo or import cleanup in a file you're already changing. Use judgment, but default to separate.

package/lessons/community/community-read-before-edit.md

@@ -0,0 +1,9 @@
+# Read the file before modifying it
+
+Never edit a file you haven't read in this session. You might:
+- Overwrite recent changes
+- Duplicate existing code
+- Contradict patterns already established in the file
+- Miss context that changes your approach
+
+Read first. Understand the current state. Then modify.

package/lessons/community/community-verify-before-commit.md

@@ -0,0 +1,7 @@
+# Always run checks before committing
+
+Run type checks, linting, and tests before every commit. Not after. Not "when you remember."
+
+A broken commit means someone else pulls broken code, or you spend time reverting. The cost of running checks is seconds. The cost of a broken commit is minutes to hours.
+
+If checks are too slow to run before every commit, fix the checks — don't skip them.

package/package.json

@@ -1,12 +1,14 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "0.6.0",
+	"version": "0.6.2",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [
 		"dist",
 		"skills",
 		"templates",
+		"hooks",
+		"lessons",
 		"!dist/**/*.test.*",
 		"!dist/__tests__"
 	],