@zergai/cyberdeck 0.1.0-beta.1

package/README.md

@@ -0,0 +1,284 @@
+# zerg-cyberdeck
+
+> **License notice:** This package is source-available, not open source. Free
+> company use is limited to purpose-bound evaluation. Commercial development,
+> ongoing company engineering, customer work, and other Commercial Use require
+> a separate commercial license. By exercising a permission in the package
+> [license](./LICENSE.md), you accept its conditions; a separate signed agreement
+> controls any commercial rights.
+
+`zerg-cyberdeck` installs the `zcd` command-line client for Zerg CyberDeck. It
+manages workspace-scoped clone decks, checks running clone and Zerg services,
+and asks the CyberDeck server to run its deployed SDK/API conformance suites.
+
+This beta requires Node.js 22 or later.
+
+## Install
+
+The ZergAI organization distribution is `@zergai/cyberdeck@next`. After the
+scoped release is published, use `npm install --global @zergai/cyberdeck@next`.
+It provides the same `zcd` command and license as the legacy package below.
+Install only one distribution globally because both provide `zcd`.
+
+Until the first stable release, install the `next` channel:
+
+```bash
+npm install --global zerg-cyberdeck@next
+zcd --version
+```
+
+## Sign in
+
+```bash
+zcd login
+```
+
+The CLI prints a short user code and opens the CyberDeck authorization page.
+Sign in through the normal browser flow, choose one of your workspaces, and
+approve the device. The resulting 30-day personal token is bound to that
+workspace and stored in a mode-`0600` config file.
+
+Useful alternatives:
+
+```bash
+zcd login --url https://your-cyberdeck.example --workspace "Blue Team"
+zcd whoami
+zcd logout
+```
+
+For non-interactive automation, set `ZERGCYBERDECK_TOKEN` to an independently
+issued scoped token. `ZERGCYBERDECK_BASE_URL` changes the server, and
+`ZERGCYBERDECK_CONFIG_DIR` isolates the local config directory.
+
+## Common commands
+
+```bash
+# The server is authoritative for available targets and conformance support.
+zcd catalog
+
+# Create a deck and start explicitly selected clones.
+zcd up --clones zlunk,zokta --name "SDK check"
+
+# Or create every unique target from the authoritative server catalog. Clone
+# starts are admitted through one durable, bounded server operation.
+zcd up --all --name "Full connector range"
+
+zcd ls
+zcd status --deck <deck-id>
+zcd diagnose --deck <deck-id> --tail 100
+zcd check --deck <deck-id>
+zcd seed --deck <deck-id> --reset
+
+# Start and poll server-side SDK/API conformance; reports remain local.
+zcd sdk --deck <deck-id> --vendor zlunk
+
+zcd down --deck <deck-id> --yes
+```
+
+## Scenarios and templates
+
+The `scenario` command manages the same workspace-scoped, versioned definitions
+as the CyberDeck workbench. Draft updates use optimistic versions, and published
+revisions remain immutable.
+
+```bash
+# Read the runnable scenario library and one canonical YAML draft.
+zcd scenario list --json
+zcd scenario show --id <scenario-id> --json
+
+# Create, update, and publish a scenario from a local YAML document.
+zcd scenario create --file scenario.yaml --json
+zcd scenario update --id <scenario-id> --expected-version 1 --file scenario.yaml --json
+zcd scenario publish --id <scenario-id> --expected-version 2 --json
+
+# Manage reusable drill and company-template libraries through the same API.
+zcd scenario list --kind drill-template --json
+zcd scenario create --kind company-template --file company-template.yaml --json
+
+# Lifecycle-admin operations are explicit and recoverable.
+zcd scenario delete --id <scenario-id> --yes --json
+zcd scenario restore --id <scenario-id> --json
+```
+
+`zcd up` removes duplicate target IDs while preserving first-seen order. It
+preflights the selected clones and submits one idempotent fleet operation
+instead of sending an unbounded burst of individual start requests. A blocked
+control plane leaves the new deck intact for inspection and exits with code 2.
+
+`zcd sdk --clones ...` may provision the clones you name. Review the selection
+and the target CyberDeck before running it; clone environments consume compute.
+The CLI does not bundle vendor SDKs or a local conformance runner.
+
+## Automation and clone discovery
+
+Inventory commands retain their human-readable output by default and expose a
+stable, versioned form for scripts:
+
+```bash
+zcd catalog --json
+zcd ls --json
+zcd ls --deck <deck-id> --json
+zcd status --deck <deck-id> --json
+zcd diagnose --deck <deck-id> --json
+```
+
+Each JSON document has `"schemaVersion": 1`. Catalog targets may advertise a
+non-secret `managedCredential` descriptor with its purpose, authorization
+scheme/header, and display label. The purpose distinguishes vendor API tokens,
+official SDK tokens, and application-console credentials without exposing the
+credential itself. Older CyberDeck servers that omit this descriptor remain
+supported.
+
+Inspect one deployment by a unique vendor name or exact clone UUID:
+
+```bash
+zcd inspect --deck <deck-id> --clone zlunk
+zcd inspect --deck <deck-id> --clone <clone-uuid> --json
+```
+
+The inspection includes normalized runtime URLs and status, published Zerg
+module fields, artifact qualification, and the non-secret credential hint. If
+a deck contains multiple clones of the same vendor, pass a clone UUID.
+
+Export the current canonical `GET /__sim/export` snapshot from one running
+clone without handling its private simulation-control credential:
+
+```bash
+# Print a stable, schema-versioned envelope to stdout.
+zcd dump --deck <deck-id> --clone zentinel-one
+
+# Or write it to a mode-0600 JSON file.
+zcd dump --deck <deck-id> --clone <clone-uuid> --out ./zentinel-one.json
+```
+
+The response includes the clone and deck identity, capture time, source byte
+count, a canonical SHA-256 data hash, and the clone-native snapshot. The Deck
+server scopes the request to the active workspace, fences the live deployment
+generation, and never returns the runtime URL or simulation-control token.
+
+## Review-gated QA oracles
+
+An oracle set preserves the human-authored question and query separately from
+the connector parameters that Codex proposes. Proposed parameters cannot be
+executed until a reviewer approves them, and synthesized answers have a second
+review gate before the baseline can be sealed.
+
+```bash
+# The draft JSON contains one immutable scenario-run or clone-dump subject and
+# 1-100 questions. Each question carries 1-16 authored connector queries.
+zcd oracle create --deck <deck-id> --file ./oracle-draft.json --json
+
+# Codex runs in text-only mode and may only propose schema-valid parameters.
+zcd oracle materialize --deck <deck-id> --id <oracle-id> --json
+
+# Inspect the current immutable version, then submit a reviewed document with
+# optimistic concurrency. Later execution/answer events use the same command.
+zcd oracle show --deck <deck-id> --id <oracle-id> --json
+zcd oracle transition --deck <deck-id> --id <oracle-id> \
+  --expected-version 3 --event approve_parameters --file ./reviewed.json --json
+
+zcd oracle list --deck <deck-id> --json
+zcd oracle export --deck <deck-id> --id <oracle-id> --out ./oracle.json
+```
+
+The server stores every version as a content-addressed immutable object and
+keeps only its opaque object reference, byte count, content type, and SHA-256
+digest in the database. `oracle export` writes a mode-`0600` file. The exported
+artifact includes the stable oracle ID/version and public metadata but never an
+object-storage key, connector credential, or simulation-control token.
+
+Credential disclosure is a separate, explicit write-authorized POST action:
+
+```bash
+zcd credentials --deck <deck-id> --clone zlunk
+zcd credentials --deck <deck-id> --clone zentinel-one
+zcd credentials --deck <deck-id> --clone <clone-uuid> --json
+```
+
+Successful credential output contains a secret and should not be logged.
+Credential and runtime error payloads are redacted from stderr so a malformed
+or failed server response cannot echo a token through CLI diagnostics.
+
+## Fleet diagnostics and recovery
+
+`status` and `diagnose` use the observational diagnostics API. Reading them
+does not register routes, update clone rows, or otherwise reconcile runtime
+state. Every clone receives an ordered result envelope even when an upstream
+provider is unavailable.
+
+```bash
+# Inspect the entire deck or one clone. Vendor names must be unique in a deck;
+# an exact clone UUID is always unambiguous.
+zcd diagnose --deck <deck-id>
+zcd diagnose --deck <deck-id> --clone zlunk --tail 200 --json
+
+# Read logs without revealing clone credentials.
+zcd logs --deck <deck-id> --clone zlunk --tail 200
+zcd logs --deck <deck-id> --clone <clone-uuid> \
+  --since 2026-07-27T19:00:00.000Z --json
+
+# Check admission separately, or start all/failed/one clone.
+zcd preflight --deck <deck-id> --all
+zcd start --deck <deck-id> --failed --wait --json
+zcd start --deck <deck-id> --clone zlunk
+
+# Recovery actions are bounded and return a result for every selected clone.
+zcd stop --deck <deck-id> --all --json
+zcd reset --deck <deck-id> --clone zlunk
+zcd restart-runtime --deck <deck-id> --failed --wait
+```
+
+`restart-runtime` performs a controlled stop, waits for the observational
+status to become stopped, and then submits a new durable start operation.
+
+Fleet operation history is available independently of the current clone
+projection:
+
+```bash
+zcd operations --deck <deck-id> --limit 20
+zcd operation --deck <deck-id> --run <run-id> --json
+zcd operation --deck <deck-id> --run <run-id> --retry-failed --wait
+```
+
+CLI exit codes are stable for automation:
+
+- `0`: the command completed without clone failures.
+- `1`: one or more clone actions or operation items failed.
+- `2`: platform readiness blocked admission; no start operation was created.
+
+Run `zcd <command> --help` for all options.
+
+## Licensing
+
+This package is source-available, not open source. Purpose-limited evaluation
+and the specified personal, educational, research, and nonprofit uses are
+available under the
+[Zerg Source Available License 1.0](./LICENSE.md). Commercial production,
+commercial development, for-profit internal use, managed services,
+governmental operational use, and competing general-purpose platforms require
+a separate signed license. See
+[commercial licensing](./COMMERCIAL-LICENSING.md) or contact
+licensing@zergai.com.
+
+Third-party software remains under its own terms; see
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+# Scenario execution and evidence
+
+Use the same run API as the web workbench. A custom scenario must be published;
+the server binds the run to its immutable revision and rechecks clone readiness.
+
+```sh
+zcd scenario run --deck <deck-id> --scenario <catalog-or-definition-id> --json
+zcd scenario run --deck <deck-id> --scenario <id> --capture-evidence --reset-targets --seed repro-1 --json
+zcd scenario runs --deck <deck-id> --json
+zcd scenario run-show --deck <deck-id> --run <run-id> --json
+zcd scenario run-control --deck <deck-id> --run <run-id> --action pause --json
+```
+
+Simulation-only is the default. **`--reset-targets` authorizes clearing existing
+data on all running scenario targets**; capture will refuse without it. Server
+preflight checks storage and compatible deployments before reset. The launch
+response is provisioning, not execution success or evidence readiness. Keep its
+exact run ID/URL; inspect `run-show` for execution, artifact status, expiry, and
+authorized download URLs. Evaluator access remains enforced by the server.
+Control commands request a state change; inspect the run to confirm it happened.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-Party Notices for zerg-cyberdeck
+
+`zerg-cyberdeck` uses the following direct runtime dependencies. They are not
+licensed under the Zerg Source Available License 1.0 and remain governed by
+their own terms and copyright notices.
+
+| Component | Requested version | License | Project |
+| --- | --- | --- | --- |
+| Commander.js (`commander`) | `^12.1.0` | MIT | <https://github.com/tj/commander.js> |
+| Socket.IO client (`socket.io-client`) | `^4.8.1` | MIT | <https://github.com/socketio/socket.io> |
+
+The dependency installation may include transitive packages. Their package
+distributions contain the authoritative notices and license texts for those
+components. Nothing in this file changes any third-party license.

package/dist/automation.js

@@ -0,0 +1,161 @@
+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;
+export function normalizeCatalogForJson(catalog) {
+    return {
+        schemaVersion: 1,
+        targets: catalog.targets.map(target => ({
+            ...target,
+            managedCredential: target.managedCredential ?? null,
+        })),
+    };
+}
+export function deckSummary(deck) {
+    return {
+        id: deck.id,
+        name: deck.name,
+        slug: deck.slug,
+        status: deck.status ?? null,
+    };
+}
+export function cloneSummary(clone) {
+    return {
+        id: clone.id,
+        vendor: clone.vendor,
+        name: clone.name,
+        status: clone.status,
+        zergId: clone.zerg_id,
+        serviceUrl: clone.service_url,
+        deckRouteSlug: clone.deck_route_slug,
+    };
+}
+export function resolveCloneSelector(deck, selector) {
+    const value = selector.trim();
+    const clones = deck.clones ?? [];
+    if (!value) {
+        throw new Error('--clone must name a vendor or clone UUID.');
+    }
+    if (CLONE_UUID.test(value)) {
+        const exact = clones.find(clone => clone.id.toLowerCase() === value.toLowerCase());
+        if (exact)
+            return exact;
+        throw new Error(`Clone UUID '${value}' was not found in deck ${deck.id}.`);
+    }
+    const vendor = value.toLowerCase();
+    const matches = clones.filter(clone => clone.vendor.toLowerCase() === vendor);
+    if (matches.length === 0) {
+        throw new Error(`Clone selector '${value}' did not match a clone in deck ${deck.id}. `
+            + `Run \`zcd ls --deck ${deck.id}\` to list clone UUIDs.`);
+    }
+    if (matches.length > 1) {
+        const ids = matches.map(clone => clone.id).join(', ');
+        throw new Error(`Clone vendor '${vendor}' is ambiguous in deck ${deck.id}. `
+            + `Matching clone IDs: ${ids}. Pass a clone UUID.`);
+    }
+    return matches[0];
+}
+export function catalogTarget(catalog, vendor) {
+    return catalog.targets.find(target => target.id === vendor);
+}
+export function explicitlyUnsupportedCredential(target) {
+    return (target !== undefined
+        && Object.hasOwn(target, 'managedCredential')
+        && target.managedCredential === null);
+}
+const PUBLISHED_CREDENTIAL_FIELDS = new Set([
+    'connector_credential_label',
+    'connector_credential_header',
+    'connector_credential_scheme',
+    'connector_credential',
+]);
+export function publishedCredentialFromRuntime(vendor, runtime) {
+    const candidates = [];
+    for (const module of runtime.publishedModules ?? []) {
+        const credentialFields = module.fields.filter(field => (PUBLISHED_CREDENTIAL_FIELDS.has(field.name)));
+        if (credentialFields.length !== PUBLISHED_CREDENTIAL_FIELDS.size
+            || new Set(credentialFields.map(field => field.name)).size
+                !== PUBLISHED_CREDENTIAL_FIELDS.size)
+            continue;
+        const fields = new Map(credentialFields.map(field => [field.name, field]));
+        const label = publishedString(fields.get('connector_credential_label'), 'text', 256);
+        const header = publishedString(fields.get('connector_credential_header'), 'text', 128);
+        const scheme = publishedScheme(fields.get('connector_credential_scheme'));
+        const token = publishedString(fields.get('connector_credential'), 'code', 2_048);
+        if (!label || !header || scheme === null || !token)
+            continue;
+        if (!/^[A-Za-z0-9-]+$/.test(header)
+            || (scheme !== ''
+                && !/^[A-Za-z][A-Za-z0-9._~-]*$/.test(scheme))
+            || (scheme === '' && header.toLowerCase() === 'authorization'))
+            continue;
+        candidates.push({
+            label,
+            credential: {
+                schemaVersion: 1,
+                vendor,
+                authentication: {
+                    type: 'token',
+                    scheme,
+                    header,
+                    token,
+                },
+            },
+        });
+    }
+    return candidates.length === 1 ? candidates[0] : null;
+}
+function publishedScheme(field) {
+    if (!field
+        || !field.available
+        || field.kind !== 'text'
+        || typeof field.value !== 'string')
+        return null;
+    const value = field.value;
+    return (value === value.trim()
+        && value.length <= 64
+        && !/[\u0000-\u001f\u007f]/u.test(value)) ? value : null;
+}
+function publishedString(field, kind, maxLength) {
+    if (!field
+        || !field.available
+        || field.kind !== kind
+        || typeof field.value !== 'string')
+        return '';
+    const value = field.value;
+    return (value === value.trim()
+        && value
+        && value.length <= maxLength
+        && !/[\u0000-\u001f\u007f]/u.test(value)) ? value : '';
+}
+function optionalRuntimeValue(value, fallback) {
+    return value === undefined ? fallback : value;
+}
+export function inspectClone(deck, clone, runtime, target) {
+    return {
+        schemaVersion: 1,
+        deck: deckSummary(deck),
+        clone: cloneSummary(clone),
+        managedCredential: target?.managedCredential ?? null,
+        runtime: {
+            provisioned: runtime.provisioned ?? clone.zerg_id !== null,
+            zergId: optionalRuntimeValue(runtime.zergId, clone.zerg_id),
+            status: runtime.status ?? clone.status,
+            cloneStatus: runtime.cloneStatus ?? clone.status,
+            deployPhase: runtime.deployPhase ?? null,
+            serviceUrl: optionalRuntimeValue(runtime.serviceUrl, clone.service_url),
+            socketUrl: runtime.socketUrl ?? null,
+            mirrorUrl: runtime.mirrorUrl ?? null,
+            errorMessage: runtime.errorMessage ?? null,
+            zergCloudUrl: runtime.zergCloudUrl ?? null,
+            zstackRunUrl: runtime.zstackRunUrl ?? null,
+            flyAppName: runtime.flyAppName ?? null,
+            flyAppUrl: runtime.flyAppUrl ?? null,
+            updatedAt: runtime.updatedAt ?? null,
+        },
+        publications: {
+            status: runtime.publicationStatus ?? 'none',
+            error: runtime.publicationError ?? null,
+            modules: runtime.publishedModules ?? [],
+        },
+        qualification: runtime.qualification ?? null,
+    };
+}
+//# sourceMappingURL=automation.js.map