whygraph 0.1.0

package/dist/platform/rules.js

@@ -0,0 +1,229 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+const START_MARKER = "<!-- whygraph:start -->";
+const END_MARKER = "<!-- whygraph:end -->";
+function generateInstructions(config) {
+    const tagList = config.tags.join(", ");
+    return [
+        "## Whygraph — Decision Capture",
+        "",
+        "Before writing, modifying, or deleting production code, capture any non-trivial",
+        "decision as a Decision node. A decision is non-trivial if a junior engineer would",
+        "benefit from knowing why the choice was made.",
+        "",
+        "### Recognition Heuristic",
+        "",
+        "Scan your output for these signals:",
+        "- Choosing between alternatives",
+        "- Rejecting an approach",
+        "- Setting a convention or pattern",
+        "- Adding, removing, or changing a dependency",
+        "- Configuring infrastructure or deployment",
+        "- Making a security or performance tradeoff",
+        "- Altering user-facing behavior",
+        "- Scoping to production code the agent authored",
+        "- Establishing an invariant or constraint",
+        "",
+        "### Decision File Format",
+        "",
+        "Write decision files to `.whygraph/graph/` with YAML frontmatter:",
+        "",
+        "```yaml",
+        "---",
+        `id: ${config.prefix}<4-char-nanoid>`,
+        "label: Decision",
+        "title: <short title>",
+        "status: active",
+        "date: <YYYY-MM-DD>",
+        "affects:",
+        "  - <entity-id>",
+        "tags:",
+        `  - <one of: ${tagList}>`,
+        `created_at: <ISO 8601>`,
+        `updated_at: <ISO 8601>`,
+        "---",
+        "",
+        "## Context",
+        "<why this decision was needed>",
+        "",
+        "## Decision",
+        "<what was decided>",
+        "",
+        "## Tradeoffs",
+        "<what was gained and lost>",
+        "",
+        "## Alternatives",
+        "<what was considered and rejected>",
+        "```",
+        "",
+        `Allowed tags: ${tagList}`,
+        "",
+        "### MCP Server",
+        "",
+        `Use the \`whygraph\` MCP server for decision capture tools.`,
+        "If the server is unreachable, write decision files directly to `.whygraph/graph/`.",
+        "",
+        "### Server Status",
+        "",
+        "Run `whygraph status` to check if the server is running.",
+        "Run `whygraph up` to start the server.",
+        "",
+    ].join("\n");
+}
+function upsertMarkedSection(existing, content) {
+    const wrapped = `${START_MARKER}\n${content}${END_MARKER}\n`;
+    if (existing.includes(START_MARKER)) {
+        const startIdx = existing.indexOf(START_MARKER);
+        const endIdx = existing.indexOf(END_MARKER);
+        /* v8 ignore next 1 */
+        const afterEnd = endIdx >= 0 ? endIdx + END_MARKER.length + 1 : existing.length;
+        return existing.slice(0, startIdx) + wrapped + existing.slice(afterEnd);
+    }
+    /* v8 ignore next 1 */
+    const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    return existing + sep + wrapped;
+}
+// ============================================================
+// MCP Registration
+// ============================================================
+function registerMcpWithClaude(projectDir) {
+    try {
+        execSync("claude mcp add --scope project whygraph -- whygraph mcp", {
+            cwd: projectDir,
+            stdio: "ignore",
+        });
+        return true;
+        /* v8 ignore start */
+    }
+    catch {
+        // claude CLI not available — write .mcp.json directly as fallback
+        try {
+            const mcpJsonPath = join(projectDir, ".mcp.json");
+            let mcpJson = {};
+            if (existsSync(mcpJsonPath)) {
+                mcpJson = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
+            }
+            const servers = (mcpJson.mcpServers ?? {});
+            if (!servers.whygraph) {
+                servers.whygraph = { type: "stdio", command: "whygraph", args: ["mcp"] };
+                mcpJson.mcpServers = servers;
+                writeFileSync(mcpJsonPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf-8");
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /* v8 ignore stop */
+}
+function registerMcpWithCursor(projectDir) {
+    try {
+        const cursorDir = join(projectDir, ".cursor");
+        mkdirSync(cursorDir, { recursive: true });
+        const mcpPath = join(cursorDir, "mcp.json");
+        let mcp = {};
+        if (existsSync(mcpPath)) {
+            mcp = JSON.parse(readFileSync(mcpPath, "utf-8"));
+        }
+        const servers = (mcp.mcpServers ?? {});
+        if (!servers.whygraph) {
+            servers.whygraph = { command: "whygraph", args: ["mcp"] };
+            mcp.mcpServers = servers;
+            writeFileSync(mcpPath, JSON.stringify(mcp, null, 2) + "\n", "utf-8");
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function registerMcpWithCopilot(projectDir) {
+    try {
+        const vscodeDir = join(projectDir, ".vscode");
+        mkdirSync(vscodeDir, { recursive: true });
+        const mcpPath = join(vscodeDir, "mcp.json");
+        let mcp = {};
+        if (existsSync(mcpPath)) {
+            mcp = JSON.parse(readFileSync(mcpPath, "utf-8"));
+        }
+        const servers = (mcp.servers ?? {});
+        if (!servers.whygraph) {
+            servers.whygraph = { type: "stdio", command: "whygraph", args: ["mcp"] };
+            mcp.servers = servers;
+            writeFileSync(mcpPath, JSON.stringify(mcp, null, 2) + "\n", "utf-8");
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function writeMcpSetupMd(projectDir, environment) {
+    const whygraphDir = join(projectDir, ".whygraph");
+    mkdirSync(whygraphDir, { recursive: true });
+    const filePath = join(whygraphDir, "MCP_SETUP.md");
+    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", "```");
+            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), "```");
+            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), "```");
+            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.");
+    }
+    writeFileSync(filePath, lines.join("\n") + "\n", "utf-8");
+    return filePath;
+}
+// ============================================================
+// Platform Writers
+// ============================================================
+export function writePlatformRules(projectDir, environment, _primeOutput, config) {
+    const instructions = config ? generateInstructions(config) : _primeOutput;
+    switch (environment) {
+        case "claude-code":
+            return writeClaudeCodeRules(projectDir, instructions);
+        case "cursor": {
+            const mcpRegistered = registerMcpWithCursor(projectDir);
+            const mcpSetupPath = mcpRegistered ? undefined : writeMcpSetupMd(projectDir, environment);
+            return { ...writeAgentsMd(projectDir, instructions, environment), mcpRegistered, mcpSetupPath };
+        }
+        case "copilot": {
+            const mcpRegistered = registerMcpWithCopilot(projectDir);
+            const mcpSetupPath = mcpRegistered ? undefined : writeMcpSetupMd(projectDir, environment);
+            return { ...writeAgentsMd(projectDir, instructions, environment), mcpRegistered, mcpSetupPath };
+        }
+        case "other": {
+            const mcpSetupPath = writeMcpSetupMd(projectDir, environment);
+            return { ...writeAgentsMd(projectDir, instructions, environment), mcpRegistered: false, mcpSetupPath };
+        }
+    }
+}
+function writeClaudeCodeRules(projectDir, instructions) {
+    const mcpRegistered = registerMcpWithClaude(projectDir);
+    const mcpSetupPath = mcpRegistered ? undefined : writeMcpSetupMd(projectDir, "claude-code");
+    const claudeMdPath = join(projectDir, "CLAUDE.md");
+    let existing = "";
+    if (existsSync(claudeMdPath)) {
+        existing = readFileSync(claudeMdPath, "utf-8");
+    }
+    const newContent = upsertMarkedSection(existing, instructions);
+    writeFileSync(claudeMdPath, newContent, "utf-8");
+    return { environment: "claude-code", filePath: claudeMdPath, mcpRegistered, mcpSetupPath };
+}
+function writeAgentsMd(projectDir, instructions, environment) {
+    const filePath = join(projectDir, "AGENTS.md");
+    let existing = "";
+    if (existsSync(filePath)) {
+        existing = readFileSync(filePath, "utf-8");
+    }
+    const newContent = upsertMarkedSection(existing, instructions);
+    writeFileSync(filePath, newContent, "utf-8");
+    return { environment, filePath };
+}

package/dist/server/core.d.ts

@@ -0,0 +1,26 @@
+import graphology from "graphology";
+import type { EntityIssue } from "../entity/issues.js";
+import { PubSub } from "./pubsub.js";
+import type { Entity } from "../entity/types.js";
+type MultiDirectedGraph = graphology.MultiDirectedGraph;
+declare const MultiDirectedGraph: typeof graphology.MultiDirectedGraph;
+export declare class ServerCore {
+    private entityMap;
+    private graph;
+    private readonly whygraphDir;
+    readonly pubsub: PubSub;
+    constructor(whygraphDir: string);
+    getWhygraphDir(): string;
+    load(): Promise<void>;
+    getIssues(): EntityIssue[];
+    getEntity(id: string): Entity | undefined;
+    getAllEntities(): Entity[];
+    getGraph(): MultiDirectedGraph;
+    getEntityMap(): Map<string, Entity>;
+    addOrUpdateEntity(id: string, entity: Entity): void;
+    removeEntity(id: string): void;
+    private rebuildGraph;
+    private reconcileEntityIssue;
+    private reconcileAllIssues;
+}
+export {};

package/dist/server/core.js

@@ -0,0 +1,111 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import graphology from "graphology";
+import { parseEntity } from "../entity/parser.js";
+import { validateEntity, validateEntityRefs } from "../entity/validate.js";
+import { reconcileIssue, listIssues, deleteIssue } from "../entity/issues.js";
+import { buildGraph } from "../graph/projection.js";
+import { PubSub } from "./pubsub.js";
+const MultiDirectedGraph = graphology.MultiDirectedGraph;
+export class ServerCore {
+    entityMap;
+    graph;
+    whygraphDir;
+    pubsub;
+    constructor(whygraphDir) {
+        this.whygraphDir = whygraphDir;
+        this.entityMap = new Map();
+        this.graph = new MultiDirectedGraph();
+        this.pubsub = new PubSub();
+    }
+    getWhygraphDir() {
+        return this.whygraphDir;
+    }
+    async load() {
+        const graphDir = path.join(this.whygraphDir, "graph");
+        let entries;
+        try {
+            entries = await fs.readdir(graphDir);
+        }
+        catch {
+            // Directory doesn't exist — start with empty state
+            return;
+        }
+        const mdFiles = entries.filter((f) => f.endsWith(".md"));
+        for (const file of mdFiles) {
+            const filePath = path.join(graphDir, file);
+            try {
+                const content = await fs.readFile(filePath, "utf-8");
+                const entity = parseEntity(content);
+                if (entity) {
+                    this.entityMap.set(entity.id, entity);
+                }
+                else {
+                    console.warn(`Skipping unparseable file: ${file}`);
+                }
+            }
+            catch (err) {
+                console.warn(`Error reading file ${file}:`, err);
+            }
+        }
+        this.rebuildGraph();
+        this.reconcileAllIssues();
+    }
+    getIssues() {
+        return listIssues(this.whygraphDir);
+    }
+    getEntity(id) {
+        return this.entityMap.get(id);
+    }
+    getAllEntities() {
+        return Array.from(this.entityMap.values());
+    }
+    getGraph() {
+        return this.graph;
+    }
+    getEntityMap() {
+        return this.entityMap;
+    }
+    addOrUpdateEntity(id, entity) {
+        const isUpdate = this.entityMap.has(id);
+        this.entityMap.set(id, entity);
+        this.rebuildGraph();
+        this.reconcileEntityIssue(id, entity);
+        this.pubsub.publish({
+            type: isUpdate ? "entity_updated" : "entity_created",
+            entityId: id,
+            entity,
+        });
+    }
+    removeEntity(id) {
+        const existed = this.entityMap.has(id);
+        this.entityMap.delete(id);
+        this.rebuildGraph();
+        deleteIssue(this.whygraphDir, id);
+        if (existed) {
+            this.pubsub.publish({
+                type: "entity_deleted",
+                entityId: id,
+            });
+        }
+    }
+    rebuildGraph() {
+        this.graph = buildGraph(this.getAllEntities());
+    }
+    reconcileEntityIssue(id, entity) {
+        const { errors } = validateEntity(entity);
+        const refErrors = validateEntityRefs(entity, this.entityMap);
+        reconcileIssue(this.whygraphDir, id, [...errors, ...refErrors]);
+    }
+    reconcileAllIssues() {
+        for (const [id, entity] of this.entityMap) {
+            this.reconcileEntityIssue(id, entity);
+        }
+        const existingIssues = listIssues(this.whygraphDir);
+        for (const issue of existingIssues) {
+            if (!this.entityMap.has(issue.entityId)) {
+                deleteIssue(this.whygraphDir, issue.entityId);
+            }
+        }
+    }
+}

package/dist/server/derived.d.ts

@@ -0,0 +1,8 @@
+import type { Entity } from "../entity/types.js";
+import type { ValidationError } from "../entity/validate.js";
+import type { SupersedeCandidate } from "../graph/supersede.js";
+export interface DerivedState {
+    validationErrors: Map<string, ValidationError[]>;
+    supersedeCandidates: SupersedeCandidate[];
+}
+export declare function computeDerivedState(entities: Map<string, Entity>): DerivedState;

package/dist/server/derived.js

@@ -0,0 +1,13 @@
+import { validateEntity } from "../entity/validate.js";
+import { detectSupersedeCandidates } from "../graph/supersede.js";
+export function computeDerivedState(entities) {
+    const validationErrors = new Map();
+    for (const [id, entity] of entities) {
+        const result = validateEntity(entity);
+        if (result.errors.length > 0) {
+            validationErrors.set(id, result.errors);
+        }
+    }
+    const supersedeCandidates = detectSupersedeCandidates(entities);
+    return { validationErrors, supersedeCandidates };
+}

package/dist/server/etag.d.ts

@@ -0,0 +1,9 @@
+import type { Entity } from "../entity/types.js";
+/**
+ * Compute an ETag for an entity by hashing its rendered markdown output.
+ */
+export declare function computeETag(entity: Entity): string;
+/**
+ * Compare two entities by ETag to determine if the worktree copy has diverged.
+ */
+export declare function isDirty(worktreeEntity: Entity, mainEntity: Entity): boolean;

package/dist/server/etag.js

@@ -0,0 +1,25 @@
+import { renderEntity } from "../entity/writer.js";
+/**
+ * FNV-1a hash of a string, returned as hex.
+ */
+function fnv1a(input) {
+    let hash = 0x811c9dc5; // FNV offset basis (32-bit)
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = (hash * 0x01000193) >>> 0; // FNV prime, keep as uint32
+    }
+    return hash.toString(16);
+}
+/**
+ * Compute an ETag for an entity by hashing its rendered markdown output.
+ */
+export function computeETag(entity) {
+    const rendered = renderEntity(entity);
+    return fnv1a(rendered);
+}
+/**
+ * Compare two entities by ETag to determine if the worktree copy has diverged.
+ */
+export function isDirty(worktreeEntity, mainEntity) {
+    return computeETag(worktreeEntity) !== computeETag(mainEntity);
+}

package/dist/server/http.d.ts

@@ -0,0 +1,13 @@
+import { type Server } from "node:http";
+import type { ServerCore } from "./core.js";
+export interface HttpServerOptions {
+    port?: number;
+    frontendDir?: string;
+}
+export interface HttpServer {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    readonly server: Server;
+}
+export declare function createHttpServer(core: ServerCore, portOrOptions?: number | HttpServerOptions): HttpServer;
+export declare function startServer(core: ServerCore, port?: number): Promise<HttpServer>;

package/dist/server/http.js

@@ -0,0 +1,131 @@
+import { createServer } from "node:http";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { WebSocketServer } from "ws";
+import { useServer } from "graphql-ws/use/ws";
+import { createYoga } from "graphql-yoga";
+import { execute, subscribe } from "graphql";
+import { buildSchema } from "./schema.js";
+const DEFAULT_PORT = 4777;
+const MIME_TYPES = {
+    ".html": "text/html",
+    ".js": "application/javascript",
+    ".css": "text/css",
+    ".json": "application/json",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+};
+function defaultFrontendDir() {
+    // In production, frontend is at dist/frontend relative to the package root.
+    // import.meta.url points to dist/server/http.js, so go up one level to dist/,
+    // then into frontend/.
+    const thisFile = new URL(import.meta.url).pathname;
+    return path.resolve(path.dirname(thisFile), "..", "frontend");
+}
+function tryServeStatic(frontendDir, reqUrl, res) {
+    const urlPath = reqUrl.split("?")[0];
+    const filePath = path.join(frontendDir, urlPath);
+    // Prevent directory traversal
+    /* v8 ignore next 3 */
+    if (!filePath.startsWith(frontendDir)) {
+        return false;
+    }
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.isFile()) {
+            const ext = path.extname(filePath);
+            const mime = MIME_TYPES[ext] ?? "application/octet-stream";
+            const content = fs.readFileSync(filePath);
+            res.writeHead(200, { "Content-Type": mime });
+            res.end(content);
+            return true;
+        }
+    }
+    catch {
+        // File not found, fall through
+    }
+    return false;
+}
+function serveIndexFallback(frontendDir, res) {
+    const indexPath = path.join(frontendDir, "index.html");
+    try {
+        const content = fs.readFileSync(indexPath, "utf-8");
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(content);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createHttpServer(core, portOrOptions) {
+    const options = typeof portOrOptions === "number"
+        ? { port: portOrOptions }
+        /* v8 ignore next 1 */
+        : portOrOptions ?? {};
+    /* v8 ignore next 1 */
+    const port = options.port ?? DEFAULT_PORT;
+    const frontendDir = options.frontendDir ?? defaultFrontendDir();
+    const schema = buildSchema(core);
+    const yoga = createYoga({
+        schema,
+        graphqlEndpoint: "/api/graphql",
+        landingPage: false,
+    });
+    const server = createServer((req, res) => {
+        /* v8 ignore next 1 */
+        const url = req.url ?? "/";
+        // Health endpoint
+        if (url === "/api/health" && req.method === "GET") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "ok" }));
+            return;
+        }
+        // API routes go to yoga
+        if (url.startsWith("/api/")) {
+            yoga(req, res);
+            return;
+        }
+        // Try to serve a static file
+        if (tryServeStatic(frontendDir, url, res)) {
+            return;
+        }
+        // SPA fallback: serve index.html for all non-API routes
+        if (serveIndexFallback(frontendDir, res)) {
+            return;
+        }
+        // No frontend built — fall back to yoga for backwards compat
+        yoga(req, res);
+    });
+    // WebSocket server for graphql-ws subscriptions
+    const wss = new WebSocketServer({ server, path: "/api/graphql" });
+    const wsCleanup = useServer({
+        schema,
+        execute: execute,
+        subscribe: subscribe,
+    }, wss);
+    return {
+        server,
+        start() {
+            return new Promise((resolve, reject) => {
+                server.on("error", reject);
+                server.listen(port, () => resolve());
+            });
+        },
+        stop() {
+            return new Promise((resolve) => {
+                wsCleanup.dispose();
+                wss.close();
+                server.close(() => resolve());
+            });
+        },
+    };
+}
+export function startServer(core, port = DEFAULT_PORT) {
+    const httpServer = createHttpServer(core, { port });
+    return httpServer.start().then(() => httpServer);
+}

package/dist/server/pubsub.d.ts

@@ -0,0 +1,12 @@
+import type { Entity } from "../entity/types.js";
+export interface GraphEvent {
+    type: "entity_created" | "entity_updated" | "entity_deleted" | "graph_changed";
+    entityId?: string;
+    entity?: Entity;
+}
+export type Subscriber = (event: GraphEvent) => void;
+export declare class PubSub {
+    private subscribers;
+    subscribe(callback: Subscriber): () => void;
+    publish(event: GraphEvent): void;
+}

package/dist/server/pubsub.js

@@ -0,0 +1,19 @@
+export class PubSub {
+    subscribers = new Set();
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+    publish(event) {
+        for (const subscriber of this.subscribers) {
+            try {
+                subscriber(event);
+            }
+            catch {
+                // Non-blocking: errors in one subscriber must not affect others
+            }
+        }
+    }
+}

package/dist/server/schema.d.ts

@@ -0,0 +1,2 @@
+import type { ServerCore } from "./core.js";
+export declare function buildSchema(core: ServerCore): import("graphql-yoga").GraphQLSchemaWithContext<import("graphql-yoga").YogaInitialContext>;