@zergai/cyberdeck 0.1.0-beta.1

package/dist/commands/fleet.js

@@ -0,0 +1,393 @@
+import { randomUUID } from 'node:crypto';
+import { DeckClient } from '../client.js';
+import { diagnosticHasFailure, diagnosticsHaveFailures, isTerminalRun, mapLimit, redactLogValue, runHasFailures, selectDiagnostic, } from '../fleet.js';
+const sleep = (ms) => new Promise(resolve => (setTimeout(resolve, ms)));
+const CLONE_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function setExitCode(code) {
+    const current = typeof process.exitCode === 'number' ? process.exitCode : 0;
+    process.exitCode = Math.max(current, code);
+}
+function parseInteger(value, fallback, minimum, maximum, label) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < minimum || parsed > maximum) {
+        throw new Error(`${label} must be an integer between ${minimum} and ${maximum}.`);
+    }
+    return parsed;
+}
+async function diagnosticsForSelector(client, deckId, selector, tail) {
+    if (selector && CLONE_UUID.test(selector)) {
+        return client.getDiagnostics(deckId, { cloneId: selector, tail });
+    }
+    const diagnostics = await client.getDiagnostics(deckId, { tail });
+    if (!selector)
+        return diagnostics;
+    return {
+        ...diagnostics,
+        clones: [selectDiagnostic(diagnostics, selector)],
+    };
+}
+async function resolveTargets(client, options) {
+    const modes = [
+        options.clone !== undefined,
+        options.all === true,
+        options.failed === true,
+    ].filter(Boolean).length;
+    if (modes !== 1) {
+        throw new Error('Choose exactly one target: --clone <vendor-or-uuid>, --all, or --failed.');
+    }
+    const diagnostics = options.clone !== undefined
+        ? await diagnosticsForSelector(client, options.deck, options.clone)
+        : await client.getDiagnostics(options.deck);
+    let clones;
+    if (options.clone !== undefined) {
+        clones = [selectDiagnostic(diagnostics, options.clone)];
+    }
+    else if (options.failed) {
+        clones = diagnostics.clones.filter(diagnosticHasFailure);
+    }
+    else {
+        clones = diagnostics.clones;
+    }
+    if (clones.length === 0) {
+        throw new Error(options.failed
+            ? `Deck ${options.deck} has no failed clones.`
+            : `Deck ${options.deck} has no matching clones.`);
+    }
+    return { diagnostics, clones };
+}
+function printPreflight(preflight) {
+    console.log(`Preflight: ${preflight.status}`);
+    for (const check of preflight.checks) {
+        console.log(`  ${check.status.padEnd(4)} ${check.code} — ${check.message}`);
+    }
+    for (const clone of preflight.clones) {
+        console.log(`  ${clone.vendor.padEnd(18)} ${clone.status} (${clone.cloneId}) `
+            + `artifact=${clone.imageId} runtime=${clone.runtimeMode}`);
+        for (const check of clone.checks) {
+            console.log(`    ${check.status.padEnd(4)} ${check.code} — ${check.message}`);
+        }
+    }
+}
+function printRun(envelope) {
+    console.log(`Operation ${envelope.run.id}: ${envelope.run.status} `
+        + `(${envelope.run.succeededCount}/${envelope.run.targetCount} succeeded, `
+        + `${envelope.run.failedCount} failed)`);
+    for (const clone of envelope.clones) {
+        console.log(`  ${clone.vendor.padEnd(18)} ${clone.status.padEnd(9)} ${clone.stage} `
+            + `artifact=${clone.imageId ?? '—'} `
+            + `runtime=${clone.runtimeMode ?? '—'}`);
+        if (clone.error) {
+            console.log(`    ${clone.error.code}: ${clone.error.message} `
+                + `(retryable=${clone.error.retryable})`);
+        }
+    }
+}
+function printDiagnostics(diagnostics) {
+    console.log(`Deck "${diagnostics.deck.name}" (${diagnostics.deck.id}) — `
+        + `${diagnostics.clones.length} clone(s)`);
+    for (const clone of diagnostics.clones) {
+        const url = clone.runtime?.serviceUrl ?? clone.serviceUrl ?? '—';
+        console.log(`  ${clone.vendor.padEnd(18)} ${clone.status.padEnd(10)} ${url}`);
+        if (clone.operation) {
+            console.log(`    operation=${clone.operation.runId} `
+                + `stage=${clone.operation.stage} attempt=${clone.operation.attempt} `
+                + `artifact=${clone.operation.imageId ?? '—'} `
+                + `runtime=${clone.operation.runtimeMode ?? '—'}`);
+        }
+        if (clone.latestFailure) {
+            console.log(`    failure=${clone.latestFailure.code}: `
+                + clone.latestFailure.message);
+        }
+        if (clone.error) {
+            console.log(`    diagnostic=${clone.error.code}: ${clone.error.message}`);
+        }
+    }
+}
+export async function waitForCloneStartRun(client, deckId, initial, timeoutMs) {
+    let current = initial;
+    const deadline = Date.now() + timeoutMs;
+    while (!isTerminalRun(current.run.status) && Date.now() < deadline) {
+        await sleep(2000);
+        current = await client.getCloneStartRun(deckId, current.run.id);
+    }
+    return current;
+}
+export async function submitCloneStartRun(client, deckId, cloneIds) {
+    const preflight = await client.preflightClones(deckId, cloneIds);
+    if (preflight.status === 'blocked') {
+        return { preflight, run: null };
+    }
+    const run = await client.createCloneStartRun(deckId, cloneIds, randomUUID());
+    return { preflight, run };
+}
+async function startSelected(client, options) {
+    const { clones } = await resolveTargets(client, options);
+    await startClones(client, options, clones);
+}
+async function startClones(client, options, clones) {
+    const submitted = await submitCloneStartRun(client, options.deck, clones.map(clone => clone.cloneId));
+    if (!submitted.run) {
+        if (options.json) {
+            console.log(JSON.stringify(submitted.preflight, null, 2));
+        }
+        else {
+            printPreflight(submitted.preflight);
+        }
+        setExitCode(2);
+        return;
+    }
+    const timeoutMs = parseInteger(options.timeout, 420, 30, 3600, '--timeout') * 1000;
+    const result = options.wait
+        ? await waitForCloneStartRun(client, options.deck, submitted.run, timeoutMs)
+        : submitted.run;
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        printRun(result);
+    if (runHasFailures(result)
+        || (options.wait === true && !isTerminalRun(result.run.status))) {
+        setExitCode(1);
+    }
+}
+async function applyCloneAction(client, options, action) {
+    const { clones } = await resolveTargets(client, options);
+    const results = await mapLimit(clones, 4, async (clone) => {
+        try {
+            const result = action === 'stop'
+                ? await client.setClone(options.deck, clone.cloneId, 'stopped')
+                : await client.resetClone(options.deck, clone.cloneId);
+            return {
+                cloneId: clone.cloneId,
+                vendor: clone.vendor,
+                ok: true,
+                result,
+                error: null,
+            };
+        }
+        catch (error) {
+            return {
+                cloneId: clone.cloneId,
+                vendor: clone.vendor,
+                ok: false,
+                result: null,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    });
+    return {
+        schemaVersion: 1,
+        action,
+        deckId: options.deck,
+        results,
+    };
+}
+function printAction(envelope) {
+    console.log(`${envelope.action} (${envelope.deckId})`);
+    for (const result of envelope.results) {
+        console.log(`  ${result.ok ? '✓' : '✗'} ${result.vendor} (${result.cloneId})`
+            + (result.error ? ` — ${result.error}` : ''));
+    }
+}
+async function waitUntilStopped(client, deckId, clones, timeoutMs) {
+    await mapLimit(clones, 4, async (clone) => {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            try {
+                const runtime = await client.getRuntime(deckId, clone.cloneId);
+                if (runtime.cloneStatus === 'stopped'
+                    || runtime.status === 'stopped')
+                    return;
+            }
+            catch {
+                // A runtime can disappear between teardown and reconciliation. The
+                // deck diagnostic remains the fallback observation for this poll.
+            }
+            const diagnostics = await client.getDiagnostics(deckId, {
+                cloneId: clone.cloneId,
+            });
+            const current = diagnostics.clones[0];
+            if (current?.status === 'stopped')
+                return;
+            if (current?.status === 'error') {
+                throw new Error(`${clone.vendor} entered error while stopping for restart.`);
+            }
+            await sleep(2000);
+        }
+        throw new Error(`${clone.vendor} did not stop before the timeout.`);
+    });
+}
+function registerTargetOptions(command) {
+    return command
+        .requiredOption('--deck <id>', 'deck id')
+        .option('--clone <vendor-or-uuid>', 'one vendor or exact clone UUID')
+        .option('--all', 'target every clone in the deck')
+        .option('--failed', 'target clones with a recorded failure')
+        .option('--json', 'emit stable schema-versioned JSON');
+}
+export function registerFleetCommands(program) {
+    registerTargetOptions(program
+        .command('preflight')
+        .description('Check platform admission readiness for selected clones')).action(async (options) => {
+        const client = DeckClient.fromConfig();
+        const { clones } = await resolveTargets(client, options);
+        const preflight = await client.preflightClones(options.deck, clones.map(clone => clone.cloneId));
+        if (options.json)
+            console.log(JSON.stringify(preflight, null, 2));
+        else
+            printPreflight(preflight);
+        if (preflight.status === 'blocked')
+            setExitCode(2);
+    });
+    registerTargetOptions(program
+        .command('start')
+        .description('Start selected clones through a durable fleet operation'))
+        .option('--wait', 'wait for the fleet operation to finish')
+        .option('--timeout <seconds>', 'fleet operation timeout', '420')
+        .action(async (options) => {
+        await startSelected(DeckClient.fromConfig(), options);
+    });
+    registerTargetOptions(program
+        .command('stop')
+        .description('Stop selected existing clones')).action(async (options) => {
+        const envelope = await applyCloneAction(DeckClient.fromConfig(), options, 'stop');
+        if (options.json)
+            console.log(JSON.stringify(envelope, null, 2));
+        else
+            printAction(envelope);
+        if (envelope.results.some(result => !result.ok))
+            setExitCode(1);
+    });
+    registerTargetOptions(program
+        .command('reset')
+        .description('Reset synthetic data in selected running clones')).action(async (options) => {
+        const envelope = await applyCloneAction(DeckClient.fromConfig(), options, 'reset');
+        if (options.json)
+            console.log(JSON.stringify(envelope, null, 2));
+        else
+            printAction(envelope);
+        if (envelope.results.some(result => !result.ok))
+            setExitCode(1);
+    });
+    registerTargetOptions(program
+        .command('restart-runtime')
+        .description('Stop selected clones and start a new durable runtime run'))
+        .option('--wait', 'wait for the start operation to finish')
+        .option('--timeout <seconds>', 'stop and start timeout', '420')
+        .action(async (options) => {
+        const client = DeckClient.fromConfig();
+        const selected = await resolveTargets(client, options);
+        const stopped = await applyCloneAction(client, options, 'stop');
+        if (stopped.results.some(result => !result.ok)) {
+            if (options.json)
+                console.log(JSON.stringify(stopped, null, 2));
+            else
+                printAction(stopped);
+            setExitCode(1);
+            return;
+        }
+        const timeoutMs = parseInteger(options.timeout, 420, 30, 3600, '--timeout') * 1000;
+        await waitUntilStopped(client, options.deck, selected.clones, timeoutMs);
+        await startClones(client, options, selected.clones);
+    });
+    program
+        .command('diagnose')
+        .description('Read observational fleet diagnostics without reconciling state')
+        .requiredOption('--deck <id>', 'deck id')
+        .option('--clone <vendor-or-uuid>', 'one vendor or exact clone UUID')
+        .option('--tail <count>', 'include this many recent log entries', '50')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (options) => {
+        const tail = parseInteger(options.tail, 50, 0, 500, '--tail');
+        const diagnostics = await diagnosticsForSelector(DeckClient.fromConfig(), options.deck, options.clone, tail);
+        if (options.json)
+            console.log(JSON.stringify(diagnostics, null, 2));
+        else
+            printDiagnostics(diagnostics);
+        if (diagnosticsHaveFailures(diagnostics))
+            setExitCode(1);
+    });
+    program
+        .command('logs')
+        .description('Read clone runtime logs')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--clone <vendor-or-uuid>', 'vendor or exact clone UUID')
+        .option('--tail <count>', 'number of recent entries', '100')
+        .option('--since <timestamp>', 'only entries at or after this ISO timestamp')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (options) => {
+        const tail = parseInteger(options.tail, 100, 1, 500, '--tail');
+        const client = DeckClient.fromConfig();
+        const diagnostics = await diagnosticsForSelector(client, options.deck, options.clone);
+        const clone = selectDiagnostic(diagnostics, options.clone);
+        if (options.since
+            && !Number.isFinite(new Date(options.since).getTime())) {
+            throw new Error('--since must be a valid ISO timestamp.');
+        }
+        const logs = redactLogValue(await client.getCloneLogs(options.deck, clone.cloneId, { tail, since: options.since }));
+        if (options.json) {
+            console.log(JSON.stringify({
+                schemaVersion: 1,
+                deckId: options.deck,
+                cloneId: clone.cloneId,
+                vendor: clone.vendor,
+                logs,
+            }, null, 2));
+            return;
+        }
+        if (typeof logs === 'string') {
+            console.log(logs);
+        }
+        else {
+            console.log(JSON.stringify(logs, null, 2));
+        }
+    });
+    program
+        .command('operations')
+        .description('List recent durable clone start operations')
+        .requiredOption('--deck <id>', 'deck id')
+        .option('--limit <count>', 'number of operations', '20')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (options) => {
+        const limit = parseInteger(options.limit, 20, 1, 100, '--limit');
+        const list = await DeckClient.fromConfig().listCloneStartRuns(options.deck, limit);
+        if (options.json) {
+            console.log(JSON.stringify(list, null, 2));
+            return;
+        }
+        for (const run of list.runs) {
+            console.log(`${run.id}  ${run.status.padEnd(9)} `
+                + `${run.succeededCount}/${run.targetCount} succeeded  `
+                + `${run.failedCount} failed  ${run.createdAt}`);
+        }
+    });
+    program
+        .command('operation')
+        .description('Inspect or retry one durable clone start operation')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--run <id>', 'operation id')
+        .option('--retry-failed', 'requeue retryable failed clones')
+        .option('--wait', 'wait for the operation to finish')
+        .option('--timeout <seconds>', 'operation timeout', '420')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (options) => {
+        const client = DeckClient.fromConfig();
+        let envelope = options.retryFailed
+            ? await client.retryFailedCloneStartRun(options.deck, options.run)
+            : await client.getCloneStartRun(options.deck, options.run);
+        if (options.wait) {
+            const timeoutMs = parseInteger(options.timeout, 420, 30, 3600, '--timeout') * 1000;
+            envelope = await waitForCloneStartRun(client, options.deck, envelope, timeoutMs);
+        }
+        if (options.json)
+            console.log(JSON.stringify(envelope, null, 2));
+        else
+            printRun(envelope);
+        if (runHasFailures(envelope)
+            || (options.wait === true && !isTerminalRun(envelope.run.status))) {
+            setExitCode(1);
+        }
+    });
+}
+//# sourceMappingURL=fleet.js.map

package/dist/commands/oracle.js

@@ -0,0 +1,143 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { DeckClient, } from '../client.js';
+const ORACLE_EVENTS = new Set([
+    'materialize',
+    'materialization_ready',
+    'approve_parameters',
+    'reject_parameters',
+    'execute',
+    'execution_ready',
+    'approve_answers',
+    'reject_answers',
+    'seal',
+    'sealed',
+    'fail',
+    'mark_stale',
+    'retry',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function readJsonObject(path, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(resolve(path), 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${label} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed))
+        throw new Error(`${label} must contain one JSON object.`);
+    return parsed;
+}
+function outputJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function printRecord(record) {
+    console.log(`${record.id}  ${record.status.padEnd(27)} v${record.currentVersion}`
+        + `  ${record.subjectKind}:${record.subjectId}`);
+}
+function printDetail(detail) {
+    printRecord(detail.oracleSet);
+    console.log(`  artifact sha256:${detail.oracleSet.artifact.sha256} (${detail.oracleSet.artifact.sizeBytes} bytes)`);
+    console.log(`  questions ${detail.document.questions.length}`);
+}
+function positiveInteger(value, label, maximum = Number.MAX_SAFE_INTEGER) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > maximum) {
+        throw new Error(`${label} must be an integer between 1 and ${maximum}.`);
+    }
+    return parsed;
+}
+function outputDetail(detail, json) {
+    if (json)
+        outputJson(detail);
+    else
+        printDetail(detail);
+}
+export function registerOracleCommands(program) {
+    const oracle = program.command('oracle').description('Author and replay review-gated QA oracle sets');
+    oracle
+        .command('list')
+        .description('List QA oracle sets for a deck')
+        .requiredOption('--deck <id>', 'deck id')
+        .option('--limit <count>', 'maximum records (1-100)', '50')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        const records = await DeckClient.fromConfig().listOracleSets(options.deck, positiveInteger(options.limit, '--limit', 100));
+        if (options.json)
+            outputJson(records);
+        else
+            records.forEach(printRecord);
+    });
+    oracle
+        .command('show')
+        .description('Inspect the current immutable oracle-set version')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--id <oracle-id>', 'oracle set id')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        outputDetail(await DeckClient.fromConfig().getOracleSet(options.deck, options.id), options.json);
+    });
+    oracle
+        .command('create')
+        .description('Create a draft oracle set from an authored subject and questions')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--file <path>', 'JSON file containing subject and questions')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        const input = await readJsonObject(options.file, 'Oracle draft');
+        if (!isRecord(input.subject) || !Array.isArray(input.questions)) {
+            throw new Error('Oracle draft must contain subject and questions.');
+        }
+        outputDetail(await DeckClient.fromConfig().createOracleSet(options.deck, {
+            subject: input.subject,
+            questions: input.questions,
+        }), options.json);
+    });
+    oracle
+        .command('materialize')
+        .description('Generate review-pending connector parameters with Codex')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--id <oracle-id>', 'oracle set id')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        outputDetail(await DeckClient.fromConfig().materializeOracleSet(options.deck, options.id), options.json);
+    });
+    oracle
+        .command('transition')
+        .description('Apply one optimistic, review-gated oracle lifecycle event')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--id <oracle-id>', 'oracle set id')
+        .requiredOption('--expected-version <version>', 'current oracle set version')
+        .requiredOption('--event <event>', 'lifecycle event')
+        .requiredOption('--file <path>', 'reviewed oracle document JSON')
+        .option('--json', 'emit stable JSON')
+        .action(async (options) => {
+        if (!ORACLE_EVENTS.has(options.event)) {
+            throw new Error(`Unknown oracle event '${options.event}'.`);
+        }
+        const document = await readJsonObject(options.file, 'Oracle document');
+        outputDetail(await DeckClient.fromConfig().transitionOracleSet(options.deck, options.id, {
+            expectedVersion: positiveInteger(options.expectedVersion, '--expected-version'),
+            event: options.event,
+            document,
+        }), options.json);
+    });
+    oracle
+        .command('export')
+        .description('Write the current oracle artifact and public metadata to a private JSON file')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--id <oracle-id>', 'oracle set id')
+        .requiredOption('--out <path>', 'output JSON path')
+        .action(async (options) => {
+        const detail = await DeckClient.fromConfig().getOracleSet(options.deck, options.id);
+        const target = resolve(options.out);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, `${JSON.stringify(detail, null, 2)}\n`, { mode: 0o600 });
+        await chmod(target, 0o600);
+        console.log(`Oracle ${detail.oracleSet.id} v${detail.oracleSet.currentVersion} → ${target}`);
+    });
+}
+//# sourceMappingURL=oracle.js.map

package/dist/commands/portfolio.js

@@ -0,0 +1,19 @@
+import { DeckClient } from '../client.js';
+import { renderDeckPortfolio } from '../portfolio.js';
+import { resolveDeckId } from './decks.js';
+export function registerPortfolioCommand(program) {
+    program
+        .command('portfolio')
+        .description('Show the 69-target deck qualification and evidence matrix')
+        .option('--deck <id>', 'deck id')
+        .option('--json', 'emit canonical schema-versioned JSON')
+        .action(async (options) => {
+        const client = DeckClient.fromConfig();
+        const deckId = await resolveDeckId(client, options.deck);
+        const portfolio = await client.getPortfolio(deckId);
+        console.log(options.json
+            ? JSON.stringify(portfolio, null, 2)
+            : renderDeckPortfolio(portfolio));
+    });
+}
+//# sourceMappingURL=portfolio.js.map