badgr-cli 1.0.41 → 1.0.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "badgr-cli",
-  "version": "1.0.41",
+  "version": "1.0.42",
   "description": "Badgr — run or serve GPU workloads from one command",
   "type": "module",
   "bin": {

package/src/catalog.js

@@ -442,6 +442,44 @@ export const TEMPLATES = [
 
 export const TEMPLATE_MAP = Object.fromEntries(TEMPLATES.map(t => [t.name, t]));
 
+// ---------------------------------------------------------------------------
+// Productized runner catalogs
+// ---------------------------------------------------------------------------
+
+/** Blessed vLLM model aliases. `badgr serve qwen-7b` expands to the full model ID. */
+export const BLESSED_VLLM_MODELS = {
+  'qwen-7b': {
+    model_id:    'Qwen/Qwen2.5-7B-Instruct',
+    gpu_type:    'RTX_4090',
+    image:       'vllm/vllm-openai:latest',
+    health_path: '/v1/models',
+    description: 'Qwen 2.5 7B Instruct — fast, multilingual',
+  },
+  'llama-8b': {
+    model_id:    'meta-llama/Llama-3.1-8B-Instruct',
+    gpu_type:    'RTX_4090',
+    image:       'vllm/vllm-openai:latest',
+    health_path: '/v1/models',
+    description: 'Llama 3.1 8B Instruct — Meta flagship 8B',
+  },
+  'qwen-coder-7b': {
+    model_id:    'Qwen/Qwen2.5-Coder-7B-Instruct',
+    gpu_type:    'RTX_4090',
+    image:       'vllm/vllm-openai:latest',
+    health_path: '/v1/models',
+    description: 'Qwen 2.5 Coder 7B — code generation specialist',
+  },
+};
+
+/** Blessed ComfyUI workflows accepted by `POST /v1/jobs` comfy.batch. */
+export const BLESSED_COMFY_WORKFLOWS = {
+  'sdxl-basic': {
+    description: 'SDXL text-to-image with default sampler settings',
+    gpu_type:    'RTX_4090',
+    output_type: 'images',
+  },
+};
+
 /**
  * Build the args array passed to serveCommand / runCommand.
  * Template defaults are applied first; CLI overrides win.

package/src/commands/comfyui.js

@@ -110,11 +110,143 @@ async function validateComfyNodes(endpointUrl, nodeList, chalk) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// badgr comfyui batch — productized batch via POST /v1/jobs comfy.batch
+// ---------------------------------------------------------------------------
+
+export function parseComfyBatchArgs(args) {
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === '--workflow')    { flags.workflow = args[++i]; i++; continue; }
+    if (a === '--prompts')     { flags.prompts = args[++i]; i++; continue; }
+    if (a === '--prompt')      { if (!flags.inlinePrompts) flags.inlinePrompts = []; flags.inlinePrompts.push(args[++i]); i++; continue; }
+    if (a === '--max-cost')    { flags.maxCost = parseFloat(args[++i]); i++; continue; }
+    if (a === '--max-runtime') { flags.maxRuntime = parseFloat(args[++i]); i++; continue; }
+    if (a === '--tier')        { flags.tier = args[++i]; i++; continue; }
+    if (a === '--gpu-type')    { flags.gpuType = args[++i]; i++; continue; }
+    i++;
+  }
+  return flags;
+}
+
+export async function comfyBatchCommand(config, args, chalk) {
+  const { readFileSync, existsSync } = await import('fs');
+  const { callApi } = await import('../api.js');
+  const { addReceipt, generateReceiptId } = await import('../store.js');
+  const flags = parseComfyBatchArgs(args);
+
+  if (!flags.workflow) {
+    console.error(chalk.red('\n  Usage: badgr comfyui batch --workflow sdxl-basic --prompts prompts.txt --max-cost 10\n'));
+    console.error(chalk.dim('  Runs a batch of prompts through a blessed ComfyUI workflow and returns image URLs.\n'));
+    console.error(chalk.dim('  Blessed workflows: sdxl-basic\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!flags.maxCost) {
+    console.error(chalk.red('\n  ✗ --max-cost is required.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  requireApiKey(config);
+
+  // Collect prompts from file or --prompt flags
+  let prompts = flags.inlinePrompts || [];
+  if (flags.prompts) {
+    if (!existsSync(flags.prompts)) {
+      console.error(chalk.red(`\n  ✗ Prompts file not found: ${flags.prompts}\n`));
+      process.exitCode = 1;
+      return;
+    }
+    const lines = readFileSync(flags.prompts, 'utf8')
+      .split('\n')
+      .map(l => l.trim())
+      .filter(Boolean);
+    prompts = prompts.concat(lines);
+  }
+
+  if (prompts.length === 0) {
+    console.error(chalk.red('\n  ✗ No prompts provided. Use --prompts file.txt or --prompt "text"\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (prompts.length > 20) {
+    console.error(chalk.red(`\n  ✗ Max 20 prompts per batch (got ${prompts.length})\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const input = { workflow_id: flags.workflow, prompts };
+  if (flags.gpuType) input.gpu_type = flags.gpuType;
+
+  const rcptId = generateReceiptId();
+  const maxRuntime = flags.maxRuntime ?? 60;
+
+  console.log(chalk.bold('\n⚡ Starting ComfyUI batch\n'));
+  console.log(`  ${chalk.bold('Workflow:')}   ${flags.workflow}`);
+  console.log(`  ${chalk.bold('Prompts:')}    ${prompts.length}`);
+  console.log(`  ${chalk.bold('Max cost:')}   $${flags.maxCost}`);
+  console.log(`  ${chalk.bold('Max runtime:')} ${maxRuntime} min\n`);
+
+  let job;
+  try {
+    job = await callApi(config, 'POST', '/v1/jobs', {
+      type: 'comfy.batch',
+      input,
+      policy: { max_cost: flags.maxCost, max_runtime_minutes: maxRuntime, tier: flags.tier },
+    });
+  } catch (err) {
+    console.error(chalk.red(`\n  ✗ Failed to submit job: ${err.message}\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  addReceipt({ id: rcptId, type: 'comfy.batch', job_id: job.job_id, started_at: Date.now() });
+  console.log(`  ${chalk.bold('Job ID:')}  ${job.job_id}`);
+  console.log(`  ${chalk.bold('Receipt:')} ${chalk.dim(rcptId)}`);
+  console.log(chalk.dim('\n  Polling for completion…\n'));
+
+  const startMs = Date.now();
+  const maxMs = maxRuntime * 60 * 1000;
+  while (Date.now() - startMs < maxMs) {
+    await new Promise(r => setTimeout(r, 15_000));
+    let detail;
+    try { detail = await callApi(config, 'GET', `/v1/jobs/${job.job_id}`); } catch { continue; }
+    process.stdout.write(`\r  Status: ${detail.status}  elapsed: ${Math.floor((Date.now() - startMs) / 1000)}s  `);
+    if (detail.status === 'completed') {
+      const out = detail.output || {};
+      console.log(chalk.green('\n\n  ✓ Batch complete\n'));
+      if (out.image_urls && out.image_urls.length > 0) {
+        console.log(`  ${chalk.bold('Images (${out.image_urls.length}):')}`);
+        out.image_urls.forEach((url, i) => console.log(`    ${i + 1}. ${url}`));
+      }
+      console.log(`\n  ${chalk.bold('Receipt:')} ${chalk.dim(rcptId)}\n`);
+      return;
+    }
+    if (detail.status === 'failed') {
+      console.error(chalk.red(`\n\n  ✗ Batch failed: ${detail.error_code || ''} — ${detail.error_message || ''}\n`));
+      process.exitCode = 1;
+      return;
+    }
+  }
+  console.error(chalk.yellow('\n\n  Batch still running — detached. Check status:\n'));
+  console.error(chalk.dim(`    badgr status\n`));
+}
+
 export async function comfyuiCommand(config, args, chalk) {
+  // Route subcommands
+  const sub = args[0];
+  if (sub === 'batch') return comfyBatchCommand(config, args.slice(1), chalk);
+
   const { workflow, flags } = parseComfyuiArgs(args);
 
   if (!workflow) {
     console.error(chalk.red('\n  Usage: badgr comfyui run workflow.json\n'));
+    console.error(chalk.dim('  Batch mode: badgr comfyui batch --workflow sdxl-basic --prompts prompts.txt --max-cost 10\n'));
     console.error(chalk.dim('  Launches ComfyUI, queues your workflow, and returns the URL.\n'));
     process.exitCode = 1;
     return;

package/src/commands/serve.js

@@ -3,7 +3,7 @@ import { callApi, listDeployments } from '../api.js';
 import { addDeployment, addReceipt, updateReceipt, generateReceiptId } from '../store.js';
 import { normalizeTier, callWithFallback, HIGH_RATE_THRESHOLD } from '../fallback.js';
 import { formatCliError } from '../errors.js';
-import { TEMPLATE_MAP, buildTemplateFlags, parseTemplateOverrides } from '../catalog.js';
+import { TEMPLATE_MAP, buildTemplateFlags, parseTemplateOverrides, BLESSED_VLLM_MODELS } from '../catalog.js';
 
 const LLAMA_CPP_IMAGE = 'michaelmanleyx/llama-cpp:server-cuda';
 
@@ -221,6 +221,10 @@ export async function serveCommand(config, args, chalk) {
   const customImage = flags.image || null;
   const isLlamaCpp = flags.runtime === 'llama.cpp';
 
+  // Expand blessed alias (qwen-7b, llama-8b, qwen-coder-7b) to full model ID + GPU.
+  const vllmAlias = model && !customImage && !isLlamaCpp ? BLESSED_VLLM_MODELS[model] : null;
+  const effectiveModel = vllmAlias ? vllmAlias.model_id : model;
+
   // Detect flags that ended up as positional args due to broken shell line continuation
   // (e.g. `\ ` with a trailing space instead of `\<newline>`).
   // After parseServeArgs, only the model name should be in positional. Any extra token
@@ -293,7 +297,9 @@ export async function serveCommand(config, args, chalk) {
 
   const envObj = parseEnvFlag(flags.env);
 
-  const gpu = flags.gpu ? flags.gpu.toUpperCase().replace('-', '_') : (customImage ? 'L40S' : 'AUTO');
+  const gpu = flags.gpu
+    ? flags.gpu.toUpperCase().replace('-', '_')
+    : (vllmAlias ? vllmAlias.gpu_type : (customImage ? 'L40S' : 'AUTO'));
   const gpuLabel = gpu === 'AUTO' ? 'auto' : gpu;
 
   const effectiveTier = normalizeTier(flags.tier);
@@ -319,13 +325,17 @@ export async function serveCommand(config, args, chalk) {
     if (flags.env?.length) console.log(`  ${chalk.bold('Env:')}    ${flags.env.join(', ')}`);
   } else {
     console.log(chalk.bold('\n⚡ Serving model\n'));
-    console.log(`  ${chalk.bold('Model:')}  ${model}`);
+    if (vllmAlias) {
+      console.log(`  ${chalk.bold('Alias:')}  ${model}  ${chalk.dim(`→ ${effectiveModel}`)}`);
+    } else {
+      console.log(`  ${chalk.bold('Model:')}  ${effectiveModel}`);
+    }
     console.log(`  ${chalk.bold('GPU:')}    ${gpuLabel}`);
     if (flags.task) console.log(`  ${chalk.bold('Task:')}   ${flags.task}`);
     if (flags.env?.length) console.log(`  ${chalk.bold('Env:')}    ${flags.env.join(', ')}`);
 
     if (gpu === 'AUTO') {
-      const prof = _inferServeProfile(model);
+      const prof = _inferServeProfile(effectiveModel);
       console.log();
       console.log(`  ${chalk.bold('Estimated workload:')}      ${prof.label}`);
       console.log(`  ${chalk.bold('Estimated minimum VRAM:')}  ${prof.vram}`);
@@ -348,7 +358,7 @@ export async function serveCommand(config, args, chalk) {
         ACTIVE.has(d.status) &&
         d.workload_type === 'endpoint' &&
         (
-          (model && d.model === model) ||
+          (effectiveModel && d.model === effectiveModel) ||
           (customImage && d.image === customImage) ||
           (isLlamaCpp && d.image === LLAMA_CPP_IMAGE &&
            d.env?.LLAMA_ARG_HF_REPO === flags.hfRepo && d.env?.LLAMA_ARG_HF_FILE === flags.hfFile)
@@ -381,7 +391,7 @@ export async function serveCommand(config, args, chalk) {
       ? { LLAMA_ARG_HF_REPO: flags.hfRepo, LLAMA_ARG_HF_FILE: flags.hfFile, ...envObj }
       : envObj;
     return {
-      ...(model ? { model } : {}),
+      ...(effectiveModel ? { model: effectiveModel } : {}),
       ...(isLlamaCpp ? { image: LLAMA_CPP_IMAGE } : customImage ? { image: customImage } : {}),
       ...(flags.task ? { task: flags.task } : {}),
       gpu: gpuOverride || gpu,
@@ -424,7 +434,7 @@ export async function serveCommand(config, args, chalk) {
     id:          dep.deployment_id,
     name:        dep.name,
     type:        'endpoint',
-    model:       dep.model || model,
+    model:       dep.model || effectiveModel,
     gpu:         dep.gpu_type,
     count:       dep.gpu_count,
     status:      dep.status,
@@ -556,7 +566,7 @@ export async function serveCommand(config, args, chalk) {
     console.log(`  ${chalk.bold('HF Repo:')}      ${flags.hfRepo}`);
     console.log(`  ${chalk.bold('HF File:')}      ${flags.hfFile}`);
   }
-  else if (dep.model || model) console.log(`  ${chalk.bold('Model:')}        ${dep.model || model}`);
+  else if (dep.model || effectiveModel) console.log(`  ${chalk.bold('Model:')}        ${dep.model || effectiveModel}`);
   if (customImage)        console.log(`  ${chalk.bold('Image:')}        ${customImage}`);
   console.log(`  ${chalk.bold('GPU:')}          ${dep.gpu_type} × ${dep.gpu_count}`);
   if (serveRate > 0) console.log(`  ${chalk.bold('Rate:')}         $${serveRate.toFixed(2)}/hr`);
@@ -574,7 +584,7 @@ export async function serveCommand(config, args, chalk) {
 
   if (endpointReady && !customImage) {
     const keySnip = config.apiKey?.slice(0, 4) || 'sk-...';
-    const sdkModel = isLlamaCpp ? 'default' : (dep.model || model);
+    const sdkModel = isLlamaCpp ? 'default' : (dep.model || effectiveModel);
     console.log(`  ${chalk.bold('Use with OpenAI SDK:')}`);
     console.log(chalk.dim(`    from openai import OpenAI`));
     console.log(chalk.dim(`    client = OpenAI(base_url="${endpointUrl}", api_key="${keySnip}...")`));

package/src/commands/train.js

@@ -87,11 +87,140 @@ export function findLocalDatasetPaths(configContent) {
   return paths;
 }
 
+// ---------------------------------------------------------------------------
+// badgr train lora — productized LoRA training via POST /v1/jobs
+// ---------------------------------------------------------------------------
+
+export function parseTrainLoraArgs(args) {
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === '--base-model')   { flags.baseModel = args[++i]; i++; continue; }
+    if (a === '--dataset')      { flags.dataset = args[++i]; i++; continue; }
+    if (a === '--file-id')      { flags.fileId = args[++i]; i++; continue; }
+    if (a === '--preset')       { flags.preset = args[++i]; i++; continue; }
+    if (a === '--max-cost')     { flags.maxCost = parseFloat(args[++i]); i++; continue; }
+    if (a === '--max-runtime')  { flags.maxRuntime = parseFloat(args[++i]); i++; continue; }
+    if (a === '--tier')         { flags.tier = args[++i]; i++; continue; }
+    if (a === '--gpu-type')     { flags.gpuType = args[++i]; i++; continue; }
+    i++;
+  }
+  return flags;
+}
+
+export async function trainLoraCommand(config, args, chalk) {
+  const { callApi } = await import('../api.js');
+  const { addReceipt, generateReceiptId } = await import('../store.js');
+  const flags = parseTrainLoraArgs(args);
+
+  if (!flags.baseModel) {
+    console.error(chalk.red('\n  Usage: badgr train lora --base-model <model> --dataset <file-or-url> --preset small --max-cost 20\n'));
+    console.error(chalk.dim('  Dataset sources:'));
+    console.error(chalk.dim('    --dataset ./train.jsonl        local file (uploaded first)'));
+    console.error(chalk.dim('    --dataset https://...          direct URL'));
+    console.error(chalk.dim('    --file-id up_abc123            Badgr upload ID\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!flags.maxCost) {
+    console.error(chalk.red('\n  ✗ --max-cost is required to cap GPU spend.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  requireApiKey(config);
+
+  // Build dataset input field
+  const input = { base_model: flags.baseModel, config_preset: flags.preset || 'small' };
+  if (flags.fileId) {
+    input.dataset_file_id = flags.fileId;
+  } else if (flags.dataset && (flags.dataset.startsWith('http://') || flags.dataset.startsWith('https://') || flags.dataset.startsWith('s3://'))) {
+    input.dataset_url = flags.dataset;
+  } else if (flags.dataset) {
+    // Local file — upload first
+    const { createReadStream, statSync } = await import('fs');
+    if (!existsSync(flags.dataset)) {
+      console.error(chalk.red(`\n  ✗ Dataset file not found: ${flags.dataset}\n`));
+      process.exitCode = 1;
+      return;
+    }
+    console.log(chalk.dim(`\n  Uploading dataset ${flags.dataset}…`));
+    const FormData = (await import('formdata-node')).FormData;
+    const { fileFromPath } = await import('formdata-node/file-from-path');
+    const form = new FormData();
+    form.set('file', await fileFromPath(flags.dataset));
+    const uploadResp = await callApi(config, 'POST', '/v1/uploads', null, form);
+    input.dataset_file_id = uploadResp.upload_id;
+    console.log(chalk.dim(`  Uploaded: ${uploadResp.upload_id}`));
+  }
+
+  if (flags.gpuType) input.gpu_type = flags.gpuType;
+
+  const rcptId = generateReceiptId();
+  const maxRuntime = flags.maxRuntime ?? 240;
+
+  console.log(chalk.bold('\n⚡ Starting LoRA training\n'));
+  console.log(`  ${chalk.bold('Base model:')} ${flags.baseModel}`);
+  console.log(`  ${chalk.bold('Preset:')}     ${input.config_preset}`);
+  console.log(`  ${chalk.bold('Max cost:')}   $${flags.maxCost}`);
+  console.log(`  ${chalk.bold('Max runtime:')} ${maxRuntime} min\n`);
+
+  let job;
+  try {
+    job = await callApi(config, 'POST', '/v1/jobs', {
+      type: 'train.lora',
+      input,
+      policy: { max_cost: flags.maxCost, max_runtime_minutes: maxRuntime, tier: flags.tier },
+    });
+  } catch (err) {
+    console.error(chalk.red(`\n  ✗ Failed to submit job: ${err.message}\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  addReceipt({ id: rcptId, type: 'train.lora', job_id: job.job_id, started_at: Date.now() });
+  console.log(`  ${chalk.bold('Job ID:')}  ${job.job_id}`);
+  console.log(`  ${chalk.bold('Receipt:')} ${chalk.dim(rcptId)}`);
+  console.log(chalk.dim('\n  Polling for completion — Ctrl+C to detach (GPU keeps running)\n'));
+
+  // Poll until complete
+  const startMs = Date.now();
+  const maxMs = maxRuntime * 60 * 1000;
+  while (Date.now() - startMs < maxMs) {
+    await new Promise(r => setTimeout(r, 15_000));
+    let detail;
+    try { detail = await callApi(config, 'GET', `/v1/jobs/${job.job_id}`); } catch { continue; }
+    process.stdout.write(`\r  Status: ${detail.status}  elapsed: ${Math.floor((Date.now() - startMs) / 1000)}s  `);
+    if (detail.status === 'completed') {
+      const out = detail.output || {};
+      console.log(chalk.green('\n\n  ✓ Training complete\n'));
+      if (out.adapter_url) console.log(`  ${chalk.bold('Adapter:')} ${out.adapter_url}`);
+      if (out.checkpoint_url) console.log(`  ${chalk.bold('Checkpoint:')} ${out.checkpoint_url}`);
+      console.log(`  ${chalk.bold('Receipt:')} ${chalk.dim(rcptId)}\n`);
+      return;
+    }
+    if (detail.status === 'failed') {
+      console.error(chalk.red(`\n\n  ✗ Training failed: ${detail.error_code || ''} — ${detail.error_message || ''}\n`));
+      process.exitCode = 1;
+      return;
+    }
+  }
+  console.error(chalk.yellow('\n\n  Training still running — detached. Check status:\n'));
+  console.error(chalk.dim(`    badgr status\n`));
+}
+
 export async function trainCommand(config, args, chalk) {
+  // Route subcommands
+  const sub = args[0];
+  if (sub === 'lora') return trainLoraCommand(config, args.slice(1), chalk);
+
   const { configFile, flags } = parseTrainArgs(args);
 
   if (!configFile) {
     console.error(chalk.red('\n  Usage: badgr train config.yaml\n'));
+    console.error(chalk.dim('  Productized LoRA: badgr train lora --base-model MODEL --dataset FILE --max-cost N\n'));
     console.error(chalk.dim('  Runs LoRA / fine-tuning on GPU and streams logs.\n'));
     process.exitCode = 1;
     return;

package/tests/productized-runners.test.js

@@ -0,0 +1,230 @@
+/**
+ * Productized runner tests
+ *
+ * Covers:
+ *   - Blessed vLLM aliases expand to full model ID + correct GPU
+ *   - serveCommand sends full model ID to API when alias is given
+ *   - BLESSED_VLLM_MODELS has required fields
+ *   - BLESSED_COMFY_WORKFLOWS has required fields
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { parseServeArgs, serveCommand } from '../src/commands/serve.js';
+import { BLESSED_VLLM_MODELS, BLESSED_COMFY_WORKFLOWS } from '../src/catalog.js';
+
+// ── Module mocks ──────────────────────────────────────────────────────────────
+
+vi.mock('../src/api.js', () => ({
+  callApi:             vi.fn(),
+  terminateDeployment: vi.fn().mockResolvedValue({}),
+  listDeployments:     vi.fn().mockResolvedValue({ deployments: [], count: 0 }),
+}));
+
+vi.mock('../src/store.js', () => ({
+  addDeployment:        vi.fn(),
+  addReceipt:           vi.fn(),
+  updateReceipt:        vi.fn(),
+  generateReceiptId:    vi.fn(() => 'rcpt-prod-001'),
+  generateDeploymentId: vi.fn(() => 'dep-prod-001'),
+  listDeployments:      vi.fn(() => []),
+  listReceipts:         vi.fn(() => []),
+  findDeployment:       vi.fn(() => null),
+  updateDeployment:     vi.fn(),
+  removeDeployment:     vi.fn(),
+}));
+
+vi.mock('../src/fallback.js', () => ({
+  normalizeTier:         vi.fn(t => t || null),
+  callWithFallback:      vi.fn(),
+  HIGH_RATE_THRESHOLD:   2.0,
+}));
+
+vi.mock('../src/config.js', () => ({
+  requireApiKey: vi.fn(),
+}));
+
+vi.mock('../src/errors.js', () => ({
+  formatCliError: vi.fn((code, ctx) => `Error: ${code}`),
+}));
+
+import * as fallback from '../src/fallback.js';
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const config = { apiKey: 'sk-test', baseUrl: 'https://api.test/v1' };
+
+const chalk = {
+  bold:   s => s,
+  dim:    s => s,
+  red:    s => s,
+  yellow: s => s,
+  green:  s => s,
+  cyan:   s => s,
+};
+
+function makeServeDep(overrides = {}) {
+  return {
+    deployment_id: 'dep-prod-001',
+    status:        'running',
+    gpu_type:      'RTX_4090',
+    gpu_count:     1,
+    cost_per_hour: 1.20,
+    provider:      'runpod',
+    receipt_id:    'rcpt-prod-001',
+    tier:          '1',
+    endpoint_url:  'https://dep-prod-001.aibadgr.com/v1',
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  process.exitCode = undefined;
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  vi.spyOn(process.stdout, 'write').mockImplementation(() => {});
+});
+
+// ── Catalog shape tests ───────────────────────────────────────────────────────
+
+describe('BLESSED_VLLM_MODELS catalog', () => {
+  it('has qwen-7b, llama-8b, qwen-coder-7b', () => {
+    expect(Object.keys(BLESSED_VLLM_MODELS)).toEqual(
+      expect.arrayContaining(['qwen-7b', 'llama-8b', 'qwen-coder-7b'])
+    );
+  });
+
+  it('each entry has model_id, gpu_type, image, health_path', () => {
+    for (const [alias, spec] of Object.entries(BLESSED_VLLM_MODELS)) {
+      expect(spec.model_id, `${alias}.model_id`).toBeTruthy();
+      expect(spec.gpu_type, `${alias}.gpu_type`).toBeTruthy();
+      expect(spec.image,    `${alias}.image`).toBeTruthy();
+      expect(spec.health_path, `${alias}.health_path`).toBeTruthy();
+    }
+  });
+
+  it('qwen-7b resolves to Qwen2.5-7B-Instruct on RTX_4090', () => {
+    const spec = BLESSED_VLLM_MODELS['qwen-7b'];
+    expect(spec.model_id).toBe('Qwen/Qwen2.5-7B-Instruct');
+    expect(spec.gpu_type).toBe('RTX_4090');
+  });
+
+  it('llama-8b resolves to Llama-3.1-8B-Instruct on RTX_4090', () => {
+    const spec = BLESSED_VLLM_MODELS['llama-8b'];
+    expect(spec.model_id).toBe('meta-llama/Llama-3.1-8B-Instruct');
+    expect(spec.gpu_type).toBe('RTX_4090');
+  });
+
+  it('qwen-coder-7b resolves to Qwen2.5-Coder-7B-Instruct on RTX_4090', () => {
+    const spec = BLESSED_VLLM_MODELS['qwen-coder-7b'];
+    expect(spec.model_id).toBe('Qwen/Qwen2.5-Coder-7B-Instruct');
+    expect(spec.gpu_type).toBe('RTX_4090');
+  });
+});
+
+describe('BLESSED_COMFY_WORKFLOWS catalog', () => {
+  it('has sdxl-basic', () => {
+    expect(BLESSED_COMFY_WORKFLOWS['sdxl-basic']).toBeDefined();
+  });
+
+  it('sdxl-basic has gpu_type and output_type', () => {
+    const wf = BLESSED_COMFY_WORKFLOWS['sdxl-basic'];
+    expect(wf.gpu_type).toBe('RTX_4090');
+    expect(wf.output_type).toBe('images');
+  });
+});
+
+// ── parseServeArgs alias recognition ─────────────────────────────────────────
+
+describe('parseServeArgs — alias handling', () => {
+  it('passes alias through as positional model', () => {
+    const { model } = parseServeArgs(['qwen-7b', '--max-cost', '10']);
+    expect(model).toBe('qwen-7b');
+  });
+
+  it('alias is distinct from full model ID in parseServeArgs', () => {
+    const { model: alias } = parseServeArgs(['qwen-7b']);
+    const { model: full }  = parseServeArgs(['Qwen/Qwen2.5-7B-Instruct']);
+    expect(alias).toBe('qwen-7b');
+    expect(full).toBe('Qwen/Qwen2.5-7B-Instruct');
+  });
+});
+
+// ── serveCommand alias expansion ──────────────────────────────────────────────
+
+describe('serveCommand — alias expansion', () => {
+  it('sends full model_id to API when alias qwen-7b is used', async () => {
+    fallback.callWithFallback.mockResolvedValue(makeServeDep({
+      model: 'Qwen/Qwen2.5-7B-Instruct',
+    }));
+    // Mock fetch for health check (immediate pass)
+    global.fetch = vi.fn().mockResolvedValue({ ok: true });
+
+    await serveCommand(config, ['qwen-7b', '--max-cost', '10', '--no-wait'], chalk);
+
+    expect(fallback.callWithFallback).toHaveBeenCalled();
+    const bodyFn = fallback.callWithFallback.mock.calls[0][2];
+    const body = bodyFn(null);
+    expect(body.model).toBe('Qwen/Qwen2.5-7B-Instruct');
+    expect(body.gpu).toBe('RTX_4090');
+  });
+
+  it('sends full model_id to API when alias llama-8b is used', async () => {
+    fallback.callWithFallback.mockResolvedValue(makeServeDep({
+      model: 'meta-llama/Llama-3.1-8B-Instruct',
+    }));
+    global.fetch = vi.fn().mockResolvedValue({ ok: true });
+
+    await serveCommand(config, ['llama-8b', '--max-cost', '10', '--no-wait'], chalk);
+
+    const bodyFn = fallback.callWithFallback.mock.calls[0][2];
+    const body = bodyFn(null);
+    expect(body.model).toBe('meta-llama/Llama-3.1-8B-Instruct');
+    expect(body.gpu).toBe('RTX_4090');
+  });
+
+  it('sends full model_id to API when alias qwen-coder-7b is used', async () => {
+    fallback.callWithFallback.mockResolvedValue(makeServeDep({
+      model: 'Qwen/Qwen2.5-Coder-7B-Instruct',
+    }));
+    global.fetch = vi.fn().mockResolvedValue({ ok: true });
+
+    await serveCommand(config, ['qwen-coder-7b', '--max-cost', '5', '--no-wait'], chalk);
+
+    const bodyFn = fallback.callWithFallback.mock.calls[0][2];
+    const body = bodyFn(null);
+    expect(body.model).toBe('Qwen/Qwen2.5-Coder-7B-Instruct');
+    expect(body.gpu).toBe('RTX_4090');
+  });
+
+  it('passes full model ID unchanged (no alias lookup)', async () => {
+    fallback.callWithFallback.mockResolvedValue(makeServeDep({
+      model: 'meta-llama/Llama-3.1-70B-Instruct',
+      gpu_type: 'H100',
+    }));
+    global.fetch = vi.fn().mockResolvedValue({ ok: true });
+
+    await serveCommand(config, ['meta-llama/Llama-3.1-70B-Instruct', '--max-cost', '20', '--gpu', 'H100', '--no-wait'], chalk);
+
+    const bodyFn = fallback.callWithFallback.mock.calls[0][2];
+    const body = bodyFn(null);
+    expect(body.model).toBe('meta-llama/Llama-3.1-70B-Instruct');
+    expect(body.gpu).toBe('H100');
+  });
+
+  it('rejects --max-cost missing for alias (same as non-alias)', async () => {
+    await serveCommand(config, ['qwen-7b'], chalk);
+    expect(process.exitCode).toBe(1);
+    expect(fallback.callWithFallback).not.toHaveBeenCalled();
+  });
+
+  it('alias auto-sets RTX_4090 but --gpu flag overrides it', async () => {
+    fallback.callWithFallback.mockResolvedValue(makeServeDep({ gpu_type: 'L40S' }));
+    global.fetch = vi.fn().mockResolvedValue({ ok: true });
+
+    await serveCommand(config, ['qwen-7b', '--max-cost', '10', '--gpu', 'L40S', '--no-wait'], chalk);
+
+    const bodyFn = fallback.callWithFallback.mock.calls[0][2];
+    const body = bodyFn(null);
+    expect(body.gpu).toBe('L40S');
+  });
+});