archbyte 0.7.1 → 0.7.3

package/dist/cli/export.js

@@ -1,61 +1,70 @@
 import chalk from "chalk";
 import { fileURLToPath } from "url";
 import { resolveArchitecturePath, loadArchitectureFile } from "./shared.js";
+import { isJsonMode, outputSuccess, ArchByteError, EXIT } from "./output.js";
 /**
- * Export architecture diagram to Mermaid, Markdown, or JSON format.
+ * Generate export content as structured data.
+ * Pure function — no console output, no process.exit().
  */
-export async function handleExport(options) {
+export async function generateExport(options) {
     const diagramPath = resolveArchitecturePath(options);
     const arch = loadArchitectureFile(diagramPath);
     const format = options.format || "mermaid";
     const SUPPORTED_FORMATS = ["mermaid", "markdown", "json", "plantuml", "dot", "html"];
     if (!SUPPORTED_FORMATS.includes(format)) {
-        const formatList = SUPPORTED_FORMATS.map(f => f === "html" ? `html ${chalk.yellow("[Pro]")}` : f).join(", ");
-        console.error(chalk.red(`Unknown format: "${format}". Supported: ${formatList}`));
-        process.exit(1);
+        throw new ArchByteError("EXPORT_FAILED", `Unknown format: "${format}". Supported: ${SUPPORTED_FORMATS.join(", ")}`, EXIT.EXPORT_FAILED);
     }
-    // HTML export requires Pro tier (skip in dev/local builds)
     if (format === "html" && !process.env.ARCHBYTE_DEV) {
         const { loadCredentials } = await import("./auth.js");
         const creds = loadCredentials();
         if (!creds || creds.tier !== "premium") {
-            console.error();
-            console.error(chalk.red("HTML export requires a Pro subscription."));
-            console.error(chalk.gray("Upgrade at https://heartbyte.io/archbyte"));
-            console.error();
-            process.exit(1);
+            throw new ArchByteError("LICENSE_DENIED", "HTML export requires a Pro subscription. Upgrade at https://heartbyte.io/archbyte", EXIT.LICENSE_DENIED);
         }
     }
-    let output;
+    let content;
     switch (format) {
         case "mermaid":
-            output = exportMermaid(arch);
+            content = exportMermaid(arch);
             break;
         case "json":
-            output = exportJson(arch);
+            content = exportJson(arch);
             break;
         case "plantuml":
-            output = exportPlantUML(arch);
+            content = exportPlantUML(arch);
             break;
         case "dot":
-            output = exportDot(arch);
+            content = exportDot(arch);
             break;
         case "html":
-            output = await exportHtml(arch);
+            content = await exportHtml(arch);
             break;
         default:
-            output = exportMarkdown(arch);
+            content = exportMarkdown(arch);
             break;
     }
+    let outputPath;
     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}`));
+        const fsMod = await import("fs");
+        const pathMod = await import("path");
+        outputPath = pathMod.resolve(process.cwd(), options.output);
+        fsMod.writeFileSync(outputPath, content, "utf-8");
+    }
+    return { format, content, outputPath };
+}
+/**
+ * Export architecture diagram to Mermaid, Markdown, or JSON format.
+ */
+export async function handleExport(options) {
+    const result = await generateExport(options);
+    if (isJsonMode()) {
+        outputSuccess(result);
+        return;
+    }
+    if (result.outputPath) {
+        console.error(chalk.green(`✓ Exported to ${result.outputPath}`));
     }
     else {
-        console.log(output);
+        console.log(result.content);
     }
 }
 /**
@@ -335,9 +344,7 @@ async function exportHtml(arch) {
     const __dirname = pathMod.dirname(__filename);
     const uiDist = pathMod.resolve(__dirname, "../../ui/dist");
     if (!fs.existsSync(uiDist)) {
-        console.error(chalk.red("UI build not found at " + uiDist));
-        console.error(chalk.gray("Run: npm run build:ui"));
-        process.exit(1);
+        throw new ArchByteError("EXPORT_FAILED", "UI build not found. Run: npm run build:ui", EXIT.EXPORT_FAILED);
     }
     // Read CSS and JS assets
     const assetsDir = pathMod.join(uiDist, "assets");

package/dist/cli/license-gate.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import { loadCredentials, cacheVerifiedTier, resetOfflineActions, checkOfflineAction } from "./auth.js";
 import { API_BASE, NETWORK_TIMEOUT_MS } from "./constants.js";
 import { confirm } from "./ui.js";
+import { ArchByteError, EXIT } from "./output.js";
 /**
  * Pre-flight license check. Must be called before scan/analyze/generate.
  *
@@ -26,13 +27,12 @@ export async function requireLicense(action) {
         console.log();
         const shouldLogin = await confirm("Sign in now?");
         if (!shouldLogin)
-            process.exit(1);
+            throw new ArchByteError("AUTH_REQUIRED", "Login required", EXIT.AUTH_REQUIRED);
         const { handleLogin } = await import("./auth.js");
         await handleLogin();
         creds = loadCredentials();
         if (!creds) {
-            console.error(chalk.red("Login failed. Please try again with `archbyte login`."));
-            process.exit(1);
+            throw new ArchByteError("AUTH_REQUIRED", "Login failed. Please try again with `archbyte login`.", EXIT.AUTH_REQUIRED);
         }
     }
     // Token expired locally — offer re-login
@@ -42,18 +42,16 @@ export async function requireLicense(action) {
         console.log(chalk.yellow("Session expired."));
         const shouldRelogin = await confirm("Sign in again?");
         if (!shouldRelogin)
-            process.exit(1);
+            throw new ArchByteError("AUTH_EXPIRED", "Session expired", EXIT.AUTH_EXPIRED);
         const { handleLogin } = await import("./auth.js");
         await handleLogin();
         creds = loadCredentials();
         if (!creds) {
-            console.error(chalk.red("Login failed. Please try again with `archbyte login`."));
-            process.exit(1);
+            throw new ArchByteError("AUTH_REQUIRED", "Login failed. Please try again with `archbyte login`.", EXIT.AUTH_REQUIRED);
         }
         const freshExpiry = new Date(creds.expiresAt);
         if (isNaN(freshExpiry.getTime()) || freshExpiry < new Date()) {
-            console.error(chalk.red("Session still expired. Please try `archbyte login`."));
-            process.exit(1);
+            throw new ArchByteError("AUTH_EXPIRED", "Session still expired. Please try `archbyte login`.", EXIT.AUTH_EXPIRED);
         }
     }
     // Check usage with server
@@ -72,12 +70,12 @@ export async function requireLicense(action) {
             console.log(chalk.yellow("Session invalid."));
             const shouldRelogin = await confirm("Sign in again?");
             if (!shouldRelogin)
-                process.exit(1);
+                throw new ArchByteError("AUTH_INVALID", "Session invalid", EXIT.AUTH_INVALID);
             const { handleLogin } = await import("./auth.js");
             await handleLogin();
             creds = loadCredentials();
             if (!creds)
-                process.exit(1);
+                throw new ArchByteError("AUTH_REQUIRED", "Login required", EXIT.AUTH_REQUIRED);
             // Re-check usage with fresh credentials
             return requireLicense(action);
         }
@@ -91,11 +89,7 @@ export async function requireLicense(action) {
         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);
+            throw new ArchByteError("LICENSE_DENIED", data.message ?? "Scan not allowed. Check your account status.", EXIT.LICENSE_DENIED);
         }
     }
     catch (err) {
@@ -114,12 +108,7 @@ export async function requireLicense(action) {
 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);
+        throw new ArchByteError("NETWORK_ERROR", `License server unreachable (${reason}). ${blockReason ?? "Offline actions not permitted."}`, EXIT.NETWORK_ERROR);
     }
     // Premium user within offline grace window
     console.warn(chalk.yellow(`⚠ License server unreachable (${reason}). Using offline grace period.`));

package/dist/cli/output.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Structured output infrastructure for agent-ready CLI.
+ *
+ * Provides JSON envelope format, domain-specific exit codes,
+ * and output mode state (--json, --quiet) for all commands.
+ */
+export declare const EXIT: {
+    readonly SUCCESS: 0;
+    readonly GENERAL_ERROR: 1;
+    readonly AUTH_REQUIRED: 2;
+    readonly AUTH_EXPIRED: 3;
+    readonly AUTH_INVALID: 4;
+    readonly LICENSE_DENIED: 5;
+    readonly CONFIG_MISSING: 6;
+    readonly CONFIG_INVALID: 7;
+    readonly ANALYSIS_FAILED: 10;
+    readonly EXPORT_FAILED: 12;
+    readonly FILE_NOT_FOUND: 20;
+    readonly NETWORK_ERROR: 30;
+    readonly PROVIDER_ERROR: 31;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+export declare class ArchByteError extends Error {
+    readonly code: string;
+    readonly exitCode: ExitCode;
+    constructor(code: string, message: string, exitCode?: ExitCode);
+}
+export declare function setOutputMode(opts: {
+    json?: boolean;
+    quiet?: boolean;
+    command?: string;
+    version?: string;
+}): void;
+export declare function isJsonMode(): boolean;
+export declare function isQuietMode(): boolean;
+/**
+ * Output a success response. In JSON mode, prints the envelope to stdout.
+ * Returns the data so callers can chain.
+ */
+export declare function outputSuccess(data: unknown): void;
+/**
+ * Output an error response and exit. In JSON mode, prints the envelope to stdout.
+ * In human mode, prints to stderr and exits.
+ */
+export declare function outputError(code: string, message: string, exitCode?: ExitCode): never;
+/**
+ * Log a message to stderr, respecting quiet and JSON modes.
+ * In JSON mode: suppressed (only envelope goes to stdout).
+ * In quiet mode: suppressed.
+ * Otherwise: prints to stderr.
+ */
+export declare function log(message: string): void;
+/**
+ * Handle an ArchByteError (or any error) and exit appropriately.
+ * Used as the top-level error handler in the CLI.
+ */
+export declare function handleError(err: unknown): never;

package/dist/cli/output.js

@@ -0,0 +1,111 @@
+/**
+ * Structured output infrastructure for agent-ready CLI.
+ *
+ * Provides JSON envelope format, domain-specific exit codes,
+ * and output mode state (--json, --quiet) for all commands.
+ */
+// ─── Exit Codes ───
+export const EXIT = {
+    SUCCESS: 0,
+    GENERAL_ERROR: 1,
+    AUTH_REQUIRED: 2,
+    AUTH_EXPIRED: 3,
+    AUTH_INVALID: 4,
+    LICENSE_DENIED: 5,
+    CONFIG_MISSING: 6,
+    CONFIG_INVALID: 7,
+    ANALYSIS_FAILED: 10,
+    EXPORT_FAILED: 12,
+    FILE_NOT_FOUND: 20,
+    NETWORK_ERROR: 30,
+    PROVIDER_ERROR: 31,
+};
+// ─── ArchByteError ───
+export class ArchByteError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = EXIT.GENERAL_ERROR) {
+        super(message);
+        this.name = "ArchByteError";
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+// ─── Output Mode State ───
+let _jsonMode = false;
+let _quietMode = false;
+let _currentCommand = "";
+let _version = "";
+export function setOutputMode(opts) {
+    if (opts.json != null)
+        _jsonMode = opts.json;
+    if (opts.quiet != null)
+        _quietMode = opts.quiet;
+    if (opts.command != null)
+        _currentCommand = opts.command;
+    if (opts.version != null)
+        _version = opts.version;
+}
+export function isJsonMode() {
+    return _jsonMode;
+}
+export function isQuietMode() {
+    return _quietMode;
+}
+function buildMeta() {
+    return {
+        command: _currentCommand,
+        version: _version,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Output a success response. In JSON mode, prints the envelope to stdout.
+ * Returns the data so callers can chain.
+ */
+export function outputSuccess(data) {
+    if (_jsonMode) {
+        const envelope = { ok: true, data, meta: buildMeta() };
+        process.stdout.write(JSON.stringify(envelope) + "\n");
+    }
+}
+/**
+ * Output an error response and exit. In JSON mode, prints the envelope to stdout.
+ * In human mode, prints to stderr and exits.
+ */
+export function outputError(code, message, exitCode = EXIT.GENERAL_ERROR) {
+    if (_jsonMode) {
+        const envelope = {
+            ok: false,
+            error: { code, message },
+            meta: buildMeta(),
+        };
+        process.stdout.write(JSON.stringify(envelope) + "\n");
+    }
+    else {
+        process.stderr.write(`Error: ${message}\n`);
+    }
+    process.exit(exitCode);
+}
+/**
+ * Log a message to stderr, respecting quiet and JSON modes.
+ * In JSON mode: suppressed (only envelope goes to stdout).
+ * In quiet mode: suppressed.
+ * Otherwise: prints to stderr.
+ */
+export function log(message) {
+    if (_jsonMode || _quietMode)
+        return;
+    process.stderr.write(message + "\n");
+}
+/**
+ * Handle an ArchByteError (or any error) and exit appropriately.
+ * Used as the top-level error handler in the CLI.
+ */
+export function handleError(err) {
+    if (err instanceof ArchByteError) {
+        outputError(err.code, err.message, err.exitCode);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    outputError("GENERAL_ERROR", message, EXIT.GENERAL_ERROR);
+}

package/dist/cli/shared.d.ts

@@ -36,7 +36,12 @@ export interface CustomRule {
 export declare function resolveArchitecturePath(options: DiagramOptions): string;
 /**
  * Load and parse the architecture JSON file.
- * Exits with an error message if the file is missing or invalid.
+ * Returns null if the file is missing or invalid — no process.exit().
+ */
+export declare function loadArchitectureFileSafe(filePath: string): Architecture | null;
+/**
+ * Load and parse the architecture JSON file.
+ * Throws ArchByteError if the file is missing or invalid.
  */
 export declare function loadArchitectureFile(filePath: string): Architecture;
 /**

package/dist/cli/shared.js

@@ -1,6 +1,6 @@
 import * as path from "path";
 import * as fs from "fs";
-import chalk from "chalk";
+import { ArchByteError, EXIT } from "./output.js";
 /**
  * Resolve the path to the architecture JSON file from CLI options or defaults.
  */
@@ -12,22 +12,32 @@ export function resolveArchitecturePath(options) {
 }
 /**
  * Load and parse the architecture JSON file.
- * Exits with an error message if the file is missing or invalid.
+ * Returns null if the file is missing or invalid — no process.exit().
  */
-export function loadArchitectureFile(filePath) {
-    if (!fs.existsSync(filePath)) {
-        console.error(chalk.red(`Architecture file not found: ${filePath}`));
-        console.error(chalk.gray("Run archbyte generate first, or provide --diagram <path>"));
-        process.exit(1);
-    }
+export function loadArchitectureFileSafe(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
     try {
         const content = fs.readFileSync(filePath, "utf-8");
         return JSON.parse(content);
     }
     catch {
-        console.error(chalk.red(`Failed to parse architecture file: ${filePath}`));
-        process.exit(1);
+        return null;
+    }
+}
+/**
+ * Load and parse the architecture JSON file.
+ * Throws ArchByteError if the file is missing or invalid.
+ */
+export function loadArchitectureFile(filePath) {
+    const arch = loadArchitectureFileSafe(filePath);
+    if (!arch) {
+        if (!fs.existsSync(filePath)) {
+            throw new ArchByteError("FILE_NOT_FOUND", `Architecture file not found: ${filePath}. Run archbyte generate first, or provide --diagram <path>`, EXIT.FILE_NOT_FOUND);
+        }
+        throw new ArchByteError("FILE_NOT_FOUND", `Failed to parse architecture file: ${filePath}`, EXIT.FILE_NOT_FOUND);
     }
+    return arch;
 }
 /**
  * Load rules configuration from archbyte.yaml.

package/dist/cli/stats.d.ts

@@ -2,6 +2,42 @@ interface StatsOptions {
     diagram?: string;
     config?: string;
 }
+interface AnalysisMetadata {
+    analyzedAt?: string;
+    durationMs?: number;
+    filesScanned?: number;
+    mode?: string;
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+}
+interface HealthIndicator {
+    rule: string;
+    status: "pass" | "warn";
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface StatsData {
+    summary: {
+        components: number;
+        databases: number;
+        externals: number;
+        connections: number;
+        totalNodes: number;
+    };
+    layers: Record<string, {
+        count: number;
+        percent: number;
+    }>;
+    health: HealthIndicator[];
+    scan?: AnalysisMetadata;
+}
+/**
+ * Compute architecture stats as a structured object.
+ * Pure data function — no console output.
+ */
+export declare function computeStats(options: StatsOptions): StatsData;
 /**
  * Print an architecture health dashboard to the terminal.
  */