archbyte 0.2.2 → 0.2.5

package/dist/cli/mcp-server.js

@@ -0,0 +1,443 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { loadCredentials, getVerifiedTier, cacheVerifiedTier, resetOfflineActions, checkOfflineAction, } from "./auth.js";
+import { API_BASE, NETWORK_TIMEOUT_MS } from "./constants.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// At runtime, __dirname = dist/cli/ — project root is two levels up
+const PROJECT_ROOT = path.resolve(__dirname, "..", "..");
+const BIN_PATH = path.join(PROJECT_ROOT, "bin", "archbyte.js");
+// Read version from package.json
+function getVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, "package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+// ─── ANSI strip ───
+const ANSI_RE = /\x1B\[[0-9;]*[A-Za-z]/g;
+function stripAnsi(s) {
+    return s.replace(ANSI_RE, "");
+}
+// ─── Auth check ───
+function checkAuth() {
+    const creds = loadCredentials();
+    if (!creds) {
+        return {
+            ok: false,
+            error: "Not logged in. Run `archbyte login` to sign in.",
+        };
+    }
+    if (new Date(creds.expiresAt) < new Date()) {
+        return {
+            ok: false,
+            error: "Session expired. Run `archbyte login` to refresh.",
+        };
+    }
+    return { ok: true };
+}
+// ─── License check ───
+async function checkLicense(action) {
+    const creds = loadCredentials();
+    if (!creds) {
+        return {
+            allowed: false,
+            reason: "Not logged in. Run `archbyte login` to sign in.",
+        };
+    }
+    try {
+        const res = await fetch(`${API_BASE}/api/v1/check-usage`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ action }),
+            signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),
+        });
+        if (res.status === 401) {
+            return {
+                allowed: false,
+                reason: "Session invalid. Run `archbyte login` again.",
+            };
+        }
+        if (!res.ok) {
+            return handleOffline();
+        }
+        const data = (await res.json());
+        const tier = data.tier === "premium" ? "premium" : "free";
+        cacheVerifiedTier(tier, creds.email);
+        resetOfflineActions();
+        if (!data.allowed) {
+            return {
+                allowed: false,
+                reason: data.message ?? "Scan not allowed. Check your account status.",
+            };
+        }
+        return { allowed: true };
+    }
+    catch {
+        return handleOffline();
+    }
+}
+function handleOffline() {
+    const { allowed, reason } = checkOfflineAction();
+    if (!allowed) {
+        return {
+            allowed: false,
+            reason: reason ??
+                "License server unreachable and offline actions not permitted.",
+        };
+    }
+    return { allowed: true };
+}
+function runArchbyte(args, cwd, timeoutMs = 300_000) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [BIN_PATH, ...args], {
+            cwd,
+            env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: timeoutMs,
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("close", (code) => {
+            resolve({
+                stdout: stripAnsi(Buffer.concat(stdoutChunks).toString("utf-8")),
+                stderr: stripAnsi(Buffer.concat(stderrChunks).toString("utf-8")),
+                exitCode: code ?? 1,
+            });
+        });
+        child.on("error", (err) => {
+            resolve({
+                stdout: "",
+                stderr: `Failed to spawn archbyte: ${err.message}`,
+                exitCode: 1,
+            });
+        });
+    });
+}
+// ─── Result helpers ───
+function errorResult(msg) {
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+function defineTools() {
+    return [
+        {
+            tool: {
+                name: "archbyte_analyze",
+                description: "Run AI-powered architecture analysis on a codebase. Scans source code and produces a structured analysis of components, services, connections, and data flows. Requires a configured model provider (archbyte init) unless --static is used.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                        static: {
+                            type: "boolean",
+                            description: "Static-only analysis. No model needed, free.",
+                        },
+                        provider: {
+                            type: "string",
+                            description: "Model provider: anthropic, openai, google",
+                        },
+                        apiKey: {
+                            type: "string",
+                            description: "Model API key (overrides config)",
+                        },
+                        force: {
+                            type: "boolean",
+                            description: "Force full re-scan (skip incremental detection)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: "analyze",
+            handler: async (params) => {
+                const args = ["analyze"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.dir)
+                    args.push("--dir", params.dir);
+                if (params.static)
+                    args.push("--static");
+                if (params.provider)
+                    args.push("--provider", params.provider);
+                if (params.apiKey)
+                    args.push("--api-key", params.apiKey);
+                if (params.force)
+                    args.push("--force");
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "Analysis complete.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_generate",
+                description: "Generate an interactive architecture diagram from analysis output. Reads analysis.json and produces architecture.json for the visualization UI.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        input: {
+                            type: "string",
+                            description: "Input analysis path (default: .archbyte/analysis.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: "generate",
+            handler: async (params) => {
+                const args = ["generate"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.input)
+                    args.push("--input", params.input);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "Diagram generated.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_validate",
+                description: "Run architecture fitness function rules against the current diagram. Returns structured JSON results with pass/fail status for each rule. Useful for CI/CD pipelines and automated quality checks.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        diagram: {
+                            type: "string",
+                            description: "Path to architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        config: {
+                            type: "string",
+                            description: "Path to archbyte.yaml config",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "premium",
+            licenseAction: "analyze",
+            handler: async (params) => {
+                const args = ["validate", "--ci"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.diagram)
+                    args.push("--diagram", params.diagram);
+                if (params.config)
+                    args.push("--config", params.config);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "Validation complete.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_export",
+                description: "Export architecture diagram to various formats: mermaid, markdown, json, plantuml, or dot. Returns the exported content as text.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        format: {
+                            type: "string",
+                            enum: ["mermaid", "markdown", "json", "plantuml", "dot"],
+                            description: "Output format (default: mermaid)",
+                        },
+                        diagram: {
+                            type: "string",
+                            description: "Path to architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: null,
+            handler: async (params) => {
+                const args = ["export"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.format)
+                    args.push("--format", params.format);
+                if (params.diagram)
+                    args.push("--diagram", params.diagram);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "Export complete.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_stats",
+                description: "Show architecture health dashboard with metrics: node count, edge count, complexity scores, and component breakdown.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        diagram: {
+                            type: "string",
+                            description: "Path to architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: null,
+            handler: async (params) => {
+                const args = ["stats"];
+                const cwd = params.dir ?? process.cwd();
+                if (params.diagram)
+                    args.push("--diagram", params.diagram);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "No stats available.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_diff",
+                description: "Compare two architecture snapshots to detect drift. Shows added, removed, and modified nodes and edges between a baseline and current diagram.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        baseline: {
+                            type: "string",
+                            description: "Path to baseline architecture JSON",
+                        },
+                        current: {
+                            type: "string",
+                            description: "Path to current architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                    required: ["baseline"],
+                },
+            },
+            minTier: "free",
+            licenseAction: null,
+            handler: async (params) => {
+                const args = ["diff", "--baseline", params.baseline];
+                const cwd = params.dir ?? process.cwd();
+                if (params.current)
+                    args.push("--current", params.current);
+                const result = await runArchbyte(args, cwd);
+                const output = (result.stdout + (result.stderr ? `\n${result.stderr}` : "")).trim();
+                return textResult(output || "No differences found.", result.exitCode !== 0);
+            },
+        },
+        {
+            tool: {
+                name: "archbyte_read_diagram",
+                description: "Read the current architecture diagram JSON. Returns the full architecture.json content including all nodes, edges, and metadata. Useful for understanding the project structure without re-running analysis.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        diagram: {
+                            type: "string",
+                            description: "Path to architecture JSON (default: .archbyte/architecture.json)",
+                        },
+                        dir: {
+                            type: "string",
+                            description: "Project root directory (default: current directory)",
+                        },
+                    },
+                },
+            },
+            minTier: "free",
+            licenseAction: null,
+            handler: async (params) => {
+                const cwd = params.dir ?? process.cwd();
+                const diagramPath = params.diagram ??
+                    path.join(cwd, ".archbyte", "architecture.json");
+                const resolved = path.isAbsolute(diagramPath)
+                    ? diagramPath
+                    : path.join(cwd, diagramPath);
+                try {
+                    const content = fs.readFileSync(resolved, "utf-8");
+                    return textResult(content);
+                }
+                catch {
+                    return errorResult(`Diagram not found at ${resolved}. Run \`archbyte analyze\` then \`archbyte generate\` first.`);
+                }
+            },
+        },
+    ];
+}
+// ─── Tier comparison ───
+const TIER_RANK = { free: 0, premium: 1 };
+function tierSatisfies(userTier, required) {
+    return TIER_RANK[userTier] >= TIER_RANK[required];
+}
+// ─── Start MCP server ───
+export async function startMcpServer() {
+    const allTools = defineTools();
+    const toolMap = new Map(allTools.map((t) => [t.tool.name, t]));
+    const server = new Server({ name: "archbyte", version: getVersion() }, { capabilities: { tools: { listChanged: true } } });
+    // ─── tools/list — filtered by user tier ───
+    // Always show free-tier tools (even when not logged in) so the AI agent
+    // can attempt to call them and receive the "please login" error message.
+    // Premium tools are only shown to premium users.
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const auth = checkAuth();
+        const userTier = auth.ok ? getVerifiedTier() : "free";
+        const visible = allTools
+            .filter((t) => tierSatisfies(userTier, t.minTier))
+            .map((t) => t.tool);
+        return { tools: visible };
+    });
+    // ─── tools/call — auth + license + execute ───
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const def = toolMap.get(name);
+        if (!def) {
+            return errorResult(`Unknown tool: ${name}`);
+        }
+        // Auth check
+        const auth = checkAuth();
+        if (!auth.ok)
+            return errorResult(auth.error);
+        // Tier check (defense in depth — tool might not be in list but called directly)
+        const userTier = getVerifiedTier();
+        if (!tierSatisfies(userTier, def.minTier)) {
+            return errorResult(`${name} requires a Pro subscription. Upgrade at https://archbyte.heartbyte.io`);
+        }
+        // License check for gated tools
+        if (def.licenseAction) {
+            const license = await checkLicense(def.licenseAction);
+            if (!license.allowed)
+                return errorResult(license.reason);
+        }
+        return def.handler(args ?? {});
+    });
+    // ─── Connect transport ───
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/cli/mcp.d.ts

@@ -0,0 +1 @@
+export declare function handleMcpInstall(): Promise<void>;

package/dist/cli/mcp.js

@@ -0,0 +1,102 @@
+import { execSync, spawnSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+function isInPath(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function handleMcpInstall() {
+    console.log();
+    console.log(chalk.bold.cyan("ArchByte MCP Setup"));
+    console.log();
+    let configured = false;
+    // ─── Claude Code ───
+    if (isInPath("claude")) {
+        console.log(chalk.white("Detected Claude Code."));
+        const result = spawnSync("claude", ["mcp", "add", "archbyte", "--transport", "stdio", "--", "npx", "-y", "archbyte@latest", "mcp"], { stdio: "inherit" });
+        if (result.status === 0) {
+            console.log(chalk.green("  Configured Claude Code MCP server."));
+            configured = true;
+        }
+        else {
+            console.log(chalk.yellow("  Failed to configure Claude Code. See error above."));
+        }
+        console.log();
+    }
+    // ─── Codex CLI ───
+    const codexDir = path.join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".codex");
+    const codexConfig = path.join(codexDir, "config.toml");
+    if (fs.existsSync(codexDir)) {
+        console.log(chalk.white("Detected Codex CLI."));
+        let existing = "";
+        try {
+            existing = fs.readFileSync(codexConfig, "utf-8");
+        }
+        catch {
+            // File doesn't exist yet — we'll create it
+        }
+        if (existing.includes("[mcp_servers.archbyte]")) {
+            console.log(chalk.gray("  Codex already configured for archbyte."));
+            configured = true;
+        }
+        else {
+            const block = `
+[mcp_servers.archbyte]
+type = "stdio"
+command = "npx"
+args = ["-y", "archbyte@latest", "mcp"]
+`;
+            fs.appendFileSync(codexConfig, block, "utf-8");
+            console.log(chalk.green("  Configured Codex CLI MCP server."));
+            configured = true;
+        }
+        console.log();
+    }
+    // ─── Fallback instructions ───
+    if (!configured) {
+        console.log(chalk.yellow("No supported AI coding tool detected."));
+        console.log();
+    }
+    // ─── Usage examples ───
+    if (configured) {
+        console.log(chalk.bold("What to do next:"));
+        console.log();
+        console.log(chalk.white("  Open your AI coding tool and ask it to use ArchByte. For example:"));
+        console.log();
+        console.log(chalk.cyan('    "Analyze the architecture of this project"'));
+        console.log(chalk.cyan('    "Export the architecture as a Mermaid diagram"'));
+        console.log(chalk.cyan('    "Show me the architecture stats"'));
+        console.log(chalk.cyan('    "Read the current architecture diagram"'));
+        console.log();
+        console.log(chalk.gray("  Your AI tool will call ArchByte tools automatically via MCP."));
+        console.log(chalk.gray("  No commands to memorize. Just describe what you need."));
+        console.log();
+    }
+    console.log(chalk.bold("Manual setup:"));
+    console.log();
+    console.log(chalk.white("  Claude Code:"));
+    console.log(chalk.gray("    claude mcp add archbyte --transport stdio -- npx -y archbyte@latest mcp"));
+    console.log();
+    console.log(chalk.white("  Codex CLI:"));
+    console.log(chalk.gray("    Add to ~/.codex/config.toml:"));
+    console.log(chalk.gray('    [mcp_servers.archbyte]'));
+    console.log(chalk.gray('    type = "stdio"'));
+    console.log(chalk.gray('    command = "npx"'));
+    console.log(chalk.gray('    args = ["-y", "archbyte@latest", "mcp"]'));
+    console.log();
+    console.log(chalk.bold("  Available MCP tools:"));
+    console.log(chalk.gray("    archbyte_analyze        Scan codebase with AI agents"));
+    console.log(chalk.gray("    archbyte_generate       Generate diagram from analysis"));
+    console.log(chalk.gray("    archbyte_validate       Run fitness rules (Pro)"));
+    console.log(chalk.gray("    archbyte_export         Export to Mermaid, PlantUML, DOT, etc."));
+    console.log(chalk.gray("    archbyte_stats          Architecture health metrics"));
+    console.log(chalk.gray("    archbyte_diff           Compare snapshots, detect drift"));
+    console.log(chalk.gray("    archbyte_read_diagram   Read current architecture JSON"));
+    console.log();
+}

package/dist/cli/patrol.js

@@ -106,7 +106,7 @@ function printPatrolResult(record, cycleNum) {
     const time = new Date(record.timestamp).toLocaleTimeString();
     const status = record.passed ? chalk.green("HEALTHY") : chalk.red("VIOLATION");
     console.log();
-    console.log(chalk.bold.cyan(`  Patrol #${cycleNum} — ${time} — ${status}`));
+    console.log(chalk.bold.cyan(`  Patrol #${cycleNum} | ${time} | ${status}`));
     if (record.newViolations.length > 0) {
         console.log(chalk.red(`  ${record.newViolations.length} new violation(s):`));
         for (const v of record.newViolations) {
@@ -121,7 +121,7 @@ function printPatrolResult(record, cycleNum) {
         }
     }
     if (record.newViolations.length === 0 && record.resolvedViolations.length === 0) {
-        console.log(chalk.gray(`  No changes — ${record.errors} errors, ${record.warnings} warnings`));
+        console.log(chalk.gray(`  No changes. ${record.errors} errors, ${record.warnings} warnings`));
     }
 }
 function printHistory(patrolDir) {
@@ -137,7 +137,7 @@ function printHistory(patrolDir) {
     }
     const projectName = process.cwd().split("/").pop() || "project";
     console.log();
-    console.log(chalk.bold.cyan(`  ArchByte Patrol History — ${projectName}`));
+    console.log(chalk.bold.cyan(`  ArchByte Patrol History: ${projectName}`));
     console.log();
     // Show last 20 records (skip malformed lines)
     const records = lines.slice(-20).flatMap((l) => {
@@ -208,7 +208,7 @@ export async function handlePatrol(options) {
     const intervalStr = options.interval || "5m";
     const action = options.onViolation || "log";
     console.log();
-    console.log(chalk.bold.cyan(`  ArchByte Patrol — ${projectName}`));
+    console.log(chalk.bold.cyan(`  ArchByte Patrol: ${projectName}`));
     console.log(chalk.gray(`  Interval: ${intervalStr} | On violation: ${action}`));
     console.log(chalk.gray(`  History: ${path.join(PATROL_DIR, HISTORY_FILE)}`));
     console.log(chalk.gray("  Press Ctrl+C to stop."));

package/dist/cli/run.d.ts

@@ -7,6 +7,7 @@ interface RunOptions {
     verbose?: boolean;
     force?: boolean;
     dryRun?: boolean;
+    dir?: string;
 }
 export declare function handleRun(options: RunOptions): Promise<void>;
 export {};

package/dist/cli/run.js

@@ -1,11 +1,8 @@
-import chalk from "chalk";
 import { handleAnalyze } from "./analyze.js";
 import { handleServe } from "./serve.js";
+import { DEFAULT_PORT } from "./constants.js";
 export async function handleRun(options) {
-    const port = options.port || 3847;
-    console.log();
-    console.log(chalk.bold.cyan("  ArchByte Run"));
-    console.log();
+    const port = options.port || DEFAULT_PORT;
     // 1. Analyze (includes auto-generate)
     await handleAnalyze({
         verbose: options.verbose,
@@ -15,11 +12,10 @@ export async function handleRun(options) {
         apiKey: options.apiKey,
         force: options.force,
         dryRun: options.dryRun,
+        dir: options.dir,
     });
     if (options.dryRun)
         return;
     // 2. Serve the UI
-    console.log(chalk.bold.cyan("  Starting UI..."));
-    console.log();
     await handleServe({ port });
 }

package/dist/cli/serve.js

@@ -1,12 +1,13 @@
 import * as path from "path";
 import * as fs from "fs";
 import chalk from "chalk";
+import { DEFAULT_PORT } from "./constants.js";
 /**
  * Start the ArchByte UI server
  */
 export async function handleServe(options) {
     const rootDir = process.cwd();
-    const port = options.port || 3847;
+    const port = options.port || DEFAULT_PORT;
     const diagramPath = options.diagram
         ? path.resolve(rootDir, options.diagram)
         : path.join(rootDir, ".archbyte", "architecture.json");
@@ -22,7 +23,7 @@ export async function handleServe(options) {
             // ignore
         }
     }
-    console.log(chalk.cyan(`🏗️  ArchByte - ${projectName}`));
+    console.log(chalk.cyan(`🏗️  ArchByte - See what agents build. As they build it.`));
     console.log(chalk.gray(`Diagram: ${path.relative(rootDir, diagramPath)}`));
     console.log(chalk.gray(`Port: ${port}`));
     console.log();