@shardflux/cli 0.1.0 → 0.3.0

package/dist/commands.js

@@ -7,15 +7,38 @@
 import { randomUUID } from 'node:crypto';
 import { readFile, writeFile } from 'node:fs/promises';
 import { SDK_VERSION, ShardfluxApiError } from '@shardflux/sdk';
-import { CLI_VERSION, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
+import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { InterruptedError, NotFoundError, UsageError } from "./errors.js";
-import { fileTable, json, kv, operationDetail, operationTable, sessionTable, usageText, workspaceDetail, workspaceTable } from "./format.js";
+import { timingJson } from "./timing.js";
+import { bindingsText, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, fileTable, json, kv, operationDetail, operationTable, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, templateEntryText, templateFileTable, templateTable, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
 const str = (v) => (typeof v === 'string' ? v : undefined);
+/**
+ * The workspace's cell client as this invocation configures it: the CLI's agent label, wake on use unless turned off,
+ * and the wake timeout (an OperationTimeoutError past it exits 5).
+ */
+const cellOf = (ctx, ws) => ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs, ...(ctx.wake ? {} : { wake: null }) });
+const strs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []);
+const MAX_SECRET_VALUE_BYTES = 65_536;
+const TOOLS = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
+function secretNames(names, option) {
+    for (const n of names)
+        if (!SECRET_NAME.test(n))
+            throw new UsageError(`${option} expects a secret name like OPENAI_API_KEY (^[A-Z_][A-Z0-9_]*$), got "${n}"`);
+    if (new Set(names).size !== names.length)
+        throw new UsageError(`${option} names a secret twice`);
+    return [...names];
+}
+/** With --json --timing the JSON gains a `timing` field (null when the command made no traced lifecycle call). */
+function withTiming(ctx, machine) {
+    if (!ctx.timing || typeof machine !== 'object' || machine === null || Array.isArray(machine))
+        return machine;
+    return { ...machine, timing: timingJson(ctx.traces.last) };
+}
 function out(ctx, human, machine) {
-    ctx.io.stdout.write(ctx.json ? json(machine) : human);
+    ctx.io.stdout.write(ctx.json ? json(withTiming(ctx, machine)) : human);
 }
 function caps(values) {
     const c = {};
@@ -34,7 +57,11 @@ function waitTimeout(values) {
     const t = str(values.timeout);
     return t === undefined ? DEFAULT_WAIT_MS : parseDuration(t, 'timeout');
 }
-/** `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key. */
+/**
+ * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
+ * lifetime and purpose (sessions, drafts and test instances are hidden from the default list), preferring the live
+ * workspace over tombstones of ended sessions that had the same key (contracts §19.11).
+ */
 export async function resolveWorkspace(ctx, ref) {
     const cloud = ctx.cloud();
     if (UUID.test(ref)) {
@@ -46,14 +73,87 @@ export async function resolveWorkspace(ctx, ref) {
                 throw err;
         }
     }
-    for await (const w of cloud.workspaces.listAll({ keyPrefix: ref, includeDeleted: true, limit: 200 })) {
-        if (w.key === ref)
-            return w;
+    let found;
+    try {
+        found = await cloud.workspaces.findByKey(ref, { signal: ctx.signal });
+    }
+    catch (err) {
         if (ctx.signal.aborted)
             throw new InterruptedError('interrupted');
+        throw err;
     }
+    if (found)
+        return found;
     throw new NotFoundError(`No workspace with id or key "${ref}" in this project.`);
 }
+const LIFETIMES = ['persistent', 'session'];
+const LIFETIME_FILTERS = ['persistent', 'session', 'any'];
+const PURPOSE_FILTERS = ['standard', 'template_draft', 'template_test', 'any'];
+const DIFF_CHANGES = ['added', 'removed', 'changed', 'type_changed', 'metadata'];
+const OWNERS = ['platform', 'organization'];
+const DEFAULT_BUILD_WAIT_MS = 1_800_000;
+function oneOf(values, option, allowed) {
+    const v = str(values[option]);
+    if (v === undefined)
+        return undefined;
+    if (!allowed.includes(v))
+        throw new UsageError(`--${option} must be one of ${allowed.join(', ')} (got "${v}")`);
+    return v;
+}
+function listLimit(values, max) {
+    const t = str(values.limit);
+    return t === undefined ? undefined : parsePositiveInt(t, 'limit', max);
+}
+/** `--default-lifetime` / `--default-idle-timeout` as the new version's `defaults` (undefined when neither is given). */
+function saveDefaults(values) {
+    const lifetime = oneOf(values, 'default-lifetime', LIFETIMES);
+    const idle = str(values['default-idle-timeout']);
+    if (lifetime === undefined && idle === undefined)
+        return undefined;
+    const d = {};
+    if (lifetime !== undefined)
+        d.lifetime = lifetime;
+    if (idle !== undefined) {
+        const seconds = Math.round(parseDuration(idle, 'default-idle-timeout') / 1000);
+        if (seconds < 60 || seconds > 86_400)
+            throw new UsageError('--default-idle-timeout must be between 60s and 24h');
+        d.idle_timeout_seconds = seconds;
+    }
+    return d;
+}
+function acknowledged(values) {
+    const paths = strs(values.acknowledge);
+    for (const p of paths)
+        if (!p.startsWith('/'))
+            throw new UsageError(`--acknowledge expects an absolute path, got "${p}"`);
+    if (paths.length > 200)
+        throw new UsageError('--acknowledge takes at most 200 paths');
+    return paths.length ? paths : undefined;
+}
+/** Prints a save-as-template / draft publish result; `--wait` follows the build until it settles. */
+async function reportSave(ctx, values, res, what) {
+    let build = res.build;
+    if (values.wait === true) {
+        const t = str(values.timeout);
+        const timeoutMs = t === undefined ? DEFAULT_BUILD_WAIT_MS : parseDuration(t, 'timeout');
+        try {
+            build = await ctx.cloud().templates.builds.waitForBuild(build.organization_id, build.id, { timeoutMs, signal: ctx.signal });
+        }
+        catch (err) {
+            if (ctx.signal.aborted)
+                throw new InterruptedError(`Interrupted; build ${build.id} continues server side.`);
+            throw err;
+        }
+    }
+    const capture = res.operation ? `capture: operation ${res.operation.id} ${res.operation.kind} ${res.operation.state}\n` : '';
+    out(ctx, `${what}\n${capture}${buildText(build)}`, { operation: res.operation, build });
+    return build.state === 'failed' || build.state === 'canceled' || build.registration.state === 'failed' ? 6 : 0;
+}
+function parseVersion(text, what) {
+    if (!/^\d+$/.test(text) || Number(text) < 1)
+        throw new UsageError(`${what} must be a version number (got "${text}")`);
+    return Number(text);
+}
 /** Waits with the SDK's backoff; Ctrl-C reports the operation that keeps running. */
 async function waitOperation(ctx, operationId, timeoutMs) {
     try {
@@ -65,6 +165,21 @@ async function waitOperation(ctx, operationId, timeoutMs) {
         throw err;
     }
 }
+/**
+ * Runs an SDK call that waits itself (a waited open or lifecycle call). Ctrl-C reports the operation it was waiting
+ * for, as the SDK observed it; a held open interrupted before the server answered has none yet (`unnamed`).
+ */
+async function waited(ctx, unnamed, call) {
+    try {
+        return await call();
+    }
+    catch (err) {
+        if (!ctx.signal.aborted)
+            throw err;
+        const id = ctx.traces.operationId;
+        throw id ? new InterruptedError(`Interrupted; operation ${id} continues server side.`, id) : new InterruptedError(`Interrupted; ${unnamed}`);
+    }
+}
 async function getOperation(ctx, operationId) {
     if (!UUID.test(operationId))
         throw new UsageError(`<operation-id> must be a UUID (got "${operationId}")`);
@@ -162,14 +277,22 @@ export const HANDLERS = {
         if (!template)
             throw new UsageError('--template <slug> is required for "shard workspaces open"');
         const c = caps(values);
+        const bind = secretNames(strs(values.secret), '--secret');
+        const lifetime = oneOf(values, 'lifetime', LIFETIMES);
         const timeoutMs = waitTimeout(values);
         const cloud = ctx.cloud();
-        let ws = await cloud.workspaces.open({ key: key, template, ...(c ? { caps: c } : {}), agentLabel: ctx.agentLabel, wait: false });
+        // The SDK's waited open: the server holds the request until the workspace is ready (Prefer: wait), then the SDK
+        // polls for what is left of --timeout; one trace (ws.lastTiming) covers all of it.
+        const ws = await waited(ctx, 'the open continues server side (open the key again to keep waiting).', () => cloud.workspaces.open({
+            key: key,
+            template,
+            ...(c ? { caps: c } : {}),
+            ...(bind.length ? { secrets: bind } : {}),
+            ...(lifetime ? { lifetime } : {}),
+            agentLabel: ctx.agentLabel,
+            wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
+        }));
         const op = ws.activeOperation;
-        if (values.wait !== false && !ws.ready && op) {
-            await waitOperation(ctx, op.id, timeoutMs);
-            ws = await cloud.workspaces.get(ws.id);
-        }
         const view = ws.data;
         const human = ws.ready
             ? `Workspace ${ws.key} (${ws.id}) is ready.\n${workspaceDetail(view)}`
@@ -182,9 +305,13 @@ export const HANDLERS = {
         const state = str(values.state);
         const prefix = str(values.prefix);
         const limitText = str(values.limit);
+        const lifetime = oneOf(values, 'lifetime', LIFETIME_FILTERS);
+        const purpose = oneOf(values, 'purpose', PURPOSE_FILTERS);
         const params = {
             ...(state ? { state: state } : {}),
             ...(prefix ? { keyPrefix: prefix } : {}),
+            ...(lifetime ? { lifetime } : {}),
+            ...(purpose ? { purpose } : {}),
             ...(values['include-deleted'] === true ? { includeDeleted: true } : {}),
             ...(limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {}),
         };
@@ -220,7 +347,7 @@ export const HANDLERS = {
         const stdinSource = str(values.stdin);
         const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
         const ws = await resolveWorkspace(ctx, ref);
-        const cell = ws.cell({ agentLabel: ctx.agentLabel });
+        const cell = cellOf(ctx, ws);
         const sessionId = `cli-${randomUUID().replace(/-/g, '').slice(0, 24)}`;
         let r;
         try {
@@ -244,20 +371,20 @@ export const HANDLERS = {
         }
         const code = execExitCode(r);
         if (ctx.json) {
-            ctx.io.stdout.write(json({ session_id: r.sessionId, exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, canceled: r.canceled, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, reconnects: r.reconnects }));
+            ctx.io.stdout.write(json(withTiming(ctx, { session_id: r.sessionId, exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, canceled: r.canceled, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, reconnects: r.reconnects })));
         }
         return code;
     },
     async 'files read'(ctx, values, [ref, path]) {
         const ws = await resolveWorkspace(ctx, ref);
-        const bytes = await ws.cell({ agentLabel: ctx.agentLabel }).files.read(path);
+        const bytes = await cellOf(ctx, ws).files.read(path);
         const dest = str(values.out);
         if (dest !== undefined) {
             await writeFile(dest, bytes);
             out(ctx, `wrote ${bytes.length} bytes to ${dest}\n`, { path, bytes: bytes.length, out: dest });
         }
         else if (ctx.json) {
-            ctx.io.stdout.write(json({ path, bytes: bytes.length, content_base64: Buffer.from(bytes).toString('base64') }));
+            ctx.io.stdout.write(json(withTiming(ctx, { path, bytes: bytes.length, content_base64: Buffer.from(bytes).toString('base64') })));
         }
         else {
             ctx.io.stdout.write(bytes);
@@ -267,36 +394,290 @@ export const HANDLERS = {
     async 'files write'(ctx, values, [ref, path]) {
         const data = await readInput(ctx, str(values.from) ?? '-', 1024 * 1024 * 1024, 'input');
         const ws = await resolveWorkspace(ctx, ref);
-        const r = await ws.cell({ agentLabel: ctx.agentLabel }).files.write(path, data, { append: values.append === true, createParents: values.parents !== false });
+        const r = await cellOf(ctx, ws).files.write(path, data, { append: values.append === true, createParents: values.parents !== false });
         out(ctx, `wrote ${r.bytes_written} bytes to ${r.path}${r.sha256 ? ` (sha256 ${r.sha256})` : ''}\n`, r);
         return 0;
     },
     async 'files ls'(ctx, values, [ref, path]) {
         const limitText = str(values.limit);
         const ws = await resolveWorkspace(ctx, ref);
-        const list = await ws.cell({ agentLabel: ctx.agentLabel }).files.list(path, { limit: limitText ? parsePositiveInt(limitText, 'limit', 10_000) : 1000 });
+        const list = await cellOf(ctx, ws).files.list(path, { limit: limitText ? parsePositiveInt(limitText, 'limit', 10_000) : 1000 });
         out(ctx, `${fileTable(list)}${list.truncated ? '(truncated)\n' : ''}`, list);
         return 0;
     },
     async 'workspaces suspend'(ctx, values, [ref]) {
-        return lifecycle(ctx, values, ref, 'Suspending', (ws) => ctx.cloud().workspaces.suspend(ws.id));
+        return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, o));
     },
     async 'workspaces resume'(ctx, values, [ref]) {
-        return lifecycle(ctx, values, ref, 'Resuming', (ws) => ctx.cloud().workspaces.resume(ws.id));
+        return lifecycle(ctx, values, ref, 'Resuming', (ws, o) => ctx.cloud().workspaces.resume(ws.id, o));
     },
     async 'workspaces delete'(ctx, values, [ref]) {
         if (values.yes !== true)
             throw new UsageError('refusing to delete without --yes (deletion revokes tool access immediately and cannot be undone)');
-        return lifecycle(ctx, values, ref, 'Deleting', (ws) => ctx.cloud().workspaces.delete(ws.id));
+        return lifecycle(ctx, values, ref, 'Deleting', (ws, o) => ctx.cloud().workspaces.delete(ws.id, o));
+    },
+    async 'workspaces close'(ctx, values, [ref]) {
+        return lifecycle(ctx, values, ref, 'Closing', (ws, o) => ctx.cloud().workspaces.close(ws.id, o));
+    },
+    async 'workspaces reset'(ctx, values, [ref]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to reset without --yes (reset wipes every change in the workspace and restarts it on its template)');
+        return lifecycle(ctx, values, ref, 'Resetting', (ws, o) => ctx.cloud().workspaces.reset(ws.id, o));
+    },
+    async 'workspaces save-as-template'(ctx, values, [ref]) {
+        const template = str(values.template);
+        if (!template)
+            throw new UsageError('--template <slug> is required for "shard workspaces save-as-template"');
+        const checkpoint = str(values.checkpoint);
+        if (checkpoint !== undefined && !UUID.test(checkpoint))
+            throw new UsageError('--checkpoint must be a checkpoint id (UUID)');
+        const defaults = saveDefaults(values);
+        const ack = acknowledged(values);
+        const ws = await resolveWorkspace(ctx, ref);
+        const res = await ctx.cloud().workspaces.saveAsTemplate(ws.id, {
+            templateSlug: template,
+            ...(str(values['display-name']) !== undefined ? { displayName: str(values['display-name']) } : {}),
+            ...(str(values.description) !== undefined ? { description: str(values.description) } : {}),
+            ...(defaults ? { defaults } : {}),
+            ...(checkpoint ? { checkpointId: checkpoint } : {}),
+            ...(values['auto-publish'] === false ? { autoPublish: false } : {}),
+            ...(ack ? { acknowledgedScanFindings: ack } : {}),
+        });
+        return reportSave(ctx, values, res, `Saving ${ws.key} (${ws.id}) as ${template} v${res.build.target_version ?? '?'}.`);
+    },
+    async 'workspaces changes'(ctx, values, [ref]) {
+        const path = str(values.path);
+        if (path !== undefined && !path.startsWith('/'))
+            throw new UsageError('--path must be an absolute path');
+        const limit = listLimit(values, 1000);
+        const ws = await resolveWorkspace(ctx, ref);
+        const cell = cellOf(ctx, ws);
+        const base = { ...(path ? { pathPrefix: path } : {}), ...(values.hash === true ? { hash: true } : {}), ...(limit ? { limit } : {}) };
+        let rows = [];
+        let next = null;
+        let summary;
+        if (values.all === true) {
+            let cursor;
+            do {
+                const page = await cell.changes({ ...base, ...(cursor ? { cursor } : {}), ...(cursor === undefined && values.summary === true ? { summary: true } : {}) });
+                if (page.summary)
+                    summary = page.summary;
+                rows.push(...page.data);
+                cursor = page.next_cursor ?? undefined;
+                if (ctx.signal.aborted)
+                    throw new InterruptedError('Interrupted.');
+            } while (cursor);
+        }
+        else {
+            const cursor = str(values.cursor);
+            const page = await cell.changes({ ...base, ...(cursor ? { cursor } : {}), ...(values.summary === true ? { summary: true } : {}) });
+            rows = page.data;
+            next = page.next_cursor;
+            summary = page.summary;
+        }
+        const s = summary;
+        const head = s ? `added ${s.added}, modified ${s.modified}, deleted ${s.deleted}, replaced ${s.replaced} (${s.bytes} bytes)\n` : '';
+        out(ctx, `${head}${rows.length ? changesTable(rows) : 'No changes against the template.\n'}`, { data: rows, next_cursor: next, ...(summary ? { summary } : {}) });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard workspaces changes ${ref} --cursor ${next}\n`);
+        return 0;
+    },
+    async 'templates list'(ctx, values) {
+        const owner = oneOf(values, 'owner', OWNERS);
+        const limit = listLimit(values, 200);
+        const params = { ...(owner ? { owner } : {}), ...(values['include-archived'] === true ? { includeArchived: true } : {}) };
+        const templates = ctx.cloud().templates;
+        let rows = [];
+        let next = null;
+        if (values.all === true) {
+            for await (const t of templates.listAll(params))
+                rows.push(t);
+        }
+        else {
+            const cursor = str(values.cursor);
+            const page = await templates.list({ ...params, ...(limit ? { limit } : {}), ...(cursor ? { cursor } : {}) });
+            rows = page.data;
+            next = page.nextCursor;
+        }
+        out(ctx, rows.length ? templateTable(rows) : 'No templates.\n', { data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard templates list --cursor ${next}\n`);
+        return 0;
+    },
+    async 'templates files'(ctx, values, [slug, versionText, path]) {
+        const version = parseVersion(versionText, '<version>');
+        const owner = oneOf(values, 'owner', OWNERS);
+        const templates = ctx.cloud().templates;
+        const dir = path ?? '/';
+        if (values.stat === true) {
+            const entry = await templates.fileEntry(slug, version, dir, owner ? { owner } : {});
+            out(ctx, templateEntryText(entry), entry);
+            return 0;
+        }
+        const limit = listLimit(values, 1000);
+        let rows = [];
+        let next = null;
+        if (values.all === true) {
+            for await (const e of templates.filesAll(slug, version, { path: dir, ...(owner ? { owner } : {}), ...(limit ? { limit } : {}) })) {
+                rows.push(e);
+                if (ctx.signal.aborted)
+                    throw new InterruptedError('Interrupted.');
+            }
+        }
+        else {
+            const cursor = str(values.cursor);
+            const page = await templates.files(slug, version, { path: dir, ...(owner ? { owner } : {}), ...(limit ? { limit } : {}), ...(cursor ? { cursor } : {}) });
+            rows = page.data;
+            next = page.next_cursor;
+        }
+        out(ctx, rows.length ? templateFileTable(rows) : `${dir} is empty.\n`, { path: dir, data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard templates files ${slug} ${version} ${dir} --cursor ${next}\n`);
+        return 0;
+    },
+    async 'templates diff'(ctx, values, [slug]) {
+        const fromText = str(values.from);
+        const toText = str(values.to);
+        if (fromText === undefined || toText === undefined)
+            throw new UsageError('--from <version|base> and --to <version> are required for "shard templates diff"');
+        const from = fromText === 'base' ? 'base' : parseVersion(fromText, '--from');
+        const to = parseVersion(toText, '--to');
+        const change = oneOf(values, 'change', DIFF_CHANGES);
+        const owner = oneOf(values, 'owner', OWNERS);
+        const prefix = str(values.prefix);
+        if (prefix !== undefined && !prefix.startsWith('/'))
+            throw new UsageError('--prefix must be an absolute path');
+        const limit = listLimit(values, 1000);
+        const base = { from, to, ...(prefix ? { pathPrefix: prefix } : {}), ...(change ? { change } : {}), ...(owner ? { owner } : {}), ...(limit ? { limit } : {}) };
+        const templates = ctx.cloud().templates;
+        let rows = [];
+        let next = null;
+        let summary = null;
+        if (values.all === true) {
+            let cursor;
+            do {
+                const page = await templates.diff(slug, { ...base, ...(cursor ? { cursor } : {}) });
+                if (page.summary)
+                    summary = page.summary;
+                rows.push(...page.data);
+                cursor = page.next_cursor ?? undefined;
+                if (ctx.signal.aborted)
+                    throw new InterruptedError('Interrupted.');
+            } while (cursor);
+        }
+        else {
+            const cursor = str(values.cursor);
+            const page = await templates.diff(slug, { ...base, ...(cursor ? { cursor } : {}) });
+            rows = page.data;
+            next = page.next_cursor;
+            summary = page.summary;
+        }
+        out(ctx, `${diffSummaryText(summary)}${rows.length ? diffTable(rows) : 'No differences.\n'}`, { data: rows, next_cursor: next, summary });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard templates diff ${slug} --from ${fromText} --to ${toText} --cursor ${next}\n`);
+        return 0;
+    },
+    async 'templates draft open'(ctx, values, [slug]) {
+        const c = caps(values);
+        const timeoutMs = waitTimeout(values);
+        const base = str(values.base);
+        const cloud = ctx.cloud();
+        const opened = await cloud.templates.draft(slug).create({ ...(base ? { base } : {}), ...(c ? { caps: c } : {}), agentLabel: ctx.agentLabel, wait: false });
+        let ws = opened.workspace;
+        const op = opened.operation;
+        if (values.wait !== false && !ws.ready && op) {
+            await waitOperation(ctx, op.id, timeoutMs);
+            ws = await cloud.workspaces.get(ws.id);
+        }
+        const human = ws.ready
+            ? `Draft of ${slug} is ready: workspace ${ws.key} (${ws.id}) on ${opened.draft.base_version.slug} v${opened.draft.base_version.version}.\nedit it with: shard ws exec ${ws.key} -- <command>\n`
+            : `Draft of ${slug}: workspace ${ws.key} (${ws.id}) is ${ws.state}${op ? `; operation ${op.id} ${op.kind} ${op.state}` : ''}.\n${op ? `wait with: shard operations wait ${op.id}\n` : ''}`;
+        out(ctx, human, { draft: { ...opened.draft, workspace: ws.data }, operation: op });
+        return 0;
+    },
+    async 'templates draft status'(ctx, _values, [slug]) {
+        const draft = await ctx.cloud().templates.draft(slug).get();
+        out(ctx, draftText(draft), draft);
+        return 0;
+    },
+    async 'templates draft state'(ctx, values, [slug]) {
+        const draft = ctx.cloud().templates.draft(slug);
+        if (values.list === true) {
+            const states = [];
+            for await (const st of draft.statesAll({ limit: 200 }))
+                states.push(st);
+            out(ctx, states.length ? draftStateTable(states) : 'No states captured yet.\n', { data: states });
+            return 0;
+        }
+        const label = str(values.label);
+        let op = await draft.captureState(label === undefined ? {} : { label });
+        if (values.wait === true)
+            op = await waitOperation(ctx, op.id, waitTimeout(values));
+        const checkpoint = typeof op.result?.checkpoint_id === 'string' ? `state ${op.result.checkpoint_id}\n` : '';
+        out(ctx, `Capturing a state of the ${slug} draft: operation ${op.id} ${op.kind} ${op.state}\n${checkpoint}${op.state === 'succeeded' ? '' : `wait with: shard operations wait ${op.id}\n`}`, op);
+        return 0;
+    },
+    async 'templates draft test'(ctx, values, [slug]) {
+        const draft = ctx.cloud().templates.draft(slug);
+        if (values.list === true) {
+            const views = [];
+            let cursor;
+            do {
+                const page = await draft.testInstances({ limit: 200, ...(values['include-ended'] === true ? { includeEnded: true } : {}), ...(cursor ? { cursor } : {}) });
+                views.push(...page.data.map((w) => w.data));
+                cursor = page.nextCursor ?? undefined;
+            } while (cursor);
+            out(ctx, views.length ? workspaceTable(views) : 'No test instances.\n', { data: views });
+            return 0;
+        }
+        const state = str(values.state);
+        if (state !== undefined && !UUID.test(state))
+            throw new UsageError('--state must be a draft state id (UUID)');
+        const c = caps(values);
+        const timeoutMs = waitTimeout(values);
+        const instanceKey = str(values['instance-key']);
+        let ws = await draft.openTestInstance({ ...(state ? { stateId: state } : {}), ...(instanceKey ? { key: instanceKey } : {}), ...(c ? { caps: c } : {}), agentLabel: ctx.agentLabel, wait: false });
+        const op = ws.activeOperation;
+        if (values.wait !== false && !ws.ready && op) {
+            await waitOperation(ctx, op.id, timeoutMs);
+            ws = await ctx.cloud().workspaces.get(ws.id);
+        }
+        const human = ws.ready
+            ? `Test instance ${ws.key} (${ws.id}) is ready. It ends with: shard ws close ${ws.key}\n`
+            : `Test instance ${ws.key} (${ws.id}) is ${ws.state}${op ? `; operation ${op.id} ${op.kind} ${op.state}` : ''}.\n${op ? `wait with: shard operations wait ${op.id}\n` : ''}`;
+        out(ctx, human, ws.data);
+        return 0;
+    },
+    async 'templates draft publish'(ctx, values, [slug]) {
+        const state = str(values.state);
+        if (state !== undefined && !UUID.test(state))
+            throw new UsageError('--state must be a draft state id (UUID)');
+        const defaults = saveDefaults(values);
+        const ack = acknowledged(values);
+        const res = await ctx.cloud().templates.draft(slug).publish({
+            ...(state ? { stateId: state } : {}),
+            ...(str(values.description) !== undefined ? { description: str(values.description) } : {}),
+            ...(defaults ? { defaults } : {}),
+            ...(values['auto-publish'] === false ? { autoPublish: false } : {}),
+            ...(ack ? { acknowledgedScanFindings: ack } : {}),
+        });
+        return reportSave(ctx, values, res, `Publishing the ${slug} draft as v${res.build.target_version ?? '?'}.`);
+    },
+    async 'templates draft discard'(ctx, values, [slug]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to discard without --yes (the draft is deleted and its live test instances end)');
+        let op = await ctx.cloud().templates.draft(slug).discard();
+        if (values.wait === true)
+            op = await waitOperation(ctx, op.id, waitTimeout(values));
+        out(ctx, `Discarding the ${slug} draft: operation ${op.id} ${op.kind} ${op.state}\n`, op);
+        return 0;
     },
     async 'workspaces fork'(ctx, values, [ref, newKey]) {
         const c = caps(values);
         const timeoutMs = waitTimeout(values);
         const source = await resolveWorkspace(ctx, ref);
-        const res = await ctx.cloud().workspaces.fork(source.id, { key: newKey, ...(c ? { caps: c } : {}) });
-        let op = res.operation;
-        if (values.wait === true)
-            op = await waitOperation(ctx, op.id, timeoutMs);
+        const res = await waited(ctx, 'the fork continues server side.', () => ctx.cloud().workspaces.fork(source.id, { key: newKey, ...(c ? { caps: c } : {}) }, lifecycleOptions(ctx, values, timeoutMs)));
+        const op = res.operation;
         out(ctx, lifecycleText(`Forking ${source.key} into`, res.workspace, op), { operation: op, workspace: res.workspace.data });
         return 0;
     },
@@ -312,6 +693,114 @@ export const HANDLERS = {
         out(ctx, sessions.length ? sessionTable(sessions) : 'No agent sessions (no tool token was issued for this workspace yet).\n', { data: sessions });
         return 0;
     },
+    async 'workspaces secrets'(ctx, values, [ref]) {
+        const set = secretNames(strs(values.set), '--set');
+        const clear = values.clear === true;
+        if (clear && set.length > 0)
+            throw new UsageError('use either --set NAME... or --clear, not both');
+        const ws = await resolveWorkspace(ctx, ref);
+        const b = clear || set.length > 0 ? await ws.secrets.set(clear ? [] : set) : await ws.secrets.get();
+        out(ctx, bindingsText(b), b);
+        return 0;
+    },
+    async 'secrets create'(ctx, values, [name]) {
+        if (!SECRET_NAME.test(name))
+            throw new UsageError(`<name> must be an environment variable name like OPENAI_API_KEY (^[A-Z_][A-Z0-9_]*$), got "${name}"`);
+        const scope = scopeFlag(values);
+        const perms = permissionParams(values, scope === null ? 'project' : 'organization', 'create');
+        const description = str(values.description);
+        const value = await readSecretValue(ctx, values);
+        const cloud = ctx.cloud();
+        const base = { name: name, value, ...(description !== undefined ? { description } : {}) };
+        const s = scope === null
+            ? await cloud.secrets.create((await principal(ctx)).project_id, { ...base, ...perms })
+            : await cloud.secrets.createOrganization(scope, { ...base, ...perms });
+        out(ctx, `Created ${s.scope} secret ${s.name} (${s.id}), version ${s.current_version}. The value is stored encrypted and is never shown.\n${secretDetail(s)}`, s);
+        return 0;
+    },
+    async 'secrets list'(ctx, values) {
+        const cloud = ctx.cloud();
+        const org = scopeFlag(values);
+        const project = org === null ? (await principal(ctx)).project_id : null;
+        const limitText = str(values.limit);
+        const opts = { ...(values['include-deleted'] === true ? { includeDeleted: true } : {}), ...(limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {}) };
+        const page = (cursor) => (project !== null ? cloud.secrets.list(project, { ...opts, ...(cursor ? { cursor } : {}) }) : cloud.secrets.listOrganization(org, { ...opts, ...(cursor ? { cursor } : {}) }));
+        let rows = [];
+        let next = null;
+        if (values.all === true) {
+            let cursor;
+            do {
+                const p = await page(cursor);
+                rows.push(...p.data);
+                cursor = p.nextCursor ?? undefined;
+            } while (cursor);
+        }
+        else {
+            const p = await page(str(values.cursor));
+            rows = p.data;
+            next = p.nextCursor;
+        }
+        out(ctx, rows.length ? secretTable(rows) : 'No secrets.\n', { data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard secrets list${org ? ` --org ${org}` : ''} --cursor ${next}\n`);
+        return 0;
+    },
+    async 'secrets get'(ctx, values, [ref]) {
+        const s = await resolveSecret(ctx, values, ref);
+        out(ctx, secretDetail(s), s);
+        return 0;
+    },
+    async 'secrets update'(ctx, values, [ref]) {
+        const s = await resolveSecret(ctx, values, ref);
+        const params = { ...permissionParams(values, s.scope, 'update') };
+        const description = str(values.description);
+        if (description !== undefined)
+            params.description = description;
+        if (Object.keys(params).length === 0)
+            throw new UsageError('nothing to update: pass --description, --tool, --allow-workspace, --any-workspace, --allow-project, --all-projects or --clear-projects');
+        const updated = await ctx.cloud().secrets.update(s.id, params);
+        out(ctx, `Updated ${updated.name}; applies from the next session start.\n${secretDetail(updated)}`, updated);
+        return 0;
+    },
+    async 'secrets rotate'(ctx, values, [ref]) {
+        const value = await readSecretValue(ctx, values);
+        const s = await resolveSecret(ctx, values, ref);
+        const r = await ctx.cloud().secrets.rotate(s.id, value);
+        out(ctx, `Rotated ${r.secret.name} to version ${r.version.version}; older values were erased. Processes that already read the old value keep it.\n`, r);
+        return 0;
+    },
+    async 'secrets versions'(ctx, values, [ref]) {
+        const s = await resolveSecret(ctx, values, ref);
+        const limitText = str(values.limit);
+        const page = await ctx.cloud().secrets.versions(s.id, limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {});
+        out(ctx, secretVersionTable(page.data), { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    },
+    async 'secrets delete'(ctx, values, [ref]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to delete without --yes (the values are erased and the name is removed from every workspace binding)');
+        const s = await resolveSecret(ctx, values, ref);
+        await ctx.cloud().secrets.delete(s.id);
+        out(ctx, `Deleted ${s.scope} secret ${s.name} (${s.id}): its values were erased and it was removed from every workspace binding.\n`, { deleted: true, id: s.id, name: s.name, scope: s.scope });
+        return 0;
+    },
+    async 'secrets access-log'(ctx, values, [ref]) {
+        const outcome = str(values.outcome);
+        if (outcome !== undefined && !['granted', 'denied', 'failed'].includes(outcome))
+            throw new UsageError('--outcome must be granted, denied or failed');
+        const workspace = str(values.workspace);
+        if (workspace !== undefined && !UUID.test(workspace))
+            throw new UsageError('--workspace must be a workspace id (UUID)');
+        const limitText = str(values.limit);
+        const s = await resolveSecret(ctx, values, ref);
+        const page = await ctx.cloud().secrets.accessEvents(s.id, {
+            ...(outcome ? { outcome: outcome } : {}),
+            ...(workspace ? { workspaceId: workspace } : {}),
+            ...(limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {}),
+        });
+        out(ctx, page.data.length ? secretAccessTable(page.data) : 'No session has resolved this secret yet.\n', { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    },
     async 'operations list'(ctx, values, [ref]) {
         const ws = await resolveWorkspace(ctx, ref);
         const limitText = str(values.limit);
@@ -338,12 +827,117 @@ export const HANDLERS = {
         return 0;
     },
 };
+/** `--org <id>`: organization scope; null: the API key's project. */
+function scopeFlag(values) {
+    const org = str(values.org);
+    if (org === undefined)
+        return null;
+    if (!UUID.test(org))
+        throw new UsageError('--org must be an organization id (UUID)');
+    return org;
+}
+/** Usage permissions from the flags (create: defaults left to the API; update: only what was passed). */
+function permissionParams(values, scope, mode) {
+    const out = {};
+    const tools = strs(values.tool);
+    for (const t of tools)
+        if (!TOOLS.includes(t))
+            throw new UsageError(`--tool must be one of ${TOOLS.join(', ')} (got "${t}")`);
+    if (tools.length)
+        out.allowedTools = [...new Set(tools)];
+    const workspaces = strs(values['allow-workspace']);
+    for (const w of workspaces)
+        if (!UUID.test(w))
+            throw new UsageError(`--allow-workspace expects a workspace id (UUID), got "${w}"`);
+    if (workspaces.length && values['any-workspace'] === true)
+        throw new UsageError('use either --allow-workspace or --any-workspace');
+    if (workspaces.length)
+        out.allowedWorkspaceIds = workspaces;
+    if (mode === 'update' && values['any-workspace'] === true)
+        out.allowedWorkspaceIds = null;
+    const projects = strs(values['allow-project']);
+    const all = values['all-projects'] === true;
+    const none = mode === 'update' && values['clear-projects'] === true;
+    if ((projects.length ? 1 : 0) + (all ? 1 : 0) + (none ? 1 : 0) > 1)
+        throw new UsageError('use only one of --allow-project, --all-projects, --clear-projects');
+    if ((projects.length || all || none) && scope === 'project')
+        throw new UsageError('--allow-project/--all-projects/--clear-projects apply to organization secrets only (--org)');
+    for (const p of projects)
+        if (!UUID.test(p))
+            throw new UsageError(`--allow-project expects a project id (UUID), got "${p}"`);
+    if (projects.length)
+        out.allowedProjectIds = projects;
+    if (all)
+        out.allowedProjectIds = null;
+    if (none)
+        out.allowedProjectIds = [];
+    return out;
+}
+/**
+ * The secret value from --from-file or standard input (never from arguments): UTF-8 text, one trailing
+ * newline removed, 1..65536 bytes. Never echoed.
+ */
+async function readSecretValue(ctx, values) {
+    const file = str(values['from-file']);
+    const bytes = await readInput(ctx, file ?? '-', MAX_SECRET_VALUE_BYTES + 2, file === undefined ? 'secret value (standard input)' : '--from-file');
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new UsageError('the secret value must be UTF-8 text');
+    }
+    finally {
+        bytes.fill(0);
+    }
+    if (text.endsWith('\r\n'))
+        text = text.slice(0, -2);
+    else if (text.endsWith('\n'))
+        text = text.slice(0, -1);
+    if (text.length === 0)
+        throw new UsageError('the secret value is empty: pipe it on standard input or pass --from-file <file>');
+    if (Buffer.byteLength(text, 'utf8') > MAX_SECRET_VALUE_BYTES)
+        throw new UsageError(`the secret value exceeds ${MAX_SECRET_VALUE_BYTES} bytes`);
+    if (text.includes('\u0000'))
+        throw new UsageError('the secret value must not contain NUL characters');
+    return text;
+}
+/** `<id|name>`: a UUID is tried as an id first; otherwise the live secret of that name in the scope (project, or --org). */
+async function resolveSecret(ctx, values, ref) {
+    const cloud = ctx.cloud();
+    if (UUID.test(ref)) {
+        try {
+            return await cloud.secrets.get(ref);
+        }
+        catch (err) {
+            if (!(err instanceof ShardfluxApiError && err.status === 404))
+                throw err;
+        }
+    }
+    const org = scopeFlag(values);
+    if (!SECRET_NAME.test(ref))
+        throw new NotFoundError(`No secret with id or name "${ref}".`);
+    const project = org === null ? (await principal(ctx)).project_id : null;
+    let cursor;
+    do {
+        const page = project !== null ? await cloud.secrets.list(project, { limit: 200, ...(cursor ? { cursor } : {}) }) : await cloud.secrets.listOrganization(org, { limit: 200, ...(cursor ? { cursor } : {}) });
+        const hit = page.data.find((s) => s.name === ref && s.deleted_at === null);
+        if (hit)
+            return hit;
+        cursor = page.nextCursor ?? undefined;
+        if (ctx.signal.aborted)
+            throw new InterruptedError('Interrupted.');
+    } while (cursor);
+    throw new NotFoundError(project !== null ? `No secret named "${ref}" in this project (organization-wide secrets: add --org <organization-id>).` : `No organization secret named "${ref}".`);
+}
+/** `--wait`: the SDK's own wait (the call resolves once the operation finished; one trace covers request and wait). */
+function lifecycleOptions(ctx, values, timeoutMs) {
+    return values.wait === true ? { wait: { timeoutMs, signal: ctx.signal } } : {};
+}
 async function lifecycle(ctx, values, ref, verb, start) {
     const timeoutMs = waitTimeout(values);
     const ws = await resolveWorkspace(ctx, ref);
-    let op = await start(ws);
-    if (values.wait === true)
-        op = await waitOperation(ctx, op.id, timeoutMs);
+    const op = await waited(ctx, 'the operation continues server side.', () => start(ws, lifecycleOptions(ctx, values, timeoutMs)));
     out(ctx, lifecycleText(verb, ws, op), op);
     return 0;
 }