@zergai/cyberdeck 0.1.0-beta.1

package/dist/commands/scenarios.js

@@ -0,0 +1,207 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { DeckClient, } from '../client.js';
+const DEFINITION_KINDS = new Set([
+    'scenario',
+    'drill-template',
+    'company-template',
+]);
+function definitionKind(value) {
+    if (!DEFINITION_KINDS.has(value)) {
+        throw new Error('--kind must be scenario, drill-template, or company-template.');
+    }
+    return value;
+}
+function positiveVersion(value) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new Error('--expected-version must be a positive integer.');
+    }
+    return parsed;
+}
+function output(value, json) {
+    if (json) {
+        process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+        return;
+    }
+    const definition = value;
+    console.log(`${definition.id}  ${definition.kind}  v${definition.draft.version}  ${definition.name}`);
+}
+function outputList(envelope, json) {
+    if (json) {
+        process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+        return;
+    }
+    for (const definition of envelope.definitions)
+        output(definition, false);
+}
+async function scenarioYaml(path) {
+    const yaml = await readFile(resolve(path), 'utf8');
+    if (!yaml.trim())
+        throw new Error('Scenario YAML file is empty.');
+    return yaml;
+}
+export function registerScenarioCommands(program) {
+    const scenario = program
+        .command('scenario')
+        .description('Create, read, version, publish, and manage workspace scenarios and templates');
+    scenario.command('run')
+        .description('Launch a catalog drill or a published scenario; simulation-only unless evidence is requested')
+        .requiredOption('--deck <id>', 'target deck id')
+        .requiredOption('--scenario <id>', 'catalog id or published scenario definition id')
+        .option('--capture-evidence', 'capture dataset and sealed evaluator archives (requires target reset)')
+        .option('--reset-targets', 'authorize clearing existing data on all running scenario targets before this run')
+        .option('--seed <seed>', 'deterministic simulation seed')
+        .option('--tick-delay <ms>', 'real-time delay per simulation tick, 0–5000 ms', '200')
+        .option('--json', 'emit stable JSON with the exact run URL')
+        .action(async (options) => {
+        const tickDelayMs = Number(options.tickDelay);
+        if (!Number.isSafeInteger(tickDelayMs) || tickDelayMs < 0 || tickDelayMs > 5000) {
+            throw new Error('--tick-delay must be an integer between 0 and 5000.');
+        }
+        if (options.captureEvidence && !options.resetTargets) {
+            throw new Error('Evidence capture clears existing target data. Pass --reset-targets to explicitly authorize it.');
+        }
+        const client = DeckClient.fromConfig();
+        const run = await client.launchScenarioRun(options.deck, {
+            scenarioId: options.scenario,
+            artifactMode: options.captureEvidence ? 'split' : 'none',
+            resetFirst: options.resetTargets === true,
+            tickDelayMs,
+            ...(options.seed !== undefined ? { seed: options.seed } : {}),
+        });
+        const url = `${client.baseUrl}/app/decks/${encodeURIComponent(options.deck)}/runs/${encodeURIComponent(run.runId)}`;
+        if (options.json)
+            process.stdout.write(`${JSON.stringify({ ...run, url }, null, 2)}\n`);
+        else
+            console.log(`${run.runId}  ${run.status}  ${run.artifactMode === 'split' ? 'evidence requested; not yet ready' : 'simulation only'}\n${url}`);
+    });
+    scenario.command('runs')
+        .description('List recent runs and their execution/evidence status')
+        .requiredOption('--deck <id>', 'target deck id')
+        .option('--json', 'emit the complete API response including artifact status')
+        .action(async (options) => {
+        const result = await DeckClient.fromConfig().listScenarioRuns(options.deck);
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        else
+            for (const run of result.runs)
+                console.log(`${run.id}  ${run.status}  ${run.scenario_name}`);
+    });
+    scenario.command('run-show')
+        .description('Read one exact run, replay metadata, and authorized evidence availability')
+        .requiredOption('--deck <id>', 'target deck id')
+        .requiredOption('--run <id>', 'run id returned by scenario run')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        const result = await DeckClient.fromConfig().getScenarioRun(options.deck, options.run);
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    });
+    scenario.command('run-control')
+        .description('Request pause, resume, or stop for one exact active run; does not imply runner acknowledgment')
+        .requiredOption('--deck <id>', 'target deck id')
+        .requiredOption('--run <id>', 'run id')
+        .requiredOption('--action <action>', 'pause, resume, or stop')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        if (!['pause', 'resume', 'stop'].includes(options.action))
+            throw new Error('--action must be pause, resume, or stop.');
+        const result = await DeckClient.fromConfig().controlScenarioRun(options.deck, options.run, options.action);
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        else
+            console.log(`${options.action} requested for ${options.run}. Use scenario run-show to observe reconciliation.`);
+    });
+    scenario
+        .command('list')
+        .description('List one workspace scenario or template library')
+        .option('--kind <kind>', 'scenario, drill-template, or company-template', 'scenario')
+        .option('--include-deleted', 'include soft-deleted definitions (admin only)')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        outputList(await DeckClient.fromConfig().listScenarioDefinitions(definitionKind(options.kind), options.includeDeleted === true), options.json);
+    });
+    scenario
+        .command('show')
+        .description('Read a scenario or template, including its current YAML draft')
+        .requiredOption('--id <id>', 'definition id')
+        .option('--include-deleted', 'read a soft-deleted definition (admin only)')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        output(await DeckClient.fromConfig().getScenarioDefinition(options.id, options.includeDeleted === true), options.json);
+    });
+    scenario
+        .command('create')
+        .description('Create a versioned scenario or reusable template from YAML')
+        .requiredOption('--file <path>', 'scenario YAML file')
+        .option('--kind <kind>', 'scenario, drill-template, or company-template', 'scenario')
+        .option('--name <name>', 'display name (defaults to YAML name)')
+        .option('--description <description>', 'optional description')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        output(await DeckClient.fromConfig().createScenarioDefinition({
+            kind: definitionKind(options.kind),
+            yaml: await scenarioYaml(options.file),
+            ...(options.name ? { name: options.name } : {}),
+            ...(options.description !== undefined ? { description: options.description } : {}),
+        }), options.json);
+    });
+    scenario
+        .command('update')
+        .description('Optimistically update a scenario or template draft')
+        .requiredOption('--id <id>', 'definition id')
+        .requiredOption('--expected-version <version>', 'current draft version')
+        .option('--file <path>', 'replacement scenario YAML file')
+        .option('--name <name>', 'replacement display name')
+        .option('--description <description>', 'replacement description')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        if (!options.file && options.name === undefined && options.description === undefined) {
+            throw new Error('Pass --file, --name, or --description to update the draft.');
+        }
+        output(await DeckClient.fromConfig().updateScenarioDefinition(options.id, {
+            expectedVersion: positiveVersion(options.expectedVersion),
+            ...(options.file ? { yaml: await scenarioYaml(options.file) } : {}),
+            ...(options.name !== undefined ? { name: options.name } : {}),
+            ...(options.description !== undefined ? { description: options.description } : {}),
+        }), options.json);
+    });
+    scenario
+        .command('publish')
+        .description('Publish the current draft as an immutable runnable revision')
+        .requiredOption('--id <id>', 'definition id')
+        .requiredOption('--expected-version <version>', 'current draft version')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        const result = await DeckClient.fromConfig().publishScenarioDefinition(options.id, positiveVersion(options.expectedVersion));
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        else
+            output(result.definition, false);
+    });
+    scenario
+        .command('delete')
+        .description('Soft-delete a scenario or template (admin only)')
+        .requiredOption('--id <id>', 'definition id')
+        .option('--yes', 'confirm deletion')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        if (!options.yes)
+            throw new Error('Pass --yes to confirm scenario deletion.');
+        const result = await DeckClient.fromConfig().deleteScenarioDefinition(options.id);
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        else
+            console.log(`Deleted ${result.definition.id}  ${result.definition.name}`);
+    });
+    scenario
+        .command('restore')
+        .description('Restore a soft-deleted scenario or template (admin only)')
+        .requiredOption('--id <id>', 'definition id')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        const result = await DeckClient.fromConfig().restoreScenarioDefinition(options.id);
+        output(result.definition, options.json);
+    });
+}
+//# sourceMappingURL=scenarios.js.map

package/dist/commands/sdk.js

@@ -0,0 +1,229 @@
+/**
+ * `zcd sdk` — run each clone's official vendor SDK through CyberDeck.
+ *
+ * The server owns the official SDKs and conformance runner. The standalone CLI
+ * starts a run for each supported clone, polls that exact run ID, writes the
+ * returned reports, and applies the requested score threshold locally.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { DeckClient, } from '../client.js';
+import { parseCloneTargets, resolveDeckId, pollClone } from './decks.js';
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+function pct(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeReport(run) {
+    const raw = isRecord(run.report) ? run.report : {};
+    const categories = isRecord(raw.perCategory)
+        ? raw.perCategory
+        : {};
+    const failures = Array.isArray(raw.failureReports)
+        ? raw.failureReports
+        : undefined;
+    return {
+        vendor: typeof raw.vendor === 'string' ? raw.vendor : run.vendor,
+        weightedScore: typeof raw.weightedScore === 'number'
+            ? raw.weightedScore
+            : run.weightedScore ?? 0,
+        passed: typeof raw.passed === 'number' ? raw.passed : run.passed ?? 0,
+        totalCases: typeof raw.totalCases === 'number' ? raw.totalCases : run.totalCases ?? 0,
+        perCategory: categories,
+        ...(failures ? { failureReports: failures } : {}),
+    };
+}
+async function pollConformanceRun(client, deckId, cloneId, runId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let firstRequest = true;
+    while (true) {
+        const remainingBeforeRequest = deadline - Date.now();
+        if (!firstRequest && remainingBeforeRequest <= 0) {
+            throw new Error(`conformance timed out after ${(timeoutMs / 1000).toFixed(1)}s`);
+        }
+        const requestTimeoutMs = Math.max(1, Math.min(30_000, remainingBeforeRequest));
+        const { run } = await client.getConformanceRun(deckId, cloneId, runId, requestTimeoutMs).catch((error) => {
+            // The deadline can expire while fetch is awaiting headers or a body, not
+            // only between polls. Keep both timeout paths recognizable to CLI users.
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                throw new Error(`conformance request timed out after ${(requestTimeoutMs / 1000).toFixed(1)}s`, { cause: error });
+            }
+            throw error;
+        });
+        firstRequest = false;
+        if (run.status !== 'running')
+            return run;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            throw new Error(`conformance timed out after ${(timeoutMs / 1000).toFixed(1)}s`);
+        }
+        await sleep(Math.min(1000, remaining));
+    }
+}
+function scoreTarget(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? Math.min(Math.max(parsed, 0), 1) : 0.9;
+}
+function runTimeout(value) {
+    const seconds = Number(value);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 600_000;
+}
+export function registerSdkCommand(program) {
+    program
+        .command('sdk')
+        .description('Run each clone\'s official vendor SDK against it through CyberDeck')
+        .option('--deck <id>', 'target an existing deck (else --clones spins a new one)')
+        .option('--clones <list>', 'comma-separated clone target ids to spin up first')
+        .option('--vendor <v>', 'only run this one clone target from the deck')
+        .option('--no-seed', 'tell the server not to reseed clones before each SDK run')
+        .option('--target <score>', 'min weighted score per vendor (0-1)', '0.9')
+        .option('--down', 'tear the deck down after (only meaningful with --clones)')
+        .option('--timeout <seconds>', 'per-clone provision/run wait timeout', '600')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const catalog = await client.getCatalog();
+        const targets = new Map(catalog.targets.map((entry) => [entry.id, entry]));
+        const targetScore = scoreTarget(opts.target);
+        const timeoutMs = runTimeout(opts.timeout);
+        let deckId;
+        let ownsDeck = false;
+        const createdClones = [];
+        if (opts.clones) {
+            const vendors = parseCloneTargets(opts.clones, catalog);
+            if (vendors.length === 0)
+                throw new Error('--clones is empty');
+            const created = await client.createDeck(`zcd sdk ${new Date().toISOString().slice(0, 19).replace('T', ' ')}`);
+            deckId = created.id;
+            ownsDeck = true;
+            console.log(`Created deck "${created.name}"  (${created.id})`);
+            for (const vendor of vendors) {
+                const clone = await client.addClone(created.id, vendor);
+                createdClones.push(clone);
+                await client.setClone(created.id, clone.id, 'running');
+                console.log(`  + ${vendor} started (${clone.id})`);
+            }
+            console.log('\nWaiting for clones to reach running…');
+        }
+        else {
+            deckId = await resolveDeckId(client, opts.deck);
+        }
+        const deck = await client.getDeck(deckId);
+        let clones = deck.clones && deck.clones.length > 0 ? deck.clones : createdClones;
+        if (opts.vendor) {
+            const selected = opts.vendor.trim().toLowerCase();
+            clones = clones.filter((clone) => clone.vendor === selected);
+        }
+        const sdkClones = clones.filter((clone) => targets.get(clone.vendor)?.conformanceAvailable === true);
+        const skipped = clones
+            .filter((clone) => targets.get(clone.vendor)?.conformanceAvailable !== true)
+            .map((clone) => clone.vendor);
+        if (sdkClones.length === 0) {
+            console.log('No clones with a server-side SDK conformance suite in this deck.');
+            if (skipped.length > 0)
+                console.log(`  skipped (no SDK suite): ${skipped.join(', ')}`);
+            return;
+        }
+        const reportDir = resolve(process.cwd(), 'reports', 'live', deckId);
+        mkdirSync(reportDir, { recursive: true });
+        const rows = [];
+        const createdIds = new Set(createdClones.map((clone) => clone.id));
+        for (const clone of sdkClones) {
+            const metadata = targets.get(clone.vendor);
+            console.log(`\n── ${clone.vendor} (${metadata.vendorEvokes}) ─────────────────────────`);
+            try {
+                if (createdIds.has(clone.id)) {
+                    const runtime = await pollClone(client, deckId, clone.id, timeoutMs);
+                    const status = runtime.cloneStatus || runtime.status;
+                    if (status !== 'running') {
+                        throw new Error(`not running (${status ?? 'unknown'})${runtime.errorMessage ? ` — ${runtime.errorMessage}` : ''}`);
+                    }
+                }
+                const started = await client.startConformance(deckId, clone.id, opts.seed !== false);
+                console.log(`  run: ${started.runId}${opts.seed === false ? ' (seed skipped)' : ''}`);
+                const run = await pollConformanceRun(client, deckId, clone.id, started.runId, timeoutMs);
+                if (run.status === 'failed') {
+                    throw new Error(run.error || 'server-side conformance run failed');
+                }
+                const report = normalizeReport(run);
+                const sdkCategory = report.perCategory.sdk;
+                const sdkApplicable = Boolean(sdkCategory && sdkCategory.total > 0);
+                const sdkOk = !sdkApplicable || sdkCategory?.score === 1;
+                const pass = report.weightedScore >= targetScore && sdkOk;
+                console.log(`  ${pass ? '✓' : '✗'} ${pct(report.weightedScore)} weighted  `
+                    + `(${report.passed}/${report.totalCases} cases`
+                    + `${sdkCategory ? `, sdk ${sdkApplicable ? `${sdkCategory.passed}/${sdkCategory.total}` : 'n/a'}` : ''})`);
+                for (const failure of (report.failureReports ?? []).slice(0, 5)) {
+                    console.log(`      [${failure.category}] ${failure.caseId} — ${failure.error.slice(0, 90)}`);
+                }
+                writeFileSync(resolve(reportDir, `${clone.vendor}.json`), JSON.stringify(report, null, 2));
+                rows.push({ vendor: clone.vendor, evokes: metadata.vendorEvokes, report, pass });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.log(`  ✗ run failed: ${message}`);
+                rows.push({
+                    vendor: clone.vendor,
+                    evokes: metadata.vendorEvokes,
+                    error: message,
+                    pass: false,
+                });
+            }
+        }
+        console.log(`\n═══ SDK conformance summary (target ≥ ${pct(targetScore)}, sdk = 100%) ═══`);
+        for (const row of rows) {
+            const score = row.report ? pct(row.report.weightedScore).padStart(6) : '   —  ';
+            const sdk = row.report?.perCategory.sdk && row.report.perCategory.sdk.total > 0
+                ? `${row.report.perCategory.sdk.passed}/${row.report.perCategory.sdk.total}`
+                : 'n/a';
+            console.log(`  ${row.pass ? '✓' : '✗'} ${row.vendor.padEnd(8)} ${score}  sdk ${String(sdk).padStart(5)}  `
+                + `${row.evokes}${row.error ? `  (${row.error})` : ''}`);
+        }
+        if (skipped.length > 0)
+            console.log(`  · skipped (no SDK suite): ${skipped.join(', ')}`);
+        const summary = {
+            deckId,
+            generatedAt: new Date().toISOString(),
+            target: targetScore,
+            vendors: rows.map((row) => ({
+                vendor: row.vendor,
+                evokes: row.evokes,
+                pass: row.pass,
+                weightedScore: row.report?.weightedScore ?? null,
+                passed: row.report?.passed ?? null,
+                totalCases: row.report?.totalCases ?? null,
+                sdk: row.report?.perCategory.sdk ?? null,
+                error: row.error ?? null,
+            })),
+        };
+        writeFileSync(resolve(reportDir, 'summary.json'), JSON.stringify(summary, null, 2));
+        console.log(`\n  reports → ${reportDir}`);
+        if (opts.down && ownsDeck) {
+            console.log(`\nTearing down deck ${deckId}…`);
+            for (const clone of deck.clones ?? createdClones) {
+                try {
+                    await client.deleteClone(deckId, clone.id);
+                }
+                catch {
+                    // Best effort: continue tearing down the remaining deck resources.
+                }
+            }
+            try {
+                await client.deleteDeck(deckId);
+            }
+            catch {
+                // Best effort: the run result remains authoritative even if cleanup fails.
+            }
+            console.log('  done.');
+        }
+        else if (opts.down) {
+            console.log('\n--down ignored (targets an existing deck; tear down with `zcd down --deck <id>`).');
+        }
+        const failed = rows.filter((row) => !row.pass);
+        console.log(`\n${failed.length === 0 ? '✓ all SDK vendors met target' : `✗ ${failed.length} vendor(s) below target`}`);
+        if (failed.length > 0)
+            process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=sdk.js.map

package/dist/commands/workbench.js

@@ -0,0 +1,225 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+import { posix } from 'node:path';
+import { resolveCloneSelector } from '../automation.js';
+import { DeckClient, } from '../client.js';
+async function selectClone(client, deckId, selector) {
+    const deck = await client.getDeck(deckId);
+    return { deck, clone: resolveCloneSelector(deck, selector) };
+}
+function printWorkbench(workbench) {
+    console.log(`${workbench.clone.vendor} (${workbench.clone.id})`);
+    console.log(`  runtime: ${workbench.runtime.serviceStatus}`
+        + ` / ${workbench.runtime.lifecycleStatus}`
+        + ` / ${workbench.runtime.presenceStatus}`);
+    console.log(`  ztc: ${workbench.terminal.status}`
+        + ` / ${workbench.terminal.provider || '—'}`
+        + ` / ${workbench.terminal.model || '—'}`);
+    console.log(`  changes: ${workbench.changes.clean ? 'clean' : `${workbench.changes.changedFiles} files`}`
+        + ` (+${workbench.changes.additions} -${workbench.changes.deletions})`);
+    console.log(`  head: ${workbench.changes.head ?? '—'}`);
+    console.log(`  seed: ${workbench.changes.seed ?? '—'}`);
+}
+async function requirementText(options) {
+    if (options.file && options.requirement) {
+        throw new Error('Use either --file or --requirement, not both.');
+    }
+    const value = options.file
+        ? await readFile(resolve(options.file), 'utf8')
+        : options.requirement ?? '';
+    const cleaned = value.trim();
+    if (!cleaned)
+        throw new Error('A non-empty --file or --requirement is required.');
+    if (cleaned.length > 8000)
+        throw new Error('Requirement exceeds the 8000 character limit.');
+    return cleaned;
+}
+async function submitRequirement(options, captureBefore = false) {
+    const client = DeckClient.fromConfig();
+    const selected = await selectClone(client, options.deck, options.clone);
+    const before = captureBefore
+        ? await client.getWorkbench(selected.deck.id, selected.clone.id)
+        : null;
+    if (before && !before.capabilities.requirements) {
+        throw new Error(`Clone '${selected.clone.vendor}' does not accept live requirements.`);
+    }
+    await client.submitWorkbenchRequirement(selected.deck.id, selected.clone.id, await requirementText(options));
+    console.log(`Requirement accepted by ${selected.clone.vendor} (${selected.clone.id}).`);
+    return { client, selected, before };
+}
+function safeRelativePath(value) {
+    const normalized = posix.normalize(value.replaceAll('\\', '/'));
+    if (!normalized
+        || normalized === '.'
+        || normalized.startsWith('/')
+        || normalized === '..'
+        || normalized.startsWith('../')) {
+        throw new Error(`Unsafe clone source path: ${value}`);
+    }
+    return normalized;
+}
+function localTarget(root, relative) {
+    const base = resolve(root);
+    const target = resolve(base, relative);
+    if (target !== base && !target.startsWith(`${base}${sep}`)) {
+        throw new Error(`Clone source path escapes output directory: ${relative}`);
+    }
+    return target;
+}
+async function pullChanges(client, selected, workbench, outDir, promotion) {
+    const workspaceRoot = workbench.changes.workspaceRoot;
+    if (!workspaceRoot?.startsWith('/')) {
+        throw new Error('Runtime did not advertise an absolute clone workspace root.');
+    }
+    const outputRoot = resolve(outDir);
+    await mkdir(outputRoot, { recursive: true });
+    const pulled = [];
+    const deleted = [];
+    for (const file of workbench.changes.files) {
+        const relative = safeRelativePath(file.path);
+        if (file.status.includes('D')) {
+            deleted.push(relative);
+            continue;
+        }
+        const remote = posix.join(workspaceRoot, relative);
+        const snapshot = await client.getCloneFileContent(selected.deck.id, selected.clone.id, remote);
+        if (snapshot.status !== 'available' || snapshot.truncated) {
+            throw new Error(`Could not pull complete source file: ${relative}`);
+        }
+        const content = snapshot.encoding === 'base64'
+            ? Buffer.from(snapshot.content, 'base64')
+            : Buffer.from(snapshot.content, 'utf8');
+        const target = localTarget(outputRoot, relative);
+        await mkdir(resolve(target, '..'), { recursive: true });
+        await writeFile(target, content);
+        pulled.push(relative);
+    }
+    if (promotion) {
+        await writeFile(localTarget(outputRoot, 'zerg-promotion.json'), `${JSON.stringify({
+            schemaVersion: 1,
+            deckId: selected.deck.id,
+            cloneId: selected.clone.id,
+            vendor: selected.clone.vendor,
+            seed: workbench.changes.seed,
+            head: workbench.changes.head,
+            files: pulled,
+            deletedFiles: deleted,
+        }, null, 2)}\n`);
+    }
+    console.log(`${promotion ? 'Promotion bundle' : 'Changes'}: ${pulled.length} files`
+        + `${deleted.length ? `, ${deleted.length} deletions recorded` : ''} → ${outputRoot}`);
+}
+function addSelectionOptions(command) {
+    return command
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--clone <vendor-or-uuid>', 'unique vendor or exact clone UUID');
+}
+export function registerWorkbenchCommands(program) {
+    const zerg = program.command('zerg').description('Operate a clone-resident Zerg');
+    addSelectionOptions(zerg.command('inspect').description('Inspect the resident Zerg and live source'))
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        const client = DeckClient.fromConfig();
+        const selected = await selectClone(client, options.deck, options.clone);
+        const workbench = await client.getWorkbench(selected.deck.id, selected.clone.id);
+        if (options.json)
+            console.log(JSON.stringify(workbench, null, 2));
+        else
+            printWorkbench(workbench);
+    });
+    addSelectionOptions(zerg.command('require').description('Submit one compatibility requirement'))
+        .option('--file <path>', 'read requirement from a UTF-8 file')
+        .option('--requirement <text>', 'inline requirement')
+        .action(async (options) => {
+        await submitRequirement(options);
+    });
+    addSelectionOptions(zerg.command('run').description('Submit a requirement and optionally watch for edits'))
+        .option('--file <path>', 'read requirement from a UTF-8 file')
+        .option('--requirement <text>', 'inline requirement')
+        .option('--watch', 'poll until the workspace changes')
+        .option('--timeout <seconds>', 'watch timeout', '600')
+        .action(async (options) => {
+        const { client, selected, before } = await submitRequirement(options, true);
+        if (!options.watch)
+            return;
+        if (!before)
+            throw new Error('Could not capture the pre-run workbench state.');
+        const timeoutSeconds = Number(options.timeout);
+        if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 3600) {
+            throw new Error('--timeout must be between 1 and 3600 seconds.');
+        }
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        while (Date.now() < deadline) {
+            await new Promise(resolveWait => setTimeout(resolveWait, 2000));
+            const current = await client.getWorkbench(selected.deck.id, selected.clone.id);
+            if (current.changes.head !== before.changes.head
+                || current.changes.changedFiles !== before.changes.changedFiles) {
+                printWorkbench(current);
+                return;
+            }
+        }
+        throw new Error('Timed out waiting for the clone workspace to change.');
+    });
+    const changes = program.command('changes').description('Inspect and recover clone source divergence');
+    addSelectionOptions(changes.command('status').description('Show current source divergence'))
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        const client = DeckClient.fromConfig();
+        const selected = await selectClone(client, options.deck, options.clone);
+        const workbench = await client.getWorkbench(selected.deck.id, selected.clone.id);
+        if (options.json)
+            console.log(JSON.stringify(workbench, null, 2));
+        else
+            printWorkbench(workbench);
+    });
+    addSelectionOptions(changes.command('show').description('List changed source files'))
+        .action(async (options) => {
+        const client = DeckClient.fromConfig();
+        const selected = await selectClone(client, options.deck, options.clone);
+        const workbench = await client.getWorkbench(selected.deck.id, selected.clone.id);
+        for (const file of workbench.changes.files) {
+            console.log(`${file.status.padEnd(3)} ${file.path}`);
+        }
+    });
+    addSelectionOptions(changes.command('history').description('List clone checkpoints'))
+        .action(async (options) => {
+        const client = DeckClient.fromConfig();
+        const selected = await selectClone(client, options.deck, options.clone);
+        const workbench = await client.getWorkbench(selected.deck.id, selected.clone.id);
+        for (const item of workbench.changes.history ?? []) {
+            console.log(`${item.head.slice(0, 12)}  ${item.createdAt}  ${item.label}`);
+        }
+    });
+    addSelectionOptions(changes.command('checkpoint').description('Commit the current live source'))
+        .option('--label <text>', 'checkpoint label', 'operator checkpoint')
+        .action(async (options) => {
+        const client = DeckClient.fromConfig();
+        const selected = await selectClone(client, options.deck, options.clone);
+        await client.runWorkbenchAction(selected.deck.id, selected.clone.id, 'checkpoint', { label: options.label });
+        console.log(`Checkpoint created for ${selected.clone.vendor}.`);
+    });
+    addSelectionOptions(changes.command('reset').description('Discard uncheckpointed live source'))
+        .option('--yes', 'confirm reset')
+        .action(async (options) => {
+        if (!options.yes)
+            throw new Error('Reset requires --yes.');
+        const client = DeckClient.fromConfig();
+        const selected = await selectClone(client, options.deck, options.clone);
+        await client.runWorkbenchAction(selected.deck.id, selected.clone.id, 'reset');
+        console.log(`Reset ${selected.clone.vendor} to its latest checkpoint.`);
+    });
+    for (const promotion of [false, true]) {
+        const command = changes.command(promotion ? 'promote' : 'pull')
+            .description(promotion
+            ? 'Create a canonical promotion bundle from live changes'
+            : 'Pull changed live source files')
+            .requiredOption('--out <directory>', 'local output directory');
+        addSelectionOptions(command).action(async (options) => {
+            const client = DeckClient.fromConfig();
+            const selected = await selectClone(client, options.deck, options.clone);
+            const workbench = await client.getWorkbench(selected.deck.id, selected.clone.id);
+            await pullChanges(client, selected, workbench, options.out, promotion);
+        });
+    }
+}
+//# sourceMappingURL=workbench.js.map