badgr-cli 1.0.47 → 1.1.0

package/src/slurm.js

@@ -0,0 +1,193 @@
+/**
+ * Slurm batch-script translation — `badgr sbatch job.slurm`.
+ *
+ * Not full Slurm compatibility. Parses the common 20% of #SBATCH directives
+ * (per the workload-primitives spec: CPU, memory, GPU count, time limit,
+ * job arrays, environment variables, the command line, output logs) and
+ * translates them into the same normalized job shape `badgr run`/`badgr
+ * batch` already submit to /run — no new execution backend, just another
+ * entry point into it.
+ *
+ * Unrecognized #SBATCH directives are collected and surfaced as warnings
+ * rather than silently dropped or hard failures — obscure scheduler
+ * features are out of scope until users demand them, but users should know
+ * what got ignored.
+ */
+import { readFileSync } from 'fs';
+import { basename } from 'path';
+import { parseGbSize } from './spec.js';
+
+export class SlurmParseError extends Error {}
+
+// Directives we understand and translate. Everything else in an #SBATCH
+// line is reported as an "ignored directive" warning, not an error — Slurm
+// scripts commonly carry cluster-specific flags (--partition, --qos,
+// --account, --mail-user, ...) that have no meaning for a single-provider
+// GPU marketplace and are safe to no-op.
+const KNOWN_DIRECTIVE_RE = new RegExp(
+  '^(job-name|cpus-per-task|mem|mem-per-cpu|gres|gpus|gpus-per-task|array|time|output|error|export)$',
+);
+
+// Slurm's own convention: a bare --mem value with no suffix means MB.
+function parseMemToGb(raw) {
+  return parseGbSize(raw, { bareUnit: 'M' });
+}
+
+function parseTimeToMinutes(raw) {
+  // Slurm --time formats: "minutes", "minutes:seconds", "hours:minutes:seconds",
+  // "days-hours", "days-hours:minutes", "days-hours:minutes:seconds"
+  const t = raw.trim();
+  let days = 0;
+  let rest = t;
+  if (t.includes('-')) {
+    [days, rest] = t.split('-');
+    days = parseInt(days, 10);
+  }
+  const parts = rest.split(':').map(Number);
+  let h = 0, m = 0, s = 0;
+  if (parts.length === 1) [m] = parts;
+  else if (parts.length === 2) [m, s] = parts;
+  else if (parts.length === 3) [h, m, s] = parts;
+  if (parts.some(Number.isNaN)) return null;
+  return days * 24 * 60 + h * 60 + m + Math.ceil(s / 60);
+}
+
+function parseArrayRange(raw) {
+  // Supports "1-100", "1-100:5" (step), "1,3,5-8" (list + ranges), "1-10%4" (throttle, ignored)
+  const throttleIdx = raw.indexOf('%');
+  const spec = throttleIdx === -1 ? raw : raw.slice(0, throttleIdx);
+  const indices = new Set();
+  for (const part of spec.split(',')) {
+    const stepIdx = part.indexOf(':');
+    const rangePart = stepIdx === -1 ? part : part.slice(0, stepIdx);
+    const step = stepIdx === -1 ? 1 : parseInt(part.slice(stepIdx + 1), 10) || 1;
+    if (rangePart.includes('-')) {
+      const [start, end] = rangePart.split('-').map(Number);
+      if (Number.isNaN(start) || Number.isNaN(end)) continue;
+      for (let i = start; i <= end; i += step) indices.add(i);
+    } else {
+      const n = Number(rangePart);
+      if (!Number.isNaN(n)) indices.add(n);
+    }
+  }
+  return [...indices].sort((a, b) => a - b);
+}
+
+function parseGres(raw) {
+  // "gpu:2", "gpu:a100:2", "gpu:1"
+  const parts = raw.split(':');
+  if (parts[0] !== 'gpu') return { gpuCount: 0, gpuType: null };
+  if (parts.length === 2) return { gpuCount: parseInt(parts[1], 10) || 1, gpuType: null };
+  if (parts.length >= 3) return { gpuCount: parseInt(parts[2], 10) || 1, gpuType: parts[1] };
+  return { gpuCount: 1, gpuType: null };
+}
+
+/**
+ * Parse a Slurm batch script into a normalized job spec.
+ * Throws SlurmParseError if there is no runnable command line.
+ */
+export function parseSlurmScript(text, { filename = 'job.slurm' } = {}) {
+  const lines = text.split('\n');
+  const directives = {};
+  const ignoredDirectives = [];
+  const exportEnv = {};
+  const scriptLines = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const sbatchMatch = /^#SBATCH\s+(.*)$/.exec(trimmed);
+    if (sbatchMatch) {
+      const body = sbatchMatch[1].trim();
+      const eqMatch = /^--?([\w-]+)(?:[=\s]+(.*))?$/.exec(body);
+      if (!eqMatch) continue;
+      const key = eqMatch[1];
+      const value = (eqMatch[2] ?? '').trim();
+      if (!KNOWN_DIRECTIVE_RE.test(key)) {
+        ignoredDirectives.push(body);
+        continue;
+      }
+      directives[key] = value;
+      continue;
+    }
+    if (trimmed.startsWith('#!') || trimmed.startsWith('#')) continue; // shebang/comment
+    if (trimmed === '') continue;
+    // "export KEY=VALUE" lines in the script body, in addition to --export=
+    const exportMatch = /^export\s+([\w]+)=(.*)$/.exec(trimmed);
+    if (exportMatch) {
+      exportEnv[exportMatch[1]] = exportMatch[2].replace(/^["']|["']$/g, '');
+      continue;
+    }
+    scriptLines.push(line);
+  }
+
+  if (scriptLines.length === 0) {
+    throw new SlurmParseError(`No command found in ${filename} — a Slurm script needs at least one non-#SBATCH, non-comment line to run.`);
+  }
+
+  if (directives.export) {
+    for (const kv of directives.export.split(',')) {
+      const idx = kv.indexOf('=');
+      if (idx > 0) exportEnv[kv.slice(0, idx).trim()] = kv.slice(idx + 1).trim();
+    }
+  }
+
+  const cpus = directives['cpus-per-task'] ? parseInt(directives['cpus-per-task'], 10) : null;
+
+  let memGb = null;
+  if (directives.mem) {
+    memGb = parseMemToGb(directives.mem);
+  } else if (directives['mem-per-cpu'] && cpus) {
+    const perCpu = parseMemToGb(directives['mem-per-cpu']);
+    memGb = perCpu != null ? perCpu * cpus : null;
+  }
+
+  let gpuCount = 0;
+  let gpuType = null;
+  if (directives.gres) {
+    ({ gpuCount, gpuType } = parseGres(directives.gres));
+  } else if (directives.gpus || directives['gpus-per-task']) {
+    const raw = directives.gpus ?? directives['gpus-per-task'];
+    gpuCount = parseInt(raw, 10) || (raw.includes(':') ? parseInt(raw.split(':')[1], 10) : 1) || 1;
+  }
+
+  const timeMinutes = directives.time ? parseTimeToMinutes(directives.time) : null;
+  const arrayIndices = directives.array ? parseArrayRange(directives.array) : [];
+
+  return {
+    name: directives['job-name'] || basename(filename).replace(/\.slurm$|\.sbatch$/i, ''),
+    command: scriptLines.join('\n'),
+    cpus,
+    memGb,
+    gpuCount,
+    gpuType,
+    timeMinutes,
+    arrayIndices, // empty = not a job array
+    env: exportEnv,
+    outputPattern: directives.output || null,
+    errorPattern: directives.error || null,
+    ignoredDirectives,
+  };
+}
+
+export function loadSlurmScript(path) {
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (err) {
+    throw new SlurmParseError(`Could not read ${path}: ${err.message}`);
+  }
+  return parseSlurmScript(text, { filename: basename(path) });
+}
+
+/**
+ * Substitute Slurm's %a (array task id) / %A (array job id) / %j (job id)
+ * placeholders in --output/--error patterns, and expose SLURM_ARRAY_TASK_ID
+ * the way a real Slurm runtime would for scripts that read it themselves.
+ */
+export function envForArrayTask(baseEnv, taskId, arrayJobId) {
+  return {
+    ...baseEnv,
+    ...(taskId != null ? { SLURM_ARRAY_TASK_ID: String(taskId) } : {}),
+    ...(arrayJobId != null ? { SLURM_ARRAY_JOB_ID: String(arrayJobId) } : {}),
+  };
+}

package/src/spec.js

@@ -4,8 +4,28 @@
  */
 
 export const WORKLOAD_TYPES = ['endpoint', 'job'];
+export const CPU_SIZES = ['small', 'medium', 'large'];
 export const REGIONS = ['US', 'EU', 'AU'];
 
+// Phase 1 VM class catalogue for `badgr launch <workload>` — deterministic,
+// not a dynamic autosizing model. vcpu/ramGb are the stable Badgr-facing
+// numbers shown in the pre-launch plan; the exact provider SKU behind each
+// class (BADGR_CPU_FLAVOR_<SIZE>) can change without these changing.
+export const VM_CLASSES = {
+  small:   { vcpu: 2, ramGb: 4, label: 'general coding jobs' },
+  medium:  { vcpu: 4, ramGb: 8, label: 'larger repositories and test suites' },
+  browser: { vcpu: 4, ramGb: 8, label: 'Chromium and Playwright workloads' },
+};
+
+export const LAUNCH_VM_SIZES = Object.keys(VM_CLASSES);
+
+// Deterministic workload → VM class table (Phase 1 rule, not autosizing):
+// playwright gets the browser class; every other agent/explicit launch
+// gets small. `--size` always overrides this default.
+export function vmClassForWorkload(workloadName) {
+  return workloadName === 'playwright' ? 'browser' : 'small';
+}
+
 // Match canonical GPU IDs used in overflow_providers.py GPU_ALIASES
 export const GPU_TYPE_MAP = {
   'rtx-4090': 'RTX_4090',  'rtx4090': 'RTX_4090',  '4090': 'RTX_4090',
@@ -18,6 +38,18 @@ export const GPU_TYPE_MAP = {
   'l40s': 'L40S',
 };
 
+export function normalizeCompute(input) {
+  const value = String(input || 'gpu').toLowerCase();
+  return value === 'cpu' ? 'cpu' : 'gpu';
+}
+
+export function selectCpuSize({ agent = null, task = '' } = {}) {
+  const text = `${agent || ''} ${task || ''}`.toLowerCase();
+  if (/monorepo|large|full repo|e2e|playwright/.test(text)) return 'large';
+  if (/test|refactor|build|typecheck/.test(text)) return 'medium';
+  return 'small';
+}
+
 export function normalizeGpuType(input) {
   if (!input) return 'RTX_4090';
   const lower = input.toLowerCase().replace(/[_\s]/g, '-');
@@ -52,11 +84,15 @@ export function parseSpec(args) {
     ?? (flags.job      ? 'job'      : null)
     ?? (hasImage ? 'job' : 'endpoint');
 
+  const compute = normalizeCompute(flags.compute);
+
   return {
     type,
+    compute,
     model:    flags.model ?? (type === 'endpoint' ? 'meta-llama/Llama-3.1-8B-Instruct' : null),
     image:    flags.image ?? (type === 'job' ? 'vllm/vllm-openai:latest' : null),
-    gpu:      normalizeGpuType(flags.gpu),
+    gpu:      compute === 'cpu' ? 'CPU' : normalizeGpuType(flags.gpu),
+    cpuSize:  compute === 'cpu' ? selectCpuSize({ agent: flags.agent, task: flags.task }) : null,
     count:    Math.max(1, parseInt(flags.count ?? '1', 10)),
     region:   (flags.region ?? 'US').toUpperCase(),
     maxPrice: flags['max-price'] ? parseFloat(flags['max-price']) : null,
@@ -79,12 +115,33 @@ export function validateSpec(spec) {
   return errors;
 }
 
+/**
+ * Parse a size like "64GB", "64G", "65536MB", "24576" into a GB float.
+ * Shared by `badgr run --memory`/`--gpu-memory` and the Slurm `#SBATCH
+ * --mem` translator (src/slurm.js) — one parser, two callers, so "64GB"
+ * means the same 64 either way.
+ * @param {string|number} raw
+ * @param {{ bareUnit?: 'K'|'M'|'G'|'T' }} [opts] - unit assumed when no
+ *   suffix is given. CLI flags default to GB ("64" -> 64GB); Slurm's own
+ *   convention for a bare --mem value is MB, so its caller overrides this.
+ * @returns {number|null} GB, or null if unparseable.
+ */
+export function parseGbSize(raw, { bareUnit = 'G' } = {}) {
+  if (raw == null) return null;
+  const m = /^(\d+(?:\.\d+)?)\s*([KMGT]?)B?$/i.exec(String(raw).trim());
+  if (!m) return null;
+  const value = parseFloat(m[1]);
+  const unit = (m[2] || bareUnit).toUpperCase();
+  const multiplierRelativeToGb = { K: 1 / 1024 / 1024, M: 1 / 1024, G: 1, T: 1024 };
+  return value * multiplierRelativeToGb[unit];
+}
+
 export function specLines(spec) {
   return [
     `type:    ${spec.type}`,
     spec.model ? `model:   ${spec.model}` : null,
     spec.image ? `image:   ${spec.image}` : null,
-    `gpu:     ${spec.gpu} × ${spec.count}`,
+    spec.compute === 'cpu' ? `compute: cpu (${spec.cpuSize})` : `gpu:     ${spec.gpu} × ${spec.count}`,
     `region:  ${spec.region}`,
     spec.maxPrice != null ? `max:     $${spec.maxPrice.toFixed(2)}/GPU-hr` : null,
     spec.name ? `name:    ${spec.name}` : null,

package/src/store.js

@@ -75,6 +75,22 @@ export function listDeployments(storeFile = STORE_FILE) {
   return loadStore(storeFile).deployments;
 }
 
+/**
+ * The "what did we actually provision" half of a receipt's compute record —
+ * shared by every command that writes a receipt after a /run response
+ * (badgr run, badgr sbatch, badgr batch run, badgr batch run --fan-out) so
+ * the shape can't drift between them.
+ */
+export function selectedComputeFromDeployment(dep) {
+  return {
+    gpu: dep.gpu_type ?? null,
+    gpuCount: dep.gpu_count ?? null,
+    vcpus: dep.selected_vcpus ?? null,
+    ramGb: dep.selected_ram_gb ?? null,
+    vramGb: dep.selected_vram_gb ?? null,
+  };
+}
+
 export function addReceipt(receipt, storeFile = STORE_FILE) {
   const store = loadStore(storeFile);
   store.receipts.unshift(receipt); // newest first

package/tests/agent-images.test.js

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+const root = resolve(import.meta.dirname, '../../..');
+
+describe('Phase 1 agent runtime images', () => {
+  it.each([
+    ['claude', 'images/badgr-agent-claude/Dockerfile', '@anthropic-ai/claude-code'],
+    ['codex', 'images/badgr-agent-codex/Dockerfile', '@openai/codex'],
+    ['opencode', 'images/badgr-agent-opencode/Dockerfile', 'opencode-ai'],
+  ])('%s image extends the Badgr job runner and installs the CLI', (_name, file, pkg) => {
+    const text = readFileSync(resolve(root, file), 'utf8');
+    expect(text).toContain('badgr-job-runner');
+    expect(text).toContain(pkg);
+  });
+});

package/tests/artifactDownload.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { artifactDownloadUrl } from '../src/artifactDownload.js';
+
+describe('artifactDownloadUrl', () => {
+  it('appends /v1/deployments/.../artifacts/download when baseUrl already ends in /v1', () => {
+    expect(artifactDownloadUrl('https://aibadgr.com/v1', 'dep-abc')).toBe(
+      'https://aibadgr.com/v1/deployments/dep-abc/artifacts/download',
+    );
+  });
+
+  it('appends /v1 when baseUrl has no /v1 suffix', () => {
+    expect(artifactDownloadUrl('https://aibadgr.com', 'dep-abc')).toBe(
+      'https://aibadgr.com/v1/deployments/dep-abc/artifacts/download',
+    );
+  });
+
+  it('normalizes a trailing slash on baseUrl', () => {
+    expect(artifactDownloadUrl('https://aibadgr.com/v1/', 'dep-abc')).toBe(
+      'https://aibadgr.com/v1/deployments/dep-abc/artifacts/download',
+    );
+  });
+
+  it('treats a missing/empty baseUrl as an empty string prefix', () => {
+    expect(artifactDownloadUrl('', 'dep-abc')).toBe('/v1/deployments/dep-abc/artifacts/download');
+    expect(artifactDownloadUrl(undefined, 'dep-abc')).toBe('/v1/deployments/dep-abc/artifacts/download');
+  });
+});
+
+let tarExtractBehavior = () => {};
+
+// Matches the real node-tar v7 export shape: named exports only, no
+// default — the mock previously provided both shapes ({ default: { x }, x
+// }), which silently masked a real bug where the source destructured
+// `{ default: tar }` and crashed with "Cannot read properties of undefined
+// (reading 'x')" on every real extraction (found via a live artifact
+// download, never caught by this test).
+vi.mock('tar', () => {
+  const x = vi.fn(async opts => tarExtractBehavior(opts));
+  return { x };
+});
+
+const { downloadAndExtractArtifact } = await import('../src/artifactDownload.js');
+
+describe('downloadAndExtractArtifact', () => {
+  const config = { apiKey: 'test-key', baseUrl: 'https://example.test/v1' };
+  let destDir;
+
+  beforeEach(() => {
+    tarExtractBehavior = ({ cwd }) => {
+      fs.writeFileSync(path.join(cwd, 'marker.txt'), 'ok');
+    };
+    destDir = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'badgr-artifact-dl-')), 'dest');
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete global.fetch;
+    fs.rmSync(path.dirname(destDir), { recursive: true, force: true });
+  });
+
+  it('creates destDir, downloads, and extracts', async () => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
+    await downloadAndExtractArtifact(config, 'dep-abc', destDir);
+
+    expect(fs.existsSync(destDir)).toBe(true);
+    expect(fs.existsSync(path.join(destDir, 'marker.txt'))).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      'https://example.test/v1/deployments/dep-abc/artifacts/download',
+      { headers: { Authorization: 'Bearer test-key' } },
+    );
+  });
+
+  it('throws an Error with httpStatus/statusText/bodyText set on a non-OK response', async () => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: false, status: 404, statusText: 'Not Found', text: async () => 'nope' });
+    await expect(downloadAndExtractArtifact(config, 'dep-missing', destDir)).rejects.toMatchObject({
+      httpStatus: 404,
+      statusText: 'Not Found',
+      bodyText: 'nope',
+    });
+  });
+
+  it('includes the response body text in the default error message', async () => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error', text: async () => 'boom' });
+    await expect(downloadAndExtractArtifact(config, 'dep-broken', destDir)).rejects.toThrow(/500 Internal Server Error — boom/);
+  });
+
+  it('propagates a network-level failure with no httpStatus set', async () => {
+    global.fetch = vi.fn().mockRejectedValue(new Error('getaddrinfo ENOTFOUND'));
+    let caught;
+    try {
+      await downloadAndExtractArtifact(config, 'dep-offline', destDir);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeDefined();
+    expect(caught.message).toBe('getaddrinfo ENOTFOUND');
+    expect(caught.httpStatus).toBeUndefined();
+  });
+
+  it('cleans up the temp tarball file after extraction', async () => {
+    let capturedTmpFile;
+    tarExtractBehavior = ({ file }) => { capturedTmpFile = file; };
+    global.fetch = vi.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
+
+    await downloadAndExtractArtifact(config, 'dep-cleanup', destDir);
+
+    expect(capturedTmpFile).toBeTruthy();
+    expect(fs.existsSync(capturedTmpFile)).toBe(false);
+  });
+});

package/tests/artifacts.test.js

@@ -0,0 +1,168 @@
+import { describe, it, expect, vi, beforeEach, afterEach, afterAll } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const _fakeConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), 'badgr-artifacts-configdir-'));
+
+vi.mock('../src/config.js', async (importOriginal) => {
+  const actual = await importOriginal();
+  return { ...actual, CONFIG_DIR: _fakeConfigDir };
+});
+
+const { parseArtifactsArgs, listFilesRecursive, artifactsCommand } = await import('../src/commands/artifacts.js');
+
+afterAll(() => {
+  fs.rmSync(_fakeConfigDir, { recursive: true, force: true });
+});
+
+describe('parseArtifactsArgs', () => {
+  it('parses the deployment id and --output', () => {
+    expect(parseArtifactsArgs(['dep-123'])).toEqual({ deploymentId: 'dep-123', flags: {} });
+    expect(parseArtifactsArgs(['dep-123', '--output', './out'])).toEqual({
+      deploymentId: 'dep-123',
+      flags: { output: './out' },
+    });
+  });
+
+  it('returns an undefined deploymentId when no positional arg is given', () => {
+    expect(parseArtifactsArgs(['--output', './out']).deploymentId).toBeUndefined();
+  });
+
+  it('parses the deployment id without any flags', () => {
+    expect(parseArtifactsArgs(['dep-xyz'])).toEqual({ deploymentId: 'dep-xyz', flags: {} });
+  });
+});
+
+describe('listFilesRecursive', () => {
+  let dir;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'badgr-artifacts-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('lists nested files with relative paths', () => {
+    fs.mkdirSync(path.join(dir, 'playwright-report'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'playwright-report', 'index.html'), '<html></html>');
+    fs.writeFileSync(path.join(dir, 'summary.json'), '{}');
+
+    const files = listFilesRecursive(dir);
+    expect(files).toEqual(['playwright-report/index.html', 'summary.json']);
+  });
+
+  it('returns an empty array for an empty directory', () => {
+    expect(listFilesRecursive(dir)).toEqual([]);
+  });
+
+  it('lists deeply nested files and sorts the result', () => {
+    fs.mkdirSync(path.join(dir, 'a', 'b', 'c'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'a', 'b', 'c', 'deep.txt'), 'x');
+    fs.writeFileSync(path.join(dir, 'zzz.txt'), 'x');
+    fs.writeFileSync(path.join(dir, 'aaa.txt'), 'x');
+
+    expect(listFilesRecursive(dir)).toEqual(['a/b/c/deep.txt', 'aaa.txt', 'zzz.txt']);
+  });
+});
+
+let tarExtractBehavior = () => {};
+
+vi.mock('tar', () => {
+  const x = vi.fn(async opts => tarExtractBehavior(opts));
+  return { default: { x }, x };
+});
+
+function extractTestResults({ cwd }) {
+  fs.mkdirSync(path.join(cwd, 'test-results'), { recursive: true });
+  fs.writeFileSync(path.join(cwd, 'test-results', 'trace.zip'), 'fake-zip');
+}
+
+function extractNothing() {
+  // empty artifact — no files written
+}
+
+describe('artifactsCommand', () => {
+  const chalk = { red: s => s, dim: s => s, green: s => s };
+  const config = { apiKey: 'test-key', baseUrl: 'https://example.test/v1' };
+  let destDir;
+
+  beforeEach(() => {
+    process.exitCode = undefined;
+    tarExtractBehavior = extractTestResults;
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    destDir = fs.mkdtempSync(path.join(os.tmpdir(), 'badgr-artifacts-dest-'));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    process.exitCode = undefined;
+    delete global.fetch;
+    fs.rmSync(destDir, { recursive: true, force: true });
+  });
+
+  it('requires a deployment id', async () => {
+    await artifactsCommand(config, [], chalk);
+    expect(process.exitCode).toBe(1);
+    const logged = console.error.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(logged).toContain('Usage');
+  });
+
+  it('reports a clear error on 404 (no artifact uploaded)', async () => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: false, status: 404, statusText: 'Not Found', text: async () => '' });
+    await artifactsCommand(config, ['dep-missing'], chalk);
+    expect(process.exitCode).toBe(1);
+    const logged = console.error.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(logged).toContain('No artifact found for dep-missing');
+  });
+
+  it('reports a generic error on a 500', async () => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error', text: async () => 'boom' });
+    await artifactsCommand(config, ['dep-broken'], chalk);
+    expect(process.exitCode).toBe(1);
+    const logged = console.error.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(logged).toContain('500');
+    expect(logged).toContain('boom');
+  });
+
+  it('reports a clear error when the network request itself fails', async () => {
+    global.fetch = vi.fn().mockRejectedValue(new Error('getaddrinfo ENOTFOUND'));
+    await artifactsCommand(config, ['dep-offline'], chalk);
+    expect(process.exitCode).toBe(1);
+    const logged = console.error.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(logged).toContain('Could not reach Badgr');
+  });
+
+  it('downloads and extracts the artifact tarball, listing files', async () => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
+    await artifactsCommand(config, ['dep-abc', '--output', destDir], chalk);
+
+    expect(process.exitCode).toBeUndefined();
+    expect(fs.existsSync(path.join(destDir, 'test-results', 'trace.zip'))).toBe(true);
+    const logged = console.log.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(logged).toContain('test-results/trace.zip');
+    expect(logged).toContain(destDir);
+  });
+
+  it('reports an empty artifact without erroring', async () => {
+    tarExtractBehavior = extractNothing;
+    global.fetch = vi.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
+    await artifactsCommand(config, ['dep-empty', '--output', destDir], chalk);
+
+    expect(process.exitCode).toBeUndefined();
+    const logged = console.log.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(logged).toContain('artifact was empty');
+  });
+
+  it('defaults to <CONFIG_DIR>/artifacts/<id> when --output is not given', async () => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
+    await artifactsCommand(config, ['dep-default-dir'], chalk);
+
+    expect(process.exitCode).toBeUndefined();
+    const logged = console.log.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(logged).toContain(path.join(_fakeConfigDir, 'artifacts', 'dep-default-dir'));
+  });
+});