@shardflux/cli 0.1.0 → 0.3.0

package/dist/args.js

@@ -10,11 +10,13 @@
  */
 import { parseArgs } from 'node:util';
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.1.0';
+export const CLI_VERSION = '0.3.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
     'agent-label': { type: 'string', value: '<label>', description: 'Attribution label for workspace tool tokens (default $SHARDFLUX_AGENT_LABEL, else "cli").' },
+    wake: { type: 'boolean', description: 'Resume a suspended workspace when exec/files/changes use it (default; --no-wake or SHARDFLUX_NO_WAKE=1 fails with workspace_not_running instead).' },
+    'wake-timeout': { type: 'string', value: '<ms>', description: 'Longest wait in milliseconds for the workspace to wake or finish a transition (default $SHARDFLUX_WAKE_TIMEOUT_MS, else 120000); then exit 5.' },
     help: { type: 'boolean', short: 'h', description: 'Show help.' },
     version: { type: 'boolean', short: 'V', description: 'Print the version.' },
 };
@@ -23,11 +25,56 @@ const CAPS = {
     'memory-mib': { type: 'string', value: '<n>', description: 'Memory cap in MiB.' },
     'disk-gib': { type: 'string', value: '<n>', description: 'Disk cap in GiB.' },
 };
+/** `--timing` (0.3.0+): the SDK's lifecycle timing of the command's open, wait or wake (README "Timing"). */
+const TIMING = {
+    timing: {
+        type: 'boolean',
+        description: 'Print where the time went on stderr after the call, also when it fails: client phases, the operation’s server timing, retries (with --json: a "timing" field instead).',
+    },
+};
+/** `--timing` of the commands that can wake a suspended workspace: the wake's timing, when there was one. */
+const WAKE_TIMING = {
+    timing: { type: 'boolean', description: 'Print where the time went when the command had to wake the workspace (stderr; with --json a "timing" field, null without a wake).' },
+};
 const WAIT = {
     wait: { type: 'boolean', description: 'Wait until the operation finishes.' },
     timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side.' },
+    ...TIMING,
 };
 const REF = { name: 'id|key', required: true };
+const SLUG = { name: 'slug', required: true };
+const PAGE = {
+    all: { type: 'boolean', description: 'Fetch every page.' },
+    limit: { type: 'string', value: '<n>', description: 'Page size.' },
+    cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
+};
+/** Options of a version produced by save-as-template or a draft publish (contracts §19.8). */
+const SAVE = {
+    description: { type: 'string', value: '<text>', description: 'Version description (default: the source version’s).' },
+    'default-lifetime': { type: 'string', value: '<persistent|session>', description: 'Default lifetime of workspaces opened from the new version.' },
+    'default-idle-timeout': { type: 'string', value: '<duration>', description: 'Idle timeout of its session workspaces (60s-24h; default: the platform’s 10m).' },
+    acknowledge: { type: 'string', multiple: true, value: '<path>', description: 'Absolute path the credential scan may report without failing the build (repeatable, up to 200).' },
+    'auto-publish': { type: 'boolean', description: 'Publish the version once registered (default; --no-auto-publish leaves it for an owner/admin).' },
+    wait: { type: 'boolean', description: 'Wait until the build is published and registered (or fails).' },
+    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 30m). The build continues server side.' },
+};
+const LIFETIME_FILTER = {
+    lifetime: { type: 'string', value: '<persistent|session|any>', description: 'Lifetime filter (default persistent: sessions are hidden).' },
+    purpose: { type: 'string', value: '<standard|template_draft|template_test|any>', description: 'Purpose filter (default standard: template drafts and test instances are hidden).' },
+};
+const SECRET_REF = { name: 'id|name', required: true };
+const SECRET_SCOPE = {
+    org: { type: 'string', value: '<organization-id>', description: 'Organization-wide secrets of this organization (owners/admins; project API keys get 403). Default: the API key’s project.' },
+};
+const SECRET_VALUE = {
+    'from-file': { type: 'string', value: '<file>', description: 'Read the value from this file. Default: standard input (pipe it in). One trailing newline is removed. Values are never accepted as arguments.' },
+};
+const SECRET_PERMISSIONS = {
+    tool: { type: 'string', multiple: true, value: '<tool>', description: 'Tool that receives the value at session start (repeatable; exec, pty, files, process, git, browser). Default exec and pty.' },
+    'allow-workspace': { type: 'string', multiple: true, value: '<workspace-id>', description: 'Only these workspaces may use it (repeatable). Default: any workspace of the allowed projects.' },
+    'allow-project': { type: 'string', multiple: true, value: '<project-id>', description: 'Organization secrets: projects whose workspaces may use it (repeatable). Default: none until granted.' },
+    'all-projects': { type: 'boolean', description: 'Organization secrets: every project of the organization may use it.' },
+};
 export const COMMANDS = [
     {
         path: ['login'],
@@ -51,11 +98,29 @@ export const COMMANDS = [
         positionals: [{ name: 'key', required: true }],
         options: {
             template: { type: 'string', value: '<slug>', description: 'Template slug (required), e.g. python-node-browser.' },
+            secret: {
+                type: 'string',
+                multiple: true,
+                value: '<NAME>',
+                description: 'Bind this secret name (repeatable): injected as an environment variable into every exec and terminal. Replaces the binding of an existing workspace; omit to leave it unchanged.',
+            },
+            lifetime: {
+                type: 'string',
+                value: '<persistent|session>',
+                description: 'session: the workspace is discarded when the session ends ("shard ws close" or the idle timeout) and the key then opens a new one. Default: the template’s default, else persistent.',
+            },
             ...CAPS,
             wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
             timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m). The start continues server side.' },
+            ...TIMING,
         },
-        examples: ['shard workspaces open acme/demo --template python-node-browser', 'shard ws open acme/demo --template python-node-browser --no-wait --json'],
+        examples: [
+            'shard workspaces open acme/demo --template python-node-browser',
+            'shard ws open job-42 --template python-node-browser --lifetime session',
+            'shard ws open acme/demo --template python-node-browser --secret OPENAI_API_KEY --secret DATABASE_URL',
+            'shard ws open acme/demo --template python-node-browser --no-wait --json',
+            'shard ws open acme/demo --template python-node-browser --timing',
+        ],
     },
     {
         path: ['workspaces', 'list'],
@@ -64,7 +129,8 @@ export const COMMANDS = [
         options: {
             state: { type: 'string', value: '<state>', description: 'Observed state filter (running, suspended, creating, ...).' },
             prefix: { type: 'string', value: '<key-prefix>', description: 'Only keys starting with this prefix.' },
-            'include-deleted': { type: 'boolean', description: 'Include deleted workspaces (tombstones).' },
+            ...LIFETIME_FILTER,
+            'include-deleted': { type: 'boolean', description: 'Include deleted workspaces and ended sessions (tombstones).' },
             all: { type: 'boolean', description: 'Fetch every page.' },
             limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
             cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
@@ -81,6 +147,7 @@ export const COMMANDS = [
             env: { type: 'string', multiple: true, value: '<K=V>', description: 'Environment variable (repeatable).' },
             timeout: { type: 'string', value: '<duration>', description: 'Kill the command after this long (exit code 124).' },
             stdin: { type: 'string', value: '<file|->', description: 'Send this file (or - for standard input) to the command’s stdin (max 1 MiB).' },
+            ...WAKE_TIMING,
         },
         examples: ['shard ws exec acme/demo -- python3 -V', 'shard ws exec acme/demo --cwd /home/user/app --env CI=1 -- bash -lc "npm test"'],
     },
@@ -98,12 +165,64 @@ export const COMMANDS = [
         positionals: [REF],
         options: { yes: { type: 'boolean', description: 'Required: confirm the deletion.' }, ...WAIT },
     },
+    {
+        path: ['workspaces', 'close'],
+        summary: 'End a session workspace now (it is deleted; the key then opens a new workspace)',
+        description: 'Sessions only: a persistent workspace is refused with conflict (not_session); suspend or delete it instead. Repeating returns the same delete operation.',
+        positionals: [REF],
+        options: { ...WAIT },
+    },
+    {
+        path: ['workspaces', 'reset'],
+        summary: 'Wipe every change in a layered workspace and restart it on its template',
+        description: 'Keeps the key, id, template version, caps, secret bindings and volume attachments; processes are gone. A suspended workspace stays suspended and boots blank on its next resume. The previous state stays restorable for 7 days (the operation result names the recovery checkpoint).',
+        positionals: [REF],
+        options: { yes: { type: 'boolean', description: 'Required: confirm that every change is wiped.' }, ...WAIT },
+    },
+    {
+        path: ['workspaces', 'save-as-template'],
+        summary: 'Save a layered workspace as the next version of an organization template',
+        description: 'Everything in the workspace becomes template content (minus the sf-scrub.v1 list: machine identity, histories, credentials, .env files, caches), stored as one new layer on the workspace’s template. A running workspace is captured briefly and keeps running.',
+        positionals: [REF],
+        options: {
+            template: { type: 'string', value: '<slug>', description: 'Organization template to save into (required; created when absent).' },
+            'display-name': { type: 'string', value: '<name>', description: 'Template name when this save creates the template.' },
+            checkpoint: { type: 'string', value: '<checkpoint-id>', description: 'Save this committed checkpoint of the workspace instead of its current state.' },
+            ...SAVE,
+        },
+        examples: ['shard ws save-as-template acme/demo --template acme-dev --description "node 22 + repo deps" --wait'],
+    },
+    {
+        path: ['workspaces', 'changes'],
+        summary: 'List what a layered workspace changed against its template',
+        description: 'Served by the cell gateway from the running workspace (needs the files tool). added, modified, metadata (with --hash), deleted, replaced (opaque directory).',
+        positionals: [REF],
+        options: {
+            path: { type: 'string', value: '<prefix>', description: 'Only entries at or below this absolute path (default /).' },
+            hash: { type: 'boolean', description: 'Hash regular files up to 16 MiB (reports metadata-only changes).' },
+            summary: { type: 'boolean', description: 'Also print totals over everything under --path.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-1000 (default 1000).' },
+            ...WAKE_TIMING,
+        },
+    },
     { path: ['workspaces', 'sessions'], summary: 'List the attributed agent sessions (tool-token principals and labels) of a workspace', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'secrets'],
+        summary: 'Show (or replace) the secret names bound to a workspace',
+        description: 'Bound secrets are injected as environment variables into every exec and terminal of the workspace. Status: available, not_allowed (starts are refused until the secret’s permissions allow this workspace) or deleted. Values are never shown.',
+        positionals: [REF],
+        options: {
+            set: { type: 'string', multiple: true, value: '<NAME>', description: 'Replace the binding with these names (repeatable).' },
+            clear: { type: 'boolean', description: 'Remove every bound name.' },
+        },
+        examples: ['shard ws secrets acme/demo', 'shard ws secrets acme/demo --set OPENAI_API_KEY --set DATABASE_URL', 'shard ws secrets acme/demo --clear'],
+    },
     {
         path: ['files', 'read'],
         summary: 'Print (or save) a file from a workspace',
         positionals: [REF, { name: 'path', required: true }],
-        options: { out: { type: 'string', value: '<file>', description: 'Write to this local file instead of stdout.' } },
+        options: { out: { type: 'string', value: '<file>', description: 'Write to this local file instead of stdout.' }, ...WAKE_TIMING },
     },
     {
         path: ['files', 'write'],
@@ -113,13 +232,14 @@ export const COMMANDS = [
             from: { type: 'string', value: '<file|->', description: 'Local file to upload, or - for standard input (default -).' },
             append: { type: 'boolean', description: 'Append instead of replacing.' },
             parents: { type: 'boolean', description: 'Create missing parent directories (default; --no-parents to refuse).' },
+            ...WAKE_TIMING,
         },
     },
     {
         path: ['files', 'ls'],
         summary: 'List a directory in a workspace',
         positionals: [REF, { name: 'path', required: true }],
-        options: { limit: { type: 'string', value: '<n>', description: 'Maximum entries (default 1000).' } },
+        options: { limit: { type: 'string', value: '<n>', description: 'Maximum entries (default 1000).' }, ...WAKE_TIMING },
     },
     {
         path: ['operations', 'list'],
@@ -132,19 +252,177 @@ export const COMMANDS = [
         },
     },
     { path: ['operations', 'get'], summary: 'Show one operation', positionals: [{ name: 'operation-id', required: true }], options: {} },
+    {
+        path: ['secrets', 'create'],
+        summary: 'Create a secret; the value is read from standard input or --from-file, never from arguments',
+        description: 'Project secret of the API key’s project by default, or an organization-wide secret with --org. The value (UTF-8 text, up to 64 KiB) is encrypted and never shown again. Bind it to workspaces with "shard ws open --secret NAME" or "shard ws secrets <ws> --set NAME".',
+        positionals: [{ name: 'name', required: true }],
+        options: { ...SECRET_SCOPE, ...SECRET_VALUE, description: { type: 'string', value: '<text>', description: 'Description (up to 500 characters).' }, ...SECRET_PERMISSIONS },
+        examples: ['printf %s "$OPENAI_API_KEY" | shard secrets create OPENAI_API_KEY', 'shard secrets create DATABASE_URL --from-file ./database-url.txt --description "Staging database"'],
+    },
+    {
+        path: ['secrets', 'list'],
+        summary: 'List secrets (metadata only; never values)',
+        positionals: [],
+        options: {
+            ...SECRET_SCOPE,
+            'include-deleted': { type: 'boolean', description: 'Include deleted secrets.' },
+            all: { type: 'boolean', description: 'Fetch every page.' },
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+            cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
+        },
+    },
+    { path: ['secrets', 'get'], summary: 'Show one secret’s metadata (never the value)', positionals: [SECRET_REF], options: { ...SECRET_SCOPE } },
+    {
+        path: ['secrets', 'update'],
+        summary: 'Change a secret’s description or usage permissions (applies from the next session start)',
+        positionals: [SECRET_REF],
+        options: {
+            ...SECRET_SCOPE,
+            description: { type: 'string', value: '<text>', description: 'New description.' },
+            ...SECRET_PERMISSIONS,
+            'any-workspace': { type: 'boolean', description: 'Remove the workspace restriction (any workspace of the allowed projects).' },
+            'clear-projects': { type: 'boolean', description: 'Organization secrets: no project may use it (until granted again).' },
+        },
+    },
+    {
+        path: ['secrets', 'rotate'],
+        summary: 'Store a new value as the next version (standard input or --from-file); older values are erased',
+        positionals: [SECRET_REF],
+        options: { ...SECRET_SCOPE, ...SECRET_VALUE },
+        examples: ['printf %s "$NEW_TOKEN" | shard secrets rotate API_TOKEN'],
+    },
+    {
+        path: ['secrets', 'versions'],
+        summary: 'List a secret’s versions, newest first (metadata only)',
+        positionals: [SECRET_REF],
+        options: { ...SECRET_SCOPE, limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' } },
+    },
+    {
+        path: ['secrets', 'delete'],
+        summary: 'Delete a secret: its values are erased and it is removed from every workspace binding',
+        positionals: [SECRET_REF],
+        options: { ...SECRET_SCOPE, yes: { type: 'boolean', description: 'Required: confirm the deletion.' } },
+    },
+    {
+        path: ['secrets', 'access-log'],
+        summary: 'Show which sessions resolved a secret (owners/admins; project API keys get 403)',
+        positionals: [SECRET_REF],
+        options: {
+            ...SECRET_SCOPE,
+            outcome: { type: 'string', value: '<outcome>', description: 'granted, denied or failed.' },
+            workspace: { type: 'string', value: '<workspace-id>', description: 'Only this workspace.' },
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+        },
+    },
+    {
+        path: ['templates', 'list'],
+        summary: 'List the templates this project can open (platform and organization)',
+        positionals: [],
+        options: {
+            owner: { type: 'string', value: '<platform|organization>', description: 'Only platform or only organization templates.' },
+            'include-archived': { type: 'boolean', description: 'Include archived templates.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+        },
+    },
+    {
+        path: ['templates', 'files'],
+        summary: 'List one directory of a template version’s file tree (or show one entry with --stat)',
+        description: 'Needs a version with a file list (versions from before file lists answer conflict file_list_unavailable). File contents are not served: open a draft or test instance for that.',
+        positionals: [SLUG, { name: 'version', required: true }, { name: 'path' }],
+        options: {
+            stat: { type: 'boolean', description: 'Show the entry at <path> itself instead of listing it.' },
+            owner: { type: 'string', value: '<platform|organization>', description: 'Pick the platform template even when an organization template shadows its slug.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-1000 (default 200).' },
+        },
+        examples: ['shard templates files python-node-browser 5 /usr/local/bin', 'shard templates files acme-dev 3 /etc/hostname --stat'],
+    },
+    {
+        path: ['templates', 'diff'],
+        summary: 'Diff two versions of a template (added, removed, changed, type_changed, metadata)',
+        positionals: [SLUG],
+        options: {
+            from: { type: 'string', value: '<version|base>', description: 'Older version, or "base" (the --to version’s build base). Required.' },
+            to: { type: 'string', value: '<version>', description: 'Newer version (required).' },
+            prefix: { type: 'string', value: '<path>', description: 'Only paths starting with this absolute prefix.' },
+            change: { type: 'string', value: '<kind>', description: 'Only added, removed, changed, type_changed or metadata.' },
+            owner: { type: 'string', value: '<platform|organization>', description: 'Pick the platform template even when an organization template shadows its slug.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-1000 (default 200).' },
+        },
+        examples: ['shard templates diff acme-dev --from 2 --to 3', 'shard templates diff acme-dev --from base --to 3 --prefix /home/user'],
+    },
+    {
+        path: ['templates', 'draft', 'open'],
+        summary: 'Open the draft of an organization template (a layered workspace to edit live)',
+        description: 'One live draft per template. Edit it with "shard ws exec|files ... <draft key>", capture states, open test instances, then publish it as the next version.',
+        positionals: [SLUG],
+        options: {
+            base: { type: 'string', value: '<slug@version>', description: 'Version to start from (default: the template’s latest published version; required for a new template).' },
+            ...CAPS,
+            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m).' },
+            ...TIMING,
+        },
+        examples: ['shard templates draft open acme-dev --base python-node-browser@5'],
+    },
+    { path: ['templates', 'draft', 'status'], summary: 'Show a template’s draft: workspace, base version, states and live test instances', positionals: [SLUG], options: {} },
+    {
+        path: ['templates', 'draft', 'state'],
+        summary: 'Capture a state of the running draft (or list its states with --list)',
+        positionals: [SLUG],
+        options: {
+            label: { type: 'string', value: '<text>', description: 'Label of the captured state.' },
+            list: { type: 'boolean', description: 'List the draft’s states instead of capturing one.' },
+            ...WAIT,
+        },
+    },
+    {
+        path: ['templates', 'draft', 'test'],
+        summary: 'Open a test instance of a draft state (a disposable session workspace), or list them with --list',
+        description: 'Its writes never reach the draft. It ends with "shard ws close <key>", when idle, or when the draft is discarded.',
+        positionals: [SLUG],
+        options: {
+            state: { type: 'string', value: '<state-id>', description: 'Draft state to test (default: a fresh capture of the running draft).' },
+            'instance-key': { type: 'string', value: '<key>', description: 'Workspace key of the test instance (default sf:test:<slug>:<random>).' },
+            list: { type: 'boolean', description: 'List the draft’s test instances instead of opening one.' },
+            'include-ended': { type: 'boolean', description: 'With --list: include ended test instances.' },
+            ...CAPS,
+            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m).' },
+            ...TIMING,
+        },
+    },
+    {
+        path: ['templates', 'draft', 'publish'],
+        summary: 'Publish the draft as the template’s next version',
+        description: 'Refused (conflict draft_stale) when the template got a version from elsewhere since the draft was opened. The draft stays open afterwards.',
+        positionals: [SLUG],
+        options: { state: { type: 'string', value: '<state-id>', description: 'State to publish (default: the draft’s current state).' }, ...SAVE },
+    },
+    {
+        path: ['templates', 'draft', 'discard'],
+        summary: 'Discard the draft (it is deleted and its live test instances end)',
+        positionals: [SLUG],
+        options: { yes: { type: 'boolean', description: 'Required: confirm the discard.' }, ...WAIT },
+    },
     {
         path: ['operations', 'wait'],
         summary: 'Wait for an operation to finish (exit 0 succeeded, 6 failed/canceled, 5 timeout)',
         positionals: [{ name: 'operation-id', required: true }],
-        options: { timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' } },
+        options: { timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' }, ...TIMING },
     },
 ];
 const GROUPS = {
     workspaces: 'Open, inspect and manage workspaces',
     files: 'Read, write and list files in a workspace',
     operations: 'Inspect and wait for lifecycle operations',
+    secrets: 'Manage secrets (values are write-only) and bind them to workspaces',
+    templates: 'Browse templates (file tree, diff) and develop organization templates in a draft',
 };
-const ALIASES = { ws: 'workspaces', workspace: 'workspaces', ops: 'operations', operation: 'operations', file: 'files' };
+const ALIASES = { ws: 'workspaces', workspace: 'workspaces', ops: 'operations', operation: 'operations', file: 'files', secret: 'secrets', template: 'templates' };
 /** Canonical command words: aliases resolved, `workspaces files|operations` folded to the top-level group. */
 export function normalizeWords(words) {
     const w = words.map((x) => ALIASES[x] ?? x);
@@ -202,6 +480,8 @@ export function parseEnvPairs(pairs) {
     return out;
 }
 export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Secret names (environment-variable safe; the API's SECRET_NAME_PATTERN). */
+export const SECRET_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
 const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
 /** Validates the API base URL: https, or http only to a loopback address (the key is a bearer credential). */
 export function resolveApiUrl(flag, env) {
@@ -220,8 +500,37 @@ export function resolveApiUrl(flag, env) {
         throw new UsageError('API URL must not contain credentials, a query or a fragment');
     return u.toString().replace(/\/+$/, '');
 }
-const FORBIDDEN_KEY_FLAG = /^--?(api-?key|apikey|key|token|secret)(=.*)?$/i;
-const GLOBAL_VALUE_FLAGS = new Set(['--api-url', '--agent-label']);
+export const DEFAULT_WAKE_TIMEOUT_MS = 120_000;
+const MAX_WAKE_TIMEOUT_MS = 7 * 24 * 3600 * 1000;
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+const FALSY = new Set(['', '0', 'false', 'no', 'off']);
+/** Wake on use: --wake / --no-wake, else SHARDFLUX_NO_WAKE (1/true/yes/on disables), else on. */
+export function resolveWake(flag, noWakeEnv) {
+    if (flag !== undefined)
+        return flag;
+    const v = (noWakeEnv ?? '').trim().toLowerCase();
+    if (TRUTHY.has(v))
+        return false;
+    if (FALSY.has(v))
+        return true;
+    throw new UsageError(`SHARDFLUX_NO_WAKE must be 1 (or true) to turn wake on use off, or 0/empty (got "${noWakeEnv}")`);
+}
+/** The wake/transition budget per call in ms: --wake-timeout, else SHARDFLUX_WAKE_TIMEOUT_MS, else 120000. */
+export function resolveWakeTimeout(flag, env) {
+    if (flag !== undefined)
+        return parsePositiveInt(flag, 'wake-timeout', MAX_WAKE_TIMEOUT_MS);
+    const v = env?.trim();
+    if (!v)
+        return DEFAULT_WAKE_TIMEOUT_MS;
+    if (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > MAX_WAKE_TIMEOUT_MS) {
+        throw new UsageError(`SHARDFLUX_WAKE_TIMEOUT_MS must be an integer number of milliseconds between 1 and ${MAX_WAKE_TIMEOUT_MS} (got "${env}")`);
+    }
+    return Number(v);
+}
+const FORBIDDEN_KEY_FLAG = /^--?(api-?key|apikey|key|token|secret|value|secret-value|password)(=.*)?$/i;
+/** `--secret NAME` binds a secret by name on `workspaces open`; anything else shaped like --secret is refused. */
+const SECRET_NAME_FLAG = /^--secret(?:=(.*))?$/;
+const GLOBAL_VALUE_FLAGS = new Set(['--api-url', '--agent-label', '--wake-timeout']);
 function toParseArgsOptions(opts) {
     const out = {};
     for (const [name, o] of Object.entries(opts))
@@ -235,10 +544,30 @@ function toParseArgsOptions(opts) {
 export function parseCommandLine(argv) {
     const terminator = argv.indexOf('--');
     const head = terminator < 0 ? argv : argv.slice(0, terminator);
-    for (const a of head) {
-        if (FORBIDDEN_KEY_FLAG.test(a)) {
-            throw new UsageError('shard reads the API key only from the SHARDFLUX_API_KEY environment variable; never pass it on the command line (shell history and process listings would expose it)');
+    const leading = [];
+    for (let i = 0; i < head.length && leading.length < 2; i += 1) {
+        const a = head[i];
+        if (!a.startsWith('-'))
+            leading.push(a);
+        else if (GLOBAL_VALUE_FLAGS.has(a))
+            i += 1;
+    }
+    const opensWorkspace = key(normalizeWords(leading)) === 'workspaces open';
+    for (let i = 0; i < head.length; i += 1) {
+        const a = head[i];
+        if (!FORBIDDEN_KEY_FLAG.test(a))
+            continue;
+        const named = SECRET_NAME_FLAG.exec(a);
+        if (named && opensWorkspace) {
+            const name = named[1] ?? head[i + 1];
+            if (name !== undefined && SECRET_NAME.test(name))
+                continue;
+            throw new UsageError('--secret takes a secret NAME (^[A-Z_][A-Z0-9_]*$) to bind, never a value; create the secret with "shard secrets create NAME" (value on standard input)');
+        }
+        if (/^--?(value|secret-value|password)(=.*)?$/i.test(a)) {
+            throw new UsageError('shard never accepts secret values on the command line (shell history and process listings would expose them); pipe the value on standard input or use --from-file');
         }
+        throw new UsageError('shard reads the API key only from the SHARDFLUX_API_KEY environment variable; never pass it on the command line (shell history and process listings would expose it)');
     }
     // Pick the command words (the leading non-option words that form a known command path).
     const words = [];
@@ -323,6 +652,8 @@ export function parseCommandLine(argv) {
             apiUrl: typeof values['api-url'] === 'string' ? values['api-url'] : undefined,
             json: values.json === true,
             agentLabel: typeof values['agent-label'] === 'string' ? values['agent-label'] : undefined,
+            wake: typeof values.wake === 'boolean' ? values.wake : undefined,
+            wakeTimeout: typeof values['wake-timeout'] === 'string' ? values['wake-timeout'] : undefined,
         },
     };
 }
@@ -380,9 +711,11 @@ export function topHelp() {
         ...optionLines(GLOBAL_OPTIONS),
         '',
         'Environment:',
-        '  SHARDFLUX_API_KEY      project API key (sfk_...), required; never pass it as an argument',
-        '  SHARDFLUX_API_URL      API base URL (default https://api.shardflux.dev)',
-        '  SHARDFLUX_AGENT_LABEL  attribution label for tool tokens (default cli)',
+        '  SHARDFLUX_API_KEY          project API key (sfk_...), required; never pass it as an argument',
+        '  SHARDFLUX_API_URL          API base URL (default https://api.shardflux.dev)',
+        '  SHARDFLUX_AGENT_LABEL      attribution label for tool tokens (default cli)',
+        '  SHARDFLUX_NO_WAKE          1: do not resume a suspended workspace on use (same as --no-wake)',
+        '  SHARDFLUX_WAKE_TIMEOUT_MS  longest wait in ms for a workspace to wake or finish a transition (default 120000; --wake-timeout overrides)',
         '',
         'Exit codes:',
         ...EXIT_CODE_HELP,

package/dist/commands.d.ts

@@ -1,5 +1,6 @@
 import type { RunResult, Shardflux, Workspace } from '@shardflux/sdk';
 import type { Values } from './args.js';
+import type { TimingRecorder } from './timing.js';
 export interface Writer {
     write(chunk: string | Uint8Array): boolean;
 }
@@ -16,11 +17,23 @@ export interface Ctx {
     json: boolean;
     apiUrl: string;
     agentLabel: string;
+    /** Wake a suspended workspace on use (--no-wake / SHARDFLUX_NO_WAKE=1 turn it off). */
+    wake: boolean;
+    /** Bound on lifecycle waits per cell call, wakes included (--wake-timeout / SHARDFLUX_WAKE_TIMEOUT_MS). */
+    wakeTimeoutMs: number;
     signal: AbortSignal;
+    /** --timing: print the SDK's timing of the command's open, wait or wake (stderr; a `timing` field with --json). */
+    timing: boolean;
+    /** Timings and the last observed operation of the traced SDK calls this command made (the client's onProgress). */
+    traces: TimingRecorder;
     cloud(): Shardflux;
 }
 export type Handler = (ctx: Ctx, values: Values, positionals: string[]) => Promise<number>;
-/** `<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 declare function resolveWorkspace(ctx: Ctx, ref: string): Promise<Workspace>;
 /** The exit code `shard exec` returns for a finished command. */
 export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'>): number;