badgr-cli 1.0.31 → 1.0.34

package/src/commands/test-run.js

@@ -0,0 +1,240 @@
+import { requireApiKey } from '../config.js';
+import { callApi, terminateDeployment } from '../api.js';
+import { addReceipt, generateReceiptId } from '../store.js';
+
+// max $0.80/hr × 2 min ≈ $0.027 total spend cap (smoke / Modal T4 tier)
+const TEST_MAX_PRICE  = 0.80;
+const TEST_MAX_RUNTIME_MS = 2 * 60 * 1000;
+const TEST_COMMAND    = ['python', '-c', "print('hello from badgr')"];
+// Use alpine (7MB) instead of slim (50MB) — dramatically faster image pull for smoke tests.
+// Falls back gracefully: alpine has python3 and supports the test command identically.
+const TEST_IMAGE      = 'python:3.11-alpine';
+const EXPECTED_OUTPUT = 'hello from badgr';
+
+// --provider flag resolves to a backend tier value.
+// 'tier1' → managed routing (default), 'tier2' → marketplace routing, 'secondary' → secondary dispatch.
+const PROVIDER_TO_TIER = { tier1: '1', tier2: '2', secondary: 'modal' };
+
+export function parseTestArgs(args) {
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    if (args[i] === '--provider' && args[i + 1]) { flags.provider = args[++i]; i++; continue; }
+    if (args[i] === '--no-tier-fallback') { flags.noTierFallback = true; i++; continue; }
+    i++;
+  }
+  return flags;
+}
+
+function step(chalk, ok, msg, detail = '') {
+  const icon = ok ? chalk.green('✓') : chalk.red('✗');
+  const suffix = detail ? chalk.dim(` — ${detail}`) : '';
+  console.log(`  ${icon} ${msg}${suffix}`);
+}
+
+async function pollStatus(config, depId, targetStatuses, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, 3000));
+    try {
+      const dep = await callApi(`/deployments/${depId}`, {
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+      });
+      if (targetStatuses.has(dep.status)) return dep;
+    } catch { /* retry */ }
+  }
+  return null;
+}
+
+async function pollOutputOrDone(config, depId, expected, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, 3000));
+    try {
+      const dep = await callApi(`/deployments/${depId}`, {
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+      });
+      if (dep.status === 'succeeded' || dep.status === 'failed') {
+        const data = await callApi(`/deployments/${depId}/logs`, {
+          apiKey: config.apiKey,
+          baseUrl: config.baseUrl,
+        });
+        const lines = data?.logs ?? [];
+        return {
+          done: true,
+          ok: dep.status === 'succeeded' && lines.some(l => l.includes(expected)),
+          exitCode: dep.exit_code,
+        };
+      }
+      const data = await callApi(`/deployments/${depId}/logs`, {
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+      });
+      const lines = data?.logs ?? [];
+      if (lines.some(l => l.includes(expected))) return { done: true, ok: true, exitCode: 0 };
+    } catch { /* retry */ }
+  }
+  return { done: false, ok: false, exitCode: null };
+}
+
+export async function testCommand(config, args, chalk) {
+  requireApiKey(config);
+
+  const flags = parseTestArgs(Array.isArray(args) ? args : []);
+  const providerKey = flags.provider ? flags.provider.toLowerCase() : 'tier1';
+
+  if (providerKey === 'secondary') {
+    // Secondary dispatch provider uses a webhook model, not direct GPU rental.
+    // Verify the backend reports it as configured.
+    console.log(chalk.bold('\n⚡ Testing secondary dispatch provider\n'));
+    let routes;
+    try {
+      routes = await callApi('/compute/routes', { apiKey: config.apiKey, baseUrl: config.baseUrl });
+    } catch {
+      routes = null;
+    }
+    const secondaryRoute = Array.isArray(routes) ? routes.find(r => r.name === 'modal') : null;
+    if (secondaryRoute?.available) {
+      step(chalk, true, 'Secondary provider configured');
+      console.log(chalk.green('\n  ✓ Secondary dispatch provider is ready\n'));
+    } else {
+      step(chalk, false, 'Secondary provider configured', 'contact support to enable secondary dispatch');
+      console.log(chalk.red('\n  ✗ Secondary dispatch provider is not configured\n'));
+      process.exit(1);
+    }
+    return;
+  }
+
+  const tier = PROVIDER_TO_TIER[providerKey] ?? '1';
+  const tierLabel = tier === '1' ? 'tier 1 (managed routing)' : 'tier 2 (marketplace routing)';
+
+  console.log(chalk.bold('\n⚡ Running end-to-end test\n'));
+  console.log(chalk.dim(`  Command:  ${TEST_COMMAND.join(' ')}`));
+  console.log(chalk.dim(`  Routing:  ${tier === '1' ? 'tier 1 — managed provider routing' : 'tier 2 — marketplace routing'}`));
+  console.log(chalk.dim(`  Budget:   max $${TEST_MAX_PRICE.toFixed(2)}/hr · 2 minute cap (~$0.05 max)`));
+  console.log();
+
+  const rcptId = generateReceiptId();
+  let depId;
+
+  // ── 1. Provision ─────────────────────────────────────────────────────────
+  process.stdout.write(chalk.dim(`  Provisioning GPU (${tierLabel})...\n`));
+  let dep;
+  const baseBody = {
+    command: TEST_COMMAND,
+    image:   TEST_IMAGE,
+    gpu:     'auto',
+    max_price_per_hour: TEST_MAX_PRICE,
+  };
+  try {
+    dep = await callApi('/run', {
+      method: 'POST',
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      body: { ...baseBody, tier },
+    });
+  } catch (err) {
+    if (err.errorData?.code === 'NO_CAPACITY_MATCH' && tier === '1' && !flags.noTierFallback) {
+      process.stdout.write('\n');
+      process.stdout.write(chalk.dim('  No tier 1 capacity — trying tier 2 marketplace routing...'));
+      try {
+        dep = await callApi('/run', {
+          method: 'POST',
+          apiKey: config.apiKey,
+          baseUrl: config.baseUrl,
+          body: { ...baseBody, tier: '2' },
+        });
+      } catch (err2) {
+        process.stdout.write('\n');
+        step(chalk, false, 'Provisioned', err2.message);
+        console.log();
+        console.error(chalk.red('  Test failed — no GPU capacity available on any provider.\n'));
+        process.exit(1);
+      }
+    } else if (err.errorData?.code === 'NO_CAPACITY_MATCH' && flags.noTierFallback) {
+      process.stdout.write('\n');
+      step(chalk, false, 'Provisioned', 'no tier 1 capacity');
+      console.log();
+      console.error(chalk.red('  Test failed — no tier 1 capacity (strict mode, no tier 2 fallback).\n'));
+      process.exit(1);
+    } else {
+      process.stdout.write('\n');
+      step(chalk, false, 'Provisioned', err.message);
+      console.log();
+      console.error(chalk.red('  Test failed — could not provision GPU.\n'));
+      process.exit(1);
+    }
+  }
+  depId = dep.deployment_id;
+  process.stdout.write('\n');
+  step(chalk, true, 'Provisioned', `${dep.deployment_id} on ${dep.gpu_type}`);
+
+  // ── 2. Container started ─────────────────────────────────────────────────
+  process.stdout.write(chalk.dim('  Waiting for container to start...'));
+  const started = await pollStatus(
+    config, depId,
+    // Modal serverless jobs may skip straight to succeeded when the callback fires.
+    new Set(['running', 'starting', 'succeeded', 'failed', 'stopped', 'completed']),
+    TEST_MAX_RUNTIME_MS,
+  );
+  process.stdout.write('\n');
+
+  if (!started || started.status === 'failed') {
+    step(chalk, false, 'Container started', started?.status ?? 'timeout');
+    console.log();
+    console.error(chalk.red('  Test failed — container did not start.\n'));
+    try { await terminateDeployment(config, depId); } catch { /* best-effort */ }
+    process.exit(1);
+  }
+  step(chalk, true, 'Container started');
+
+  // ── 3. Command output ────────────────────────────────────────────────────
+  process.stdout.write(chalk.dim('  Checking command output...'));
+  const outputResult = await pollOutputOrDone(config, depId, EXPECTED_OUTPUT, 90_000);
+  process.stdout.write('\n');
+  const gotOutput = outputResult.ok;
+  if (gotOutput) {
+    step(chalk, true, 'Command printed output');
+  } else if (outputResult.done && outputResult.exitCode !== 0) {
+    step(chalk, false, 'Command printed output', `exit ${outputResult.exitCode}`);
+  } else {
+    step(chalk, false, 'Command printed output', 'not found in logs (logs may be buffered)');
+  }
+
+  // ── 4. Stop billing ──────────────────────────────────────────────────────
+  process.stdout.write(chalk.dim('  Stopping deployment...'));
+  let stopped = false;
+  try {
+    await terminateDeployment(config, depId);
+    stopped = true;
+  } catch { /* best-effort */ }
+  process.stdout.write('\n');
+  step(chalk, stopped, 'Billing stopped');
+
+  // ── 5. Receipt ───────────────────────────────────────────────────────────
+  addReceipt({
+    receiptId:    rcptId,
+    action:       'badgr test',
+    deploymentId: depId,
+    gpu:          dep.gpu_type,
+    status:       gotOutput ? 'test_passed' : 'test_failed',
+    createdAt:    new Date().toISOString(),
+  });
+  step(chalk, true, 'Receipt created', rcptId);
+
+  // ── Summary ──────────────────────────────────────────────────────────────
+  console.log();
+  const passed = stopped && gotOutput;
+  if (passed) {
+    console.log(chalk.green(chalk.bold('  ✓ Test passed\n')));
+  } else {
+    if (!gotOutput) {
+      console.error(chalk.red('  Test failed — expected output not found in logs\n'));
+    } else {
+      console.error(chalk.red('  Test failed — could not stop billing\n'));
+    }
+    process.exit(1);
+  }
+}

package/src/commands/up.js

@@ -1,37 +1,31 @@
 import { parseSpec, validateSpec, specLines } from '../spec.js';
-import { getRoutePlan } from '../router.js';
 import { requireApiKey } from '../config.js';
 import { generateDeploymentId, generateReceiptId, addDeployment, addReceipt } from '../store.js';
-import { createDeployment } from '../api.js';
+import { createDeployment, callApi } from '../api.js';
 
-const OVERHEAD_PCT = 0.25;
+function printLivePlan(suggestions, gpu, chalk) {
+  const { matches = [], alternatives = [] } = suggestions;
 
-function printRoutePlan(plan, chalk) {
-  const { lane1, lane2, cheapestRate, costWithOverhead, canonical } = plan;
-
-  console.log(chalk.bold('  Lane 1 — Own GPU Hosts'));
+  console.log(chalk.bold('  Live availability'));
   console.log(`  ${'─'.repeat(40)}`);
-  console.log(chalk.dim(`  ${lane1.description}`));
+  if (matches.length === 0) {
+    console.log(chalk.yellow(`  No ${gpu} capacity found right now`));
+  } else {
+    const cheapest = matches[0];
+    console.log(`  ${chalk.cyan(gpu)} available — from ${chalk.green('$' + cheapest.price.toFixed(2) + '/hr')}`);
+    console.log(chalk.dim(`  ${matches.length} offer(s) found`));
+  }
   console.log();
 
-  console.log(chalk.bold('  Lane 2 — Overflow Providers  (cheapest-first)'));
-  console.log(`  ${'─'.repeat(40)}`);
-  if (lane2.length === 0) {
-    console.log(chalk.yellow(`  No pricing data for ${canonical}`));
-  } else {
-    lane2.forEach((p, i) => {
-      const arrow = i === 0 ? chalk.green(' ← primary') : '';
-      console.log(
-        `  ${String(i + 1)}. ${p.provider.padEnd(12)} ${canonical.padEnd(10)}` +
-        `  $${p.ratePerHour.toFixed(2)}/hr` +
-        `  reliability: ${Math.round(p.reliability * 100)}%${arrow}`
-      );
+  if (alternatives.length > 0) {
+    console.log(chalk.bold('  Alternatives if unavailable'));
+    console.log(`  ${'─'.repeat(40)}`);
+    alternatives.slice(0, 3).forEach((a, i) => {
+      const diff = a.diff_desc ? chalk.dim(` — ${a.diff_desc}`) : '';
+      console.log(`  ${i + 1}. ${chalk.cyan(a.gpu)} in ${a.region}  $${a.price.toFixed(2)}/hr${diff}`);
     });
     console.log();
-    console.log(`  Estimated range: $${cheapestRate.toFixed(2)}–$${lane2[lane2.length - 1].ratePerHour.toFixed(2)}/hr`);
-    console.log(chalk.dim(`  Estimated Badgr price: ~$${costWithOverhead.toFixed(2)}/hr`));
   }
-  console.log();
   console.log(chalk.dim('  Remove --dry-run to provision.'));
   console.log();
 }
@@ -45,15 +39,27 @@ export async function upCommand(config, args, chalk) {
     return;
   }
 
-  // ── Dry-run: show route plan and exit ─────────────────────────────────────
+  // ── Dry-run: show live route plan from backend ───────────────────────────
   if (spec.dryRun) {
     console.log(chalk.bold('\n🔍 Dry Run — Route Plan\n'));
     console.log(chalk.bold('  Spec'));
     console.log(`  ${'─'.repeat(40)}`);
     specLines(spec).forEach(l => console.log(`  ${l}`));
     console.log();
-    const plan = getRoutePlan(spec.gpu, spec.count);
-    printRoutePlan(plan, chalk);
+
+    requireApiKey(config);
+    try {
+      const params = new URLSearchParams({ gpu: spec.gpu, max_price: String(spec.maxPrice ?? 10) });
+      if (spec.region) params.set('region', spec.region);
+      const suggestions = await callApi(`/capacity/suggestions?${params}`, {
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+      });
+      printLivePlan(suggestions, spec.gpu, chalk);
+    } catch (err) {
+      console.log(chalk.yellow(`  Could not fetch live availability: ${err.message}`));
+      console.log(chalk.dim('  Tip: check `badgr capacity` for live data.\n'));
+    }
     return;
   }
 

package/src/config.js

@@ -6,16 +6,61 @@ export const CONFIG_DIR = join(homedir(), '.badgr');
 export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
 
 export const DEFAULTS = {
-  baseUrl: 'https://api.badgr.ai/v1',
+  baseUrl: 'https://aibadgr.com/v1',
   defaultModel: 'meta-llama/Llama-3.1-8B-Instruct',
 };
 
+/** URLs that do not resolve or are superseded by aibadgr.com/v1 (nginx) */
+const LEGACY_BASE_URLS = new Set([
+  'https://api.badgr.ai/v1',
+  'https://api.badgr.ai',
+  'http://api.badgr.ai/v1',
+  'http://api.badgr.ai',
+  'https://api.aibadgr.com/v1',
+  'https://api.aibadgr.com',
+  'http://api.aibadgr.com/v1',
+  'http://api.aibadgr.com',
+]);
+
+export function normalizeBaseUrl(url) {
+  if (!url?.trim()) return DEFAULTS.baseUrl;
+  const trimmed = url.trim().replace(/\/+$/, '');
+  if (LEGACY_BASE_URLS.has(trimmed)) return DEFAULTS.baseUrl;
+  return trimmed.endsWith('/v1') ? trimmed : `${trimmed}/v1`;
+}
+
+function applyEnvOverrides(config) {
+  const envBase = process.env.BADGR_API_URL?.trim();
+  if (envBase) config.baseUrl = normalizeBaseUrl(envBase);
+  const envKey = process.env.BADGR_API_KEY?.trim();
+  if (envKey) config.apiKey = envKey;
+  return config;
+}
+
 export function loadConfig(configFile = CONFIG_FILE) {
-  if (!existsSync(configFile)) return { ...DEFAULTS };
+  if (!existsSync(configFile)) {
+    return applyEnvOverrides({ ...DEFAULTS });
+  }
   try {
-    return { ...DEFAULTS, ...JSON.parse(readFileSync(configFile, 'utf8')) };
+    const parsed = JSON.parse(readFileSync(configFile, 'utf8'));
+    const previousBase = parsed.baseUrl;
+    const config = applyEnvOverrides({
+      ...DEFAULTS,
+      ...parsed,
+      baseUrl: normalizeBaseUrl(parsed.baseUrl ?? DEFAULTS.baseUrl),
+    });
+    if (
+      configFile === CONFIG_FILE &&
+      previousBase &&
+      normalizeBaseUrl(previousBase) !== previousBase
+    ) {
+      const merged = { ...parsed, baseUrl: config.baseUrl };
+      mkdirSync(dirname(configFile), { recursive: true });
+      writeFileSync(configFile, JSON.stringify(merged, null, 2));
+    }
+    return config;
   } catch {
-    return { ...DEFAULTS };
+    return applyEnvOverrides({ ...DEFAULTS });
   }
 }
 

package/src/errors.js

@@ -0,0 +1,299 @@
+/**
+ * Unified CLI error catalog — single source of truth for all user-facing errors.
+ *
+ * Each entry defines:
+ *   message  — what happened (user-safe, no provider/host details)
+ *   billing  — whether billing started, stopped, or is uncertain
+ *   retried  — whether Badgr automatically retried before surfacing this error
+ *   hint     — concrete next step(s) for the user
+ *   severity — P1/P2/P3/P4 for backend incident tracking
+ *
+ * Use formatCliError() to render entries as multiline CLI output.
+ * Pass internal-only fields (provider names, raw errors) via the `internal`
+ * argument — they are only shown when BADGR_DEBUG=1.
+ */
+
+export const CATALOG = {
+  // ── Capacity ──────────────────────────────────────────────────────────────
+
+  NO_CAPACITY: {
+    message: (ctx) =>
+      `No ${ctx.gpu || 'GPU'} available${ctx.region ? ` in ${ctx.region}` : ''} right now.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: (ctx) => [
+      ...(ctx.alternatives?.length
+        ? [`Closest available: ${ctx.alternatives.slice(0, 2).map(a => a.gpu).join(', ')}`]
+        : []),
+      ctx.region ? 'Remove --region to search globally.' : null,
+      'Run `badgr capacity` to see live availability.',
+    ].filter(Boolean),
+    severity: 'P3',
+  },
+
+  STALE_CAPACITY: {
+    message: () => 'A GPU slot appeared available but could not be reserved (stale capacity).',
+    billing:  'never_started',
+    retried:  true,
+    hint: () => ['Please try again shortly.'],
+    severity: 'P3',
+  },
+
+  PROVISIONING_TIMEOUT: {
+    message: () => 'GPU provisioning timed out.',
+    billing:  'never_started',
+    retried:  false,
+    hint: () => [
+      'Please try again.',
+      'If this repeats, try a different --gpu type or --region.',
+    ],
+    severity: 'P2',
+  },
+
+  PROVISIONING_FAILED: {
+    message: (ctx) =>
+      ctx.failure_category === 'compat_failure'
+        ? 'GPU/CUDA driver incompatibility — the container requires a CUDA version this GPU does not support.'
+        : 'GPU was reserved but the container failed to start.',
+    billing:  'never_started',
+    retried:  true,
+    hint: (ctx) =>
+      ctx.failure_category === 'compat_failure'
+        ? ['Try a different base image or a different --gpu type.']
+        : ['Badgr retried once. Please try again, or try a different --gpu type.'],
+    severity: 'P2',
+  },
+
+  // ── Auth / billing ────────────────────────────────────────────────────────
+
+  AUTH_FAILED: {
+    message: () => 'Invalid or expired API key.',
+    billing:  'never_started',
+    retried:  false,
+    hint: () => ['Run `badgr login` to set a new key.'],
+    severity: 'P3',
+  },
+
+  BILLING_INSUFFICIENT: {
+    message: (ctx) => {
+      let msg = 'Insufficient balance.';
+      if (ctx.balance_usd != null) msg += ` Balance: $${Number(ctx.balance_usd).toFixed(2)}.`;
+      if (ctx.required_usd != null) msg += ` Required: $${Number(ctx.required_usd).toFixed(2)}.`;
+      return msg;
+    },
+    billing:  'never_started',
+    retried:  false,
+    hint: (ctx) => [`Add balance: ${ctx.topup_url || 'https://aibadgr.com/dashboard#billing'}`],
+    severity: 'P3',
+  },
+
+  // ── Input validation ──────────────────────────────────────────────────────
+
+  INVALID_GPU: {
+    message: (ctx) => `GPU type '${ctx.gpu || 'unknown'}' is not recognized.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => ['Run `badgr gpus` to see available GPU types.'],
+    severity: 'P4',
+  },
+
+  MAX_COST_TOO_LOW: {
+    message: (ctx) =>
+      `--max-cost $${Number(ctx.maxCost || 0).toFixed(2)} is too low to start a job.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => [
+      'GPU jobs accrue cost from the moment a machine is reserved.',
+      'Use --max-cost 1.00 or higher.',
+    ],
+    severity: 'P4',
+  },
+
+  INVALID_MODEL: {
+    message: (ctx) =>
+      ctx.server_message ||
+      `Model '${ctx.model || 'unknown'}' not found or inaccessible on HuggingFace.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => [
+      'Check the model ID at huggingface.co.',
+      'For private or gated models, set HF_TOKEN in your environment.',
+    ],
+    severity: 'P4',
+  },
+
+  INSUFFICIENT_VRAM: {
+    message: (ctx) =>
+      ctx.server_message ||
+      `GPU '${ctx.gpu || 'unknown'}' does not have enough VRAM for this model.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => ['Try --gpu L40S, --gpu A100, or --gpu H100 for larger models.'],
+    severity: 'P4',
+  },
+
+  // ── Job / execution ───────────────────────────────────────────────────────
+
+  JOB_FAILED: {
+    message: (ctx) => `Job exited with code ${ctx.exitCode ?? 'unknown'}.`,
+    billing:  'stopped',
+    retried:  false,
+    hint: (ctx) => [`Check logs: badgr logs ${ctx.deploymentId || '<id>'}`],
+    severity: 'P4',
+  },
+
+  JOB_INFRASTRUCTURE_FAILURE: {
+    message: () => 'Container failed to start (infrastructure error — not your code).',
+    billing:  'never_started',
+    retried:  false,
+    hint: (ctx) => [
+      'The backend retried automatically. All attempts failed.',
+      'Contact support with your receipt ID for a refund.',
+      `Receipt: ${ctx.receiptId || 'run `badgr receipts`'}`,
+    ],
+    severity: 'P2',
+  },
+
+  HEARTBEAT_LOST: {
+    message: () => 'Lost connection to the running job — cloud machine became unresponsive.',
+    billing:  'stopped',
+    retried:  false,
+    hint: (ctx) => [
+      'The job was stopped and billing ended.',
+      `Receipt: ${ctx.receiptId || 'run `badgr receipts`'} — contact support if you were charged unexpectedly.`,
+    ],
+    severity: 'P2',
+  },
+
+  // ── Serve / endpoint ──────────────────────────────────────────────────────
+
+  HEALTH_CHECK_FAILED: {
+    message: (ctx) =>
+      `Endpoint at '${ctx.healthPath || '/models'}' did not become healthy.`,
+    billing:  'stopped',
+    retried:  false,
+    hint: (ctx) => [
+      'The endpoint was terminated to stop billing.',
+      ctx.deploymentId ? `Logs: badgr logs ${ctx.deploymentId}` : null,
+      'Check your model config or container startup behaviour.',
+    ].filter(Boolean),
+    severity: 'P3',
+  },
+
+  HEALTH_CHECK_DEPLOY_FAILED: {
+    message: (ctx) =>
+      `Deployment failed during startup: ${ctx.failReason || 'unknown error'}.`,
+    billing:  'stopped',
+    retried:  false,
+    hint: (ctx) => [
+      ctx.deploymentId ? `Logs: badgr logs ${ctx.deploymentId}` : null,
+    ].filter(Boolean),
+    severity: 'P3',
+  },
+
+  // ── Teardown / receipt ────────────────────────────────────────────────────
+
+  TEARDOWN_FAILED: {
+    message: () => 'Could not stop the job — billing may still be running.',
+    billing:  'check_receipt',
+    retried:  true,  // terminateDeployment already retries 3×
+    hint: (ctx) => [
+      `Run: badgr down ${ctx.deploymentId || '<dep-id>'}`,
+      'Or visit your dashboard to stop billing manually.',
+      `Receipt: ${ctx.receiptId || 'run `badgr receipts`'}`,
+    ],
+    severity: 'P1',
+  },
+
+  RECEIPT_FAILED: {
+    message: () => 'Could not record a local receipt for this job.',
+    billing:  'check_receipt',
+    retried:  false,
+    hint: () => ['Check `badgr receipts` or your dashboard for billing details.'],
+    severity: 'P3',
+  },
+
+  // ── Network / connection ──────────────────────────────────────────────────
+
+  NETWORK_ERROR: {
+    message: (ctx) =>
+      `Could not reach the Badgr API (${ctx.url || ctx.baseUrl || 'unknown URL'}).`,
+    billing:  'never_started',
+    retried:  false,
+    hint: (ctx) => [
+      'Check your internet connection.',
+      'Run `badgr config` to verify the API URL.',
+      ctx.baseUrl ? `Test: curl ${ctx.baseUrl}/health` : null,
+    ].filter(Boolean),
+    severity: 'P4',
+  },
+
+  CONNECTION_REFUSED: {
+    message: (ctx) => `Connection refused at ${ctx.baseUrl || 'the API'}.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => ['Is the server running? Run `badgr config` to check the API URL.'],
+    severity: 'P4',
+  },
+
+  DNS_FAILED: {
+    message: (ctx) => `DNS lookup failed for ${ctx.baseUrl || 'the API'}.`,
+    billing:  'never_started',
+    retried:  false,
+    hint: () => [
+      'Check your internet connection.',
+      'Run `badgr config` to verify the API URL is correct.',
+    ],
+    severity: 'P4',
+  },
+};
+
+// Human-readable billing status labels.
+const _BILLING_LABEL = {
+  never_started: 'Billing: never started.',
+  stopped:       'Billing: stopped.',
+  check_receipt: 'Billing: check your receipt or dashboard.',
+  charged:       'Billing: you were charged.',
+};
+
+/**
+ * Render a structured error as a multiline CLI string ready for console.error().
+ *
+ * @param {string} code         - Key from CATALOG
+ * @param {object} ctx          - Context passed to message/hint templates
+ * @param {object} chalk        - chalk instance (or passthrough mock in tests)
+ * @param {object} [internal]   - Internal-only fields shown only with BADGR_DEBUG=1
+ * @returns {string}
+ */
+export function formatCliError(code, ctx = {}, chalk, internal = {}) {
+  const entry = CATALOG[code];
+  if (!entry) {
+    return chalk.red(`\n  ✗ ${code} — An unexpected error occurred.\n`) +
+           chalk.dim('  Run BADGR_DEBUG=1 … for a full trace.\n');
+  }
+
+  const msg    = typeof entry.message === 'function' ? entry.message(ctx) : entry.message;
+  const hints  = (typeof entry.hint === 'function' ? entry.hint(ctx) : entry.hint) ?? [];
+  const billing = _BILLING_LABEL[entry.billing] ?? '';
+  const debug   = process.env.BADGR_DEBUG === '1' || process.env.BADGR_DEBUG === 'true';
+
+  const lines = [chalk.red(`\n  ✗ ${code} — ${msg}`)];
+  if (entry.retried) lines.push(chalk.dim('  Badgr retried automatically.'));
+  if (billing)       lines.push(chalk.dim(`  ${billing}`));
+
+  if (hints.length) {
+    lines.push('');
+    for (const h of hints) lines.push(chalk.dim(`  → ${h}`));
+  }
+
+  if (debug && Object.keys(internal).length > 0) {
+    lines.push('');
+    lines.push(chalk.dim('  [debug]'));
+    for (const [k, v] of Object.entries(internal)) {
+      if (v != null) lines.push(chalk.dim(`    ${k}: ${String(v)}`));
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}