whygraph 0.1.0

package/dist/cli/commands/issues.js

@@ -0,0 +1,376 @@
+import { join } from "node:path";
+import { readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import prompts from "prompts";
+import { listIssues, deleteIssue } from "../../entity/issues.js";
+import { parseEntity } from "../../entity/parser.js";
+import { writeEntity } from "../../entity/writer.js";
+import { DECISION_TAGS } from "../../entity/types.js";
+import { isDecisionNode, isStructuralNode } from "../../entity/types.js";
+import { findWhygraphDir, getConfiguredPort, isServerRunning } from "./server-utils.js";
+class UserCancelled extends Error {
+    constructor() { super("cancelled"); }
+}
+const onCancel = () => { throw new UserCancelled(); };
+const CLI_RESOLVABLE_FIELDS = new Set(["tags", "parent", "date", "affects", "supersedes"]);
+function isCliResolvable(issue) {
+    return issue.errors.length > 0 && issue.errors.every((e) => CLI_RESOLVABLE_FIELDS.has(e.field));
+}
+function loadEntitiesFromDisk(graphDir) {
+    const entities = new Map();
+    let files;
+    try {
+        files = readdirSync(graphDir).filter((f) => f.endsWith(".md"));
+        /* v8 ignore start */
+    }
+    catch {
+        return entities;
+    }
+    /* v8 ignore stop */
+    for (const file of files) {
+        try {
+            const content = readFileSync(join(graphDir, file), "utf-8");
+            const entity = parseEntity(content);
+            /* v8 ignore next 1 */
+            if (entity)
+                entities.set(entity.id, entity);
+            /* v8 ignore start */
+        }
+        catch { /* skip */ }
+        /* v8 ignore stop */
+    }
+    return entities;
+}
+function generateAgentPrompt(issue, graphDir) {
+    const files = readdirSync(graphDir).filter((f) => f.startsWith(issue.entityId));
+    const filePath = files.length > 0
+        ? `.whygraph/graph/${files[0]}`
+        : `.whygraph/graph/${issue.entityId}.md`;
+    const missingFields = issue.errors.map((e) => e.field).join(", ");
+    return (`Review ${issue.entityId} in ${filePath}. ` +
+        `It has validation issues: missing ${missingFields}. ` +
+        `Read the existing decision content and the surrounding codebase, ` +
+        `then fill in the missing sections.`);
+}
+export function runIssues(targetDir) {
+    const projectDir = findWhygraphDir(targetDir);
+    if (!projectDir) {
+        throw new Error(`.whygraph/ not found. Run "whygraph init" first.`);
+    }
+    const whygraphDir = join(projectDir, ".whygraph");
+    const issues = listIssues(whygraphDir);
+    let agentNeeded = 0;
+    let cliResolvable = 0;
+    for (const issue of issues) {
+        if (isCliResolvable(issue)) {
+            cliResolvable++;
+        }
+        else {
+            agentNeeded++;
+        }
+    }
+    return { agentNeeded, cliResolvable, total: issues.length, issues };
+}
+async function resolveParentInteractively(entity, entities, graphDir) {
+    /* v8 ignore start */
+    const features = Array.from(entities.values())
+        .filter((e) => isStructuralNode(e) && e.label === "Feature")
+        .sort((a, b) => a.name.localeCompare(b.name));
+    /* v8 ignore stop */
+    if (features.length === 0) {
+        process.stdout.write("  No features found in the graph. Cannot assign parent.\n");
+        return false;
+    }
+    // Show context so the developer knows what this node is
+    process.stdout.write(`\n  ${entity.label}: ${entity.name} (${entity.id})\n`);
+    if (entity.description) {
+        process.stdout.write(`  ${entity.description}\n`);
+    }
+    if (entity.refs && entity.refs.length > 0) {
+        process.stdout.write(`  Files: ${entity.refs.map((r) => r.file).join(", ")}\n`);
+    }
+    process.stdout.write("\n");
+    const featureResponse = await prompts({
+        type: "select",
+        name: "featureId",
+        message: `Which feature does "${entity.name}" belong to?`,
+        choices: features.map((f) => ({
+            title: `${f.name} (${f.id})`,
+            value: f.id,
+        })),
+    }, { onCancel });
+    /* v8 ignore next 1 */
+    if (!featureResponse.featureId)
+        return false;
+    const components = Array.from(entities.values())
+        .filter((e) => isStructuralNode(e) && e.label === "Component" && e.parent === featureResponse.featureId)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    if (components.length > 0 && entity.label === "Component") {
+        const drillDown = await prompts({
+            type: "select",
+            name: "parentId",
+            message: "Attach to the feature, or nest under a component?",
+            choices: [
+                { title: `Attach to ${entities.get(featureResponse.featureId).name}`, value: featureResponse.featureId },
+                ...components.map((c) => ({
+                    title: `Under ${c.name} (${c.id})`,
+                    value: c.id,
+                })),
+            ],
+        }, { onCancel });
+        /* v8 ignore next 1 */
+        if (!drillDown.parentId)
+            return false;
+        entity.parent = drillDown.parentId;
+    }
+    else {
+        entity.parent = featureResponse.featureId;
+    }
+    entity.updated_at = new Date().toISOString();
+    writeEntity(graphDir, entity);
+    process.stdout.write(`  Updated ${entity.id}: parent set to ${entity.parent}\n\n`);
+    return true;
+}
+function printDecisionContext(entity) {
+    process.stdout.write(`\n  Decision: ${entity.title} (${entity.id})\n`);
+    /* v8 ignore next 3 */
+    if (entity.context) {
+        const preview = entity.context.length > 120 ? entity.context.slice(0, 120) + "..." : entity.context;
+        process.stdout.write(`  Context: ${preview}\n`);
+    }
+    if (entity.affects.length > 0) {
+        process.stdout.write(`  Affects: ${entity.affects.join(", ")}\n`);
+    }
+    process.stdout.write("\n");
+}
+async function resolveDateInteractively(entity, graphDir) {
+    printDecisionContext(entity);
+    const response = await prompts({
+        type: "text",
+        name: "date",
+        message: `Invalid date "${entity.date}". Enter corrected date (YYYY-MM-DD):`,
+        /* v8 ignore start */
+        validate: (v) => /^\d{4}-\d{2}-\d{2}$/.test(v) || "Must be YYYY-MM-DD",
+        /* v8 ignore stop */
+    }, { onCancel });
+    /* v8 ignore start */
+    if (!response.date)
+        return false;
+    entity.date = response.date;
+    entity.updated_at = new Date().toISOString();
+    writeEntity(graphDir, entity);
+    process.stdout.write(`  Updated ${entity.id}: date set to ${entity.date}\n\n`);
+    return true;
+    /* v8 ignore stop */
+}
+async function resolveTagInteractively(entity, badTag, graphDir) {
+    printDecisionContext(entity);
+    const response = await prompts({
+        type: "select",
+        name: "tag",
+        message: `Invalid tag "${badTag}". Pick a replacement:`,
+        choices: DECISION_TAGS.map((t) => ({ title: t, value: t })),
+    }, { onCancel });
+    /* v8 ignore start */
+    if (!response.tag)
+        return false;
+    entity.tags = entity.tags.map((t) => (t === badTag ? response.tag : t));
+    entity.updated_at = new Date().toISOString();
+    writeEntity(graphDir, entity);
+    process.stdout.write(`  Updated ${entity.id}: tag "${badTag}" replaced with "${response.tag}"\n\n`);
+    return true;
+    /* v8 ignore stop */
+}
+async function resolveAffectsInteractively(entity, invalidRefs, entities, graphDir) {
+    printDecisionContext(entity);
+    const validChoices = Array.from(entities.values()).filter((e) => !isDecisionNode(e))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((e) => ({ title: `${e.name} (${e.id})`, value: e.id }));
+    let anyResolved = false;
+    for (const ref of invalidRefs) {
+        const isLastRef = entity.affects.length === 1;
+        const choices = isLastRef
+            ? [{ title: "Remove ref and delete node", value: "delete" }, { title: "Replace it", value: "replace" }]
+            : [{ title: "Remove it", value: "remove" }, { title: "Replace it", value: "replace" }];
+        const response = await prompts({
+            type: "select",
+            name: "action",
+            message: `Invalid affects ref "${ref}". What do you want to do?`,
+            choices,
+        }, { onCancel });
+        if (response.action === "delete") {
+            const files = readdirSync(graphDir).filter((f) => f.startsWith(entity.id));
+            /* v8 ignore next 1 */
+            if (files.length > 0)
+                unlinkSync(join(graphDir, files[0]));
+            const whygraphDir = join(graphDir, "..");
+            deleteIssue(whygraphDir, entity.id);
+            process.stdout.write(`  Deleted ${entity.id}\n\n`);
+            return true;
+            /* v8 ignore start */
+        }
+        else if (response.action === "remove") {
+            entity.affects = entity.affects.filter((a) => a !== ref);
+            anyResolved = true;
+        }
+        else if (response.action === "replace") {
+            const replacement = await prompts({
+                type: "select",
+                name: "id",
+                message: `Replace "${ref}" with:`,
+                choices: validChoices,
+            }, { onCancel });
+            if (replacement.id) {
+                entity.affects = entity.affects.map((a) => (a === ref ? replacement.id : a));
+                anyResolved = true;
+            }
+        }
+        /* v8 ignore stop */
+    }
+    /* v8 ignore next 4 */
+    if (anyResolved) {
+        entity.updated_at = new Date().toISOString();
+        writeEntity(graphDir, entity);
+        process.stdout.write(`  Updated ${entity.id}: affects refs resolved\n\n`);
+    }
+    return anyResolved;
+}
+async function resolveIssueInteractively(issue, entities, graphDir) {
+    const entity = entities.get(issue.entityId);
+    if (!entity) {
+        const whygraphDir = join(graphDir, "..");
+        deleteIssue(whygraphDir, issue.entityId);
+        process.stdout.write(`  Entity ${issue.entityId} no longer exists — issue cleared.\n\n`);
+        return true;
+    }
+    let resolved = false;
+    for (const err of issue.errors) {
+        if (err.field === "parent" && isStructuralNode(entity)) {
+            if (await resolveParentInteractively(entity, entities, graphDir))
+                resolved = true;
+        }
+        else if (err.field === "date" && isDecisionNode(entity)) {
+            /* v8 ignore next 1 */
+            if (await resolveDateInteractively(entity, graphDir))
+                resolved = true;
+        }
+        else if (err.field === "tags" && isDecisionNode(entity)) {
+            const match = err.message.match(/invalid tag "([^"]+)"/);
+            /* v8 ignore next 3 */
+            if (match) {
+                if (await resolveTagInteractively(entity, match[1], graphDir))
+                    resolved = true;
+            }
+            /* v8 ignore start */
+        }
+        else if (err.field === "affects" && isDecisionNode(entity)) {
+            const invalidRefs = issue.errors
+                .filter((e) => e.field === "affects")
+                .map((e) => e.message.match(/affects ref "([^"]+)"/)?.[1])
+                .filter((r) => r !== undefined);
+            if (invalidRefs.length > 0) {
+                if (await resolveAffectsInteractively(entity, invalidRefs, entities, graphDir))
+                    resolved = true;
+            }
+            break; // all affects errors handled in one pass
+        }
+        /* v8 ignore stop */
+    }
+    return resolved;
+}
+export function registerIssuesCommand(program) {
+    program
+        .command("issues")
+        .description("List and resolve entity validation issues")
+        .option("--json", "Output results as JSON")
+        .action(async (opts) => {
+        try {
+            const result = runIssues(process.cwd());
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+                return;
+            }
+            if (result.total === 0) {
+                process.stdout.write("No issues found.\n");
+                return;
+            }
+            const parts = [];
+            if (result.agentNeeded > 0)
+                parts.push(`${result.agentNeeded} need an agent`);
+            if (result.cliResolvable > 0)
+                parts.push(`${result.cliResolvable} resolvable now`);
+            process.stdout.write(`${result.total} issue(s): ${parts.join(", ")}\n\n`);
+            const projectDir = findWhygraphDir(process.cwd());
+            const graphDir = join(projectDir, ".whygraph", "graph");
+            // Agent-needed issues: inline if < 3, MD file if >= 3
+            const agentIssues = result.issues.filter((i) => !isCliResolvable(i));
+            if (agentIssues.length > 0) {
+                if (agentIssues.length < 3) {
+                    for (const issue of agentIssues) {
+                        process.stdout.write(`[AGENT] ${generateAgentPrompt(issue, graphDir)}\n\n`);
+                    }
+                }
+                else {
+                    // Group by missing fields to avoid repeating instructions
+                    const byFields = new Map();
+                    for (const issue of agentIssues) {
+                        const files = readdirSync(graphDir).filter((f) => f.startsWith(issue.entityId));
+                        /* v8 ignore next 1 */
+                        const filePath = files.length > 0 ? `.whygraph/graph/${files[0]}` : `.whygraph/graph/${issue.entityId}.md`;
+                        const key = issue.errors.map((e) => e.field).sort().join(", ");
+                        if (!byFields.has(key))
+                            byFields.set(key, []);
+                        byFields.get(key).push(filePath);
+                    }
+                    const mdLines = [
+                        `For each decision file below, read its existing content and write meaningful content for the missing sections.`,
+                        `Base your additions on the context, decision, and tradeoffs already written.`,
+                        `Do not write placeholder text like "None considered." or "N/A."`,
+                        `The file watcher will automatically clear each issue once the missing sections are present.`,
+                        "",
+                    ];
+                    for (const [fields, files] of byFields) {
+                        mdLines.push(`Missing: ${fields}`);
+                        for (const f of files) {
+                            mdLines.push(`- ${f}`);
+                        }
+                        mdLines.push("");
+                    }
+                    const mdPath = join(projectDir, ".whygraph", "AGENT_ISSUES.md");
+                    writeFileSync(mdPath, mdLines.join("\n"), "utf-8");
+                    process.stdout.write(`${agentIssues.length} agent issues written to .whygraph/AGENT_ISSUES.md\n` +
+                        `Prompt: "Read .whygraph/AGENT_ISSUES.md and resolve each issue."\n\n`);
+                }
+            }
+            // Walk through CLI-resolvable issues interactively
+            const cliIssues = result.issues.filter((i) => isCliResolvable(i));
+            if (cliIssues.length > 0) {
+                const port = getConfiguredPort(projectDir);
+                if (!isServerRunning(port)) {
+                    process.stdout.write(`${cliIssues.length} resolvable issue(s) found.\n` +
+                        `Run 'whygraph up' first so resolved issues are properly reconciled.\n`);
+                    return;
+                }
+                process.stdout.write("--- Resolvable issues ---\n\n");
+                const entities = loadEntitiesFromDisk(graphDir);
+                for (const issue of cliIssues) {
+                    await resolveIssueInteractively(issue, entities, graphDir);
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof UserCancelled) {
+                process.stdout.write("\nCancelled.\n");
+                return;
+            }
+            /* 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/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerMcpCommand(program: Command): void;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,9 @@
+import { startMcpServer } from "../../mcp/server.js";
+export function registerMcpCommand(program) {
+    program
+        .command("mcp")
+        .description("Start the MCP stdio server")
+        .action(/* v8 ignore next 3 */ async () => {
+        await startMcpServer();
+    });
+}

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

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

package/dist/cli/commands/restart.js

@@ -0,0 +1,43 @@
+import { runDown } from "./down.js";
+import { runUp } from "./up.js";
+export async function runRestart(targetDir, options = {}) {
+    const downResult = await runDown(targetDir, options);
+    const upResult = await runUp(targetDir, options);
+    return {
+        stopped: downResult.stopped,
+        ...upResult,
+    };
+}
+export function registerRestartCommand(program) {
+    program
+        .command("restart")
+        .description("Stop and restart 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 runRestart(process.cwd(), { port, json: opts.json });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result) + "\n");
+            }
+            else {
+                if (result.stopped) {
+                    process.stdout.write(`Stopped previous server\n`);
+                }
+                process.stdout.write(`whygraph server running at ${result.url} (pid ${result.pid})\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/serve.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+export interface ServeOptions {
+    port?: number;
+    json?: boolean;
+}
+export interface ServeResult {
+    url: string;
+    entities: number;
+    port: number;
+    stop: () => Promise<void>;
+}
+export declare function findWhygraphDir(startDir: string): string | null;
+export declare function runServe(targetDir: string, options?: ServeOptions): Promise<ServeResult>;
+export declare function registerServeCommand(program: Command): void;

package/dist/cli/commands/serve.js

@@ -0,0 +1,132 @@
+import * as fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ServerCore } from "../../server/core.js";
+import { FileWatcher } from "../../server/watcher.js";
+import { WorktreeWatcher } from "../../server/worktree-watcher.js";
+import { createHttpServer } from "../../server/http.js";
+import { parseEntity } from "../../entity/parser.js";
+// ============================================================
+// Find .whygraph directory
+// ============================================================
+export function findWhygraphDir(startDir) {
+    let current = resolve(startDir);
+    const root = resolve("/");
+    while (current !== root) {
+        const candidate = join(current, ".whygraph");
+        if (existsSync(candidate)) {
+            return current;
+        }
+        const parent = resolve(current, "..");
+        /* v8 ignore next 2 */
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // Check root too
+    /* v8 ignore next 3 */
+    if (existsSync(join(root, ".whygraph"))) {
+        return root;
+    }
+    return null;
+}
+// ============================================================
+// Core Logic
+// ============================================================
+export async function runServe(targetDir, options = {}) {
+    const projectDir = findWhygraphDir(targetDir);
+    if (!projectDir) {
+        throw new Error(`.whygraph/ not found. Run "whygraph init" first.`);
+    }
+    const whygraphDir = join(projectDir, ".whygraph");
+    /* v8 ignore next 1 */
+    const port = options.port ?? 4777;
+    // Create and load ServerCore
+    const core = new ServerCore(whygraphDir);
+    await core.load();
+    // Start file watcher on main graph dir
+    const graphDir = join(whygraphDir, "graph");
+    const mainWatcher = new FileWatcher(graphDir);
+    mainWatcher.start((events) => {
+        for (const event of events) {
+            if (event.type === "deleted" && event.entityId) {
+                core.removeEntity(event.entityId);
+            }
+            else {
+                /* v8 ignore next 1 */
+                if (event.entityId) {
+                    fs.readFile(event.filePath, "utf-8")
+                        .then((content) => {
+                        const entity = parseEntity(content);
+                        /* v8 ignore next 1 */
+                        if (entity) {
+                            core.addOrUpdateEntity(entity.id, entity);
+                        }
+                    })
+                        /* v8 ignore start */
+                        .catch(() => { });
+                    /* v8 ignore stop */
+                }
+            }
+        }
+    });
+    // Start worktree watcher
+    const worktreeWatcher = new WorktreeWatcher(core, projectDir);
+    await worktreeWatcher.startWatching();
+    // Start HTTP server
+    const httpServer = createHttpServer(core, port);
+    await httpServer.start();
+    const url = `http://localhost:${port}`;
+    // Set up graceful shutdown
+    const shutdown = async () => {
+        await httpServer.stop();
+        await worktreeWatcher.stop();
+        await mainWatcher.stop();
+    };
+    /* v8 ignore next 3 */
+    process.on("SIGINT", () => { shutdown().then(() => process.exit(0)); });
+    /* v8 ignore next 3 */
+    process.on("SIGTERM", () => { shutdown().then(() => process.exit(0)); });
+    return {
+        url,
+        entities: core.getAllEntities().length,
+        port,
+        stop: shutdown,
+    };
+}
+// ============================================================
+// CLI Wiring
+// ============================================================
+export function registerServeCommand(program) {
+    program
+        .command("serve")
+        .description("Start the whygraph server")
+        .option("--port <number>", "Port number", "4777")
+        .option("--json", "Output results as JSON")
+        .action(async (opts) => {
+        try {
+            /* v8 ignore next 1 */
+            const port = opts.port ? parseInt(opts.port, 10) : undefined;
+            const result = await runServe(process.cwd(), { port, json: opts.json });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                process.stdout.write(`whygraph server running at ${result.url}\n` +
+                    `  Entities loaded: ${result.entities}\n` +
+                    `  Press Ctrl+C to stop\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/server-utils.d.ts

@@ -0,0 +1,6 @@
+export declare function findWhygraphDir(startDir: string): string | null;
+export declare function getConfiguredPort(projectDir: string): number;
+export declare function killProcessOnPort(port: number): boolean;
+export declare function waitForPortFree(port: number, timeoutMs?: number): Promise<void>;
+export declare function waitForServerReady(port: number, timeoutMs?: number): Promise<void>;
+export declare function isServerRunning(port: number): boolean;