@shardflux/cli 0.4.1 → 0.5.1

package/dist/account-args.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The account plane's command table (0.5.0+; docs/progress/account-cli.md §5): sign-in, setup, organizations,
+ * projects, API keys, members, invitations, billing, audit, account export/deletion, plus the project-key commands
+ * that were dashboard-only before (egress, volumes) and template publish/archive. Pure data like args.ts, which
+ * merges it into COMMANDS.
+ *
+ * Credentials: commands under auth, orgs, projects, api-keys, members, invitations, billing, audit, account and
+ * templates publish|archive use the user session (SHARDFLUX_SESSION_TOKEN, else `shard auth login`'s saved one);
+ * egress and volumes use the project API key like the other workspace commands. Secrets never come from arguments:
+ * passwords are read from standard input or a no-echo prompt; emailed links are single-use positionals.
+ */
+import type { CommandSpec } from './args.js';
+export declare const ACCOUNT_COMMANDS: CommandSpec[];

package/dist/account-args.js

@@ -0,0 +1,425 @@
+const ORG = {
+    org: { type: 'string', value: '<org>', description: 'Organization: id or slug. Default: the saved one (shard orgs use), else your only organization.' },
+};
+const PROJECT = {
+    project: { type: 'string', value: '<project>', description: 'Project: id or slug. Default: the saved one (shard projects use), else the organization’s only project.' },
+};
+const SECOND_FACTOR = {
+    code: { type: 'string', value: '<totp>', description: 'Current 6-digit code of your authenticator app (two-factor accounts).' },
+    'recovery-code': { type: 'string', value: '<code>', description: 'A one-time recovery code instead of --code.' },
+};
+const YES = (what) => ({ yes: { type: 'boolean', description: `Required: confirm ${what}.` } });
+/** An emailed link (or the token in it): single use, so an argument is fine. */
+const LINK = { name: 'link|token', 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.' },
+};
+const OPEN = { open: { type: 'boolean', description: 'Also open the page in the default browser (best effort; the URL is printed either way).' } };
+const AUDIT_FILTERS = {
+    source: { type: 'string', value: '<app|cell_tool>', description: 'API events (app) or workspace tool calls (cell_tool).' },
+    'actor-type': { type: 'string', value: '<type>', description: 'user, api_key, system, operator or anonymous.' },
+    actor: { type: 'string', value: '<id>', description: 'Actor id (a user or API key id).' },
+    action: { type: 'string', value: '<prefix>', description: 'Action prefix, e.g. workspace. or tool.exec.' },
+    'target-type': { type: 'string', value: '<type>', description: 'Target type, e.g. workspace or api_key.' },
+    target: { type: 'string', value: '<id>', description: 'Target id.' },
+    'project-id': { type: 'string', value: '<id>', description: 'Only events of this project.' },
+    workspace: { type: 'string', value: '<id>', description: 'Only events of this workspace (id).' },
+    'agent-session': { type: 'string', value: '<id>', description: 'Only events of this agent session.' },
+    outcome: { type: 'string', value: '<outcome>', description: 'success, failure or denied.' },
+    from: { type: 'string', value: '<time>', description: 'Inclusive start: an RFC 3339 time, or a duration ago such as 24h or 7d.' },
+    to: { type: 'string', value: '<time>', description: 'Exclusive end: an RFC 3339 time, or a duration ago.' },
+};
+const EGRESS_SCOPE = {
+    project: { type: 'string', value: '<project-id>', description: 'Project policy of this project (default: the API key’s project).' },
+    workspace: { type: 'string', value: '<id|key>', description: 'The workspace’s own policy (override) and its enforcement instead.' },
+};
+const VOLUME_WAIT = {
+    wait: { type: 'boolean', description: 'Wait until the cell finished (default; --no-wait returns with the operation).' },
+    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m); the operation continues server side.' },
+};
+export const ACCOUNT_COMMANDS = [
+    // ---- sign-in (auth) ------------------------------------------------------------------------------------
+    {
+        path: ['auth', 'register'],
+        summary: 'Create an account; a verification link is emailed (the password is read from standard input or a prompt)',
+        description: 'The answer is the same whether or not the address already has an account (no enumeration). On a terminal the password is asked twice; otherwise it is the first line of standard input. Next: open the link, or pass it to "shard auth verify-email", then "shard auth login".',
+        positionals: [],
+        options: {
+            email: { type: 'string', value: '<email>', description: 'Your email address (required).' },
+            name: { type: 'string', value: '<display name>', description: 'Your name as others see it (default: none; setup names the organization after it).' },
+        },
+        examples: [`printf '%s\\n' "$PASSWORD" | shard auth register --email you@example.com --name "Ada Lovelace"`, 'shard auth register --email you@example.com   # prompts for the password'],
+    },
+    {
+        path: ['auth', 'verify-email'],
+        summary: 'Verify your email with the emailed link (or its token)',
+        description: 'Pass the whole link from the email (quote it: it contains #). A link from "resend-verification" needs a new password: it is read from standard input (or asked twice on a terminal) and set at once; without one the command prints how to set it later.',
+        positionals: [LINK],
+        options: {},
+        examples: [`shard auth verify-email 'https://app.shardflux.dev/auth/verify-email#token=...'`],
+    },
+    { path: ['auth', 'resend-verification'], summary: 'Email a new verification link (signed in, email not verified yet)', positionals: [], options: {} },
+    {
+        path: ['auth', 'login'],
+        summary: 'Sign in: saves a session for this API in the credentials file (the password is read from standard input or a prompt)',
+        description: 'Two-factor accounts: pass --code (or --recovery-code), or type the code at the prompt; without either the pending sign-in is saved and "shard auth mfa --code <code>" completes it within 10 minutes (exit 4 until then). Prints who you are, your organizations and the next step. A session lasts 30 days of use (90 at most). SHARDFLUX_SESSION_TOKEN, when set, is used instead of the saved session.',
+        positionals: [],
+        options: { email: { type: 'string', value: '<email>', description: 'Your email address (required).' }, ...SECOND_FACTOR },
+        examples: [`printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`, `printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com --code 123456`],
+    },
+    {
+        path: ['auth', 'mfa'],
+        summary: 'Complete a pending two-factor sign-in with a code',
+        positionals: [],
+        options: { ...SECOND_FACTOR },
+        examples: ['shard auth mfa --code 123456', 'shard auth mfa --recovery-code abcd-efgh-ijkl'],
+    },
+    {
+        path: ['auth', 'status'],
+        summary: 'Show the session (user, verification, two-factor, expiry, step-up) and the saved API key, without secrets',
+        description: 'Works signed out too ("not signed in"). A saved session the API no longer accepts is removed.',
+        positionals: [],
+        options: {},
+    },
+    {
+        path: ['auth', 'logout'],
+        summary: 'Sign out: end the session and remove it from the credentials file (a saved API key stays)',
+        positionals: [],
+        options: { all: { type: 'boolean', description: 'End every session of your account (browser and CLI) and revoke workspace tool tokens issued through them.' } },
+    },
+    {
+        path: ['auth', 'sessions'],
+        summary: 'List your live sessions (browser and CLI), or revoke one',
+        positionals: [],
+        options: { revoke: { type: 'string', value: '<session-id>', description: 'End this session.' } },
+    },
+    {
+        path: ['auth', 'step-up'],
+        summary: 'Confirm your password (and code) for sensitive actions: valid 10 minutes',
+        description: 'Needed for two-factor changes, an email change, data exports and deletions. On a terminal "shard" asks by itself when the API requires it; scripts run this first. The password comes from standard input or a prompt; two-factor accounts add --code (or type it at the prompt).',
+        positionals: [],
+        options: { ...SECOND_FACTOR },
+        examples: [`printf '%s\\n' "$PASSWORD" | shard auth step-up`, `printf '%s\\n' "$PASSWORD" | shard auth step-up --code 123456`],
+    },
+    {
+        path: ['auth', 'password', 'change'],
+        summary: 'Change your password (current, then new, from standard input lines or prompts); other sessions end',
+        positionals: [],
+        options: {},
+        examples: [`printf '%s\\n%s\\n' "$CURRENT" "$NEW" | shard auth password change`],
+    },
+    {
+        path: ['auth', 'password', 'reset'],
+        summary: 'Email a password reset link',
+        positionals: [],
+        options: { email: { type: 'string', value: '<email>', description: 'The account’s email address (required).' } },
+    },
+    {
+        path: ['auth', 'password', 'reset-confirm'],
+        summary: 'Set a new password with the emailed reset link (new password from standard input or a prompt)',
+        positionals: [LINK],
+        options: {},
+        examples: [`printf '%s\\n' "$NEW" | shard auth password reset-confirm 'https://app.shardflux.dev/auth/reset-password#token=...'`],
+    },
+    {
+        path: ['auth', 'email', 'change'],
+        summary: 'Change your sign-in email: a confirmation link goes to the new address',
+        positionals: [],
+        options: { email: { type: 'string', value: '<new email>', description: 'The new address (required).' } },
+    },
+    { path: ['auth', 'email', 'confirm'], summary: 'Confirm an email change with the link sent to the new address', positionals: [LINK], options: {} },
+    {
+        path: ['auth', 'totp', 'enroll'],
+        summary: 'Start two-factor authentication: prints the secret and otpauth:// URI for your authenticator app',
+        description: 'Then "shard auth totp confirm --code <code>" turns it on and prints recovery codes. Needs a recent step-up.',
+        positionals: [],
+        options: {},
+    },
+    {
+        path: ['auth', 'totp', 'confirm'],
+        summary: 'Turn two-factor authentication on with a current code; prints recovery codes once',
+        positionals: [],
+        options: { code: { type: 'string', value: '<totp>', description: 'Current 6-digit code (required).' } },
+    },
+    {
+        path: ['auth', 'totp', 'disable'],
+        summary: 'Turn two-factor authentication off (step-up with a code first; the password from standard input or a prompt)',
+        positionals: [],
+        options: { ...SECOND_FACTOR },
+    },
+    { path: ['auth', 'totp', 'recovery-codes'], summary: 'Replace your recovery codes (the old ones stop working); prints the new ones once', positionals: [], options: {} },
+    // ---- setup and environment -----------------------------------------------------------------------------
+    {
+        path: ['setup'],
+        summary: 'Get ready to run workspaces: use (or create) an organization and project, create an API key and save it',
+        description: 'Needs a session (shard auth login). With no organization it creates "<your name>\'s organization" and a project "Default"; the key gets every workspace tool unless --tool. The key is saved in the credentials file, checked against the API, and every workspace command uses it from then on. Idempotent: a saved key that still works is kept (unless --new-key).',
+        positionals: [],
+        options: {
+            ...ORG,
+            ...PROJECT,
+            'org-name': { type: 'string', value: '<name>', description: 'Name of the organization to create when you have none.' },
+            'project-name': { type: 'string', value: '<name>', description: 'Name of the project to create when the organization has none (default Default).' },
+            'key-name': { type: 'string', value: '<name>', description: 'Name of the API key (default "shard-cli <hostname>").' },
+            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the key may use (repeatable; exec, files, pty, process, git, browser). Default: all.' },
+            'new-key': { type: 'boolean', description: 'Create and save a new key even when the saved one works (the old key stays valid until revoked).' },
+        },
+        examples: ['shard setup', 'shard setup --org acme --project web --tool exec --tool files'],
+    },
+    {
+        path: ['env'],
+        summary: 'Print shell commands that export the saved API key (and API URL) for tools that read the environment',
+        description: 'Prints the key in clear text: for eval, not for logs. SHARDFLUX_API_URL is included when it is not the default.',
+        positionals: [],
+        options: { shell: { type: 'string', value: '<sh|fish|powershell>', description: 'Syntax (default sh: bash, zsh, dash).' } },
+        examples: ['eval "$(shard env)"', 'shard env --shell fish | source', 'shard env --shell powershell | Invoke-Expression'],
+    },
+    // ---- organizations, projects, keys, members, invitations -----------------------------------------------
+    { path: ['orgs', 'list'], summary: 'List your organizations and your role in each (* marks the default)', positionals: [], options: {} },
+    {
+        path: ['orgs', 'create'],
+        summary: 'Create an organization (you become its owner)',
+        positionals: [{ name: 'name', required: true }],
+        options: { slug: { type: 'string', value: '<slug>', description: 'URL name (default: from the name plus a random suffix).' }, use: { type: 'boolean', description: 'Make it the default organization.' } },
+    },
+    { path: ['orgs', 'get'], summary: 'Show an organization with its plan', positionals: [{ name: 'org' }], options: {} },
+    { path: ['orgs', 'use'], summary: 'Make an organization the default for account commands (saved per API URL)', positionals: [{ name: 'org', required: true }], options: {} },
+    {
+        path: ['orgs', 'export'],
+        summary: 'Export an organization’s data as JSON to a file (owners; needs a recent step-up)',
+        positionals: [{ name: 'org' }],
+        options: { out: { type: 'string', value: '<file>', description: 'Where to write it (default ./organization-export-<id>.json; created 0600).' }, force: { type: 'boolean', description: 'Overwrite an existing file.' } },
+    },
+    { path: ['orgs', 'deletion'], summary: 'Show what deleting an organization would do and what blocks it', positionals: [{ name: 'org' }], options: {} },
+    {
+        path: ['orgs', 'workspaces'],
+        summary: 'List the organization’s workspaces in every project (as the dashboard does)',
+        description: 'Your session sees what your role allows. Running commands in a workspace (ws open, exec, files) stays per project with its API key: shard projects use <project> && shard setup.',
+        positionals: [{ name: 'org' }],
+        options: {
+            project: { type: 'string', value: '<project>', description: 'Only this project (id or slug).' },
+            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.' },
+            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).' },
+            'include-deleted': { type: 'boolean', description: 'Include deleted workspaces and ended sessions.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+        },
+        examples: ['shard orgs workspaces', 'shard orgs workspaces acme --project web --state running'],
+    },
+    {
+        path: ['orgs', 'delete'],
+        summary: 'Delete an organization: workspaces are deleted, keys revoked, projects removed (owners; step-up)',
+        description: 'Irreversible. Refused while a subscription is active (cancel it in the portal: shard billing portal) or a checkout is open.',
+        positionals: [{ name: 'org', required: true }],
+        options: { confirm: { type: 'string', value: '<slug>', description: 'The organization’s slug, typed out (required).' }, ...YES('the deletion') },
+    },
+    { path: ['projects', 'list'], summary: 'List the organization’s projects (* marks the default)', positionals: [], options: { ...ORG } },
+    {
+        path: ['projects', 'create'],
+        summary: 'Create a project (owners and admins)',
+        positionals: [{ name: 'name', required: true }],
+        options: { slug: { type: 'string', value: '<slug>', description: 'URL name (default: from the name).' }, ...ORG, use: { type: 'boolean', description: 'Make it the default project.' } },
+    },
+    { path: ['projects', 'get'], summary: 'Show a project', positionals: [{ name: 'project', required: true }], options: { ...ORG } },
+    { path: ['projects', 'use'], summary: 'Make a project (and its organization) the default for account commands', positionals: [{ name: 'project', required: true }], options: { ...ORG } },
+    { path: ['api-keys', 'list'], summary: 'List the project’s API keys (never secrets; * marks the saved key)', positionals: [], options: { ...PROJECT, ...ORG } },
+    {
+        path: ['api-keys', 'create'],
+        summary: 'Create a project API key: printed once (or saved with --save)',
+        description: 'Owners and admins grant workspace tools; billing members create keys without tools. The secret cannot be shown again.',
+        positionals: [{ name: 'name', required: true }],
+        options: {
+            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the key may use (repeatable). Default: all six.' },
+            'read-only': { type: 'boolean', description: 'No workspace tools (read-only API use).' },
+            expires: { type: 'string', value: '<30d|90d|365d|never>', description: 'Expiry (default never).' },
+            save: { type: 'boolean', description: 'Save it in the credentials file for the workspace commands instead of printing it.' },
+            ...PROJECT,
+            ...ORG,
+        },
+        examples: ['shard api-keys create ci --tool exec --tool files --expires 90d', 'shard api-keys create laptop --save'],
+    },
+    {
+        path: ['api-keys', 'revoke'],
+        summary: 'Revoke an API key (API calls stop at once, tool tokens within 30 s)',
+        positionals: [{ name: 'id|key_id', required: true }],
+        options: { ...PROJECT, ...ORG, ...YES('the revocation') },
+    },
+    { path: ['members', 'list'], summary: 'List the organization’s members and roles', positionals: [], options: { ...ORG } },
+    {
+        path: ['members', 'set-role'],
+        summary: 'Change a member’s role: owner, admin, member or billing (owners and admins)',
+        positionals: [{ name: 'user|email', required: true }, { name: 'role', required: true }],
+        options: { ...ORG },
+    },
+    {
+        path: ['members', 'remove'],
+        summary: 'Remove a member (or yourself: leave the organization)',
+        positionals: [{ name: 'user|email', required: true }],
+        options: { ...ORG, ...YES('the removal') },
+    },
+    { path: ['invitations', 'list'], summary: 'List the organization’s invitations (owners and admins)', positionals: [], options: { ...ORG } },
+    {
+        path: ['invitations', 'create'],
+        summary: 'Invite someone by email (they get a link; they accept with shard invitations accept)',
+        positionals: [{ name: 'email', required: true }],
+        options: { role: { type: 'string', value: '<role>', description: 'owner, admin, member or billing (required).' }, ...ORG },
+    },
+    { path: ['invitations', 'revoke'], summary: 'Revoke a pending invitation', positionals: [{ name: 'id', required: true }], options: { ...ORG } },
+    {
+        path: ['invitations', 'accept'],
+        summary: 'Accept an invitation with the emailed link (your verified email must be the invited one)',
+        positionals: [LINK],
+        options: { use: { type: 'boolean', description: 'Make the organization the default.' } },
+    },
+    // ---- billing, audit, account ---------------------------------------------------------------------------
+    { path: ['billing', 'plans'], summary: 'List the plans and prices (public; no sign-in needed)', positionals: [], options: {} },
+    { path: ['billing', 'status'], summary: 'Show the plan, billing state, subscription period and any pending checkout', positionals: [], options: { ...ORG } },
+    {
+        path: ['billing', 'upgrade'],
+        summary: 'Buy a plan: prints the Stripe Checkout URL where a person pays (owners and billing members)',
+        description: 'The plan must be purchasable (shard billing plans). The API activates it only after Stripe confirms the payment: --wait polls until the subscription is active (exit 0), the checkout expires or is canceled (exit 6), or --timeout (exit 5; the checkout stays open). An organization that already has a subscription changes plans in the billing portal: its URL is printed instead (exit 0).',
+        positionals: [{ name: 'plan', required: true }],
+        options: {
+            ...ORG,
+            ...OPEN,
+            wait: { type: 'boolean', description: 'Wait until the subscription is active (progress on stderr).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 15m).' },
+        },
+        examples: ['shard billing upgrade developer --open --wait'],
+    },
+    { path: ['billing', 'portal'], summary: 'Open the Stripe billing portal: plan changes, payment methods, invoices, cancellation', positionals: [], options: { ...ORG, ...OPEN } },
+    { path: ['billing', 'invoices'], summary: 'List invoices, newest first', positionals: [], options: { ...ORG, ...PAGE, limit: { type: 'string', value: '<n>', description: 'Page size, 1-100 (default 20).' } } },
+    {
+        path: ['billing', 'alerts'],
+        summary: 'Show or set the usage alert thresholds (percent of each allowance; email alerts)',
+        positionals: [],
+        options: {
+            ...ORG,
+            set: { type: 'string', value: '<p1,p2,...>', description: 'Thresholds in percent, 1-100, at most 5 (e.g. 50,80,100).' },
+            clear: { type: 'boolean', description: 'Turn alerts off.' },
+        },
+        examples: ['shard billing alerts --set 50,80,100'],
+    },
+    {
+        path: ['billing', 'overage'],
+        summary: 'Show or change opt-in overage and its spend cap: status (default), on --cap <dollars>, off, cap <dollars>',
+        description: 'With overage on, workspaces keep opening and running past the CPU-hours and RAM GiB-hours allowances; the usage past them is charged on the next invoice until the charges reach the spend cap (per billing period, $1 up to the plan price). Off by default; turning it off is always allowed and what it charged stays on the invoice. Owners and billing members change it, and each of them gets an email about the change. This period\'s charges: shard usage.',
+        positionals: [{ name: 'status|on|off|cap' }, { name: 'dollars' }],
+        options: {
+            ...ORG,
+            cap: { type: 'string', value: '<dollars>', description: 'With on: the spend cap per billing period in dollars, e.g. 9 or 9.50 (needed unless a cap is set already).' },
+            'if-version': { type: 'string', value: '<n>', description: 'Only if the policy version is still n (shard billing overage --json shows it): refuses a concurrent change.' },
+        },
+        examples: ['shard billing overage', 'shard billing overage on --cap 9', 'shard billing overage cap 25.50', 'shard billing overage off'],
+    },
+    {
+        path: ['audit', 'list'],
+        summary: 'List the organization’s audit log, newest first (owners and admins)',
+        positionals: [],
+        options: { ...ORG, ...AUDIT_FILTERS, ...PAGE, limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' } },
+        examples: ['shard audit list --action api_key. --from 7d', 'shard audit list --source cell_tool --workspace <id> --all --json'],
+    },
+    {
+        path: ['audit', 'export'],
+        summary: 'Export the audit log as NDJSON or CSV (at most 90 days and 50 000 rows)',
+        positionals: [],
+        options: {
+            ...ORG,
+            format: { type: 'string', value: '<ndjson|csv>', description: 'Default ndjson.' },
+            out: { type: 'string', value: '<file>', description: 'Write to this file (created 0600) instead of stdout.' },
+            force: { type: 'boolean', description: 'Overwrite an existing --out file.' },
+            ...AUDIT_FILTERS,
+        },
+        examples: ['shard audit export --format csv --from 30d --out audit.csv'],
+    },
+    { path: ['account', 'status'], summary: 'Show your account: profile, memberships, and any scheduled deletion and what blocks it', positionals: [], options: {} },
+    {
+        path: ['account', 'export'],
+        summary: 'Export your account data as JSON to a file (needs a recent step-up)',
+        positionals: [],
+        options: { out: { type: 'string', value: '<file>', description: 'Where to write it (default ./account-export-<id>.json; created 0600).' }, force: { type: 'boolean', description: 'Overwrite an existing file.' } },
+    },
+    {
+        path: ['account', 'delete'],
+        summary: 'Schedule the deletion of your account (cancel within the grace period; step-up)',
+        description: 'Refused while you are the only owner of an organization with other members, or its only member: transfer or delete it first (shard account status names them).',
+        positionals: [],
+        options: { confirm: { type: 'string', value: '<email>', description: 'Your email address, typed out (required).' }, ...YES('the deletion') },
+    },
+    { path: ['account', 'cancel-deletion'], summary: 'Cancel a scheduled account deletion', positionals: [], options: {} },
+    // ---- project API key: egress and volumes ---------------------------------------------------------------
+    {
+        path: ['egress', 'get'],
+        summary: 'Show the outbound network policy of the project (or of a workspace, with its enforcement)',
+        positionals: [],
+        options: { ...EGRESS_SCOPE },
+    },
+    {
+        path: ['egress', 'set'],
+        summary: 'Replace the project’s (or a workspace’s) outbound network policy from a JSON file',
+        description: 'The file is {"mode": "allow_all" | "allowlist" | "deny_all", "rules": [{"host": "api.github.com", "ports": [443]}], "cidrs": [...]}. A new immutable version is stored; the host enforces it (shard egress get --workspace shows how far).',
+        positionals: [],
+        options: {
+            file: { type: 'string', value: '<policy.json|->', description: 'The policy (required; - for standard input).' },
+            ...EGRESS_SCOPE,
+            'if-version': { type: 'string', value: '<n>', description: 'Only if the current version is still n (from egress get): refuses a concurrent change.' },
+        },
+        examples: ['shard egress set --file policy.json', 'shard egress set --workspace acme/demo --file policy.json'],
+    },
+    { path: ['egress', 'history'], summary: 'List the policy versions, newest first', positionals: [], options: { ...EGRESS_SCOPE, limit: { type: 'string', value: '<n>', description: 'Page size, 1-200.' } } },
+    {
+        path: ['egress', 'clear'],
+        summary: 'Remove a workspace’s own policy (it follows the project policy again)',
+        positionals: [],
+        options: { workspace: { type: 'string', value: '<id|key>', description: 'The workspace (required).' } },
+    },
+    {
+        path: ['volumes', 'list'],
+        summary: 'List the project’s shared volumes',
+        positionals: [],
+        options: { 'include-org-shared': { type: 'boolean', description: 'Also the organization’s shared volumes (attachable here).' }, 'include-deleted': { type: 'boolean', description: 'Include deleted volumes.' }, all: { type: 'boolean', description: 'Fetch every page.' } },
+    },
+    {
+        path: ['volumes', 'create'],
+        summary: 'Create a shared volume (persistent storage attached to workspaces at a path)',
+        positionals: [{ name: 'name', required: true }],
+        options: {
+            'quota-gib': { type: 'string', value: '<n>', description: 'Size limit in GiB (required).' },
+            'org-shared': { type: 'boolean', description: 'Attachable from every project of the organization (owners/admins; API keys get 403).' },
+            ...VOLUME_WAIT,
+        },
+        examples: ['shard volumes create datasets --quota-gib 20'],
+    },
+    { path: ['volumes', 'get'], summary: 'Show a volume', positionals: [{ name: 'id|name', required: true }], options: {} },
+    {
+        path: ['volumes', 'delete'],
+        summary: 'Delete a volume and its data (refused while attached unless --force)',
+        positionals: [{ name: 'id|name', required: true }],
+        options: { force: { type: 'boolean', description: 'Detach it from every workspace first (guests see I/O errors on the mount).' }, ...YES('the deletion'), ...VOLUME_WAIT },
+    },
+    { path: ['volumes', 'attachments'], summary: 'List where a volume is attached', positionals: [{ name: 'id|name', required: true }], options: { 'include-detached': { type: 'boolean', description: 'Include past attachments.' } } },
+    {
+        path: ['volumes', 'attach'],
+        summary: 'Attach a volume to a workspace at a path',
+        positionals: [{ name: 'ws', required: true }, { name: 'volume', required: true }],
+        options: { mount: { type: 'string', value: '<path>', description: 'Absolute guest path, e.g. /mnt/data (required).' }, 'read-only': { type: 'boolean', description: 'Mount read-only (default read-write).' }, ...VOLUME_WAIT },
+        examples: ['shard volumes attach acme/demo datasets --mount /mnt/datasets --read-only'],
+    },
+    { path: ['volumes', 'detach'], summary: 'Detach a volume from a workspace', positionals: [{ name: 'ws', required: true }, { name: 'volume', required: true }], options: { ...VOLUME_WAIT } },
+    // ---- templates with the session ------------------------------------------------------------------------
+    {
+        path: ['templates', 'publish'],
+        summary: 'Publish a registered version of an organization template (owners/admins; signed in)',
+        positionals: [{ name: 'slug@version', required: true }],
+        options: { ...ORG },
+    },
+    {
+        path: ['templates', 'archive'],
+        summary: 'Archive a version: new opens stop using it; existing workspaces keep it (owners/admins; signed in)',
+        positionals: [{ name: 'slug@version', required: true }],
+        options: { ...ORG },
+    },
+];

package/dist/account-commands.d.ts

@@ -0,0 +1,18 @@
+import type { Handler } from './commands.js';
+export declare const DEFAULT_API_URL = "https://api.shardflux.dev";
+/**
+ * The organization name setup creates: "<display name or email local part>'s organization", within the API's rules
+ * for names (1-200 characters, no control characters or line breaks).
+ */
+export declare function defaultOrgName(user: {
+    display_name: string | null;
+    email: string;
+}): string;
+export type ShellKind = 'sh' | 'fish' | 'powershell';
+/** One line that sets `name` for `shell`, quoted so any value round-trips. */
+export declare function exportLine(shell: ShellKind, name: string, value: string): string;
+/** An RFC 3339 time, or a duration ago (`90m`, `24h`, `7d`, `2w`). */
+export declare function parseTime(text: string, option: string, now?: number): string;
+/** A spend cap in dollars ("9", "9.5", "9.50", "$9") as minor units (cents); at most two decimals. */
+export declare function dollarsToMinor(text: string, what: string): number;
+export declare const ACCOUNT_HANDLERS: Record<string, Handler>;