balchemy 0.2.1 → 0.2.3

package/README.md

@@ -3,8 +3,8 @@
 </h1>
 
 <p align="center">
-  <strong>Autonomous AI Trading Agent Platform</strong><br/>
-  Deploy a dual-LLM trading agent on Solana and EVM chains in 5 minutes.
+  <strong>Balchemy CLI</strong><br/>
+  Initialize a local trading agent, connect model credentials, set risk rules, and generate deployment files.
 </p>
 
 <p align="center">
@@ -17,20 +17,20 @@
 
 ---
 
-## What Is Balchemy?
+## What Balchemy Does
 
-Balchemy is an autonomous AI trading platform that connects your LLM to on-chain markets through the Model Context Protocol (MCP). You provide the strategy in natural language; your LLM decides when and what to trade; Balchemy handles wallets, execution, risk checks, and 100+ trading tools.
+Balchemy connects an external LLM to on-chain markets through MCP. The outer LLM
+chooses tools and instructions. Balchemy applies scopes, behavior rules, risk
+checks, execution, and records.
 
-**Architecture — Dual-LLM System:**
-- **External LLM** (your choice: Claude, GPT, Gemini, Grok, OpenRouter) — the brain that makes all decisions
-- **Inner LLM** (GPT-5.4-mini, server-side) — infrastructure servant that fetches data, formats responses, and serves the external LLM
+The inner LLM is infrastructure support. It fetches data and formats responses.
+It does not make trading decisions.
 
-Your LLM calls Balchemy tools via MCP — it picks the right tool from natural language descriptions, not hardcoded tool names.
-
-```
-You (strategy) → External LLM (decisions) → Balchemy MCP (execution) → Solana / Base / Ethereum
-                                  ↓
-                        Inner LLM (data fetching, formatting)
+```text
+Strategy -> external LLM -> Balchemy MCP -> policy -> execution -> record
+                                  |
+                                  v
+                         inner LLM support
 ```
 
 ## Quick Start
@@ -39,160 +39,186 @@ You (strategy) → External LLM (decisions) → Balchemy MCP (execution) → Sol
 npx balchemy
 ```
 
-The interactive wizard walks you through:
-1. **Pick your LLM** — Anthropic, OpenAI, Gemini, Grok, or OpenRouter
-2. **Set up wallets** — auto-provisioned Solana and EVM wallets
-3. **Define your strategy** — natural language rules ("max 5% position size, only trade on Solana")
-4. **Start the 24/7 agent loop** — your LLM monitors markets and trades autonomously
+The wizard handles five local steps:
+
+1. Choose an LLM provider.
+2. Add the provider API key.
+3. Set wallet and chain preferences.
+4. Define behavior rules in plain language.
+5. Start or export the agent runtime.
+
+## Commands
 
 ```bash
 npx balchemy              # Setup wizard or resume cached agent
-npx balchemy init          # Force new setup wizard
-npx balchemy start         # Start from agent.config.yaml
-npx balchemy list          # List saved agents
-npx balchemy docker        # Generate Docker files for deployment
-npx balchemy --help        # Show full usage info
-npx balchemy --version     # Show version
-npx balchemy --no-color    # Disable colored output (also: NO_COLOR=1)
+npx balchemy init         # New setup wizard
+npx balchemy start        # Start from agent.config.yaml
+npx balchemy list         # List saved agents
+npx balchemy docker       # Generate Docker files
+npx balchemy --help       # Usage
+npx balchemy --version    # Version
+npx balchemy --no-color   # Disable color output
 ```
 
-## What You Can Do
+`NO_COLOR=1` also disables colored output.
 
-### Trade
-- **Buy/Sell tokens** — `buy 0.1 SOL worth of BONK on Solana`
-- **Limit orders** — set price targets, get filled automatically
-- **DCA (Dollar-Cost Averaging)** — schedule recurring buys
-- **Trailing stops** — lock profits as price moves
+## Files Written
 
-### Research
-- **Token analysis** — market cap, volume, holder distribution, risk scores
-- **Smart money tracking** — follow profitable wallets
-- **Bundle detection** — spot insider token launches
-- **Price queries** — real-time Solana and EVM token prices
-
-### Manage
-- **Portfolio view** — see balances, P&L, positions across chains
-- **Behavior rules** — define trading constraints in natural language
-- **Subscriptions** — set up alerts for market events
-- **24/7 autonomous loop** — your LLM monitors and acts even when you're away
-
-### Risk Management (Built-In)
-Every trade passes through multi-layer safety checks before execution:
-- **RugCheck integration** — community risk scores
-- **Honeypot detection** — simulated sell before buying
-- **Contract verification** — liquidity locks, ownership renouncing
-- **Behavior rules enforcement** — your constraints are always respected
-
-## 100+ MCP Tools
-
-Your LLM accesses Balchemy through these primary agent-facing tools:
-
-| Tool | What It Does |
-|------|-------------|
-| `trade_command` | Execute buy/sell/swap on Solana or EVM |
-| `ask_bot` | Natural language market queries (inner LLM-powered) |
-| `agent_research` | Deep token research with technical analysis |
-| `agent_portfolio` | Portfolio, positions, P&L overview |
-| `configure_behavior_rules` | Set trading constraints in natural language |
-| `get_behavior_rules` | Read current active rules |
-| `create_subscription` | Set up market event alerts |
-| `setup_agent` | Wallet provisioning and onboarding |
-
-Plus 90+ internal tools for research, risk scoring, and execution — your LLM picks the right one from descriptions.
-
-## LLM Providers
-
-| Provider | Environment Variable | Notes |
-|-----------|---------------------|-------|
-| Anthropic | `ANTHROPIC_API_KEY` | Haiku 4.5, Sonnet 4.6, Opus 4.6+ |
-| OpenAI | `OPENAI_API_KEY` | GPT-4o, GPT-5.4, etc. |
-| Google Gemini | `GEMINI_API_KEY` | Gemini 3.1 Pro, Flash |
-| Google Vertex AI | `GOOGLE_APPLICATION_CREDENTIALS` | Gemini 3.1 Pro via Vertex AI |
-| xAI Grok | `GROK_API_KEY` | Grok-4-1-fast for research |
-| OpenRouter | `OPENROUTER_API_KEY` | Access to 100+ models |
-
-## Configuration
-
-After setup, `agent.config.yaml` and `.env` are generated in the current directory:
+The CLI writes local runtime files in the current directory.
 
 ```yaml
 # agent.config.yaml
 llm:
   provider: anthropic
-  model: claude-sonnet-4-20250514
+  model: selected-in-wizard
 
 agent:
   name: my-trading-agent
-  strategy: Focus on Solana memecoins with high volume and positive sentiment
+  strategy: Focus on liquid markets. Keep position size below 5%.
 
 wallets:
   solana:
     chain: solana
   evm:
-    chainId: 8453  # Base
+    chainId: 8453
 ```
 
-Edit these files to change settings without re-running the wizard.
+Secrets belong in `.env`. Do not commit that file.
+
+## What You Can Do
+
+### Trade
 
-## 24/7 Autonomous Mode
+- Buy and sell on Solana and EVM chains.
+- Create limit orders.
+- Schedule DCA rules.
+- Use trailing stops.
 
-The SDK includes an `AgentLoop` that keeps your LLM connected to Balchemy permanently:
+### Research
+
+- Query token price, liquidity, volume, and holder distribution.
+- Check risk signals before a trade.
+- Track wallets and market events.
+- Compare positions across chains.
+
+### Manage
+
+- View portfolio, balances, positions, and PnL.
+- Define behavior rules in natural language.
+- Subscribe to market events.
+- Rotate scoped MCP keys in Hub.
+
+## Risk Model
+
+Every trade path is expected to pass risk checks before execution:
+
+- RugCheck signals.
+- Honeypot simulation.
+- Contract and liquidity checks.
+- Behavior rule enforcement.
+- Scoped MCP permissions.
+
+The wallet remains the authority. Keep private keys and seed phrases out of
+source, logs, screenshots, and prompts.
+
+## MCP Tools
+
+The CLI connects agents to the curated agent-facing MCP surface.
+
+| Tool | Purpose |
+| --- | --- |
+| `trade_command` | Buy, sell, or swap through the approved execution path |
+| `ask_bot` | Natural language market query support |
+| `agent_research` | Token and market research |
+| `agent_portfolio` | Portfolio, positions, and PnL |
+| `configure_behavior_rules` | Trading constraints in natural language |
+| `get_behavior_rules` | Current active rules |
+| `create_subscription` | Market event subscription |
+| `setup_agent` | Onboarding and runtime setup |
+
+Granular internal tools stay hidden unless the platform enables them for a bot.
+
+## LLM Providers
+
+| Provider | Environment variable |
+| --- | --- |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Google Gemini | `GEMINI_API_KEY` |
+| Google Vertex AI | `GOOGLE_APPLICATION_CREDENTIALS` |
+| xAI Grok | `GROK_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+
+Pick the model in the wizard or edit `agent.config.yaml`.
+
+## Runtime Mode
+
+The SDK includes an `AgentLoop` for long-running agents.
 
 ```ts
-import { BalchemyAgentSdk, AgentLoop } from "@balchemyai/agent-sdk";
+import { AgentLoop, BalchemyAgentSdk } from "@balchemyai/agent-sdk";
+
+const sdk = new BalchemyAgentSdk({
+  apiBaseUrl: "https://api.balchemy.ai/api",
+});
 
-const sdk = new BalchemyAgentSdk({ apiBaseUrl: "https://api.balchemy.ai/api" });
-const loop = new AgentLoop(sdk, { apiKey: "your-mcp-api-key" });
+const loop = new AgentLoop(sdk, {
+  apiKey: "your-mcp-api-key",
+});
 
-// Starts SSE event stream + polling cycle
-// Your LLM receives market events and decides whether to act
 await loop.start();
 ```
 
-Events flow: Market event → SSE push → Your LLM evaluates → `trade_command` if relevant → Execution → Confirmation push
+Event flow:
+
+```text
+Market event -> SSE -> external LLM evaluates -> MCP tool call -> execution -> confirmation
+```
+
+## Hub
 
-## Hub Integration
+Agents registered through the CLI appear in [Balchemy Hub](https://balchemy.ai/hub).
 
-When you bind your EVM wallet during setup, your agent appears in your [Balchemy Hub](https://balchemy.ai/hub) dashboard:
-- **Monitor** — live portfolio, trade history, event log
-- **API Keys** — create, rotate, and revoke MCP keys with scoped permissions
-- **Scope Management** — `read` for data-only, `trade` for full execution
-- **Wallet Management** — link/unlink Solana and EVM wallets
+- Monitor portfolio, trade history, and event logs.
+- Create, rotate, and revoke MCP keys.
+- Keep `read` and `trade` scopes separate.
+- Link Solana and EVM wallets.
 
 ## Security
 
-- **Encrypted credentials** — AES-256-GCM at rest with PBKDF2 key derivation
-- **Scoped API keys** — `read` and `trade` permissions, instant revocation
-- **No seed phrases stored** — all keys encrypted, never logged
-- **Behavior rules** — hard constraints that even your LLM cannot override
-- **Pre-trade safety checks** — RugCheck, honeypot detection, contract verification
+- Credentials are encrypted at rest.
+- MCP keys are scoped and revocable.
+- Behavior rules constrain execution.
+- Pre-trade checks run before approved execution.
+- Seed phrases should never be stored in source or logs.
 
-## TUI Keyboard Shortcuts
+## TUI Shortcuts
 
 | Shortcut | Action |
-|----------|--------|
-| `^S` | Open settings panel |
+| --- | --- |
+| `^S` | Open settings |
 | `^L` | Clear chat history |
-| `^N` | New agent (return to launcher) |
+| `^N` | New agent |
 | `^Q` | Quit |
 | `PgUp/PgDn` | Scroll message history |
-| `Esc` | Go back (settings/wizard) |
+| `Esc` | Go back |
 
 ## Requirements
 
 - Node.js 18+
-- An LLM API key from any supported provider
+- One supported LLM provider key
 
 ## Links
 
-- **Platform:** [balchemy.ai](https://balchemy.ai)
-- **Documentation:** [balchemy.ai/hub/docs](https://balchemy.ai/hub/docs)
-- **Agent Explorer:** [balchemy.ai/explorer](https://balchemy.ai/explorer)
-- **GitHub:** [github.com/balchemy/balchemy-agent](https://github.com/balchemy/balchemy-agent)
-- **npm:** [balchemy](https://www.npmjs.com/package/balchemy) · [@balchemyai/agent-sdk](https://www.npmjs.com/package/@balchemyai/agent-sdk)
-- **X:** [@balchemyai](https://x.com/balchemyai)
-- **Contact:** [burak@balchemy.ai](mailto:burak@balchemy.ai)
+- [Platform](https://balchemy.ai)
+- [Documentation](https://balchemy.ai/hub/docs)
+- [Agent Explorer](https://balchemy.ai/explorer)
+- [GitHub](https://github.com/balchemy/balchemy-agent)
+- [npm: balchemy](https://www.npmjs.com/package/balchemy)
+- [npm: @balchemyai/agent-sdk](https://www.npmjs.com/package/@balchemyai/agent-sdk)
+- [X: @balchemyai](https://x.com/balchemyai)
+- [Contact](mailto:burak@balchemy.ai)
 
 ## License
 
-MIT
+MIT

package/dist/cli-options.d.ts

@@ -0,0 +1,23 @@
+export interface CliFlags {
+    help: boolean;
+    version: boolean;
+    noColor: boolean;
+    json: boolean;
+    quiet: boolean;
+    verbose: boolean;
+    debug: boolean;
+    ci: boolean;
+    dryRun: boolean;
+    yes: boolean;
+    force: boolean;
+}
+export interface ParsedCliArgs {
+    flags: CliFlags;
+    commandPath: string[];
+    args: string[];
+    unknownFlags: string[];
+}
+export declare function parseCliArgs(rawArgs: string[]): ParsedCliArgs;
+export declare function commandKey(commandPath: string[]): string;
+export declare function isNonInteractive(flags: CliFlags): boolean;
+//# sourceMappingURL=cli-options.d.ts.map

package/dist/cli-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-options.d.ts","sourceRoot":"","sources":["../src/cli-options.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAqED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,CA2B7D;AAED,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAExD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEzD"}

package/dist/cli-options.js

@@ -0,0 +1,87 @@
+const GLOBAL_FLAG_ALIASES = {
+    "--help": "help",
+    "-h": "help",
+    "--version": "version",
+    "-v": "version",
+    "--no-color": "noColor",
+    "--json": "json",
+    "--quiet": "quiet",
+    "-q": "quiet",
+    "--verbose": "verbose",
+    "--debug": "debug",
+    "--ci": "ci",
+    "--dry-run": "dryRun",
+    "--yes": "yes",
+    "-y": "yes",
+    "--force": "force",
+};
+function defaultFlags() {
+    return {
+        help: false,
+        version: false,
+        noColor: false,
+        json: false,
+        quiet: false,
+        verbose: false,
+        debug: false,
+        ci: false,
+        dryRun: false,
+        yes: false,
+        force: false,
+    };
+}
+function splitCommandAndArgs(positional) {
+    const first = positional[0];
+    const second = positional[1];
+    if (!first)
+        return { commandPath: [], args: [] };
+    if (first === "agent" && ["list", "current", "use"].includes(second ?? "")) {
+        return { commandPath: [first, second], args: positional.slice(2) };
+    }
+    if (first === "auth" && ["status", "login", "logout"].includes(second ?? "")) {
+        return { commandPath: [first, second], args: positional.slice(2) };
+    }
+    if (first === "context" && ["current", "status"].includes(second ?? "")) {
+        return { commandPath: ["agent", "current"], args: positional.slice(2) };
+    }
+    if (first === "tui") {
+        return { commandPath: ["start"], args: positional.slice(1) };
+    }
+    if (first === "config" && ["validate", "list"].includes(second ?? "")) {
+        return { commandPath: [first, second], args: positional.slice(2) };
+    }
+    if (first === "docker" && second === "generate") {
+        return { commandPath: [first], args: positional.slice(2) };
+    }
+    return { commandPath: [first], args: positional.slice(1) };
+}
+export function parseCliArgs(rawArgs) {
+    const flags = defaultFlags();
+    const positional = [];
+    const unknownFlags = [];
+    for (const arg of rawArgs) {
+        if (arg === "--init") {
+            positional.push("init");
+            continue;
+        }
+        const flagName = GLOBAL_FLAG_ALIASES[arg];
+        if (flagName) {
+            flags[flagName] = true;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            unknownFlags.push(arg);
+            continue;
+        }
+        positional.push(arg);
+    }
+    const { commandPath, args } = splitCommandAndArgs(positional);
+    return { flags, commandPath, args, unknownFlags };
+}
+export function commandKey(commandPath) {
+    return commandPath.join(" ");
+}
+export function isNonInteractive(flags) {
+    return flags.ci || !process.stdin.isTTY || !process.stdout.isTTY;
+}
+//# sourceMappingURL=cli-options.js.map

package/dist/cli-options.js.map

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

package/dist/docker-gen.d.ts

@@ -2,5 +2,24 @@
  * Generates Dockerfile + docker-compose.yml for the agent.
  * Copies static template files and does not mutate them.
  */
-export declare function generateDocker(outDir: string): Promise<void>;
+export type DockerFileAction = "create" | "overwrite" | "skip";
+export interface DockerFilePlan {
+    filename: string;
+    path: string;
+    action: DockerFileAction;
+    exists: boolean;
+    wouldOverwrite: boolean;
+    containsSecret: boolean;
+}
+export interface DockerGenerationPlan {
+    outDir: string;
+    files: DockerFilePlan[];
+    hasOverwrites: boolean;
+}
+export interface DockerGenerationOptions {
+    dryRun?: boolean;
+    force?: boolean;
+}
+export declare function buildDockerPlan(outDir: string): DockerGenerationPlan;
+export declare function generateDocker(outDir: string, options?: DockerGenerationOptions): Promise<DockerGenerationPlan>;
 //# sourceMappingURL=docker-gen.d.ts.map

package/dist/docker-gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docker-gen.d.ts","sourceRoot":"","sources":["../src/docker-gen.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBlE"}
+{"version":3,"file":"docker-gen.d.ts","sourceRoot":"","sources":["../src/docker-gen.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAgCD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAqCpE;AAMD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,oBAAoB,CAAC,CA4B/B"}

package/dist/docker-gen.js

@@ -2,39 +2,101 @@
  * Generates Dockerfile + docker-compose.yml for the agent.
  * Copies static template files and does not mutate them.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { TerminalError } from "./errors.js";
 const __filename_esm = fileURLToPath(import.meta.url);
 const __dirname_esm = path.dirname(__filename_esm);
-const TEMPLATES_DIR = path.join(__dirname_esm, '..', 'templates');
-function copyTemplate(filename, outDir) {
-    const src = path.join(TEMPLATES_DIR, filename);
-    const dest = path.join(outDir, filename);
+const TEMPLATES_DIR = path.join(__dirname_esm, "..", "templates");
+function templatePath(filename) {
+    return path.join(TEMPLATES_DIR, filename);
+}
+function assertTemplateExists(filename) {
+    const src = templatePath(filename);
     if (!fs.existsSync(src)) {
-        throw new Error(`Template file not found: ${src}`);
+        throw new TerminalError({
+            code: "CONFIG_FILE_MISSING",
+            title: "Docker template missing",
+            cause: `Template file not found: ${src}`,
+            fix: "Reinstall the balchemy CLI package or run from a complete build artifact.",
+            exitCode: 2,
+        });
     }
-    fs.copyFileSync(src, dest);
-    process.stdout.write(`  wrote ${dest}\n`);
 }
-export async function generateDocker(outDir) {
+function plannedFile(outDir, filename, overwriteAllowed) {
+    const dest = path.join(outDir, filename);
+    const exists = fs.existsSync(dest);
+    return {
+        filename,
+        path: dest,
+        action: exists ? (overwriteAllowed ? "overwrite" : "skip") : "create",
+        exists,
+        wouldOverwrite: exists && overwriteAllowed,
+        containsSecret: false,
+    };
+}
+export function buildDockerPlan(outDir) {
     if (!fs.existsSync(outDir)) {
-        throw new Error(`Output directory does not exist: ${outDir}`);
+        throw new TerminalError({
+            code: "CONFIG_FILE_MISSING",
+            title: "Output directory does not exist",
+            cause: `Output directory does not exist: ${outDir}`,
+            fix: "Create the directory first or pass an existing output directory.",
+            commandSuggestion: "mkdir -p ./deploy && balchemy docker ./deploy --dry-run",
+            exitCode: 2,
+        });
+    }
+    if (!fs.statSync(outDir).isDirectory()) {
+        throw new TerminalError({
+            code: "CONFIG_FILE_MISSING",
+            title: "Output path is not a directory",
+            cause: `Output path is not a directory: ${outDir}`,
+            fix: "Pass a directory path for Docker file generation.",
+            exitCode: 2,
+        });
+    }
+    for (const filename of ["Dockerfile", "docker-compose.yml", ".env.example"]) {
+        assertTemplateExists(filename);
+    }
+    const files = [
+        plannedFile(outDir, "Dockerfile", true),
+        plannedFile(outDir, "docker-compose.yml", true),
+        plannedFile(outDir, ".env.example", false),
+    ];
+    return {
+        outDir,
+        files,
+        hasOverwrites: files.some((file) => file.wouldOverwrite),
+    };
+}
+function copyTemplate(filename, dest) {
+    fs.copyFileSync(templatePath(filename), dest);
+}
+export async function generateDocker(outDir, options = {}) {
+    const plan = buildDockerPlan(outDir);
+    if (options.dryRun) {
+        return plan;
     }
-    process.stdout.write(`Generating Docker files in ${outDir}...\n`);
-    copyTemplate('Dockerfile', outDir);
-    copyTemplate('docker-compose.yml', outDir);
-    // Write .env.example only if not already present (don't overwrite real .env)
-    const envExampleDest = path.join(outDir, '.env.example');
-    if (!fs.existsSync(envExampleDest)) {
-        copyTemplate('.env.example', envExampleDest);
+    if (plan.hasOverwrites && !options.force) {
+        const targets = plan.files
+            .filter((file) => file.wouldOverwrite)
+            .map((file) => file.path)
+            .join(", ");
+        throw new TerminalError({
+            code: "FILE_OVERWRITE_CONFIRMATION_REQUIRED",
+            title: "Overwrite confirmation required",
+            cause: `Existing files would be overwritten: ${targets}`,
+            fix: "Review the preview and type overwrite, or rerun with --dry-run to inspect without writing.",
+            commandSuggestion: `balchemy docker ${outDir} --dry-run`,
+            exitCode: 4,
+        });
     }
-    else {
-        process.stdout.write(`  skipped .env.example (already exists)\n`);
+    for (const file of plan.files) {
+        if (file.action === "skip")
+            continue;
+        copyTemplate(file.filename, file.path);
     }
-    process.stdout.write(`\nNext steps:\n` +
-        `  1. Copy .env.example to .env and fill in your credentials\n` +
-        `  2. Place your agent.config.yaml in the same directory\n` +
-        `  3. Run: docker compose up -d\n`);
+    return plan;
 }
 //# sourceMappingURL=docker-gen.js.map

package/dist/docker-gen.js.map

@@ -1 +1 @@
-{"version":3,"file":"docker-gen.js","sourceRoot":"","sources":["../src/docker-gen.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtD,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;AACnD,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;AAElE,SAAS,YAAY,CAAC,QAAgB,EAAE,MAAc;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAc;IACjD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,MAAM,OAAO,CAAC,CAAC;IAElE,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACnC,YAAY,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IAE3C,6EAA6E;IAC7E,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACzD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACnC,YAAY,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IAC/C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACpE,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iBAAiB;QACjB,+DAA+D;QAC/D,2DAA2D;QAC3D,kCAAkC,CACnC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"docker-gen.js","sourceRoot":"","sources":["../src/docker-gen.ts"],"names":[],"mappings":"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"}