archbyte 0.1.0

package/dist/cli/diff.js

@@ -0,0 +1,144 @@
+import * as path from "path";
+import chalk from "chalk";
+import { resolveArchitecturePath, loadArchitectureFile, loadRulesConfig, getRuleLevel, getThreshold, } from "./shared.js";
+import { checkNoLayerBypass, checkMaxConnections, checkNoOrphans, checkCircularDeps, } from "./validate.js";
+/**
+ * Compare two architecture snapshots and show drift report.
+ */
+export async function handleDiff(options) {
+    if (!options.baseline) {
+        console.error(chalk.red("--baseline <path> is required"));
+        process.exit(1);
+    }
+    const baseArch = loadArchitectureFile(path.resolve(process.cwd(), options.baseline));
+    const currentPath = options.current
+        ? path.resolve(process.cwd(), options.current)
+        : resolveArchitecturePath({});
+    const currentArch = loadArchitectureFile(currentPath);
+    const projectName = process.cwd().split("/").pop() || "project";
+    console.log();
+    console.log(chalk.bold.cyan(`⚡ ArchByte Diff — ${projectName}`));
+    console.log(chalk.gray(`  Baseline: ${options.baseline}`));
+    console.log(chalk.gray(`  Current:  ${options.current || ".archbyte/architecture.json"}`));
+    console.log();
+    // ── Components ──
+    const baseNodes = new Set(baseArch.nodes.map((n) => n.id));
+    const currentNodes = new Set(currentArch.nodes.map((n) => n.id));
+    const added = [...currentNodes].filter((id) => !baseNodes.has(id));
+    const removed = [...baseNodes].filter((id) => !currentNodes.has(id));
+    const currentNodeMap = new Map();
+    for (const n of currentArch.nodes)
+        currentNodeMap.set(n.id, n);
+    const baseNodeMap = new Map();
+    for (const n of baseArch.nodes)
+        baseNodeMap.set(n.id, n);
+    console.log(chalk.bold("  Components:"));
+    if (added.length === 0 && removed.length === 0) {
+        console.log(chalk.green("    No changes"));
+    }
+    else {
+        for (const id of added) {
+            const node = currentNodeMap.get(id);
+            console.log(chalk.green(`    + ${node?.label || id} (${node?.layer || "unknown"})`));
+        }
+        for (const id of removed) {
+            const node = baseNodeMap.get(id);
+            console.log(chalk.red(`    - ${node?.label || id} (${node?.layer || "unknown"})`));
+        }
+    }
+    console.log();
+    // ── Connections ──
+    const edgeKey = (e) => `${e.source}->${e.target}`;
+    const baseEdges = new Set(baseArch.edges.map(edgeKey));
+    const currentEdges = new Set(currentArch.edges.map(edgeKey));
+    const addedEdges = currentArch.edges.filter((e) => !baseEdges.has(edgeKey(e)));
+    const removedEdges = baseArch.edges.filter((e) => !currentEdges.has(edgeKey(e)));
+    console.log(chalk.bold("  Connections:"));
+    if (addedEdges.length === 0 && removedEdges.length === 0) {
+        console.log(chalk.green("    No changes"));
+    }
+    else {
+        for (const e of addedEdges) {
+            const src = currentNodeMap.get(e.source)?.label || e.source;
+            const tgt = currentNodeMap.get(e.target)?.label || e.target;
+            console.log(chalk.green(`    + ${src} → ${tgt}`));
+        }
+        for (const e of removedEdges) {
+            const src = baseNodeMap.get(e.source)?.label || e.source;
+            const tgt = baseNodeMap.get(e.target)?.label || e.target;
+            console.log(chalk.red(`    - ${src} → ${tgt}`));
+        }
+    }
+    console.log();
+    // ── Density Change ──
+    const calcDensity = (arch) => {
+        const n = arch.nodes.length;
+        const possible = n > 1 ? (n * (n - 1)) / 2 : 1;
+        return arch.edges.length / possible;
+    };
+    const baseDensity = calcDensity(baseArch);
+    const currentDensity = calcDensity(currentArch);
+    const densityDelta = currentDensity - baseDensity;
+    console.log(chalk.bold("  Density:"));
+    const arrow = densityDelta > 0 ? "↑" : densityDelta < 0 ? "↓" : "=";
+    const densityColor = Math.abs(densityDelta) < 0.01 ? chalk.gray : densityDelta > 0 ? chalk.yellow : chalk.green;
+    console.log(densityColor(`    ${baseDensity.toFixed(3)} → ${currentDensity.toFixed(3)} (${arrow} ${Math.abs(densityDelta).toFixed(3)})`));
+    console.log();
+    // ── Violations Diff ──
+    const config = loadRulesConfig(options.config);
+    const getViolations = (arch) => {
+        const nodes = arch.nodes;
+        const map = new Map();
+        for (const n of nodes)
+            map.set(n.id, n);
+        const violations = [];
+        const bypassLevel = getRuleLevel(config, "no-layer-bypass", "error");
+        if (bypassLevel !== "off")
+            violations.push(...checkNoLayerBypass(arch, nodes, map, bypassLevel));
+        const maxLevel = getRuleLevel(config, "max-connections", "warn");
+        if (maxLevel !== "off")
+            violations.push(...checkMaxConnections(arch, nodes, maxLevel, getThreshold(config, "max-connections", 6)));
+        const orphanLevel = getRuleLevel(config, "no-orphans", "warn");
+        if (orphanLevel !== "off")
+            violations.push(...checkNoOrphans(arch, nodes, orphanLevel));
+        const circularLevel = getRuleLevel(config, "no-circular-deps", "error");
+        if (circularLevel !== "off")
+            violations.push(...checkCircularDeps(arch, nodes, map, circularLevel));
+        return violations;
+    };
+    const baseViolations = getViolations(baseArch);
+    const currentViolations = getViolations(currentArch);
+    const violationKey = (v) => `${v.rule}:${v.message}`;
+    const baseViolationKeys = new Set(baseViolations.map(violationKey));
+    const currentViolationKeys = new Set(currentViolations.map(violationKey));
+    const newViolations = currentViolations.filter((v) => !baseViolationKeys.has(violationKey(v)));
+    const resolvedViolations = baseViolations.filter((v) => !currentViolationKeys.has(violationKey(v)));
+    console.log(chalk.bold("  Violations:"));
+    if (newViolations.length === 0 && resolvedViolations.length === 0) {
+        console.log(chalk.green("    No changes"));
+    }
+    else {
+        for (const v of newViolations) {
+            const icon = v.level === "error" ? chalk.red("NEW") : chalk.yellow("NEW");
+            console.log(`    ${icon} [${v.rule}] ${v.message}`);
+        }
+        for (const v of resolvedViolations) {
+            console.log(chalk.green(`    RESOLVED [${v.rule}] ${v.message}`));
+        }
+    }
+    // ── Summary ──
+    console.log();
+    const totalChanges = added.length + removed.length + addedEdges.length + removedEdges.length;
+    if (totalChanges === 0 && newViolations.length === 0) {
+        console.log(chalk.green("  No architectural drift detected."));
+    }
+    else {
+        console.log(`  Summary: ${chalk.green(`+${added.length}`)} / ${chalk.red(`-${removed.length}`)} components, ` +
+            `${chalk.green(`+${addedEdges.length}`)} / ${chalk.red(`-${removedEdges.length}`)} connections, ` +
+            `${chalk.red(`${newViolations.length} new`)} / ${chalk.green(`${resolvedViolations.length} resolved`)} violations`);
+    }
+    console.log();
+    if (newViolations.some((v) => v.level === "error")) {
+        process.exit(1);
+    }
+}

package/dist/cli/export.d.ts

@@ -0,0 +1,10 @@
+interface ExportOptions {
+    diagram?: string;
+    format?: string;
+    output?: string;
+}
+/**
+ * Export architecture diagram to Mermaid, Markdown, or JSON format.
+ */
+export declare function handleExport(options: ExportOptions): Promise<void>;
+export {};

package/dist/cli/export.js

@@ -0,0 +1,321 @@
+import chalk from "chalk";
+import { resolveArchitecturePath, loadArchitectureFile } from "./shared.js";
+/**
+ * Export architecture diagram to Mermaid, Markdown, or JSON format.
+ */
+export async function handleExport(options) {
+    const diagramPath = resolveArchitecturePath(options);
+    const arch = loadArchitectureFile(diagramPath);
+    const format = options.format || "mermaid";
+    const SUPPORTED_FORMATS = ["mermaid", "markdown", "json", "plantuml", "dot"];
+    if (!SUPPORTED_FORMATS.includes(format)) {
+        console.error(chalk.red(`Unknown format: "${format}". Supported: ${SUPPORTED_FORMATS.join(", ")}`));
+        process.exit(1);
+    }
+    let output;
+    switch (format) {
+        case "mermaid":
+            output = exportMermaid(arch);
+            break;
+        case "json":
+            output = exportJson(arch);
+            break;
+        case "plantuml":
+            output = exportPlantUML(arch);
+            break;
+        case "dot":
+            output = exportDot(arch);
+            break;
+        default:
+            output = exportMarkdown(arch);
+            break;
+    }
+    if (options.output) {
+        const fs = await import("fs");
+        const path = await import("path");
+        const outPath = path.resolve(process.cwd(), options.output);
+        fs.writeFileSync(outPath, output, "utf-8");
+        console.error(chalk.green(`✓ Exported to ${outPath}`));
+    }
+    else {
+        console.log(output);
+    }
+}
+/**
+ * Generate a Mermaid flowchart from the architecture.
+ */
+function exportMermaid(arch) {
+    const realNodes = arch.nodes;
+    // Group nodes by layer
+    const layerGroups = new Map();
+    for (const node of realNodes) {
+        const layer = node.layer || "other";
+        if (!layerGroups.has(layer)) {
+            layerGroups.set(layer, []);
+        }
+        layerGroups.get(layer).push(node);
+    }
+    const lines = ["graph TD"];
+    // Desired layer ordering
+    const layerOrder = [
+        "presentation",
+        "application",
+        "data",
+        "external",
+        "deployment",
+    ];
+    for (const layer of layerOrder) {
+        const nodes = layerGroups.get(layer);
+        if (!nodes || nodes.length === 0)
+            continue;
+        const label = layer.charAt(0).toUpperCase() + layer.slice(1);
+        lines.push(`  subgraph ${label}`);
+        for (const node of nodes) {
+            const id = sanitizeMermaidId(node.id);
+            const techStr = node.techStack && node.techStack.length > 0
+                ? `<br/>${node.techStack.join(", ")}`
+                : "";
+            if (node.type === "database") {
+                lines.push(`    ${id}[("${node.label}${techStr}")]`);
+            }
+            else {
+                lines.push(`    ${id}["${node.label}${techStr}"]`);
+            }
+        }
+        lines.push("  end");
+    }
+    // Edges
+    for (const edge of arch.edges) {
+        const src = sanitizeMermaidId(edge.source);
+        const tgt = sanitizeMermaidId(edge.target);
+        if (edge.label) {
+            lines.push(`  ${src} -->|${edge.label}| ${tgt}`);
+        }
+        else {
+            lines.push(`  ${src} --> ${tgt}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Generate a structured Markdown document from the architecture.
+ */
+function exportMarkdown(arch) {
+    const realNodes = arch.nodes;
+    const projectName = process.cwd().split("/").pop() || "project";
+    const lines = [];
+    lines.push(`# Architecture — ${projectName}`);
+    lines.push("");
+    lines.push(`> Generated by ArchByte on ${new Date().toISOString().slice(0, 10)}`);
+    lines.push("");
+    // Summary
+    const components = realNodes.filter((n) => n.type === "component" || n.type === "service");
+    const databases = realNodes.filter((n) => n.type === "database");
+    const externals = realNodes.filter((n) => n.type === "external");
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`- **Components:** ${components.length}`);
+    lines.push(`- **Databases:** ${databases.length}`);
+    lines.push(`- **External Services:** ${externals.length}`);
+    lines.push(`- **Connections:** ${arch.edges.length}`);
+    lines.push("");
+    // Component table
+    lines.push("## Components");
+    lines.push("");
+    lines.push("| Name | Type | Layer | Tech Stack |");
+    lines.push("|------|------|-------|------------|");
+    for (const node of realNodes) {
+        const tech = node.techStack && node.techStack.length > 0
+            ? node.techStack.join(", ")
+            : "—";
+        lines.push(`| ${node.label} | ${node.type} | ${node.layer} | ${tech} |`);
+    }
+    lines.push("");
+    // Connections
+    const nodeMap = new Map();
+    for (const node of realNodes) {
+        nodeMap.set(node.id, node);
+    }
+    lines.push("## Connections");
+    lines.push("");
+    if (arch.edges.length === 0) {
+        lines.push("_No connections defined._");
+    }
+    else {
+        for (const edge of arch.edges) {
+            const src = nodeMap.get(edge.source)?.label || edge.source;
+            const tgt = nodeMap.get(edge.target)?.label || edge.target;
+            const label = edge.label ? ` — ${edge.label}` : "";
+            lines.push(`- **${src}** → **${tgt}**${label}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Export architecture as clean semantic JSON, stripping layout coordinates.
+ */
+function exportJson(arch) {
+    const realNodes = arch.nodes;
+    const components = realNodes.map((node) => {
+        const clean = {
+            id: node.id,
+            type: node.type,
+            label: node.label,
+            layer: node.layer,
+        };
+        if (node.path)
+            clean.path = node.path;
+        if (node.techStack && node.techStack.length > 0)
+            clean.techStack = node.techStack;
+        if (node.description)
+            clean.description = node.description;
+        if (node.environments && node.environments.length > 0)
+            clean.environments = node.environments;
+        return clean;
+    });
+    const connections = arch.edges.map((edge) => {
+        const clean = {
+            id: edge.id,
+            source: edge.source,
+            target: edge.target,
+        };
+        if (edge.label)
+            clean.label = edge.label;
+        if (edge.environments && edge.environments.length > 0)
+            clean.environments = edge.environments;
+        return clean;
+    });
+    const result = {
+        components,
+        connections,
+    };
+    if (arch.flows && arch.flows.length > 0) {
+        result.flows = arch.flows;
+    }
+    if (arch.environments) {
+        result.environments = arch.environments;
+    }
+    result.metadata = {
+        lastUpdated: arch.lastUpdated,
+        version: arch.version,
+    };
+    return JSON.stringify(result, null, 2);
+}
+/**
+ * Generate a PlantUML component diagram from the architecture.
+ */
+function exportPlantUML(arch) {
+    const realNodes = arch.nodes;
+    const nodeMap = new Map();
+    for (const n of realNodes)
+        nodeMap.set(n.id, n);
+    const lines = ["@startuml Architecture"];
+    lines.push("!theme plain");
+    lines.push("skinparam componentStyle rectangle");
+    lines.push("");
+    const layerOrder = [
+        "presentation",
+        "application",
+        "data",
+        "external",
+        "deployment",
+    ];
+    const layerGroups = new Map();
+    for (const node of realNodes) {
+        const layer = node.layer || "other";
+        if (!layerGroups.has(layer))
+            layerGroups.set(layer, []);
+        layerGroups.get(layer).push(node);
+    }
+    for (const layer of layerOrder) {
+        const nodes = layerGroups.get(layer);
+        if (!nodes || nodes.length === 0)
+            continue;
+        const label = layer.charAt(0).toUpperCase() + layer.slice(1);
+        lines.push(`package "${label}" {`);
+        for (const node of nodes) {
+            const type = node.type === "database" ? "database" : "component";
+            const id = sanitizePlantUMLId(node.id);
+            const name = node.label.split("\\n")[0];
+            lines.push(`  ${type} "${name}" as ${id}`);
+        }
+        lines.push("}");
+        lines.push("");
+    }
+    for (const edge of arch.edges) {
+        const src = sanitizePlantUMLId(edge.source);
+        const tgt = sanitizePlantUMLId(edge.target);
+        const label = edge.label ? ` : ${edge.label}` : "";
+        lines.push(`${src} --> ${tgt}${label}`);
+    }
+    lines.push("");
+    lines.push("@enduml");
+    return lines.join("\n");
+}
+/**
+ * Generate a DOT/Graphviz directed graph from the architecture.
+ */
+function exportDot(arch) {
+    const realNodes = arch.nodes;
+    const layerFills = {
+        presentation: "#d0ebff",
+        application: "#ffe8cc",
+        data: "#b2f2bb",
+        external: "#eebefa",
+        deployment: "#ffe3e3",
+    };
+    const lines = ["digraph Architecture {"];
+    lines.push("  rankdir=TB;");
+    lines.push('  node [shape=box, style="rounded,filled", fontname="Helvetica"];');
+    lines.push("");
+    const layerOrder = [
+        "presentation",
+        "application",
+        "data",
+        "external",
+        "deployment",
+    ];
+    const layerGroups = new Map();
+    for (const node of realNodes) {
+        const l = node.layer || "other";
+        if (!layerGroups.has(l))
+            layerGroups.set(l, []);
+        layerGroups.get(l).push(node);
+    }
+    for (const layer of layerOrder) {
+        const nodes = layerGroups.get(layer);
+        if (!nodes || nodes.length === 0)
+            continue;
+        const label = layer.charAt(0).toUpperCase() + layer.slice(1);
+        lines.push(`  subgraph cluster_${layer} {`);
+        lines.push(`    label="${label}";`);
+        lines.push(`    style=filled; color="${layerFills[layer] || "#f0f0f0"}";`);
+        for (const node of nodes) {
+            const shape = node.type === "database" ? "cylinder" : "box";
+            const name = node.label.split("\\n")[0];
+            lines.push(`    "${node.id}" [label="${name}", shape=${shape}, fillcolor="${layerFills[layer] || "#ffffff"}"];`);
+        }
+        lines.push("  }");
+    }
+    lines.push("");
+    for (const edge of arch.edges) {
+        const label = edge.label ? ` [label="${edge.label}"]` : "";
+        lines.push(`  "${edge.source}" -> "${edge.target}"${label};`);
+    }
+    lines.push("}");
+    return lines.join("\n");
+}
+/**
+ * Sanitize an ID for use in PlantUML diagrams.
+ */
+function sanitizePlantUMLId(id) {
+    return id.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+/**
+ * Sanitize an ID for use in Mermaid diagrams.
+ * Mermaid IDs must be alphanumeric (with hyphens/underscores).
+ */
+function sanitizeMermaidId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, "_");
+}

package/dist/cli/gate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Auth gate command for Claude Code integration.
+ *
+ * Usage:
+ *   archbyte gate analyze   → check if action is allowed (JSON stdout, exit 0 or 1)
+ *   archbyte gate --record  → record a completed scan cycle
+ *
+ * Outputs JSON to stdout for the Claude command to parse.
+ * Uses exit code 1 for denied/error, exit code 0 for allowed.
+ */
+export declare function handleGate(action: string | undefined, options: {
+    record?: boolean;
+}): Promise<void>;

package/dist/cli/gate.js

@@ -0,0 +1,131 @@
+import { loadCredentials, cacheVerifiedTier, resetOfflineActions, checkOfflineAction } from "./auth.js";
+const API_BASE = process.env.ARCHBYTE_API_URL ?? "https://api.heartbyte.io";
+/**
+ * Auth gate command for Claude Code integration.
+ *
+ * Usage:
+ *   archbyte gate analyze   → check if action is allowed (JSON stdout, exit 0 or 1)
+ *   archbyte gate --record  → record a completed scan cycle
+ *
+ * Outputs JSON to stdout for the Claude command to parse.
+ * Uses exit code 1 for denied/error, exit code 0 for allowed.
+ */
+export async function handleGate(action, options) {
+    if (options.record) {
+        await recordScan();
+        return;
+    }
+    if (!action) {
+        const result = { allowed: false, reason: "Usage: archbyte gate <action> or archbyte gate --record" };
+        console.log(JSON.stringify(result));
+        process.exit(1);
+    }
+    await checkGate(action);
+}
+async function checkGate(action) {
+    const creds = loadCredentials();
+    if (!creds) {
+        const result = {
+            allowed: false,
+            reason: "Not logged in. Run `archbyte login` to sign in.",
+        };
+        console.log(JSON.stringify(result));
+        process.exit(1);
+    }
+    if (new Date(creds.expiresAt) < new Date()) {
+        const result = {
+            allowed: false,
+            reason: "Session expired. Run `archbyte login` to refresh.",
+        };
+        console.log(JSON.stringify(result));
+        process.exit(1);
+    }
+    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) {
+            const result = {
+                allowed: false,
+                reason: "Session invalid. Run `archbyte login` to sign in again.",
+            };
+            console.log(JSON.stringify(result));
+            process.exit(1);
+        }
+        if (!res.ok) {
+            return handleOfflineGate("server error");
+        }
+        const data = await res.json();
+        const tier = data.tier === "premium" ? "premium" : "free";
+        cacheVerifiedTier(tier, creds.email);
+        resetOfflineActions();
+        if (!data.allowed) {
+            const result = {
+                allowed: false,
+                tier: data.tier,
+                reason: data.message ?? "Scan not allowed. Check your account status.",
+            };
+            console.log(JSON.stringify(result));
+            process.exit(1);
+        }
+        const result = {
+            allowed: true,
+            tier: data.tier,
+            remaining: data.remaining,
+        };
+        console.log(JSON.stringify(result));
+    }
+    catch (err) {
+        const reason = err instanceof Error &&
+            (err.name === "TimeoutError" || err.name === "AbortError")
+            ? "timeout" : "network error";
+        return handleOfflineGate(reason);
+    }
+}
+function handleOfflineGate(reason) {
+    const { allowed, reason: blockReason } = checkOfflineAction();
+    if (!allowed) {
+        const result = {
+            allowed: false,
+            reason: `License server unreachable (${reason}). ${blockReason ?? "Offline actions not permitted."}`,
+        };
+        console.log(JSON.stringify(result));
+        process.exit(1);
+    }
+    // Premium user within offline grace window
+    const result = {
+        allowed: true,
+        tier: "premium",
+        remaining: -1,
+    };
+    console.log(JSON.stringify(result));
+}
+async function recordScan() {
+    const creds = loadCredentials();
+    if (!creds) {
+        console.log(JSON.stringify({ recorded: false }));
+        return;
+    }
+    try {
+        await fetch(`${API_BASE}/api/v1/scans`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({}),
+            signal: AbortSignal.timeout(5000),
+        });
+        console.log(JSON.stringify({ recorded: true }));
+    }
+    catch {
+        // Best-effort — still report success to not block the pipeline
+        console.log(JSON.stringify({ recorded: false }));
+    }
+}

package/dist/cli/generate.d.ts

@@ -0,0 +1,10 @@
+interface GenerateOptions {
+    input?: string;
+    output?: string;
+    verbose?: boolean;
+}
+/**
+ * Generate excalidraw diagram from analysis JSON
+ */
+export declare function handleGenerate(options: GenerateOptions): Promise<void>;
+export {};