whygraph 0.1.1 → 0.1.3

package/dist/cli/commands/crossref.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+export interface CrossrefResult {
+    outputPath: string;
+    nodeCount: number;
+    decisionCount: number;
+}
+export declare function runCrossref(targetDir: string): CrossrefResult;
+export declare function registerCrossrefCommand(program: Command): void;

package/dist/cli/commands/crossref.js

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isStructuralNode, isDecisionNode } from "../../entity/types.js";
+import { parseEntity } from "../../entity/parser.js";
+import { findWhygraphDir } from "./serve.js";
+// ============================================================
+// Core Logic
+// ============================================================
+export function runCrossref(targetDir) {
+    const projectDir = findWhygraphDir(targetDir);
+    if (!projectDir) {
+        throw new Error(`.whygraph/ not found. Run "npx whygraph init" first.`);
+    }
+    const graphDir = join(projectDir, ".whygraph", "graph");
+    const entities = loadEntities(graphDir);
+    const nodes = entities.filter(isStructuralNode);
+    const decisions = entities.filter(isDecisionNode);
+    const idToNode = new Map(nodes.map((n) => [n.id, n]));
+    const markdown = buildMarkdown(nodes, decisions, idToNode);
+    const outputPath = join(projectDir, ".whygraph", "CONTEXT.md");
+    writeFileSync(outputPath, markdown, "utf-8");
+    return { outputPath, nodeCount: nodes.length, decisionCount: decisions.length };
+}
+function loadEntities(graphDir) {
+    if (!existsSync(graphDir))
+        return [];
+    return readdirSync(graphDir)
+        .filter((f) => f.endsWith(".md"))
+        .flatMap((file) => {
+        const content = readFileSync(join(graphDir, file), "utf-8");
+        const entity = parseEntity(content);
+        return entity !== null ? [entity] : [];
+    });
+}
+function buildMarkdown(nodes, decisions, idToNode) {
+    const lines = [
+        "# Whygraph Context Snapshot",
+        "",
+        `_Generated: ${new Date().toISOString()}_`,
+        "_This file is auto-generated by `npx whygraph crossref`. Do not edit manually._",
+        "",
+    ];
+    // Structural graph section
+    lines.push("## Graph Structure", "");
+    const apps = nodes.filter((n) => n.label === "App");
+    const features = nodes.filter((n) => n.label === "Feature");
+    const components = nodes.filter((n) => n.label === "Component");
+    for (const app of apps) {
+        lines.push(`- **App** \`${app.id}\` — ${app.name}`);
+        for (const feature of features.filter((f) => f.parent === app.id)) {
+            lines.push(`  - **Feature** \`${feature.id}\` — ${feature.name}`);
+            for (const comp of components.filter((c) => c.parent === feature.id)) {
+                lines.push(`    - **Component** \`${comp.id}\` — ${comp.name}`);
+            }
+        }
+    }
+    // Orphaned features (no matching app)
+    for (const feature of features.filter((f) => !f.parent || !idToNode.has(f.parent))) {
+        lines.push(`- **Feature** \`${feature.id}\` — ${feature.name} _(unlinked)_`);
+        for (const comp of components.filter((c) => c.parent === feature.id)) {
+            lines.push(`  - **Component** \`${comp.id}\` — ${comp.name}`);
+        }
+    }
+    lines.push("");
+    // Decisions section
+    lines.push("## Decisions", "");
+    if (decisions.length === 0) {
+        lines.push("_No decisions recorded yet._", "");
+    }
+    else {
+        for (const d of decisions) {
+            lines.push(`### [${d.id}] ${d.title}`);
+            lines.push("");
+            const affectsLabels = d.affects
+                .map((id) => {
+                const node = idToNode.get(id);
+                return node ? `\`${id}\` (${node.name})` : `\`${id}\``;
+            })
+                .join(", ");
+            lines.push(`- **Status:** ${d.status} | **Date:** ${d.date} | **Tags:** ${d.tags.join(", ")}`);
+            if (d.affects.length > 0) {
+                lines.push(`- **Affects:** ${affectsLabels}`);
+            }
+            /* v8 ignore next 3 */
+            if (d.supersedes) {
+                lines.push(`- **Supersedes:** \`${d.supersedes}\``);
+            }
+            lines.push("");
+            lines.push(`> **Context:** ${d.context}`);
+            lines.push(`> **Decision:** ${d.decision}`);
+            lines.push(`> **Tradeoffs:** ${d.tradeoffs}`);
+            lines.push(`> **Alternatives:** ${d.alternatives}`);
+            lines.push("");
+            lines.push("---");
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}
+// ============================================================
+// CLI Wiring
+// ============================================================
+export function registerCrossrefCommand(program) {
+    program
+        .command("crossref")
+        .description("Generate .whygraph/CONTEXT.md — a graph snapshot for use when MCP is unavailable")
+        .option("--json", "Output results as JSON")
+        .action((opts) => {
+        try {
+            const result = runCrossref(process.cwd());
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                process.stdout.write(`Context snapshot written to ${result.outputPath}\n` +
+                    `  Nodes: ${result.nodeCount}\n` +
+                    `  Decisions: ${result.decisionCount}\n`);
+            }
+        }
+        catch (err) {
+            /* v8 ignore next 1 */
+            const message = err instanceof Error ? err.message : String(err);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ error: message }, null, 2) + "\n");
+            }
+            else {
+                process.stderr.write(`Error: ${message}\n`);
+            }
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import { Command } from "commander";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 import { registerConfigCommand } from "./commands/config.js";
+import { registerCrossrefCommand } from "./commands/crossref.js";
 import { registerDownCommand } from "./commands/down.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerIssuesCommand } from "./commands/issues.js";
@@ -21,6 +22,7 @@ program
     .description("The graph of why — so your agent knows before it touches anything.")
     .version(version);
 registerConfigCommand(program);
+registerCrossrefCommand(program);
 registerDownCommand(program);
 registerInitCommand(program);
 registerIssuesCommand(program);

package/dist/platform/rules.js

@@ -59,10 +59,23 @@ function generateInstructions(config) {
         "",
         `Allowed tags: ${tagList}`,
         "",
-        "### MCP Server",
+        "### MCP Server (preferred)",
         "",
-        `Use the \`whygraph\` MCP server for decision capture tools.`,
-        "If the server is unreachable, write decision files directly to `.whygraph/graph/`.",
+        `Use the \`whygraph\` MCP server for decision capture tools when available.`,
+        `- \`whygraph_context\` — get existing decisions and structural nodes for a file`,
+        `- \`whygraph_create_decision\` — capture a new decision`,
+        "",
+        "### Direct File Access (fallback)",
+        "",
+        "If the MCP server is unreachable or MCP is blocked by your environment:",
+        "",
+        "**For context:** Read `.whygraph/CONTEXT.md` if it exists — this is a pre-built",
+        "graph snapshot generated by `npx whygraph crossref`. It lists all structural nodes",
+        "and decisions with their `affects` cross-references. If the file is absent, ask",
+        "the user to run `npx whygraph crossref` to generate it.",
+        "",
+        "**For capture:** Write the decision file directly to `.whygraph/graph/`",
+        "using the format above. It will be picked up automatically on next server start.",
         "",
         "### Server Status",
         "",
@@ -89,7 +102,7 @@ function upsertMarkedSection(existing, content) {
 // ============================================================
 function registerMcpWithClaude(projectDir) {
     try {
-        execSync("claude mcp add --scope project whygraph -- whygraph mcp", {
+        execSync("claude mcp add --scope project whygraph -- npx whygraph mcp", {
             cwd: projectDir,
             stdio: "ignore",
         });
@@ -106,7 +119,7 @@ function registerMcpWithClaude(projectDir) {
             }
             const servers = (mcpJson.mcpServers ?? {});
             if (!servers.whygraph) {
-                servers.whygraph = { type: "stdio", command: "whygraph", args: ["mcp"] };
+                servers.whygraph = { type: "stdio", command: "npx", args: ["whygraph", "mcp"] };
                 mcpJson.mcpServers = servers;
                 writeFileSync(mcpJsonPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf-8");
             }
@@ -129,7 +142,7 @@ function registerMcpWithCursor(projectDir) {
         }
         const servers = (mcp.mcpServers ?? {});
         if (!servers.whygraph) {
-            servers.whygraph = { command: "whygraph", args: ["mcp"] };
+            servers.whygraph = { command: "npx", args: ["whygraph", "mcp"] };
             mcp.mcpServers = servers;
             writeFileSync(mcpPath, JSON.stringify(mcp, null, 2) + "\n", "utf-8");
         }
@@ -150,7 +163,7 @@ function registerMcpWithCopilot(projectDir) {
         }
         const servers = (mcp.servers ?? {});
         if (!servers.whygraph) {
-            servers.whygraph = { type: "stdio", command: "whygraph", args: ["mcp"] };
+            servers.whygraph = { type: "stdio", command: "npx", args: ["whygraph", "mcp"] };
             mcp.servers = servers;
             writeFileSync(mcpPath, JSON.stringify(mcp, null, 2) + "\n", "utf-8");
         }
@@ -167,16 +180,16 @@ function writeMcpSetupMd(projectDir, environment) {
     const lines = ["# Whygraph MCP Setup", ""];
     switch (environment) {
         case "claude-code":
-            lines.push("Run the following command in your project root:", "", "```bash", "claude mcp add --scope project whygraph -- whygraph mcp", "```");
+            lines.push("Run the following command in your project root:", "", "```bash", "claude mcp add --scope project whygraph -- npx whygraph mcp", "```");
             break;
         case "cursor":
-            lines.push("Add the following to `.cursor/mcp.json` in your project root:", "", "```json", JSON.stringify({ mcpServers: { whygraph: { command: "whygraph", args: ["mcp"] } } }, null, 2), "```");
+            lines.push("Add the following to `.cursor/mcp.json` in your project root:", "", "```json", JSON.stringify({ mcpServers: { whygraph: { command: "npx", args: ["whygraph", "mcp"] } } }, null, 2), "```");
             break;
         case "copilot":
-            lines.push("Add the following to `.vscode/mcp.json` in your project root:", "", "```json", JSON.stringify({ servers: { whygraph: { type: "stdio", command: "whygraph", args: ["mcp"] } } }, null, 2), "```");
+            lines.push("Add the following to `.vscode/mcp.json` in your project root:", "", "```json", JSON.stringify({ servers: { whygraph: { type: "stdio", command: "npx", args: ["whygraph", "mcp"] } } }, null, 2), "```");
             break;
         default:
-            lines.push("Add the whygraph MCP server to your AI assistant's MCP configuration.", "", "**Command:** `whygraph mcp`", "**Transport:** stdio", "", "Refer to your AI assistant's documentation for how to register MCP servers.");
+            lines.push("Add the whygraph MCP server to your AI assistant's MCP configuration.", "", "**Command:** `npx whygraph mcp`", "**Transport:** stdio", "", "Refer to your AI assistant's documentation for how to register MCP servers.");
     }
     writeFileSync(filePath, lines.join("\n") + "\n", "utf-8");
     return filePath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whygraph",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The graph of why. So your agent knows before it touches anything.",
   "author": "Geovanie Ruiz",
   "license": "MIT",