balchemy 0.2.2 → 0.2.3

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+import type { JsonValue, Reporter } from "./output.js";
+export type TerminalErrorCode = "UNKNOWN_COMMAND" | "UNKNOWN_FLAG" | "CONFIG_FILE_MISSING" | "CONFIG_ENV_MISSING" | "CONFIG_YAML_INVALID" | "FILE_OVERWRITE_CONFIRMATION_REQUIRED" | "FILE_PERMISSION_DENIED" | "CI_PROMPT_BLOCKED" | "TERMINAL_UNSUPPORTED_TUI" | "RUNTIME_ERROR";
+export interface TerminalErrorParams {
+    code: TerminalErrorCode;
+    title: string;
+    cause: string;
+    fix: string;
+    commandSuggestion?: string;
+    docsHint?: string;
+    exitCode: number;
+    retryable?: boolean;
+    debugDetails?: string;
+}
+export declare class TerminalError extends Error {
+    readonly code: TerminalErrorCode;
+    readonly title: string;
+    readonly cause: string;
+    readonly fix: string;
+    readonly commandSuggestion?: string;
+    readonly docsHint: string;
+    readonly exitCode: number;
+    readonly retryable: boolean;
+    readonly debugDetails?: string;
+    constructor(params: TerminalErrorParams);
+}
+export declare function toTerminalError(err: unknown): TerminalError;
+export declare function terminalErrorToJson(error: TerminalError): JsonValue;
+export declare function renderTerminalError(reporter: Reporter, error: TerminalError): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,cAAc,GACd,qBAAqB,GACrB,oBAAoB,GACpB,qBAAqB,GACrB,sCAAsC,GACtC,wBAAwB,GACxB,mBAAmB,GACnB,0BAA0B,GAC1B,eAAe,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,mBAAmB;CAaxC;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA0D3D;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAWnE;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAiBlF"}

package/dist/errors.js

@@ -0,0 +1,115 @@
+import { C } from "./colors.js";
+export class TerminalError extends Error {
+    code;
+    title;
+    cause;
+    fix;
+    commandSuggestion;
+    docsHint;
+    exitCode;
+    retryable;
+    debugDetails;
+    constructor(params) {
+        super(params.title);
+        this.name = "TerminalError";
+        this.code = params.code;
+        this.title = params.title;
+        this.cause = params.cause;
+        this.fix = params.fix;
+        this.commandSuggestion = params.commandSuggestion;
+        this.docsHint = params.docsHint ?? "Run balchemy --help for command usage.";
+        this.exitCode = params.exitCode;
+        this.retryable = params.retryable ?? false;
+        this.debugDetails = params.debugDetails;
+    }
+}
+export function toTerminalError(err) {
+    if (err instanceof TerminalError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    if (/Config file not found:/i.test(message)) {
+        return new TerminalError({
+            code: "CONFIG_FILE_MISSING",
+            title: "Missing config file",
+            cause: message,
+            fix: "Run balchemy init or pass a config path.",
+            commandSuggestion: "balchemy start ./agent.config.yaml",
+            exitCode: 2,
+            debugDetails: err instanceof Error ? err.stack : undefined,
+        });
+    }
+    if (/Environment variable '.+' referenced in config is not set/i.test(message)) {
+        return new TerminalError({
+            code: "CONFIG_ENV_MISSING",
+            title: "Missing environment variable",
+            cause: message,
+            fix: "Add the missing variable to .env next to the config file or export it before running balchemy start.",
+            commandSuggestion: "balchemy config validate agent.config.yaml --verbose",
+            exitCode: 2,
+            debugDetails: err instanceof Error ? err.stack : undefined,
+        });
+    }
+    if (/Failed to parse YAML config:/i.test(message)) {
+        return new TerminalError({
+            code: "CONFIG_YAML_INVALID",
+            title: "Invalid YAML config",
+            cause: message,
+            fix: "Check indentation and validate the config before starting the cockpit.",
+            commandSuggestion: "balchemy config validate agent.config.yaml --verbose",
+            exitCode: 2,
+            debugDetails: err instanceof Error ? err.stack : undefined,
+        });
+    }
+    if (/EACCES|permission denied/i.test(message)) {
+        return new TerminalError({
+            code: "FILE_PERMISSION_DENIED",
+            title: "Cannot access file",
+            cause: message,
+            fix: "Choose a writable path or adjust permissions.",
+            exitCode: 6,
+            debugDetails: err instanceof Error ? err.stack : undefined,
+        });
+    }
+    return new TerminalError({
+        code: "RUNTIME_ERROR",
+        title: "Command failed",
+        cause: message,
+        fix: "Run the command again with --debug for technical details, or run balchemy --help for usage.",
+        commandSuggestion: "balchemy --help",
+        exitCode: 1,
+        retryable: false,
+        debugDetails: err instanceof Error ? err.stack : undefined,
+    });
+}
+export function terminalErrorToJson(error) {
+    return {
+        code: error.code,
+        title: error.title,
+        cause: error.cause,
+        fix: error.fix,
+        commandSuggestion: error.commandSuggestion ?? null,
+        docsHint: error.docsHint,
+        exitCode: error.exitCode,
+        retryable: error.retryable,
+    };
+}
+export function renderTerminalError(reporter, error) {
+    if (reporter.flags.json)
+        return;
+    reporter.error(`\n  ${C.ERR}${error.title}${C.R}\n`);
+    reporter.error(`  ${C.D}Cause${C.R}  ${error.cause}\n`);
+    reporter.error(`  ${C.D}Fix${C.R}    ${error.fix}\n`);
+    if (error.commandSuggestion) {
+        reporter.error(`  ${C.D}Command${C.R} ${C.W}${error.commandSuggestion}${C.R}\n`);
+    }
+    reporter.error(`  ${C.D}Help${C.R}    ${error.docsHint}\n`);
+    reporter.error(`  ${C.D}Exit${C.R}    ${error.exitCode}\n`);
+    if (reporter.flags.debug && error.debugDetails) {
+        reporter.error(`\n${C.D}${error.debugDetails}${C.R}\n`);
+    }
+    else if (error.debugDetails) {
+        reporter.error(`  ${C.D}Debug${C.R}   Re-run with --debug for technical details.\n`);
+    }
+    reporter.error("\n");
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,21 +2,8 @@
 /**
  * balchemy CLI entry point.
  *
- * On launch:
- *   - If ~/.balchemy/agents.enc has saved agents → offer resume, choose, or create/connect
- *   - If no saved agent → run wizard
- *
- * Sub-commands:
- *   (no args)       Resume cached agent or run wizard
- *   init / --init   Force run wizard (ignore cache)
- *   start [config]  Start from agent.config.yaml
- *   docker [outDir] Generate Docker files
- *   list            List saved agents
- *
- * Flags:
- *   --help, -h      Show help
- *   --version, -v   Show version
- *   --no-color      Disable colored output
+ * Public terminal surface for setup, local agent context, config validation,
+ * Docker file generation, and the Ink cockpit.
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;GAkBG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}