whygraph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geovanie Ruiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# Whygraph
+
+**The graph of why. So your agent knows before it touches anything.**
+
+[![npm version](https://img.shields.io/npm/v/whygraph)](https://www.npmjs.com/package/whygraph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen)]()
+
+> Whygraph captures the architectural decisions behind your codebase — the tradeoffs accepted, the alternatives rejected, the patterns you deliberately chose — and makes them queryable by AI agents before they write a single line.
+
+![Whygraph visualization](https://raw.githubusercontent.com/geovanie-ruiz/whygraph/main/docs/whygraph.png)
+
+---
+
+## The Problem
+
+You're vibe-coding. The agent is fast. Features ship in minutes. Then three sessions later, it confidently rebuilds something you already tried and abandoned. It re-introduces the pattern you explicitly rejected. It optimizes for the local signal — passing tests, satisfying the prompt — while losing the thread of why the architecture is shaped the way it is.
+
+This isn't a hallucination problem. **It's a memory problem.** The agent isn't wrong. It just doesn't know the why.
+
+---
+
+## Quickstart
+
+```bash
+npm install --save-dev whygraph
+npx whygraph init
+npx whygraph up
+```
+
+`init` walks you through two prompts — app name and environment — then registers the MCP server and writes agent instructions to `CLAUDE.md` (Claude Code) or `AGENTS.md` (Cursor, Copilot, other).
+
+```text
+Initialized whygraph in .whygraph/
+  App node: wg-ab12
+  Config: /your/project/.whygraph/config.yaml
+  MCP: registered
+
+Run 'whygraph up' to start the server.
+```
+
+`up` starts the server in the background:
+
+```text
+whygraph server running at http://localhost:4777 (pid 12345)
+```
+
+From here, agents capture decisions automatically as they work. Run `whygraph viz` to open the graph visualization.
+
+---
+
+## What Agents See
+
+When an agent is about to modify `src/auth/session.ts`, it calls `whygraph_context` and gets back the decisions that shaped that code:
+
+```json
+{
+  "nodes": [
+    { "id": "wg-sess", "label": "Component", "name": "Session Management" }
+  ],
+  "decisions": [
+    {
+      "id": "wg-d001",
+      "title": "JWT over server-side sessions",
+      "status": "active",
+      "context": "Needed stateless auth to support horizontal scaling...",
+      "decision": "Use short-lived JWTs with silent refresh via interceptor.",
+      "tradeoffs": "Gained: stateless, horizontally scalable. Lost: cannot invalidate tokens server-side.",
+      "alternatives": "Server-side sessions — rejected: requires sticky sessions or shared store."
+    }
+  ]
+}
+```
+
+The agent knows what was decided, why, what was traded away, and what was rejected — before it touches anything.
+
+---
+
+## MCP Tools
+
+Whygraph exposes six MCP tools for agent integration. Read tools are always available. Write tools require strict mode (`whygraph config --mcp-mode strict`).
+
+| Tool                              | Mode  | Description                                             |
+| --------------------------------- | ----- | ------------------------------------------------------- |
+| `whygraph_context(file, symbol?)` | read  | Get decisions affecting the code you're about to modify |
+| `whygraph_get_decisions(filters)` | read  | Query decisions by status, tags, or date range          |
+| `whygraph_get_gaps(limit?)`       | read  | Find structural nodes with no recorded decisions        |
+| `whygraph_list_nodes(filters)`    | read  | List app, feature, and component nodes                  |
+| `whygraph_create_decision(...)`   | write | Create a decision with full validation                  |
+| `whygraph_create_node(...)`       | write | Create a structural node                                |
+
+In default mode, write tools are not registered. Agents write decision files directly to `.whygraph/graph/` as markdown. The file watcher picks them up, validates, and flags issues as JSON sidecars that the `whygraph issues` command can resolve.
+
+---
+
+## Platform Integration
+
+Whygraph works with any AI development environment.
+
+| Platform    | Agent Instructions | MCP Registration                        |
+| ----------- | ------------------ | --------------------------------------- |
+| Claude Code | `CLAUDE.md`        | Auto-registered via `claude mcp add`    |
+| Cursor      | `AGENTS.md`        | `.cursor/mcp.json` (written by `init`)  |
+| Copilot     | `AGENTS.md`        | `.vscode/mcp.json` (written by `init`)  |
+| Other       | `AGENTS.md`        | `MCP_SETUP.md` with manual instructions |
+
+**Claude Code** gets the deepest integration: MCP auto-registration, strict mode write tools, and instructions baked directly into `CLAUDE.md`.
+
+---
+
+## The Graph
+
+<!-- GIF placeholder — coming soon -->
+
+Whygraph models your application as a hierarchy of nodes with decisions attached to the nodes they affect.
+
+```text
+App: MyProject
+├── Feature: Auth
+│   ├── Component: Session Management
+│   │   └── ◆ JWT over sessions (active)
+│   └── Component: Token Refresh
+│       └── ◆ Silent refresh via interceptor (active)
+└── Feature: API Layer
+    ├── Component: Rate Limiting
+    │   └── ◆ Redis-backed sliding window (active)
+    └── ◆ REST over tRPC (active)
+```
+
+**Node types:** `App` → `Feature` → `Component`, with `Decision` nodes attached via `AFFECTS` edges.
+
+**Decision fields:** `title`, `date`, `context`, `decision`, `tradeoffs`, `alternatives`, `status`, `affects`, `tags`
+
+**Tags** (fixed taxonomy): `arch`, `data`, `security`, `performance`, `integration`, `infra`, `ux`
+
+Decisions are never deleted. A superseded decision stays in the graph with a `SUPERSEDES` edge explaining how the architecture evolved.
+
+---
+
+## CLI
+
+| Command                        | Description                                                                 |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| `whygraph init`                | Set up whygraph: choose environment, register MCP, write agent instructions |
+| `whygraph up`                  | Start the server in the background                                          |
+| `whygraph down`                | Stop the server                                                             |
+| `whygraph restart`             | Stop and restart the server                                                 |
+| `whygraph serve`               | Start the server in the foreground                                          |
+| `whygraph status`              | Check server status and entity counts                                       |
+| `whygraph viz`                 | Open the graph visualization in a browser                                   |
+| `whygraph issues`              | List and interactively resolve validation issues                            |
+| `whygraph validate`            | Validate all entities and cross-references                                  |
+| `whygraph config [--flag val]` | View or modify configuration                                                |
+| `whygraph mcp`                 | Start the MCP stdio server                                                  |
+
+All commands accept `--json` for programmatic output.
+
+---
+
+## Philosophy
+
+**The why is not in the code.** You can read a codebase and understand what it does. You cannot read it and understand what was tried before, what was rejected, and what trade-offs were accepted.
+
+**Decisions, not documentation.** Structured records — context, choice, tradeoffs, alternatives — not prose. Structure is what makes decisions queryable by agents.
+
+**Append-only.** Superseded decisions stay in the graph. They explain the path, not just the destination.
+
+**Repo-native.** The graph lives in `.whygraph/`, versioned with your code. No external service. No account required.
+
+**Agent-first.** The MCP tools and agent instructions are the primary interface. The CLI and visualization exist so humans can inspect what agents will read.
+
+**Never lose data.** Entity files are always written, even if validation fails. Issues are tracked in sidecars, not by rejecting writes.
+
+---
+
+## Limitations
+
+- The server must be running for MCP read tools and live visualization to work. In default mode, agents can write decision files directly to `.whygraph/graph/` without the server — they'll be picked up when it starts.
+- Multi-agent worktree support detects divergence but does not auto-merge. Conflict resolution follows standard git workflow.
+- The fixed tag taxonomy (`arch`, `data`, `security`, `performance`, `integration`, `infra`, `ux`) is intentional — it keeps decisions queryable. Custom tags are not supported in v1.
+- No cloud sync or hosted option. The graph is local to your repo.
+
+---
+
+## Multi-Agent / Worktree Support
+
+Whygraph runs one server per repo and watches all git worktrees. When agents work in parallel:
+
+- Each worktree's `.whygraph/graph/` is watched independently
+- ETag-based dirty tracking detects divergence from the main graph
+- Entity IDs use NanoIDs to prevent collisions across concurrent agents
+- Conflict resolution happens at git merge time
+
+---
+
+## Acknowledgments
+
+- **[Matt Pocock](https://www.youtube.com/@mattpocockuk)** — the development workflow used to build this project (TDD, PRD-first, simplify) is based on his [5 Skills for Claude Code](https://www.youtube.com/watch?v=EJyuu6zlQCg)
+
+---
+
+## License
+
+MIT © [Geovanie Ruiz](https://github.com/geovanie-ruiz)

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

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+import type { WhygraphConfig } from "../../entity/types.js";
+export interface ConfigUpdates {
+    environment?: string;
+    mcpMode?: string;
+    serverPort?: number;
+    tags?: string[];
+}
+export interface ConfigResult {
+    config: WhygraphConfig;
+    updated: boolean;
+}
+export declare function runConfig(whygraphDir: string, updates?: ConfigUpdates): ConfigResult;
+export declare function registerConfigCommand(program: Command): void;

package/dist/cli/commands/config.js

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import { DECISION_TAGS } from "../../entity/types.js";
+// ============================================================
+// Validation
+// ============================================================
+const VALID_ENVIRONMENTS = [
+    "claude-code",
+    "cursor",
+    "copilot",
+    "other",
+];
+const VALID_MCP_MODES = ["default", "strict"];
+function validateUpdates(updates) {
+    if (updates.environment !== undefined &&
+        !VALID_ENVIRONMENTS.includes(updates.environment)) {
+        throw new Error(`Invalid environment "${updates.environment}". Must be one of: ${VALID_ENVIRONMENTS.join(", ")}`);
+    }
+    if (updates.mcpMode !== undefined &&
+        !VALID_MCP_MODES.includes(updates.mcpMode)) {
+        throw new Error(`Invalid mcpMode "${updates.mcpMode}". Must be one of: ${VALID_MCP_MODES.join(", ")}`);
+    }
+    if (updates.serverPort !== undefined) {
+        if (typeof updates.serverPort !== "number" || isNaN(updates.serverPort)) {
+            throw new Error(`Invalid serverPort "${updates.serverPort}". Must be a number.`);
+        }
+    }
+    if (updates.tags !== undefined) {
+        for (const tag of updates.tags) {
+            if (!DECISION_TAGS.includes(tag)) {
+                throw new Error(`Invalid tag "${tag}". Must be one of: ${DECISION_TAGS.join(", ")}`);
+            }
+        }
+    }
+}
+// ============================================================
+// Core Logic
+// ============================================================
+export function runConfig(whygraphDir, updates) {
+    const configPath = join(whygraphDir, ".whygraph", "config.yaml");
+    if (!existsSync(configPath)) {
+        throw new Error(`.whygraph/ not found in ${whygraphDir}. Run "whygraph init" first.`);
+    }
+    const raw = readFileSync(configPath, "utf-8");
+    const config = yaml.load(raw);
+    if (!updates || Object.keys(updates).length === 0) {
+        return { config, updated: false };
+    }
+    validateUpdates(updates);
+    if (updates.environment !== undefined) {
+        config.environment = updates.environment;
+    }
+    if (updates.mcpMode !== undefined) {
+        config.mcpMode = updates.mcpMode;
+    }
+    if (updates.serverPort !== undefined) {
+        config.serverPort = updates.serverPort;
+    }
+    if (updates.tags !== undefined) {
+        config.tags = updates.tags;
+    }
+    const configYaml = yaml.dump(config, { lineWidth: -1 });
+    writeFileSync(configPath, configYaml, "utf-8");
+    return { config, updated: true };
+}
+// ============================================================
+// CLI Wiring
+// ============================================================
+function formatConfig(config) {
+    const lines = [
+        `appName:     ${config.appName}`,
+        `environment: ${config.environment}`,
+        `prefix:      ${config.prefix}`,
+        `idLength:    ${config.idLength}`,
+        `tags:        ${config.tags.join(", ")}`,
+        `mcpMode:     ${config.mcpMode}`,
+        `serverPort:  ${config.serverPort}`,
+    ];
+    return lines.join("\n");
+}
+export function registerConfigCommand(program) {
+    program
+        .command("config")
+        .description("View or update whygraph configuration")
+        .option("--environment <env>", "Update environment")
+        .option("--mcp-mode <mode>", "Update MCP mode (default | strict)")
+        .option("--server-port <port>", "Update server port")
+        .option("--json", "Output results as JSON")
+        .action((opts) => {
+        try {
+            const updates = {};
+            if (opts.environment !== undefined)
+                updates.environment = opts.environment;
+            if (opts.mcpMode !== undefined)
+                updates.mcpMode = opts.mcpMode;
+            if (opts.serverPort !== undefined)
+                updates.serverPort = Number(opts.serverPort);
+            const hasUpdates = Object.keys(updates).length > 0;
+            const result = runConfig(process.cwd(), hasUpdates ? updates : undefined);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                if (result.updated) {
+                    process.stdout.write("Configuration updated.\n\n");
+                }
+                process.stdout.write(formatConfig(result.config) + "\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/commands/down.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+export declare function runDown(targetDir: string, options?: {
+    port?: number;
+    json?: boolean;
+}): Promise<{
+    stopped: boolean;
+    port: number;
+}>;
+export declare function registerDownCommand(program: Command): void;

package/dist/cli/commands/down.js

@@ -0,0 +1,46 @@
+import { findWhygraphDir, getConfiguredPort, killProcessOnPort, waitForPortFree, } from "./server-utils.js";
+export async function runDown(targetDir, options = {}) {
+    const projectDir = findWhygraphDir(targetDir);
+    if (!projectDir) {
+        throw new Error(`.whygraph/ not found. Run "whygraph init" first.`);
+    }
+    const port = options.port ?? getConfiguredPort(projectDir);
+    const killed = killProcessOnPort(port);
+    if (killed) {
+        await waitForPortFree(port);
+    }
+    return { stopped: killed, port };
+}
+export function registerDownCommand(program) {
+    program
+        .command("down")
+        .description("Stop the whygraph server")
+        .option("--port <number>", "Port number")
+        .option("--json", "Output results as JSON")
+        .action(async (opts) => {
+        try {
+            const port = opts.port ? parseInt(opts.port, 10) : undefined;
+            const result = await runDown(process.cwd(), { port, json: opts.json });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result) + "\n");
+            }
+            else if (result.stopped) {
+                process.stdout.write(`whygraph server stopped (port ${result.port})\n`);
+            }
+            else {
+                process.stdout.write(`No server running on port ${result.port}\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 }) + "\n");
+            }
+            else {
+                process.stderr.write(`Error: ${message}\n`);
+            }
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,17 @@
+import type { Command } from "commander";
+import type { Environment } from "../../entity/types.js";
+export interface InitOptions {
+    appName?: string;
+    environment?: Environment;
+    json?: boolean;
+}
+export interface InitResult {
+    configPath: string;
+    appNodePath: string;
+    appId: string;
+    platformRulesPath: string;
+    mcpRegistered: boolean;
+    mcpSetupPath?: string;
+}
+export declare function runInit(targetDir: string, options: InitOptions): Promise<InitResult>;
+export declare function registerInitCommand(program: Command): void;

package/dist/cli/commands/init.js

@@ -0,0 +1,144 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import prompts from "prompts";
+import { generateId } from "../../entity/id.js";
+import { writeEntity } from "../../entity/writer.js";
+import { DECISION_TAGS } from "../../entity/types.js";
+import { writePlatformRules } from "../../platform/rules.js";
+// ============================================================
+// Core Logic
+// ============================================================
+export async function runInit(targetDir, options) {
+    const whygraphDir = join(targetDir, ".whygraph");
+    if (existsSync(whygraphDir)) {
+        throw new Error(`.whygraph/ already exists in ${targetDir}. Aborting init.`);
+    }
+    // Resolve app name and environment from options or prompts
+    let appName = options.appName;
+    let environment = options.environment;
+    if (!appName || !environment) {
+        const answers = await prompts([
+            ...(appName
+                ? []
+                : [
+                    {
+                        type: "text",
+                        name: "appName",
+                        message: "App name:",
+                    },
+                ]),
+            /* v8 ignore start */
+            ...(environment
+                ? []
+                : [
+                    {
+                        type: "select",
+                        name: "environment",
+                        message: "Environment:",
+                        choices: [
+                            { title: "Claude Code", value: "claude-code" },
+                            { title: "Cursor", value: "cursor" },
+                            { title: "Copilot", value: "copilot" },
+                            { title: "Other", value: "other" },
+                        ],
+                    },
+                ]),
+            /* v8 ignore stop */
+        ], { onCancel: () => { throw new Error("Init cancelled by user."); } });
+        if (!appName)
+            appName = answers.appName;
+        /* v8 ignore next 1 */
+        if (!environment)
+            environment = answers.environment;
+    }
+    if (!appName) {
+        throw new Error("App name is required.");
+    }
+    if (!environment) {
+        throw new Error("Environment is required.");
+    }
+    // Create directory structure
+    const graphDir = join(whygraphDir, "graph");
+    mkdirSync(graphDir, { recursive: true });
+    // Build config
+    const config = {
+        appName,
+        environment,
+        prefix: "wg-",
+        idLength: 4,
+        tags: [...DECISION_TAGS],
+        mcpMode: "default",
+        serverPort: 4777,
+    };
+    // Write config.yaml
+    const configPath = join(whygraphDir, "config.yaml");
+    const configYaml = yaml.dump(config, { lineWidth: -1 });
+    writeFileSync(configPath, configYaml, "utf-8");
+    // Create App node
+    const now = new Date().toISOString();
+    const appId = generateId({ prefix: config.prefix, length: config.idLength });
+    const appNode = {
+        id: appId,
+        label: "App",
+        name: appName,
+        status: "active",
+        created_at: now,
+        updated_at: now,
+    };
+    const { filePath: appNodePath } = writeEntity(graphDir, appNode);
+    // Write platform-specific rules and register MCP server
+    const platformResult = writePlatformRules(targetDir, environment, "", config);
+    return {
+        configPath,
+        appNodePath,
+        appId,
+        platformRulesPath: platformResult.filePath,
+        mcpRegistered: platformResult.mcpRegistered,
+        mcpSetupPath: platformResult.mcpSetupPath,
+    };
+}
+// ============================================================
+// CLI Wiring
+// ============================================================
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("Initialize a new whygraph project in the current directory")
+        .option("--app-name <name>", "Application name (skips prompt)")
+        .option("--environment <env>", "Environment: claude-code, cursor, copilot, other (skips prompt)")
+        .option("--json", "Output results as JSON")
+        .action(async (opts) => {
+        try {
+            const result = await runInit(process.cwd(), {
+                appName: opts.appName,
+                environment: opts.environment,
+                json: opts.json,
+            });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                const mcpLine = result.mcpRegistered
+                    ? `  MCP: registered\n`
+                    : `  MCP: setup failed — see ${result.mcpSetupPath} for manual instructions\n`;
+                process.stdout.write(`Initialized whygraph in .whygraph/\n` +
+                    `  App node: ${result.appId}\n` +
+                    `  Config: ${result.configPath}\n` +
+                    mcpLine +
+                    `\nRun 'whygraph up' to start the server.\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/commands/issues.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import type { EntityIssue } from "../../entity/issues.js";
+export interface IssuesResult {
+    agentNeeded: number;
+    cliResolvable: number;
+    total: number;
+    issues: EntityIssue[];
+}
+export declare function runIssues(targetDir: string): IssuesResult;
+export declare function registerIssuesCommand(program: Command): void;