archbyte 0.1.0

package/dist/cli/generate.js

@@ -0,0 +1,213 @@
+import * as path from "path";
+import * as fs from "fs";
+import chalk from "chalk";
+import { generateArchitecture } from "../server/src/generator/index.js";
+/**
+ * Generate excalidraw diagram from analysis JSON
+ */
+export async function handleGenerate(options) {
+    const rootDir = process.cwd();
+    console.log();
+    console.log(chalk.bold.cyan("⚡ ArchByte Generator"));
+    console.log(chalk.gray("Generating architecture diagram from analysis..."));
+    console.log();
+    try {
+        // Find input file
+        const inputPath = options.input || path.join(rootDir, ".archbyte", "analysis.json");
+        if (!fs.existsSync(inputPath)) {
+            console.error(chalk.red(`Analysis file not found: ${inputPath}`));
+            console.error(chalk.gray("Run /analyze in Claude Code first, or provide --input path"));
+            process.exit(1);
+        }
+        // Load analysis
+        const analysisContent = fs.readFileSync(inputPath, "utf-8");
+        let analysis;
+        try {
+            analysis = JSON.parse(analysisContent);
+        }
+        catch {
+            console.error(chalk.red(`Invalid JSON in analysis file: ${inputPath}`));
+            process.exit(1);
+        }
+        if (options.verbose) {
+            console.log(chalk.gray(`Loaded analysis from: ${inputPath}`));
+            console.log(chalk.gray(`  Components: ${analysis.components.length}`));
+            console.log(chalk.gray(`  Databases: ${analysis.databases.length}`));
+            console.log(chalk.gray(`  External Services: ${analysis.externalServices.length}`));
+            console.log(chalk.gray(`  Connections: ${analysis.connections.length}`));
+        }
+        // Convert to ParsedProject format
+        const project = {
+            name: analysis.project.name,
+            description: analysis.project.description,
+            components: analysis.components.map(c => ({
+                id: c.id,
+                name: c.name,
+                type: c.type,
+                path: c.path,
+                techStack: c.techStack,
+                entryPoints: [],
+                dependencies: [],
+                devDependencies: [],
+                ports: c.ports,
+                description: c.description,
+                environments: c.environments,
+            })),
+            services: [],
+            databases: analysis.databases.map(d => ({
+                id: d.id,
+                name: d.name,
+                type: d.type,
+            })),
+            externalServices: analysis.externalServices.map(e => ({
+                id: e.id,
+                name: e.name,
+                type: e.type,
+                envVars: [],
+                environments: e.environments,
+                color: e.color,
+                strokeColor: e.strokeColor,
+            })),
+            connections: analysis.connections.map(c => ({
+                from: c.from,
+                to: c.to,
+                type: c.type,
+                label: c.description || c.type.toUpperCase(),
+                environments: c.environments,
+                color: c.color,
+                eventType: c.eventType,
+                async: c.async,
+            })),
+            metadata: {
+                isMonorepo: analysis.project.isMonorepo || false,
+                workspaces: [],
+                hasDocker: true,
+                hasCi: false,
+                primaryLanguage: analysis.project.primaryLanguage,
+                frameworks: [],
+            },
+        };
+        // Generate diagram
+        const diagram = generateArchitecture(project);
+        // Determine output path
+        const outputPath = options.output || path.join(rootDir, ".archbyte", "architecture.json");
+        // Merge with existing if present (preserve user positions)
+        if (fs.existsSync(outputPath)) {
+            try {
+                const existingContent = fs.readFileSync(outputPath, "utf-8");
+                const existing = JSON.parse(existingContent);
+                // Build lookup of existing nodes
+                const existingNodes = new Map();
+                for (const node of existing.nodes || []) {
+                    existingNodes.set(node.id, node);
+                }
+                // Apply existing positions to new diagram
+                for (const node of diagram.nodes) {
+                    const existingNode = existingNodes.get(node.id);
+                    if (existingNode) {
+                        node.x = existingNode.x;
+                        node.y = existingNode.y;
+                        node.width = existingNode.width;
+                        node.height = existingNode.height;
+                    }
+                }
+                if (options.verbose) {
+                    console.log(chalk.gray(`Merged with existing diagram, preserved ${existingNodes.size} positions`));
+                }
+            }
+            catch {
+                // Ignore merge errors
+            }
+        }
+        // Ensure output directory exists
+        const outputDir = path.dirname(outputPath);
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+        // Add environments if present
+        if (analysis.environments && analysis.environments.length > 0) {
+            diagram.environments = {};
+            for (const env of analysis.environments) {
+                diagram.environments[env.name] = {
+                    label: env.label,
+                    color: env.color,
+                    source: env.source,
+                };
+            }
+        }
+        // Add flows if present
+        if (analysis.flows && analysis.flows.length > 0) {
+            // Build a set of actual edge IDs and a prefix lookup for eventType-suffixed edges
+            const edgeIdSet = new Set(diagram.edges.map(e => e.id));
+            // Build lookup: for any "edge-A-B", find all edge IDs that start with "edge-A-B"
+            // This catches eventType-suffixed edges like "edge-A-B-task-created"
+            const findEdgeByPrefix = (prefix) => {
+                for (const id of edgeIdSet) {
+                    if (id === prefix || id.startsWith(prefix + "-"))
+                        return id;
+                }
+                return null;
+            };
+            diagram.flows = analysis.flows.map(flow => ({
+                id: flow.id,
+                name: flow.name,
+                description: flow.description,
+                color: "#3b82f6", // Default blue for flows
+                steps: flow.steps
+                    .map(step => {
+                    const forwardId = `edge-${step.from}-${step.to}`;
+                    const reverseId = `edge-${step.to}-${step.from}`;
+                    // 1. Exact match
+                    if (edgeIdSet.has(forwardId))
+                        return { edge: forwardId, label: step.label };
+                    if (edgeIdSet.has(reverseId))
+                        return { edge: reverseId, label: step.label };
+                    // 2. Try eventType-suffixed edges (e.g., edge-A-B-task-created)
+                    const forwardMatch = findEdgeByPrefix(forwardId);
+                    if (forwardMatch)
+                        return { edge: forwardMatch, label: step.label };
+                    const reverseMatch = findEdgeByPrefix(reverseId);
+                    if (reverseMatch)
+                        return { edge: reverseMatch, label: step.label };
+                    return null; // Skip steps with no matching edge
+                })
+                    .filter((s) => s !== null),
+            }));
+        }
+        // Write diagram
+        fs.writeFileSync(outputPath, JSON.stringify(diagram, null, 2), "utf-8");
+        console.log(chalk.green("✓ Diagram generated successfully!"));
+        console.log();
+        console.log(chalk.bold("Summary:"));
+        console.log(chalk.gray(`  Components: ${analysis.components.length}`));
+        console.log(chalk.gray(`  Databases: ${analysis.databases.length}`));
+        console.log(chalk.gray(`  External Services: ${analysis.externalServices.length}`));
+        console.log(chalk.gray(`  Connections: ${analysis.connections.length}`));
+        if (analysis.environments && analysis.environments.length > 0) {
+            console.log(chalk.gray(`  Environments: ${analysis.environments.map(e => e.name).join(", ")}`));
+        }
+        if (analysis.flows && analysis.flows.length > 0) {
+            console.log(chalk.gray(`  Flows: ${analysis.flows.map(f => f.name).join(", ")}`));
+        }
+        console.log();
+        console.log(chalk.green(`✓ Saved to: ${path.relative(rootDir, outputPath)}`));
+        console.log();
+        console.log(chalk.bold("Next steps:"));
+        console.log(chalk.gray(`  1. Run ${chalk.cyan("archbyte serve")} to start the visualization server`));
+        console.log(chalk.gray(`  2. Open ${chalk.cyan("http://localhost:3847")} to view and adjust the diagram`));
+        console.log();
+    }
+    catch (error) {
+        console.error();
+        if (error instanceof Error) {
+            console.error(chalk.red(`Error: ${error.message}`));
+            if (options.verbose) {
+                console.error(chalk.gray(error.stack));
+            }
+        }
+        else {
+            console.error(chalk.red("An unexpected error occurred"));
+        }
+        process.exit(1);
+    }
+}

package/dist/cli/license-gate.d.ts

@@ -0,0 +1,27 @@
+type GatedAction = "scan" | "analyze" | "generate";
+/**
+ * Pre-flight license check. Must be called before scan/analyze/generate.
+ *
+ * Flow:
+ *   1. Load credentials from ~/.archbyte/credentials.json
+ *   2. If not logged in → block with login prompt
+ *   3. Call POST /v1/check-usage to verify server-side
+ *   4. If blocked → show upgrade message and exit
+ *   5. If allowed → cache verified tier and return
+ *
+ * Offline fallback: If the server is unreachable, check offline action
+ * limits. Free tier: 0 offline actions. Premium (cached): max 3 within
+ * the 1-hour cache window. Exceeding limits blocks the action.
+ */
+export declare function requireLicense(action: GatedAction): Promise<void>;
+/**
+ * Record a completed scan with the license server.
+ * Called after a successful scan/analyze/generate cycle.
+ * Non-blocking — failures are silently ignored.
+ */
+export declare function recordUsage(meta: {
+    projectName?: string;
+    agentCount?: number;
+    durationMs?: number;
+}): Promise<void>;
+export {};

package/dist/cli/license-gate.js

@@ -0,0 +1,121 @@
+import chalk from "chalk";
+import { loadCredentials, cacheVerifiedTier, resetOfflineActions, checkOfflineAction } from "./auth.js";
+const API_BASE = process.env.ARCHBYTE_API_URL ?? "https://api.heartbyte.io";
+/**
+ * Pre-flight license check. Must be called before scan/analyze/generate.
+ *
+ * Flow:
+ *   1. Load credentials from ~/.archbyte/credentials.json
+ *   2. If not logged in → block with login prompt
+ *   3. Call POST /v1/check-usage to verify server-side
+ *   4. If blocked → show upgrade message and exit
+ *   5. If allowed → cache verified tier and return
+ *
+ * Offline fallback: If the server is unreachable, check offline action
+ * limits. Free tier: 0 offline actions. Premium (cached): max 3 within
+ * the 1-hour cache window. Exceeding limits blocks the action.
+ */
+export async function requireLicense(action) {
+    const creds = loadCredentials();
+    // Not logged in
+    if (!creds) {
+        console.error();
+        console.error(chalk.red("Authentication required."));
+        console.error();
+        console.error(chalk.gray("Sign in to use ArchByte:"));
+        console.error(chalk.gray("  archbyte login"));
+        console.error();
+        console.error(chalk.gray("Basic tier includes unlimited scans."));
+        process.exit(1);
+    }
+    // Token expired locally
+    if (new Date(creds.expiresAt) < new Date()) {
+        console.error();
+        console.error(chalk.red("Session expired."));
+        console.error(chalk.gray("Run `archbyte login` to refresh your session."));
+        process.exit(1);
+    }
+    // Check usage with server
+    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(5000),
+        });
+        if (res.status === 401) {
+            console.error();
+            console.error(chalk.red("Session invalid. Please log in again."));
+            console.error(chalk.gray("  archbyte login"));
+            process.exit(1);
+        }
+        if (!res.ok) {
+            // Server error — enforce offline limits instead of allowing freely
+            return handleOfflineFallback("server error");
+        }
+        const data = (await res.json());
+        // Server verified — cache tier and reset offline counter
+        const tier = data.tier === "premium" ? "premium" : "free";
+        cacheVerifiedTier(tier, creds.email);
+        resetOfflineActions();
+        if (!data.allowed) {
+            console.error();
+            console.error(chalk.red.bold("Scan not allowed."));
+            console.error(chalk.white(data.message ?? "Check your account status."));
+            console.error();
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        // Network error — enforce offline limits
+        const reason = err instanceof Error &&
+            (err.name === "TimeoutError" || err.name === "AbortError")
+            ? "timeout" : "network error";
+        return handleOfflineFallback(reason);
+    }
+}
+/**
+ * Handle offline fallback with strict action limits.
+ * Free tier: 0 offline actions (always blocked).
+ * Premium tier (cached): up to 3 offline actions within 1-hour window.
+ */
+function handleOfflineFallback(reason) {
+    const { allowed, reason: blockReason } = checkOfflineAction();
+    if (!allowed) {
+        console.error();
+        console.error(chalk.red(`License server unreachable (${reason}).`));
+        console.error(chalk.red(blockReason ?? "Offline actions not permitted."));
+        console.error();
+        console.error(chalk.gray("Check your internet connection and try again."));
+        process.exit(1);
+    }
+    // Premium user within offline grace window
+    console.warn(chalk.yellow(`⚠ License server unreachable (${reason}). Using offline grace period.`));
+}
+/**
+ * Record a completed scan with the license server.
+ * Called after a successful scan/analyze/generate cycle.
+ * Non-blocking — failures are silently ignored.
+ */
+export async function recordUsage(meta) {
+    const creds = loadCredentials();
+    if (!creds)
+        return;
+    try {
+        await fetch(`${API_BASE}/api/v1/scans`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(meta),
+            signal: AbortSignal.timeout(5000),
+        });
+    }
+    catch {
+        // Silently ignore — usage recording is best-effort
+    }
+}

package/dist/cli/patrol.d.ts

@@ -0,0 +1,15 @@
+interface PatrolOptions {
+    diagram?: string;
+    config?: string;
+    interval?: string;
+    onViolation?: string;
+    daemon?: boolean;
+    history?: boolean;
+}
+/**
+ * Run the architecture patrol daemon.
+ * Inspired by Gastown's patrol loop pattern — cyclic monitoring
+ * that detects drift and reports violations.
+ */
+export declare function handlePatrol(options: PatrolOptions): Promise<void>;
+export {};

package/dist/cli/patrol.js

@@ -0,0 +1,212 @@
+import * as path from "path";
+import * as fs from "fs";
+import chalk from "chalk";
+import { runValidation } from "./validate.js";
+const PATROL_DIR = ".archbyte/patrols";
+const HISTORY_FILE = "history.jsonl";
+const LATEST_FILE = "latest.json";
+function parseInterval(str) {
+    const match = str.match(/^(\d+)(s|m|h)$/);
+    if (!match) {
+        console.error(chalk.red(`Invalid interval: "${str}". Use format like 30s, 5m, 1h`));
+        process.exit(1);
+    }
+    const [, num, unit] = match;
+    const multipliers = { s: 1000, m: 60_000, h: 3_600_000 };
+    return parseInt(num) * multipliers[unit];
+}
+function ensurePatrolDir() {
+    const dir = path.join(process.cwd(), PATROL_DIR);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+function loadLatestRecord(patrolDir) {
+    const latestPath = path.join(patrolDir, LATEST_FILE);
+    if (!fs.existsSync(latestPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(latestPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function saveRecord(patrolDir, record) {
+    // Write latest
+    fs.writeFileSync(path.join(patrolDir, LATEST_FILE), JSON.stringify(record, null, 2), "utf-8");
+    // Append to history
+    fs.appendFileSync(path.join(patrolDir, HISTORY_FILE), JSON.stringify(record) + "\n", "utf-8");
+}
+function diffViolations(previous, current) {
+    const key = (v) => `${v.rule}:${v.message}`;
+    const prevKeys = new Set(previous.map(key));
+    const currKeys = new Set(current.map(key));
+    return {
+        newViolations: current.filter((v) => !prevKeys.has(key(v))),
+        resolvedViolations: previous.filter((v) => !currKeys.has(key(v))),
+    };
+}
+function runPatrolCycle(options, patrolDir) {
+    const previous = loadLatestRecord(patrolDir);
+    const result = runValidation({
+        diagram: options.diagram,
+        config: options.config,
+    });
+    const { newViolations, resolvedViolations } = previous
+        ? diffViolations(previous.violations, result.violations)
+        : { newViolations: result.violations, resolvedViolations: [] };
+    const record = {
+        timestamp: new Date().toISOString(),
+        passed: result.errors === 0,
+        errors: result.errors,
+        warnings: result.warnings,
+        violations: result.violations,
+        newViolations,
+        resolvedViolations,
+        totalNodes: result.totalNodes,
+        totalEdges: result.totalEdges,
+    };
+    saveRecord(patrolDir, record);
+    return record;
+}
+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}`));
+    if (record.newViolations.length > 0) {
+        console.log(chalk.red(`  ${record.newViolations.length} new violation(s):`));
+        for (const v of record.newViolations) {
+            const icon = v.level === "error" ? chalk.red("!!") : chalk.yellow("!!");
+            console.log(chalk.gray(`    ${icon} [${v.rule}] ${v.message}`));
+        }
+    }
+    if (record.resolvedViolations.length > 0) {
+        console.log(chalk.green(`  ${record.resolvedViolations.length} resolved:`));
+        for (const v of record.resolvedViolations) {
+            console.log(chalk.green(`    -- [${v.rule}] ${v.message}`));
+        }
+    }
+    if (record.newViolations.length === 0 && record.resolvedViolations.length === 0) {
+        console.log(chalk.gray(`  No changes — ${record.errors} errors, ${record.warnings} warnings`));
+    }
+}
+function printHistory(patrolDir) {
+    const historyPath = path.join(patrolDir, HISTORY_FILE);
+    if (!fs.existsSync(historyPath)) {
+        console.log(chalk.yellow("  No patrol history found. Run archbyte patrol to start."));
+        return;
+    }
+    const lines = fs.readFileSync(historyPath, "utf-8").trim().split("\n").filter(Boolean);
+    if (lines.length === 0) {
+        console.log(chalk.yellow("  No patrol history found."));
+        return;
+    }
+    const projectName = process.cwd().split("/").pop() || "project";
+    console.log();
+    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) => {
+        try {
+            return [JSON.parse(l)];
+        }
+        catch {
+            return [];
+        }
+    });
+    // Health sparkline
+    const sparkline = records
+        .map((r) => (r.passed ? chalk.green("*") : chalk.red("*")))
+        .join("");
+    console.log(`  Health: ${sparkline}  (last ${records.length} patrols)`);
+    console.log();
+    // Table
+    console.log(chalk.gray("  Time                 Status    Errors  Warnings  New  Resolved"));
+    console.log(chalk.gray("  " + "-".repeat(68)));
+    for (const r of records) {
+        const time = new Date(r.timestamp).toLocaleString().padEnd(20);
+        const status = r.passed ? chalk.green("PASS  ") : chalk.red("FAIL  ");
+        const errors = String(r.errors).padEnd(8);
+        const warnings = String(r.warnings).padEnd(10);
+        const newV = String(r.newViolations.length).padEnd(5);
+        const resolved = String(r.resolvedViolations.length);
+        console.log(`  ${time} ${status} ${errors}${warnings}${newV}${resolved}`);
+    }
+    console.log();
+    // Summary
+    const totalPatrols = lines.length;
+    const failedPatrols = lines.filter((l) => !JSON.parse(l).passed).length;
+    const healthPct = Math.round(((totalPatrols - failedPatrols) / totalPatrols) * 100);
+    console.log(`  Total patrols: ${totalPatrols} | Health rate: ${healthPct}% | Failed: ${failedPatrols}`);
+    console.log();
+}
+function handleViolationAction(record, action) {
+    if (record.newViolations.length === 0)
+        return;
+    switch (action) {
+        case "json":
+            console.log(JSON.stringify({
+                event: "patrol-violation",
+                timestamp: record.timestamp,
+                newViolations: record.newViolations,
+            }));
+            break;
+        case "log":
+        default:
+            // Already printed in printPatrolResult
+            break;
+    }
+}
+/**
+ * Run the architecture patrol daemon.
+ * Inspired by Gastown's patrol loop pattern — cyclic monitoring
+ * that detects drift and reports violations.
+ */
+export async function handlePatrol(options) {
+    const projectName = process.cwd().split("/").pop() || "project";
+    const patrolDir = ensurePatrolDir();
+    // History mode
+    if (options.history) {
+        printHistory(patrolDir);
+        return;
+    }
+    const intervalMs = parseInterval(options.interval || "5m");
+    const intervalStr = options.interval || "5m";
+    const action = options.onViolation || "log";
+    console.log();
+    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."));
+    // Run initial cycle immediately
+    let cycleNum = 1;
+    const record = runPatrolCycle(options, patrolDir);
+    printPatrolResult(record, cycleNum);
+    handleViolationAction(record, action);
+    // Patrol loop
+    const timer = setInterval(() => {
+        cycleNum++;
+        try {
+            const record = runPatrolCycle(options, patrolDir);
+            printPatrolResult(record, cycleNum);
+            handleViolationAction(record, action);
+        }
+        catch (err) {
+            console.error(chalk.red(`  Patrol cycle #${cycleNum} failed: ${err}`));
+        }
+    }, intervalMs);
+    // Graceful shutdown
+    const shutdown = () => {
+        clearInterval(timer);
+        console.log();
+        console.log(chalk.gray(`  Patrol stopped after ${cycleNum} cycles.`));
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    // Keep alive
+    await new Promise(() => { });
+}

package/dist/cli/run.d.ts

@@ -0,0 +1,11 @@
+interface RunOptions {
+    static?: boolean;
+    skipLlm?: boolean;
+    provider?: string;
+    apiKey?: string;
+    port?: number;
+    verbose?: boolean;
+    dryRun?: boolean;
+}
+export declare function handleRun(options: RunOptions): Promise<void>;
+export {};

package/dist/cli/run.js

@@ -0,0 +1,24 @@
+import chalk from "chalk";
+import { handleAnalyze } from "./analyze.js";
+import { handleServe } from "./serve.js";
+export async function handleRun(options) {
+    const port = options.port || 3847;
+    console.log();
+    console.log(chalk.bold.cyan("  ArchByte Run"));
+    console.log();
+    // 1. Analyze (includes auto-generate)
+    await handleAnalyze({
+        verbose: options.verbose,
+        static: options.static,
+        skipLlm: options.skipLlm,
+        provider: options.provider,
+        apiKey: options.apiKey,
+        dryRun: options.dryRun,
+    });
+    if (options.dryRun)
+        return;
+    // 2. Serve the UI
+    console.log(chalk.bold.cyan("  Starting UI..."));
+    console.log();
+    await handleServe({ port });
+}

package/dist/cli/serve.d.ts

@@ -0,0 +1,9 @@
+interface ServeOptions {
+    port?: number;
+    diagram?: string;
+}
+/**
+ * Start the ArchByte UI server
+ */
+export declare function handleServe(options: ServeOptions): Promise<void>;
+export {};