@zergai/cyberdeck 0.1.0-beta.1

package/dist/commands/automation.js

@@ -0,0 +1,164 @@
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { catalogTarget, explicitlyUnsupportedCredential, inspectClone, publishedCredentialFromRuntime, resolveCloneSelector, } from '../automation.js';
+import { DeckClient, } from '../client.js';
+async function selectClone(client, deckId, selector) {
+    const [deck, catalog] = await Promise.all([
+        client.getDeck(deckId),
+        client.getCatalog(),
+    ]);
+    const clone = resolveCloneSelector(deck, selector);
+    return {
+        deck,
+        clone,
+        catalog,
+        target: catalogTarget(catalog, clone.vendor),
+    };
+}
+function lineValue(value) {
+    const serialized = JSON.stringify(value);
+    return serialized === undefined ? 'null' : serialized;
+}
+function printInspection(inspection) {
+    console.log(`Clone ${inspection.clone.vendor} "${inspection.clone.name}" `
+        + `(${inspection.clone.id}) in deck "${inspection.deck.name}"`);
+    console.log(`  status: ${inspection.runtime.cloneStatus} `
+        + `(runtime=${inspection.runtime.status})`);
+    console.log(`  service: ${inspection.runtime.serviceUrl ?? '—'}`);
+    console.log(`  zerg: ${inspection.runtime.zergId ?? '—'}`);
+    if (inspection.runtime.socketUrl) {
+        console.log(`  socket: ${inspection.runtime.socketUrl}`);
+    }
+    if (inspection.runtime.errorMessage) {
+        console.log(`  error: ${inspection.runtime.errorMessage}`);
+    }
+    const credential = inspection.managedCredential;
+    if (credential) {
+        console.log(`  managed credential: ${credential.label} `
+            + `(${credential.purpose}; ${credential.header}: ${credential.scheme} <token>)`);
+        console.log(`    reveal: zcd credentials --deck ${inspection.deck.id} `
+            + `--clone ${inspection.clone.id}`);
+    }
+    else {
+        console.log('  managed credential: not advertised');
+    }
+    const fields = inspection.publications.modules.flatMap(module => module.fields);
+    console.log(`  publications: ${inspection.publications.status} `
+        + `(${inspection.publications.modules.length} modules, ${fields.length} fields)`);
+    if (inspection.publications.error) {
+        console.log(`    error: ${inspection.publications.error}`);
+    }
+    for (const module of inspection.publications.modules) {
+        console.log(`    ${module.moduleName}`);
+        for (const field of module.fields) {
+            const value = field.available ? lineValue(field.value) : '<unavailable>';
+            console.log(`      ${field.name}: ${value}`);
+        }
+    }
+    if (inspection.qualification) {
+        console.log(`  qualification: ${inspection.qualification.status} `
+            + `(${inspection.qualification.score}/100)`);
+    }
+    else {
+        console.log('  qualification: not qualified');
+    }
+}
+function printCredential(selected, credential, label = selected.target?.managedCredential?.label ?? 'Managed clone credential', published = false) {
+    console.log(`${label} for ${selected.clone.vendor} (${selected.clone.id})`);
+    console.log(`  ${credential.authentication.header}: `
+        + [
+            credential.authentication.scheme,
+            credential.authentication.token,
+        ].filter(Boolean).join(' '));
+    if (credential.login) {
+        console.log(`  login username: ${credential.login.username}`);
+        console.log(`  login path: ${credential.login.path}`);
+    }
+    console.log(published
+        ? 'This is a public synthetic credential for the simulation environment.'
+        : 'Treat this output as a secret.');
+}
+export function registerAutomationCommands(program) {
+    program
+        .command('dump')
+        .description('Export one running clone data snapshot as stable JSON')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--clone <vendor-or-uuid>', 'unique vendor or exact clone UUID')
+        .option('--out <path>', 'write JSON to a private local file instead of stdout')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const deck = await client.getDeck(opts.deck);
+        const clone = resolveCloneSelector(deck, opts.clone);
+        const dump = await client.getCloneDataDump(deck.id, clone.id);
+        const serialized = `${JSON.stringify(dump, null, 2)}\n`;
+        if (!opts.out) {
+            process.stdout.write(serialized);
+            return;
+        }
+        await mkdir(dirname(opts.out), { recursive: true });
+        await writeFile(opts.out, serialized, { encoding: 'utf8', mode: 0o600 });
+        // writeFile's mode applies only when creating a file. Normalize an
+        // existing output as well so repeated exports stay private.
+        await chmod(opts.out, 0o600);
+        console.log(`Wrote ${dump.clone.vendor} clone dump to ${opts.out} `
+            + `(${dump.sizeBytes} source bytes, ${dump.dataHash})`);
+    });
+    program
+        .command('inspect')
+        .description('Inspect one clone runtime, publications, and qualification')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--clone <vendor-or-uuid>', 'unique vendor or exact clone UUID')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const selected = await selectClone(client, opts.deck, opts.clone);
+        const runtime = await client.getRuntime(selected.deck.id, selected.clone.id);
+        const inspection = inspectClone(selected.deck, selected.clone, runtime, selected.target);
+        if (opts.json) {
+            console.log(JSON.stringify(inspection, null, 2));
+            return;
+        }
+        printInspection(inspection);
+    });
+    program
+        .command('credentials')
+        .description('Read one clone published or managed API/SDK/app credential')
+        .requiredOption('--deck <id>', 'deck id')
+        .requiredOption('--clone <vendor-or-uuid>', 'unique vendor or exact clone UUID')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const selected = await selectClone(client, opts.deck, opts.clone);
+        let published = null;
+        try {
+            const runtime = await client.getRuntime(selected.deck.id, selected.clone.id);
+            published = publishedCredentialFromRuntime(selected.clone.vendor, runtime);
+        }
+        catch (error) {
+            // A publication-only clone must never fall through to the privileged
+            // reveal route. Legacy managed clones retain their local reveal path
+            // when runtime discovery is temporarily unavailable.
+            if (explicitlyUnsupportedCredential(selected.target))
+                throw error;
+        }
+        if (published) {
+            if (opts.json) {
+                console.log(JSON.stringify(published.credential, null, 2));
+                return;
+            }
+            printCredential(selected, published.credential, published.label, true);
+            return;
+        }
+        if (explicitlyUnsupportedCredential(selected.target)) {
+            throw new Error(`Clone '${selected.clone.vendor}' does not publish a complete `
+                + 'simulation credential and does not advertise a Deck-managed credential.');
+        }
+        const credential = await client.revealCredentials(selected.deck.id, selected.clone.id);
+        if (opts.json) {
+            console.log(JSON.stringify(credential, null, 2));
+            return;
+        }
+        printCredential(selected, credential);
+    });
+}
+//# sourceMappingURL=automation.js.map

package/dist/commands/decks.js

@@ -0,0 +1,310 @@
+import { cloneSummary, deckSummary, normalizeCatalogForJson, } from '../automation.js';
+import { DeckClient, probeZerg, } from '../client.js';
+import { diagnosticsHaveFailures, isTerminalRun, runHasFailures, uniqueStrings, } from '../fleet.js';
+import { boundHit, smokeFor } from '../vendors.js';
+import { submitCloneStartRun, waitForCloneStartRun, } from './fleet.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function parseVendors(list) {
+    return list
+        .split(',')
+        .map((v) => v.trim().toLowerCase())
+        .filter(Boolean);
+}
+export function parseCloneTargets(list, catalog) {
+    const targets = uniqueStrings(parseVendors(list));
+    const available = new Set(catalog.targets.map((target) => target.id));
+    const unknown = targets.filter((target) => !available.has(target));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown clone target${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}. Run \`zcd catalog\` to list targets.`);
+    }
+    return targets;
+}
+/** Resolve which deck to act on: explicit id, else the sole deck, else error. */
+export async function resolveDeckId(client, explicit) {
+    if (explicit)
+        return explicit;
+    const decks = await client.listDecks();
+    if (decks.length === 0)
+        throw new Error('No decks found. Create one with `zcd up`.');
+    if (decks.length === 1)
+        return decks[0].id;
+    const names = decks.map((d) => `  ${d.id}  ${d.name} (${d.clone_count ?? d.clones?.length ?? 0} clones)`).join('\n');
+    throw new Error(`Multiple decks — pass --deck <id>:\n${names}`);
+}
+export async function pollClone(client, deckId, cloneId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let rt = {};
+    while (Date.now() < deadline) {
+        rt = await client.getRuntime(deckId, cloneId);
+        const st = rt.cloneStatus || rt.status;
+        if (st === 'running' || st === 'error' || st === 'stopped')
+            return rt;
+        await sleep(6000);
+    }
+    return rt;
+}
+export async function seedClone(client, deckId, cloneId, reset) {
+    // A freshly-provisioned clone reports "running" (Fly's internal health check)
+    // before its public IP finishes routing (~90s on a fresh dedicated v4), so an
+    // immediate seed can spuriously time out. Retry the authenticated CyberDeck
+    // proxy; the clone-control credential remains server-side.
+    let last = 'seed failed';
+    for (let attempt = 0; attempt < 9; attempt++) {
+        try {
+            const result = await client.seedClone(deckId, cloneId, reset);
+            return `seeded ${result.records ?? '?'} records`;
+        }
+        catch (error) {
+            last = `seed failed (${error instanceof Error ? error.message : 'request failed'})`;
+        }
+        if (attempt < 8)
+            await sleep(15000);
+    }
+    return last;
+}
+export function registerDeckCommands(program) {
+    // ── catalog ─────────────────────────────────────────────────────────────
+    program
+        .command('catalog')
+        .description('List every clone target available to a deck')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (opts) => {
+        const catalog = await DeckClient.fromConfig().getCatalog();
+        if (opts.json) {
+            console.log(JSON.stringify(normalizeCatalogForJson(catalog), null, 2));
+            return;
+        }
+        for (const clone of catalog.targets) {
+            const connector = clone.connectorId ? `connector=${clone.connectorId}` : 'legacy';
+            console.log(`${clone.id.padEnd(18)} ${clone.vendorEvokes.padEnd(42)} :${clone.port}  ${connector}`);
+        }
+    });
+    // ── up ──────────────────────────────────────────────────────────────────
+    program
+        .command('up')
+        .description('Spin up a new deck with a set of zerg-clones')
+        .option('--clones <list>', 'comma-separated clone target ids (e.g. zlunk,zarcher)')
+        .option('--all', 'include every unique target in the server catalog')
+        .option('--name <name>', 'deck name')
+        .option('--seed', 'seed prebaked synthetic data once each clone is running')
+        .option('--no-wait', 'return immediately without waiting for clones to run')
+        .option('--timeout <seconds>', 'per-clone wait timeout', '420')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const catalog = await client.getCatalog();
+        if (opts.all && opts.clones !== undefined) {
+            throw new Error('Choose either --all or --clones, not both.');
+        }
+        if (!opts.all && opts.clones === undefined) {
+            throw new Error('Pass --all or --clones <list>.');
+        }
+        const vendors = opts.all
+            ? uniqueStrings(catalog.targets.map(target => target.id))
+            : parseCloneTargets(opts.clones ?? '', catalog);
+        if (vendors.length === 0) {
+            throw new Error(opts.all ? 'The clone catalog is empty.' : '--clones is empty');
+        }
+        const name = opts.name || `zcd ${new Date().toISOString().slice(0, 19).replace('T', ' ')}`;
+        const deck = await client.createDeck(name);
+        console.log(`Created deck "${deck.name}"  (${deck.id})`);
+        console.log(`  ${client.baseUrl}/app/decks/${deck.id}\n`);
+        const clones = [];
+        for (const vendor of vendors) {
+            const clone = await client.addClone(deck.id, vendor);
+            clones.push(clone);
+            console.log(`  + ${vendor} added (${clone.id})`);
+        }
+        const submitted = await submitCloneStartRun(client, deck.id, clones.map(clone => clone.id));
+        if (!submitted.run) {
+            console.log(`\nPreflight: ${submitted.preflight.status}`);
+            for (const check of submitted.preflight.checks) {
+                console.log(`  ${check.status} ${check.code} — ${check.message}`);
+            }
+            process.exitCode = 2;
+            return;
+        }
+        console.log(`\nQueued clone start operation=${submitted.run.run.id}`);
+        if (opts.wait === false) {
+            console.log('Not waiting (--no-wait). Check with `zcd operation`.');
+            return;
+        }
+        console.log('\nWaiting for clones to reach running…');
+        const timeoutMs = Math.max(30, Number(opts.timeout) || 420) * 1000;
+        const result = await waitForCloneStartRun(client, deck.id, submitted.run, timeoutMs);
+        console.log('');
+        for (const item of result.clones) {
+            console.log(`  • ${item.vendor.padEnd(10)} `
+                + `${item.status.padEnd(9)} ${item.stage}`);
+            if (opts.seed && item.status === 'succeeded') {
+                const msg = await seedClone(client, deck.id, item.cloneId, true);
+                console.log(`      ${msg}`);
+            }
+            if (item.error) {
+                console.log(`      error: ${item.error.code}: ${item.error.message}`);
+            }
+        }
+        console.log(`\nDone. deck=${deck.id}`);
+        if (runHasFailures(result) || !isTerminalRun(result.run.status)) {
+            process.exitCode = 1;
+        }
+    });
+    // ── seed ────────────────────────────────────────────────────────────────
+    program
+        .command('seed')
+        .description('Seed prebaked synthetic data into a deck\'s running clones')
+        .option('--deck <id>', 'deck id')
+        .option('--reset', 'clear existing data first (idempotent re-seed)')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const deckId = await resolveDeckId(client, opts.deck);
+        const deck = await client.getDeck(deckId);
+        for (const clone of deck.clones ?? []) {
+            const rt = await client.getRuntime(deckId, clone.id);
+            const url = rt.serviceUrl || clone.service_url;
+            if (!url || (rt.cloneStatus || rt.status) !== 'running') {
+                console.log(`  • ${clone.vendor.padEnd(10)} skipped (not running)`);
+                continue;
+            }
+            const msg = await seedClone(client, deckId, clone.id, Boolean(opts.reset));
+            console.log(`  • ${clone.vendor.padEnd(10)} ${msg}`);
+        }
+    });
+    // ── status ──────────────────────────────────────────────────────────────
+    program
+        .command('status')
+        .description('Show deploy/health status of a deck\'s clones + their zergs')
+        .option('--deck <id>', 'deck id')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const deckId = await resolveDeckId(client, opts.deck);
+        const diagnostics = await client.getDiagnostics(deckId);
+        if (opts.json) {
+            console.log(JSON.stringify(diagnostics, null, 2));
+        }
+        else {
+            console.log(`Deck "${diagnostics.deck.name}" (${diagnostics.deck.id}) — `
+                + `${diagnostics.clones.length} clones\n`);
+            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.latestFailure) {
+                    console.log(`      ${clone.latestFailure.code}: `
+                        + clone.latestFailure.message);
+                }
+                if (clone.error) {
+                    console.log(`      ${clone.error.code}: ${clone.error.message}`);
+                }
+            }
+        }
+        if (diagnosticsHaveFailures(diagnostics))
+            process.exitCode = 1;
+    });
+    // ── check ───────────────────────────────────────────────────────────────
+    program
+        .command('check')
+        .description('Ping each clone\'s vendor API + its zerg; exit nonzero on failure (CI-friendly)')
+        .option('--deck <id>', 'deck id')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const catalog = await client.getCatalog();
+        const targets = new Map(catalog.targets.map((target) => [target.id, target]));
+        const deckId = await resolveDeckId(client, opts.deck);
+        const deck = await client.getDeck(deckId);
+        let failures = 0;
+        for (const clone of deck.clones ?? []) {
+            const rt = await client.getRuntime(deckId, clone.id);
+            const url = rt.serviceUrl || clone.service_url;
+            const smoke = smokeFor(clone.vendor, targets.get(clone.vendor)?.vendorEvokes);
+            console.log(`\n${clone.vendor} (${smoke.evokes})`);
+            if (!url || (rt.cloneStatus || rt.status) !== 'running') {
+                console.log('  ✗ not running');
+                failures++;
+                continue;
+            }
+            const results = await smoke.smoke(boundHit(url));
+            for (const r of results) {
+                console.log(`  ${r.ok ? '✓' : '✗'} ${r.name} — ${r.detail}`);
+                if (!r.ok)
+                    failures++;
+            }
+            if (rt.socketUrl) {
+                const z = await probeZerg(rt.socketUrl);
+                const ok = z.connected && z.contractVersion === 2 && z.manifest === 'cyber-clone';
+                console.log(`  ${ok ? '✓' : '✗'} zerg :3333 — ${z.connected ? `contract v${z.contractVersion}, manifest=${z.manifest}, status=${z.serviceStatus}` : z.error}`);
+                if (!ok)
+                    failures++;
+            }
+        }
+        console.log(`\n${failures === 0 ? '✓ all checks passed' : `✗ ${failures} check(s) failed`}`);
+        if (failures > 0)
+            process.exitCode = 1;
+    });
+    // ── ls ──────────────────────────────────────────────────────────────────
+    program
+        .command('ls')
+        .description('List decks (or a deck\'s clones with --deck)')
+        .option('--deck <id>', 'show clones for this deck')
+        .option('--json', 'emit stable schema-versioned JSON')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        if (opts.deck) {
+            const deck = await client.getDeck(opts.deck);
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    schemaVersion: 1,
+                    deck: deckSummary(deck),
+                    clones: (deck.clones ?? []).map(cloneSummary),
+                }, null, 2));
+                return;
+            }
+            console.log(`Deck "${deck.name}" (${deck.id})`);
+            for (const c of deck.clones ?? []) {
+                console.log(`  ${c.vendor.padEnd(10)} ${c.status.padEnd(9)} ${c.id}`);
+            }
+            return;
+        }
+        const decks = await client.listDecks();
+        if (opts.json) {
+            console.log(JSON.stringify({
+                schemaVersion: 1,
+                decks: decks.map(deck => ({
+                    ...deckSummary(deck),
+                    cloneCount: deck.clone_count ?? deck.clones?.length ?? 0,
+                })),
+            }, null, 2));
+            return;
+        }
+        if (decks.length === 0) {
+            console.log('No decks.');
+            return;
+        }
+        for (const d of decks) {
+            console.log(`  ${d.id}  ${d.name}  (${d.clone_count ?? d.clones?.length ?? 0} clones)`);
+        }
+    });
+    // ── down ────────────────────────────────────────────────────────────────
+    program
+        .command('down')
+        .description('Tear down a deck: remove its clones and delete the deck')
+        .option('--deck <id>', 'deck id')
+        .option('--yes', 'skip confirmation')
+        .action(async (opts) => {
+        const client = DeckClient.fromConfig();
+        const deckId = await resolveDeckId(client, opts.deck);
+        const deck = await client.getDeck(deckId);
+        if (!opts.yes) {
+            console.log(`This will delete deck "${deck.name}" and its ${deck.clones?.length ?? 0} clones. Re-run with --yes.`);
+            return;
+        }
+        for (const clone of deck.clones ?? []) {
+            await client.deleteClone(deckId, clone.id);
+            console.log(`  - removed ${clone.vendor} (${clone.id})`);
+        }
+        await client.deleteDeck(deckId);
+        console.log(`Deleted deck ${deckId}.`);
+        console.log('Each clone\'s container is being torn down (ZergCloud destroys the zerg → zstack destroys the Fly app + releases its machine/IPs); teardown is async, so the Fly app disappears shortly after.');
+    });
+}
+//# sourceMappingURL=decks.js.map