@shardflux/cli 0.9.0 → 0.11.0

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.9.0';
+export const CLI_VERSION = '0.11.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).' },
@@ -64,6 +64,13 @@ const REF = { name: 'id|key', required: true };
 /** A TCP port inside the workspace (1-65535). */
 const PORT = { name: 'port', required: true };
 const SLUG = { name: 'slug', required: true };
+/** The screenshot after a computer action or batch (0.10.0+). */
+const COMPUTER_LOOK = {
+    screenshot: { type: 'string', value: '<file>', description: 'Take a screenshot after it and write it here.' },
+    settle: { type: 'string', value: '<ms>', description: 'Wait this long before that screenshot when the screen may change (0-10000, default 250).' },
+    format: { type: 'string', value: '<png|jpeg>', description: 'Screenshot format (default png).' },
+    quality: { type: 'string', value: '<1-100>', description: 'JPEG quality (default 80).' },
+};
 const PAGE = {
     all: { type: 'boolean', description: 'Fetch every page.' },
     limit: { type: 'string', value: '<n>', description: 'Page size.' },
@@ -193,6 +200,17 @@ const KEY_COMMANDS = [
         },
         examples: ['shard usage', 'shard usage --estimate', 'shard usage --series --granularity day', 'shard usage --workspace acme/demo --meter cpu_seconds'],
     },
+    {
+        path: ['workspaces', 'retention'], summary: 'Set or clear persistent workspace idle deletion',
+        positionals: [{ name: 'key', required: true }, { name: 'policy', required: true }], options: {},
+        examples: ['shard ws retention acme/thread-42 14d', 'shard ws retention acme/thread-42 off'],
+    },
+    {
+        path: ['projects', 'retention'], summary: 'Read or set the project default idle deletion policy (project key)',
+        positionals: [{ name: 'project-id', required: true }, { name: 'policy', required: false }],
+        options: { labels: { type: 'string', value: '<json>', description: 'Exact-match label selectors.' } },
+        examples: ["shard projects retention <project-id> 14d --labels '{\"app\":\"chat\"}'"],
+    },
     {
         path: ['workspaces', 'open'],
         summary: 'Open a workspace by key (create on first use, reconnect or resume afterwards)',
@@ -201,6 +219,7 @@ const KEY_COMMANDS = [
         options: {
             template: { type: 'string', value: '<slug>', description: 'Template slug (required), e.g. python-node-browser.' },
             labels: { type: 'string', value: '<json>', description: 'Replace workspace labels with a JSON object of strings.' },
+            'delete-after-idle': { type: 'string', value: '<days>d', description: 'Delete this persistent workspace after 1..3650 idle days (e.g. 14d).' },
             'idle-policy': { type: 'string', value: '<policy>', description: 'adaptive, never or fixed:<seconds>.' },
             secret: {
                 type: 'string',
@@ -218,6 +237,11 @@ const KEY_COMMANDS = [
                 value: '<processful|file-first>',
                 description: 'file-first: the workspace is a versioned file tree with no VM between commands; each "shard ws exec" runs in a fresh VM and keeps the files it changed under /home/user as the next tree revision. Ready at once, never suspended, persistent, needs a layered template version. Default: processful for a new key, the stored mode for an existing one (a mode never changes).',
             },
+            'computer-use': {
+                type: 'string',
+                value: '<on|off|inherit>',
+                description: 'Computer use (0.10.0+): on gives the workspace a desktop agents drive (shard ws computer); inherit follows the template. Default: unchanged (off for a new key unless its template turns it on).',
+            },
             ...INPUTS,
             ...CAPS,
             ...MEMORY_ALLOCATION,
@@ -265,6 +289,11 @@ const KEY_COMMANDS = [
         description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax) and returns the session at once (JSON on stdout). Read it with "shard ws exec-read", stop it with "shard ws exec-cancel".',
         positionals: [REF, { name: 'command', required: true, variadic: true }],
         options: {
+            template: {
+                type: 'string',
+                value: '<slug>',
+                description: 'Open the key first (0.10.0+): the workspace is created from this template on first use (stderr says so) and resumed if suspended; "default" is the platform default template. Without it the key must already have a workspace.',
+            },
             'stdin-open': { type: 'boolean', description: 'Keep pipe stdin open for exec-input.' },
             'session-id': { type: 'string', value: '<id>', description: 'Caller-chosen id to deduplicate starts.' },
             cwd: { type: 'string', value: '<dir>', description: 'Absolute working directory.' },
@@ -277,6 +306,17 @@ const KEY_COMMANDS = [
         },
         examples: ['shard ws exec-start acme/demo --session-id build-1 --timeout 2h -- bash -lc "make -C /home/user/app"', 'shard ws exec-read acme/demo build-1 --follow'],
     },
+    {
+        path: ['workspaces', 'tunnel'], summary: 'Reach this machine from a workspace TCP port',
+        description: 'Runs in the foreground. The guest listener defaults to loopback; --to is dialed on this machine. Ctrl-C closes the tunnel. An open tunnel keeps the workspace awake.',
+        positionals: [REF], options: {
+            transport: { type: 'string', value: '<auto|pty|exec>', description: 'Tunnel transport (default auto).' },
+            remote: { type: 'string', value: '<port>', description: 'Required guest listener port (1..65535).' },
+            to: { type: 'string', value: '<host:port>', description: 'Required TCP target on this machine (host:port or [IPv6]:port).' },
+            bind: { type: 'string', value: '<127.0.0.1|0.0.0.0>', description: 'Guest bind address (default 127.0.0.1).' },
+        },
+        examples: ['shard ws tunnel acme/demo --remote 8081 --to localhost:8081'],
+    },
     {
         path: ['workspaces', 'exec-read'],
         summary: 'Print a background exec session’s output and state; --follow streams it until the command exits',
@@ -305,9 +345,14 @@ const KEY_COMMANDS = [
     {
         path: ['workspaces', 'exec'],
         summary: 'Run a command in a workspace; prints its output and exits with its exit code',
-        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution runs to completion: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
+        description: 'Also `shard exec` (0.10.0+). With --template the key is opened first, so one command creates the workspace on first use: `shard exec acme/demo --template default -- python3 -V`. Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution runs to completion: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
         positionals: [REF, { name: 'command', required: true, variadic: true }],
         options: {
+            template: {
+                type: 'string',
+                value: '<slug>',
+                description: 'Open the key first (0.10.0+): the workspace is created from this template on first use (stderr says so) and resumed if suspended; "default" is the platform default template. Without it the key must already have a workspace.',
+            },
             cwd: { type: 'string', value: '<dir>', description: 'Working directory, an absolute path (default /home/user; under /home/user on a file-first workspace). A relative path is refused (invalid_cwd).' },
             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).' },
@@ -365,6 +410,11 @@ const KEY_COMMANDS = [
         positionals: [REF, { name: 'new-key', required: true }],
         options: { ...CAPS, ...MEMORY_ALLOCATION, ...WAIT },
     },
+    {
+        path: ['workspaces', 'upgrade'], summary: 'Upgrade in place, keeping files and installed packages',
+        description: 'One cold start drops memory and processes. --at next-resume schedules it without stopping the VM.',
+        positionals: [REF], options: { ...WAIT, at: { type: 'string', value: '<now|next-resume>', description: 'When to cold start (default now).' } },
+    },
     {
         path: ['workspaces', 'resize'],
         summary: 'Change a workspace’s memory, CPU or disk, running or suspended, without a restart (0.9.0+)',
@@ -377,6 +427,8 @@ const KEY_COMMANDS = [
             elastic: { type: 'boolean', description: 'Switch to elastic memory: the workspace holds what its commands use and grows up to the memory size.' },
             cpu: { type: 'string', value: '<millis>', description: 'CPU in millicores (1000 = one vCPU).' },
             disk: { type: 'string', value: '<gib>', description: 'Disk in GiB (disks grow only).' },
+            'at-least': { type: 'boolean', description: 'Only grow each named resource; smaller or equal values stay unchanged.' },
+            wait: { type: 'boolean', description: 'Wait for the operation (default); --no-wait returns the held server answer.' },
             timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m); the resize continues server side.' },
             ...TIMING,
         },
@@ -471,6 +523,7 @@ const KEY_COMMANDS = [
         description: 'Opening the link starts a browser session for the port (until it expires) and lands on --path. Anyone with the link can open the port until then: share it like a password. --json prints {url, expires_at}.',
         positionals: [REF, PORT],
         options: {
+            'embed-origin': { type: 'string', multiple: true, value: '<https-origin>', description: 'Allow this HTTPS origin to embed the viewer (repeatable, 1–10 distinct origins).' },
             ttl: { type: 'string', value: '<duration>', description: 'Lifetime of the link and its browser session, 1m to 7d (default 24h).' },
             path: { type: 'string', value: '<path>', description: 'Where the link lands: a path starting with one / (query allowed; default /).' },
         },
@@ -484,6 +537,190 @@ const KEY_COMMANDS = [
         options: { revoke: { type: 'boolean', description: 'Revoke the port’s callback URL instead (idempotent).' } },
         examples: ['shard ws port callback acme/demo 3000', 'shard ws port callback acme/demo 3000 --revoke'],
     },
+    // ---- computer use (0.10.0; contracts §45) ----
+    {
+        path: ['workspaces', 'computer', 'status'],
+        summary: 'Show whether the workspace desktop runs, its size and its viewers (0.10.0+)',
+        description: 'Never starts the desktop. Needs computer use on for the workspace (shard ws computer enable). --json prints {running, display, width, height, started_at, session, streams}.',
+        positionals: [REF],
+        options: {},
+    },
+    {
+        path: ['workspaces', 'computer', 'screenshot'],
+        summary: 'Save a screenshot of the workspace desktop (0.10.0+)',
+        description: 'Starts the desktop when it does not run. Writes the image to --out (default screenshot.png, or screenshot.jpg with --format jpeg). --json prints {out, format, width, height, bytes}.',
+        positionals: [REF],
+        options: {
+            out: { type: 'string', value: '<file>', description: 'Where to write the image (default screenshot.png).' },
+            format: { type: 'string', value: '<png|jpeg>', description: 'Image format (default png).' },
+            quality: { type: 'string', value: '<1-100>', description: 'JPEG quality (default 80).' },
+        },
+        examples: ['shard ws computer screenshot acme/demo --out desktop.png', 'shard ws computer screenshot acme/demo --format jpeg --quality 60'],
+    },
+    {
+        path: ['workspaces', 'computer', 'act'],
+        summary: 'Run a batch of computer actions on the workspace desktop (0.10.0+)',
+        description: 'The actions are a JSON array of Claude computer toolset members with their parameters, e.g. [{"action":"left_click","coordinate":[640,400]},{"action":"type","text":"hello"}]; - reads it from standard input. They run in order; the first failure stops the batch and the rest are reported skipped. --screenshot saves a screenshot taken after the last action. --json prints the full result (images base64).',
+        positionals: [REF, { name: 'actions-json', required: true }],
+        options: { ...COMPUTER_LOOK },
+        examples: [
+            `shard ws computer act acme/demo '[{"action":"key","text":"ctrl+l"},{"action":"type","text":"example.com\\n"}]' --screenshot after.png`,
+            'echo \'[{"action":"cursor_position"}]\' | shard ws computer act acme/demo -',
+        ],
+    },
+    {
+        path: ['workspaces', 'computer', 'click'],
+        summary: 'Click on the workspace desktop (0.10.0+)',
+        description: 'At <x> <y> (screen pixels from the top-left of a screenshot), or at the pointer without them. --button right|middle, --count 2|3 for a double or triple click (left button), --mods holds modifier keys (e.g. shift, ctrl+shift).',
+        positionals: [REF, { name: 'x' }, { name: 'y' }],
+        options: {
+            button: { type: 'string', value: '<left|right|middle>', description: 'Mouse button (default left).' },
+            count: { type: 'string', value: '<1|2|3>', description: 'Clicks: 2 is a double click, 3 a triple click (left button; default 1).' },
+            mods: { type: 'string', value: '<keys>', description: 'Modifier keys held during the click, e.g. shift or ctrl+shift.' },
+            ...COMPUTER_LOOK,
+        },
+        examples: ['shard ws computer click acme/demo 640 400 --screenshot after.png', 'shard ws computer click acme/demo 200 120 --count 2'],
+    },
+    {
+        path: ['workspaces', 'computer', 'type'],
+        summary: 'Type text on the workspace desktop (0.10.0+)',
+        description: 'Types into the focused window, Unicode included (up to 20,000 characters); - reads the text from standard input. A newline presses Return.',
+        positionals: [REF, { name: 'text|-', required: true }],
+        options: { ...COMPUTER_LOOK },
+        examples: ['shard ws computer type acme/demo "hello world"', 'cat notes.txt | shard ws computer type acme/demo -'],
+    },
+    {
+        path: ['workspaces', 'computer', 'key'],
+        summary: 'Press keys on the workspace desktop (0.10.0+)',
+        description: 'One key or combination, or several separated by spaces: Return, Escape, ctrl+s, alt+Tab, ctrl+shift+t, F5, Page_Down.',
+        positionals: [REF, { name: 'keys', required: true }],
+        options: {
+            repeat: { type: 'string', value: '<n>', description: 'Press it n times (1-100).' },
+            ...COMPUTER_LOOK,
+        },
+        examples: ['shard ws computer key acme/demo ctrl+l', 'shard ws computer key acme/demo Tab --repeat 3 --screenshot form.png'],
+    },
+    {
+        path: ['workspaces', 'computer', 'scroll'],
+        summary: 'Scroll on the workspace desktop (0.10.0+)',
+        description: 'Scrolls up, down, left or right by --amount wheel clicks (default 3), at <x> <y> or at the pointer.',
+        positionals: [REF, { name: 'up|down|left|right', required: true }, { name: 'x' }, { name: 'y' }],
+        options: {
+            amount: { type: 'string', value: '<n>', description: 'Wheel clicks (1-100, default 3).' },
+            mods: { type: 'string', value: '<keys>', description: 'Modifier keys held while scrolling, e.g. shift.' },
+            ...COMPUTER_LOOK,
+        },
+        examples: ['shard ws computer scroll acme/demo down 640 400 --amount 5'],
+    },
+    {
+        path: ['workspaces', 'computer', 'move'],
+        summary: 'Move the pointer on the workspace desktop (0.10.0+)',
+        positionals: [REF, { name: 'x', required: true }, { name: 'y', required: true }],
+        options: { ...COMPUTER_LOOK },
+    },
+    {
+        path: ['workspaces', 'computer', 'drag'],
+        summary: 'Drag with the left button on the workspace desktop (0.10.0+)',
+        description: 'Presses at <x1> <y1>, moves to <x2> <y2> and releases.',
+        positionals: [REF, { name: 'x1', required: true }, { name: 'y1', required: true }, { name: 'x2', required: true }, { name: 'y2', required: true }],
+        options: {
+            mods: { type: 'string', value: '<keys>', description: 'Modifier keys held during the drag, e.g. alt.' },
+            ...COMPUTER_LOOK,
+        },
+        examples: ['shard ws computer drag acme/demo 100 200 500 200'],
+    },
+    {
+        path: ['workspaces', 'computer', 'mouse-down'],
+        summary: 'Press the left mouse button and keep it down (0.10.0+)',
+        description: 'At the pointer (shard ws computer move first); shard ws computer mouse-up releases it.',
+        positionals: [REF],
+        options: { ...COMPUTER_LOOK },
+    },
+    {
+        path: ['workspaces', 'computer', 'mouse-up'],
+        summary: 'Release the left mouse button (0.10.0+)',
+        positionals: [REF],
+        options: { ...COMPUTER_LOOK },
+    },
+    {
+        path: ['workspaces', 'computer', 'hold-key'],
+        summary: 'Hold keys down for some seconds on the workspace desktop (0.10.0+)',
+        positionals: [REF, { name: 'keys', required: true }, { name: 'seconds', required: true }],
+        options: { ...COMPUTER_LOOK },
+        examples: ['shard ws computer hold-key acme/demo shift 2'],
+    },
+    {
+        path: ['workspaces', 'computer', 'zoom'],
+        summary: 'Save an enlarged view of part of the workspace desktop (0.10.0+)',
+        description: 'The region <x0> <y0> <x1> <y1> (screen pixels, x0 < x1, y0 < y1), scaled up to the screen width. --json prints {out, format, width, height, bytes}.',
+        positionals: [REF, { name: 'x0', required: true }, { name: 'y0', required: true }, { name: 'x1', required: true }, { name: 'y1', required: true }],
+        options: {
+            out: { type: 'string', value: '<file>', description: 'Where to write the image (default zoom.png).' },
+            format: { type: 'string', value: '<png|jpeg>', description: 'Image format (default png).' },
+            quality: { type: 'string', value: '<1-100>', description: 'JPEG quality (default 80).' },
+        },
+        examples: ['shard ws computer zoom acme/demo 0 0 640 200 --out toolbar.png'],
+    },
+    {
+        path: ['workspaces', 'computer', 'cursor'],
+        summary: 'Print where the pointer is on the workspace desktop (0.10.0+)',
+        positionals: [REF],
+        options: {},
+    },
+    {
+        path: ['workspaces', 'computer', 'wait'],
+        summary: 'Wait on the workspace desktop, then optionally take a screenshot (0.10.0+)',
+        description: 'For a page or program that is still loading: shard ws computer wait <ws> 2 --screenshot after.png.',
+        positionals: [REF, { name: 'seconds', required: true }],
+        options: { ...COMPUTER_LOOK },
+    },
+    {
+        path: ['workspaces', 'computer', 'start'],
+        summary: 'Start the workspace desktop (0.10.0+)',
+        description: 'A no-op while it runs. The size applies to a start: 640x480 to 2560x1600 (default 1280x800).',
+        positionals: [REF],
+        options: {
+            width: { type: 'string', value: '<px>', description: 'Screen width (640-2560).' },
+            height: { type: 'string', value: '<px>', description: 'Screen height (480-1600).' },
+        },
+    },
+    { path: ['workspaces', 'computer', 'stop'], summary: 'Stop the workspace desktop; its windows close (0.10.0+)', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'computer', 'stream'],
+        summary: 'Print a private link to watch the workspace desktop live (0.10.0+)',
+        description: 'Starts the viewer in the workspace, exposes its port and signs a link to it (inbound ports). View only unless --interactive. Anyone with the link can open it until it expires: share it like a password. --stop ends every view instead. --json prints {url, expires_at, port, interactive}.',
+        positionals: [REF],
+        options: {
+            fresh: { type: 'boolean', description: 'Mint a new viewer link instead of reusing a link with more than 60 seconds left.' },
+            interactive: { type: 'boolean', description: 'Let the viewer use the mouse and keyboard.' },
+            'embed-origin': { type: 'string', multiple: true, value: '<https-origin>', description: 'Allow this HTTPS origin to embed the viewer (repeatable, 1–10 distinct origins).' },
+            ttl: { type: 'string', value: '<duration>', description: 'Lifetime of the link, 1m to 7d (default 24h).' },
+            stop: { type: 'boolean', description: 'End every view and close the viewer ports.' },
+        },
+        examples: ['open "$(shard ws computer stream acme/demo)"', 'shard ws computer stream acme/demo --stop'],
+    },
+    {
+        path: ['workspaces', 'computer', 'enable'],
+        summary: 'Switch computer use on for a workspace (0.10.0+)',
+        description: 'Tool tokens then carry the computer tool; the platform starts the desktop on the first computer call. --json prints {enabled, workspace, template, available}.',
+        positionals: [REF],
+        options: {},
+    },
+    { path: ['workspaces', 'computer', 'disable'], summary: 'Switch computer use off for a workspace (0.10.0+)', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'computer', 'inherit'],
+        summary: 'Let a workspace follow its template’s computer use switch (0.10.0+)',
+        positionals: [REF],
+        options: {},
+    },
+    {
+        path: ['templates', 'computer-use'],
+        summary: 'Switch computer use on or off for every workspace of one of your templates (0.10.0+)',
+        description: 'A workspace may override it (shard ws computer enable|disable). Platform templates keep it off: switch a workspace on instead.',
+        positionals: [SLUG, { name: 'on|off', required: true }],
+        options: {},
+        examples: ['shard templates computer-use my-desktop-agent on'],
+    },
     {
         path: ['files', 'read'],
         summary: 'Print (or save) a file from a workspace',
@@ -891,8 +1128,10 @@ const ALIASES = {
 /** Groups also reachable under `workspaces` (`shard workspaces files read ...` == `shard files read ...`). */
 const FOLDED = new Set(['files', 'operations', 'executions']);
 /** Canonical command words: aliases resolved, `workspaces files|operations|executions` folded to the top-level group. */
+/** Top-level shortcuts for a whole command path (0.10.0+): `shard exec` is `shard workspaces exec`. */
+const SHORTCUTS = { exec: ['workspaces', 'exec'] };
 export function normalizeWords(words) {
-    const w = words.map((x) => ALIASES[x] ?? x);
+    const w = words.flatMap((x, i) => (i === 0 ? SHORTCUTS[x] : undefined) ?? [ALIASES[x] ?? x]);
     if (w[0] === 'workspaces' && w[1] !== undefined && FOLDED.has(w[1]))
         return w.slice(1);
     return w;

package/dist/commands.d.ts

@@ -96,10 +96,12 @@ export declare function principal(ctx: Ctx): Promise<{
         id: string;
         key_id: string;
     };
-    tool_permissions: ("git" | "exec" | "files" | "pty" | "process" | "browser")[];
+    tool_permissions: ("git" | "exec" | "files" | "pty" | "process" | "browser" | "computer")[];
 }>;
 /** The exit code `shard exec` returns for a finished command. */
-export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'>): number;
+export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'> & {
+    canceled?: boolean;
+}): number;
 /**
  * A lifecycle call a file-first workspace does not have (suspend, resume, fork, reset,
  * save-as-template), refused before any request as the SDK's workspace handle does: NotSupportedForModeError, printed