whygraph 0.1.0

package/dist/cli/commands/server-utils.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { execSync } from "node:child_process";
+import * as yaml from "js-yaml";
+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;
+    }
+    /* v8 ignore next 3 */
+    if (existsSync(join(root, ".whygraph"))) {
+        return root;
+    }
+    return null;
+}
+export function getConfiguredPort(projectDir) {
+    const configPath = join(projectDir, ".whygraph", "config.yaml");
+    try {
+        const content = readFileSync(configPath, "utf-8");
+        const config = yaml.load(content);
+        return config.serverPort ?? 4777;
+    }
+    catch {
+        return 4777;
+    }
+}
+export function killProcessOnPort(port) {
+    try {
+        const result = execSync(`lsof -ti:${port}`, { encoding: "utf-8" }).trim();
+        if (result) {
+            const pids = result.split("\n").map((p) => p.trim()).filter(Boolean);
+            for (const pid of pids) {
+                try {
+                    execSync(`kill ${pid}`);
+                }
+                catch {
+                    // Process may have already exited
+                }
+            }
+            return true;
+        }
+    }
+    catch {
+        // No process on that port
+    }
+    return false;
+}
+export async function waitForPortFree(port, timeoutMs = 3000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            await fetch(`http://localhost:${port}/api/health`);
+            await new Promise((r) => setTimeout(r, 200));
+        }
+        catch {
+            return;
+        }
+    }
+    throw new Error(`Port ${port} still in use after ${timeoutMs}ms`);
+}
+export async function waitForServerReady(port, timeoutMs = 5000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const res = await fetch(`http://localhost:${port}/api/health`);
+            /* v8 ignore next 1 */
+            if (res.ok)
+                return;
+        }
+        catch {
+            // Not ready yet
+        }
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    throw new Error(`Server not ready on port ${port} after ${timeoutMs}ms`);
+}
+export function isServerRunning(port) {
+    try {
+        execSync(`lsof -ti:${port}`, { encoding: "utf-8" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+export interface StatusResult {
+    serverRunning: boolean;
+    serverPort: number;
+    entityCount?: number;
+    nodeCount?: number;
+    decisionCount?: number;
+    error?: string;
+}
+export declare function runStatus(targetDir: string): Promise<StatusResult>;
+export declare function registerStatusCommand(program: Command): void;

package/dist/cli/commands/status.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import { findWhygraphDir } from "./serve.js";
+// ============================================================
+// Core Logic
+// ============================================================
+export async function runStatus(targetDir) {
+    const projectDir = findWhygraphDir(targetDir);
+    if (!projectDir) {
+        throw new Error(`.whygraph/ not found. Run "whygraph init" first.`);
+    }
+    const configPath = join(projectDir, ".whygraph", "config.yaml");
+    if (!existsSync(configPath)) {
+        throw new Error(`.whygraph/config.yaml not found. Run "whygraph init" first.`);
+    }
+    const raw = readFileSync(configPath, "utf-8");
+    const config = yaml.load(raw);
+    const port = config.serverPort;
+    // Try to connect to the server
+    try {
+        const healthRes = await fetch(`http://localhost:${port}/api/health`);
+        if (!healthRes.ok) {
+            return { serverRunning: false, serverPort: port, error: "Health check failed" };
+        }
+        // Query GraphQL for status
+        const gqlRes = await fetch(`http://localhost:${port}/api/graphql`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                query: `{ status { running entityCount nodeCount decisionCount } }`,
+            }),
+        });
+        if (!gqlRes.ok) {
+            return { serverRunning: true, serverPort: port, error: "GraphQL query failed" };
+        }
+        const gqlData = (await gqlRes.json());
+        const status = gqlData.data?.status;
+        if (!status) {
+            return { serverRunning: true, serverPort: port, error: "Unexpected GraphQL response" };
+        }
+        return {
+            serverRunning: true,
+            serverPort: port,
+            entityCount: status.entityCount,
+            nodeCount: status.nodeCount,
+            decisionCount: status.decisionCount,
+        };
+    }
+    catch {
+        return { serverRunning: false, serverPort: port };
+    }
+}
+// ============================================================
+// CLI Wiring
+// ============================================================
+export function registerStatusCommand(program) {
+    program
+        .command("status")
+        .description("Check the whygraph server status and entity counts")
+        .option("--json", "Output results as JSON")
+        .action(async (opts) => {
+        try {
+            const result = await runStatus(process.cwd());
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                if (result.serverRunning) {
+                    /* v8 ignore start */
+                    const ec = result.entityCount ?? "unknown";
+                    const nc = result.nodeCount ?? "unknown";
+                    const dc = result.decisionCount ?? "unknown";
+                    /* v8 ignore stop */
+                    process.stdout.write(`Server: running (port ${result.serverPort})\n` +
+                        `  Entities: ${ec}\n` +
+                        `  Nodes: ${nc}\n` +
+                        `  Decisions: ${dc}\n`);
+                }
+                else {
+                    process.stdout.write(`Server: not running (port ${result.serverPort})\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/up.d.ts

@@ -0,0 +1,13 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import type { Command } from "commander";
+export declare function runUp(targetDir: string, options?: {
+    port?: number;
+    json?: boolean;
+    spawner?: typeof nodeSpawn;
+    waitForReady?: (port: number) => Promise<void>;
+}): Promise<{
+    url: string;
+    port: number;
+    pid: number;
+}>;
+export declare function registerUpCommand(program: Command): void;

package/dist/cli/commands/up.js

@@ -0,0 +1,62 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { findWhygraphDir, getConfiguredPort, isServerRunning, waitForServerReady, } from "./server-utils.js";
+export async function runUp(targetDir, options = {}) {
+    const projectDir = findWhygraphDir(targetDir);
+    if (!projectDir) {
+        throw new Error(`.whygraph/ not found. Run "whygraph init" first.`);
+    }
+    const port = options.port ?? getConfiguredPort(projectDir);
+    if (isServerRunning(port)) {
+        throw new Error(`Server already running on port ${port}. Use "whygraph restart" or "whygraph down" first.`);
+    }
+    // Spawn the serve command as a detached background process
+    const spawn = options.spawner ?? nodeSpawn;
+    const serveScript = join(dirname(fileURLToPath(import.meta.url)), "..", "index.js");
+    const child = spawn(process.execPath, [serveScript, "serve", "--port", String(port)], {
+        detached: true,
+        stdio: "ignore",
+        cwd: projectDir,
+    });
+    child.unref();
+    const pid = child.pid;
+    // Wait for the server to be ready
+    const waitFn = options.waitForReady ?? waitForServerReady;
+    await waitFn(port);
+    return {
+        url: `http://localhost:${port}`,
+        port,
+        pid,
+    };
+}
+export function registerUpCommand(program) {
+    program
+        .command("up")
+        .description("Start the whygraph server in the background")
+        .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 runUp(process.cwd(), { port, json: opts.json });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result) + "\n");
+            }
+            else {
+                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/validate.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+export interface FileError {
+    file: string;
+    field?: string;
+    message: string;
+    severity: "error" | "warning";
+}
+export interface ValidateResult {
+    filesChecked: number;
+    entitiesParsed: number;
+    errors: FileError[];
+}
+export declare function runValidate(whygraphDir: string): Promise<ValidateResult>;
+export declare function registerValidateCommand(program: Command): void;

package/dist/cli/commands/validate.js

@@ -0,0 +1,88 @@
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseEntity } from "../../entity/parser.js";
+import { validateEntity, validateEntityRefs } from "../../entity/validate.js";
+// ============================================================
+// Core Logic
+// ============================================================
+export async function runValidate(whygraphDir) {
+    const graphDir = join(whygraphDir, ".whygraph", "graph");
+    if (!existsSync(graphDir)) {
+        return { filesChecked: 0, entitiesParsed: 0, errors: [] };
+    }
+    const files = readdirSync(graphDir).filter((f) => f.endsWith(".md"));
+    const errors = [];
+    const entityMap = new Map();
+    const filePathMap = new Map(); // entity id → file path
+    // First pass: parse all entities into a map
+    for (const file of files) {
+        const filePath = join(graphDir, file);
+        const content = readFileSync(filePath, "utf-8");
+        const entity = parseEntity(content);
+        if (entity === null) {
+            errors.push({
+                file: filePath,
+                message: "Failed to parse entity from file",
+                severity: "error",
+            });
+            continue;
+        }
+        entityMap.set(entity.id, entity);
+        filePathMap.set(entity.id, filePath);
+    }
+    // Second pass: schema + cross-reference validation
+    for (const [id, entity] of entityMap) {
+        const filePath = filePathMap.get(id);
+        const schemaResult = validateEntity(entity);
+        for (const err of schemaResult.errors) {
+            errors.push({ file: filePath, field: err.field, message: err.message, severity: err.severity });
+        }
+        const refErrors = validateEntityRefs(entity, entityMap);
+        for (const err of refErrors) {
+            errors.push({ file: filePath, field: err.field, message: err.message, severity: err.severity });
+        }
+    }
+    return {
+        filesChecked: files.length,
+        entitiesParsed: entityMap.size,
+        errors,
+    };
+}
+// ============================================================
+// CLI Wiring
+// ============================================================
+function formatTable(result) {
+    const lines = [];
+    if (result.errors.length === 0) {
+        lines.push(`Checked ${result.filesChecked} file(s), ${result.entitiesParsed} entity(ies) parsed. No errors found.`);
+        return lines.join("\n");
+    }
+    lines.push("FILE                           FIELD        SEVERITY  MESSAGE");
+    lines.push("─".repeat(90));
+    for (const err of result.errors) {
+        /* v8 ignore next 1 */
+        const fileName = err.file.split("/").pop() ?? err.file;
+        const field = err.field ?? "-";
+        lines.push(`${fileName.padEnd(30)} ${field.padEnd(12)} ${err.severity.padEnd(9)} ${err.message}`);
+    }
+    lines.push("");
+    lines.push(`Checked ${result.filesChecked} file(s), ${result.entitiesParsed} entity(ies) parsed. ${result.errors.length} error(s) found.`);
+    return lines.join("\n");
+}
+export function registerValidateCommand(program) {
+    program
+        .command("validate")
+        .description("Validate all entity files in .whygraph/graph/")
+        .option("--json", "Output results as JSON")
+        .action(async (opts) => {
+        const result = await runValidate(process.cwd());
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        }
+        else {
+            process.stdout.write(formatTable(result) + "\n");
+        }
+        const hasErrors = result.errors.some((e) => e.severity === "error");
+        process.exitCode = hasErrors ? 1 : 0;
+    });
+}

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

@@ -0,0 +1,7 @@
+import type { Command } from "commander";
+export declare function runViz(targetDir: string, options?: {
+    port?: number;
+}): Promise<{
+    url: string;
+}>;
+export declare function registerVizCommand(program: Command): void;

package/dist/cli/commands/viz.js

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+// ============================================================
+// Find .whygraph directory (reuse serve's logic inline)
+// ============================================================
+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;
+    }
+    /* v8 ignore next 3 */
+    if (existsSync(join(root, ".whygraph"))) {
+        return root;
+    }
+    return null;
+}
+// ============================================================
+// Core Logic
+// ============================================================
+export async function runViz(targetDir, options = {}) {
+    const projectDir = findWhygraphDir(targetDir);
+    if (!projectDir) {
+        throw new Error(`.whygraph/ not found. Run "whygraph init" first.`);
+    }
+    const port = options.port ?? 4777;
+    const url = `http://localhost:${port}`;
+    // Check if server is running via health check
+    let serverRunning = false;
+    try {
+        const response = await fetch(`${url}/api/health`);
+        if (response.ok) {
+            serverRunning = true;
+        }
+    }
+    catch {
+        // Server not running
+    }
+    // If not running, start it in background
+    if (!serverRunning) {
+        const child = spawn("whygraph", ["serve", "--port", String(port)], {
+            cwd: projectDir,
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+        // Brief wait for server to start
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    // Open browser
+    const open = await import("open");
+    await open.default(url);
+    return { url };
+}
+// ============================================================
+// CLI Wiring
+// ============================================================
+export function registerVizCommand(program) {
+    program
+        .command("viz")
+        .description("Open the whygraph visualization in a browser")
+        .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 runViz(process.cwd(), { port });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                process.stdout.write(`Opening whygraph at ${result.url}\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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+import { registerConfigCommand } from "./commands/config.js";
+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 { registerRestartCommand } from "./commands/restart.js";
+import { registerServeCommand } from "./commands/serve.js";
+import { registerStatusCommand } from "./commands/status.js";
+import { registerUpCommand } from "./commands/up.js";
+import { registerValidateCommand } from "./commands/validate.js";
+import { registerVizCommand } from "./commands/viz.js";
+const program = new Command();
+program
+    .name("whygraph")
+    .description("The graph of why — so your agent knows before it touches anything.")
+    .version(version);
+registerConfigCommand(program);
+registerDownCommand(program);
+registerInitCommand(program);
+registerIssuesCommand(program);
+registerMcpCommand(program);
+registerRestartCommand(program);
+registerServeCommand(program);
+registerStatusCommand(program);
+registerUpCommand(program);
+registerValidateCommand(program);
+registerVizCommand(program);
+program.parse();

package/dist/entity/id.d.ts

@@ -0,0 +1,8 @@
+export interface IdOptions {
+    prefix?: string;
+    length?: number;
+}
+export declare function generateId(options?: IdOptions): string;
+export declare function slugify(title: string): string;
+export declare function toFilename(id: string, title: string): string;
+export declare function parseFilename(filename: string): string | null;

package/dist/entity/id.js

@@ -0,0 +1,48 @@
+import { customAlphabet } from "nanoid";
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+const DEFAULT_PREFIX = "wg-";
+const DEFAULT_LENGTH = 4;
+const MAX_SLUG_LENGTH = 50;
+export function generateId(options) {
+    const prefix = options?.prefix ?? DEFAULT_PREFIX;
+    const length = options?.length ?? DEFAULT_LENGTH;
+    const nanoid = customAlphabet(ALPHABET, length);
+    return `${prefix}${nanoid()}`;
+}
+export function slugify(title) {
+    let slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    if (slug.length > MAX_SLUG_LENGTH) {
+        slug = slug.slice(0, MAX_SLUG_LENGTH).replace(/-$/, "");
+    }
+    return slug;
+}
+export function toFilename(id, title) {
+    const slug = slugify(title);
+    if (!slug) {
+        return `${id}.md`;
+    }
+    return `${id}--${slug}.md`;
+}
+export function parseFilename(filename) {
+    // Strip directory path
+    const base = filename.includes("/")
+        ? filename.slice(filename.lastIndexOf("/") + 1)
+        : filename;
+    // Must end with .md
+    if (!base.endsWith(".md")) {
+        return null;
+    }
+    const withoutExt = base.slice(0, -3);
+    // Try double-dash split first
+    const ddIndex = withoutExt.indexOf("--");
+    const id = ddIndex >= 0 ? withoutExt.slice(0, ddIndex) : withoutExt;
+    // Validate ID looks like prefix + nanoid
+    if (!/^[a-z]+-[0-9a-z]+$/.test(id)) {
+        return null;
+    }
+    return id;
+}

package/dist/entity/issues.d.ts

@@ -0,0 +1,12 @@
+import type { ValidationError } from "./validate.js";
+export interface EntityIssue {
+    entityId: string;
+    errors: ValidationError[];
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function writeIssue(whygraphDir: string, entityId: string, errors: ValidationError[]): EntityIssue;
+export declare function readIssue(whygraphDir: string, entityId: string): EntityIssue | null;
+export declare function deleteIssue(whygraphDir: string, entityId: string): boolean;
+export declare function listIssues(whygraphDir: string): EntityIssue[];
+export declare function reconcileIssue(whygraphDir: string, entityId: string, errors: ValidationError[]): EntityIssue | null;

package/dist/entity/issues.js

@@ -0,0 +1,68 @@
+import { writeFileSync, readFileSync, readdirSync, unlinkSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+function issuesDir(whygraphDir) {
+    return join(whygraphDir, "issues");
+}
+function issueFilePath(whygraphDir, entityId) {
+    return join(issuesDir(whygraphDir), `${entityId}.json`);
+}
+export function writeIssue(whygraphDir, entityId, errors) {
+    const dir = issuesDir(whygraphDir);
+    mkdirSync(dir, { recursive: true });
+    const now = new Date().toISOString();
+    const existing = readIssue(whygraphDir, entityId);
+    const issue = {
+        entityId,
+        errors,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+    };
+    writeFileSync(issueFilePath(whygraphDir, entityId), JSON.stringify(issue, null, 2) + "\n", "utf-8");
+    return issue;
+}
+export function readIssue(whygraphDir, entityId) {
+    const filePath = issueFilePath(whygraphDir, entityId);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        /* v8 ignore next 1 */
+        return null;
+    }
+}
+export function deleteIssue(whygraphDir, entityId) {
+    const filePath = issueFilePath(whygraphDir, entityId);
+    if (!existsSync(filePath))
+        return false;
+    unlinkSync(filePath);
+    return true;
+}
+export function listIssues(whygraphDir) {
+    const dir = issuesDir(whygraphDir);
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+    const issues = [];
+    for (const file of files) {
+        try {
+            const raw = readFileSync(join(dir, file), "utf-8");
+            issues.push(JSON.parse(raw));
+        }
+        catch {
+            // Skip corrupted issue files
+        }
+    }
+    return issues;
+}
+export function reconcileIssue(whygraphDir, entityId, errors) {
+    const hasErrors = errors.some((e) => e.severity === "error");
+    const hasWarnings = errors.length > 0;
+    if (hasErrors || hasWarnings) {
+        return writeIssue(whygraphDir, entityId, errors);
+    }
+    deleteIssue(whygraphDir, entityId);
+    return null;
+}

package/dist/entity/parser.d.ts

@@ -0,0 +1,6 @@
+import type { Entity } from "./types.js";
+/**
+ * Parse a markdown string with YAML front matter into a typed Entity object.
+ * Returns null for unparseable content.
+ */
+export declare function parseEntity(content: string): Entity | null;