whygraph 0.1.0 → 0.1.2

package/dist/cli/commands/init.js

@@ -126,7 +126,8 @@ export function registerInitCommand(program) {
                     `  App node: ${result.appId}\n` +
                     `  Config: ${result.configPath}\n` +
                     mcpLine +
-                    `\nRun 'whygraph up' to start the server.\n`);
+                    `\nRun 'npx whygraph up' to start the server.\n` +
+                    `Run 'npx whygraph onboard' to get a prompt for building your graph.\n`);
             }
         }
         catch (err) {

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

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+export interface OnboardResult {
+    appId: string;
+    appName: string;
+    prefix: string;
+    prompt: string;
+}
+export declare function runOnboard(targetDir: string): OnboardResult;
+export declare function registerOnboardCommand(program: Command): void;

package/dist/cli/commands/onboard.js

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import { parseEntity } from "../../entity/parser.js";
+import { findWhygraphDir } from "./serve.js";
+// ============================================================
+// Core Logic
+// ============================================================
+export function runOnboard(targetDir) {
+    const projectDir = findWhygraphDir(targetDir);
+    if (!projectDir) {
+        throw new Error(`.whygraph/ not found. Run "npx whygraph init" first.`);
+    }
+    const configPath = join(projectDir, ".whygraph", "config.yaml");
+    if (!existsSync(configPath)) {
+        throw new Error(`.whygraph/config.yaml not found. Run "npx whygraph init" first.`);
+    }
+    const raw = readFileSync(configPath, "utf-8");
+    const config = yaml.load(raw);
+    // Find the App node
+    const graphDir = join(projectDir, ".whygraph", "graph");
+    let appId = "";
+    let appName = config.appName;
+    if (existsSync(graphDir)) {
+        const files = readdirSync(graphDir).filter((f) => f.endsWith(".md"));
+        for (const file of files) {
+            const content = readFileSync(join(graphDir, file), "utf-8");
+            const entity = parseEntity(content);
+            if (entity !== null && entity.label === "App") {
+                appId = entity.id;
+                /* v8 ignore next 1 */
+                if ("name" in entity)
+                    appName = entity.name;
+                break;
+            }
+        }
+    }
+    if (!appId) {
+        throw new Error(`No App node found in .whygraph/graph/. Run "npx whygraph init" first.`);
+    }
+    const prompt = buildOnboardingPrompt(appName, appId, config.prefix);
+    return { appId, appName, prefix: config.prefix, prompt };
+}
+function buildOnboardingPrompt(appName, appId, prefix) {
+    return [
+        `I'm using whygraph to maintain a living decision graph for ${appName}.`,
+        `The root App node is \`${appId}\`.`,
+        ``,
+        `Please explore this codebase and build out the structural graph by:`,
+        ``,
+        `1. Identifying the top-level features or modules (e.g. authentication, data pipeline, API layer, UI pages).`,
+        `   For each one, create a Feature node using the whygraph MCP tool \`whygraph_create_node\`:`,
+        `   - label: Feature`,
+        `   - parent: ${appId}`,
+        `   - name: <feature name>`,
+        `   - status: active`,
+        ``,
+        `2. For each Feature, identify its key components (e.g. services, hooks, controllers, presenters).`,
+        `   For each one, create a Component node:`,
+        `   - label: Component`,
+        `   - parent: <feature id>`,
+        `   - name: <component name>`,
+        `   - status: active`,
+        ``,
+        `3. Use the \`refs\` field to link nodes to their source files where relevant.`,
+        ``,
+        `4. After building the structural graph, review the existing decisions in .whygraph/graph/ and`,
+        `   update their \`affects\` fields to link them to the relevant Feature or Component nodes you created.`,
+        ``,
+        `Node IDs should use the prefix \`${prefix}\` followed by a 4-character nanoid (e.g. \`${prefix}abcd\`).`,
+        ``,
+        `Start by listing the top-level directories and key entry points, then propose the Feature list`,
+        `before creating any nodes. I'll confirm before you proceed.`,
+    ].join("\n");
+}
+// ============================================================
+// CLI Wiring
+// ============================================================
+export function registerOnboardCommand(program) {
+    program
+        .command("onboard")
+        .description("Print a codebase analysis prompt to bootstrap your whygraph graph")
+        .option("--json", "Output results as JSON")
+        .action((opts) => {
+        try {
+            const result = runOnboard(process.cwd());
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                process.stdout.write(`Paste the following prompt into your AI agent:\n\n` +
+                    `${"─".repeat(60)}\n` +
+                    `${result.prompt}\n` +
+                    `${"─".repeat(60)}\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

@@ -8,6 +8,7 @@ import { registerDownCommand } from "./commands/down.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerIssuesCommand } from "./commands/issues.js";
 import { registerMcpCommand } from "./commands/mcp.js";
+import { registerOnboardCommand } from "./commands/onboard.js";
 import { registerRestartCommand } from "./commands/restart.js";
 import { registerServeCommand } from "./commands/serve.js";
 import { registerStatusCommand } from "./commands/status.js";
@@ -24,6 +25,7 @@ registerDownCommand(program);
 registerInitCommand(program);
 registerIssuesCommand(program);
 registerMcpCommand(program);
+registerOnboardCommand(program);
 registerRestartCommand(program);
 registerServeCommand(program);
 registerStatusCommand(program);

package/dist/platform/rules.js

@@ -59,15 +59,20 @@ 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.`,
+        "",
+        "### Direct File Write (fallback)",
+        "",
+        "If the MCP server is unreachable or MCP is blocked by your environment,",
+        "write the decision file directly to `.whygraph/graph/` using the format above.",
+        "The file will be picked up automatically on next server start.",
         "",
         "### Server Status",
         "",
-        "Run `whygraph status` to check if the server is running.",
-        "Run `whygraph up` to start the server.",
+        "Run `npx whygraph status` to check if the server is running.",
+        "Run `npx whygraph up` to start the server.",
         "",
     ].join("\n");
 }
@@ -89,7 +94,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 +111,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 +134,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 +155,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 +172,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;
@@ -197,7 +202,7 @@ export function writePlatformRules(projectDir, environment, _primeOutput, config
         case "copilot": {
             const mcpRegistered = registerMcpWithCopilot(projectDir);
             const mcpSetupPath = mcpRegistered ? undefined : writeMcpSetupMd(projectDir, environment);
-            return { ...writeAgentsMd(projectDir, instructions, environment), mcpRegistered, mcpSetupPath };
+            return { ...writeCopilotInstructions(projectDir, instructions), mcpRegistered, mcpSetupPath };
         }
         case "other": {
             const mcpSetupPath = writeMcpSetupMd(projectDir, environment);
@@ -227,3 +232,17 @@ function writeAgentsMd(projectDir, instructions, environment) {
     writeFileSync(filePath, newContent, "utf-8");
     return { environment, filePath };
 }
+function writeCopilotInstructions(projectDir, instructions) {
+    const githubDir = join(projectDir, ".github");
+    if (!existsSync(githubDir)) {
+        mkdirSync(githubDir, { recursive: true });
+    }
+    const filePath = join(githubDir, "copilot-instructions.md");
+    let existing = "";
+    if (existsSync(filePath)) {
+        existing = readFileSync(filePath, "utf-8");
+    }
+    const newContent = upsertMarkedSection(existing, instructions);
+    writeFileSync(filePath, newContent, "utf-8");
+    return { environment: "copilot", filePath };
+}

package/package.json

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