@shardflux/cli 0.8.1 → 0.9.0

package/dist/account-commands.js

@@ -13,8 +13,8 @@
  *   setup), else the only one there is; with several the usage error lists them.
  */
 import { chmod, writeFile } from 'node:fs/promises';
-import { API_KEY_TOOL_PERMISSIONS, CheckoutTimeoutError, Shardflux, ShardfluxAccount, ShardfluxApiError, fetchBillingCatalog, parseEmailToken } from '@shardflux/sdk';
-import { UUID, parseDuration, parsePositiveInt } from "./args.js";
+import { API_KEY_TOOL_PERMISSIONS, CheckoutTimeoutError, Shardflux, ShardfluxAccount, ShardfluxApiError, codexIdentityProof, fetchBillingCatalog, parseEmailToken } from '@shardflux/sdk';
+import { CLI_VERSION, UUID, parseDuration, parsePositiveInt } from "./args.js";
 import { openUrl } from "./browser.js";
 import { fileExists, oneOf, out, parseSlugVersion, principal, readInput, resolveWorkspace, str, strs, waitTimeout } from "./commands.js";
 import { AuthConfigError, CheckoutEndedError, InterruptedError, MfaPendingError, NotFoundError, UsageError } from "./errors.js";
@@ -83,16 +83,24 @@ async function mfaEnabled(account) {
  * Step-up: the password (a prompt, or the next piped line) plus, with two-factor authentication, the factor from the
  * flags, else a prompt (or the next piped line).
  */
-async function stepUp(ctx, account, factor, command) {
+async function stepUp(ctx, account, factor, command, codex = false) {
     const needsFactor = factor === null && (await mfaEnabled(account));
-    const password = await ctx.input.secret('Password: ', 'The password', pipe(command));
+    const first = codex ? { codexIdToken: await codexProofOrThrow(ctx) } : { password: await ctx.input.secret('Password: ', 'The password', pipe(command)) };
     let f = factor;
     if (needsFactor) {
         f = factorOf(await ctx.input.answer('Authenticator code (or a recovery code): '));
         if (f === null)
             throw new UsageError('two-factor authentication is on: pass --code <totp> (or --recovery-code <code>)');
     }
-    return account.auth.stepUp({ password, ...factorParams(f) });
+    return account.auth.stepUp({ ...first, ...factorParams(f) });
+}
+/** The ID token of this machine's Codex login (0.9.0+), refreshed by Codex; a usage error says why there is none. */
+async function codexProofOrThrow(ctx) {
+    const proof = await codexIdentityProof({ env: ctx.io.env, clientName: 'shard', clientVersion: CLI_VERSION });
+    if (!proof.ok)
+        throw new UsageError(proof.message, proof.reason === 'api_key_login' || proof.reason === 'not_signed_in' ? 'codex login   (then run this again)' : undefined);
+    ctx.addSecret(proof.idToken);
+    return proof.idToken;
 }
 /** Runs an account call; on 403 step_up_required on a terminal, steps up and retries once (else the error stands). */
 async function withStepUp(ctx, account, call) {
@@ -248,7 +256,7 @@ function userLine(u) {
 /** What to do after signing in: verify, set up, or open a workspace. */
 function nextAfterSignIn(ctx, user, me) {
     if (!user.email_verified)
-        return `shard auth verify-email '<link from the email>'   (a new link: shard auth resend-verification)`;
+        return `shard verify   (emails a 6-digit code; or open the link we emailed you: shard auth verify-email '<link>')`;
     const profile = ctx.store.profile(ctx.apiUrl);
     const hasKey = profile.api_key !== undefined || Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim());
     if (!hasKey || !me || me.memberships.length === 0)
@@ -535,6 +543,127 @@ async function waitedVolume(ctx, call) {
         throw err;
     }
 }
+/**
+ * `shard setup`, also the last step of `shard signup`: uses (or creates) an organization and project, creates an API
+ * key and saves it in the credentials file. Returns the report instead of printing it.
+ */
+async function runSetup(ctx, values, account) {
+    const me = await account.me();
+    if (me.type !== 'user' || !me.user)
+        throw new UsageError('setup needs a user session: shard auth login');
+    const tools = toolsFrom(values);
+    const profile = ctx.store.profile(ctx.apiUrl);
+    const created = { organization: false, project: false, api_key: false };
+    const flagged = str(values.org) !== undefined || str(values.project) !== undefined;
+    let keyCheck = null;
+    if (profile.api_key && values['new-key'] !== true) {
+        keyCheck = await checkKey(ctx, profile.api_key.token);
+        if (!keyCheck.ok && !ctx.json)
+            ctx.io.stderr.write(`note: the saved API key ${profile.api_key.key_id} no longer works (${keyCheck.reason}); creating a new one.\n`);
+    }
+    let org;
+    let project;
+    // The working saved key's own organization and project, when this user can see them.
+    let home = null;
+    if (keyCheck?.ok && !flagged) {
+        try {
+            home = { org: await account.organizations.get(keyCheck.organizationId), project: await account.projects.get(keyCheck.projectId) };
+        }
+        catch (err) {
+            if (!gone(err))
+                throw err;
+            if (!ctx.json)
+                ctx.io.stderr.write(`note: the saved API key ${profile.api_key.key_id} belongs to a project you cannot see; creating a key for your own.\n`);
+            keyCheck = { ok: false, reason: 'another account' };
+        }
+    }
+    if (home) {
+        org = home.org;
+        project = home.project;
+    }
+    else {
+        const orgs = await allOrgs(account);
+        const orgRef = str(values.org);
+        const savedOrg = profile.organization_id ? orgs.find((o) => o.id === profile.organization_id) : undefined;
+        if (orgRef !== undefined)
+            org = await findOrg(account, orgRef);
+        else if (savedOrg)
+            org = savedOrg;
+        else if (orgs.length === 1)
+            org = orgs[0];
+        else if (orgs.length === 0) {
+            org = await account.organizations.create({ name: str(values['org-name'])?.trim() || defaultOrgName(me.user) });
+            created.organization = true;
+        }
+        else
+            throw new UsageError(`You belong to ${orgs.length} organizations; pick one with --org <id|slug>:\n${choices(orgs)}\n`, 'or save a default first: shard orgs use <id|slug>');
+        const projects = created.organization ? [] : await allProjects(account, org.id);
+        const projectRef = str(values.project);
+        const savedProject = profile.project_id ? projects.find((p) => p.id === profile.project_id) : undefined;
+        if (projectRef !== undefined) {
+            const hit = byRef(projects, projectRef);
+            if (!hit)
+                throw new NotFoundError(`No project "${projectRef}" in ${org.name} (${org.slug}).`, 'list them: shard projects list');
+            project = hit;
+        }
+        else if (savedProject)
+            project = savedProject;
+        else if (projects.length === 1)
+            project = projects[0];
+        else if (projects.length === 0) {
+            project = await account.projects.create(org.id, { name: str(values['project-name'])?.trim() || 'Default' });
+            created.project = true;
+        }
+        else
+            throw new UsageError(`${org.name} has ${projects.length} projects; pick one with --project <id|slug>:\n${choices(projects)}\n`, 'or save a default first: shard projects use <id|slug>');
+    }
+    const keep = keyCheck?.ok === true && profile.api_key?.project_id === project.id;
+    let key;
+    let permissions = tools;
+    if (keep)
+        key = profile.api_key;
+    else {
+        const name = (str(values['key-name'])?.trim() || `shard-cli ${ctx.hostname()}`).slice(0, 200);
+        const res = await account.apiKeys.create(project.id, { name, toolPermissions: tools });
+        ctx.addSecret(res.secret);
+        key = storedKey(res.api_key, res.secret);
+        permissions = res.api_key.tool_permissions;
+        created.api_key = true;
+    }
+    ctx.store.update(ctx.apiUrl, (p) => {
+        p.organization_id = org.id;
+        p.project_id = project.id;
+        p.api_key = key;
+    });
+    const check = keep ? keyCheck : await checkKey(ctx, key.token);
+    if (!check?.ok || check.projectId !== project.id)
+        throw new UsageError(`the API key ${key.key_id} was saved but does not authenticate for project ${project.id} (${check && !check.ok ? check.reason : 'another project'})`, 'try again: shard setup --new-key');
+    if (keep) {
+        const k = (await account.apiKeys.list(project.id, { limit: 200 })).data.find((x) => x.id === key.id);
+        if (k)
+            permissions = k.tool_permissions;
+    }
+    const tag = (made) => (made ? 'created' : 'existing');
+    const envNote = ctx.io.env.SHARDFLUX_API_KEY?.trim() ? 'note: SHARDFLUX_API_KEY is set in this environment and wins over the saved key; unset it to use the saved key.\n' : '';
+    return {
+        text: (keep ? 'Already set up; the saved API key works.\n' : 'Set up.\n') +
+            kv([
+                ['organization', `${org.name} (${org.slug}, ${org.id}) ${tag(created.organization)}`],
+                ['project', `${project.name} (${project.slug}, ${project.id}) ${tag(created.project)}`],
+                ['api key', `"${key.name}" ${key.key_id} (tools: ${toolsText(permissions)}) ${keep ? 'saved earlier' : 'created'}, saved in ${ctx.store.file}`],
+            ]) +
+            envNote +
+            `next: ${NEXT_WORKSPACE}\n`,
+        data: {
+            organization: org,
+            project,
+            api_key: { id: key.id, key_id: key.key_id, name: key.name, project_id: key.project_id, tool_permissions: permissions },
+            created,
+            credentials_file: ctx.store.file,
+            next: NEXT_WORKSPACE,
+        },
+    };
+}
 // ---- handlers --------------------------------------------------------------------------------------------------
 export const ACCOUNT_HANDLERS = {
     async 'auth register'(ctx, values) {
@@ -582,6 +711,8 @@ export const ACCOUNT_HANDLERS = {
         return 0;
     },
     async 'auth login'(ctx, values) {
+        if (values.codex === true)
+            return ACCOUNT_HANDLERS.signup(ctx, { ...values, setup: false, codex: true, email: undefined }, []);
         const email = emailArg(need(values, 'email', '--email you@example.com'), '--email');
         let factor = factorFlags(values);
         const password = await ctx.input.secret(`Password for ${email}: `, 'The password', pipe(`shard auth login --email ${email}`));
@@ -762,7 +893,7 @@ export const ACCOUNT_HANDLERS = {
     },
     async 'auth step-up'(ctx, values) {
         const account = ctx.account();
-        const r = await stepUp(ctx, account, factorFlags(values), 'shard auth step-up');
+        const r = await stepUp(ctx, account, factorFlags(values), 'shard auth step-up', values.codex === true);
         out(ctx, `Step-up confirmed until ${time(r.step_up_valid_until)}.\n`, { step_up_valid_until: r.step_up_valid_until });
         return 0;
     },
@@ -840,119 +971,111 @@ export const ACCOUNT_HANDLERS = {
         return 0;
     },
     async setup(ctx, values) {
-        const account = ctx.account();
-        const me = await account.me();
-        if (me.type !== 'user' || !me.user)
-            throw new UsageError('setup needs a user session: shard auth login');
-        const tools = toolsFrom(values);
-        const profile = ctx.store.profile(ctx.apiUrl);
-        const created = { organization: false, project: false, api_key: false };
-        const flagged = str(values.org) !== undefined || str(values.project) !== undefined;
-        let keyCheck = null;
-        if (profile.api_key && values['new-key'] !== true) {
-            keyCheck = await checkKey(ctx, profile.api_key.token);
-            if (!keyCheck.ok && !ctx.json)
-                ctx.io.stderr.write(`note: the saved API key ${profile.api_key.key_id} no longer works (${keyCheck.reason}); creating a new one.\n`);
-        }
-        let org;
-        let project;
-        // The working saved key's own organization and project, when this user can see them.
-        let home = null;
-        if (keyCheck?.ok && !flagged) {
-            try {
-                home = { org: await account.organizations.get(keyCheck.organizationId), project: await account.projects.get(keyCheck.projectId) };
+        const r = await runSetup(ctx, values, ctx.account());
+        out(ctx, r.text, r.data);
+        return 0;
+    },
+    async signup(ctx, values) {
+        const email = str(values.email) === undefined ? undefined : emailArg(str(values.email), '--email');
+        const name = str(values.name)?.trim();
+        let codexNote = null;
+        let idToken = null;
+        if (values.codex !== false) {
+            const proof = await codexIdentityProof({ env: ctx.io.env, clientName: 'shard', clientVersion: CLI_VERSION });
+            if (proof.ok) {
+                idToken = proof.idToken;
+                ctx.addSecret(idToken);
+                if (email !== undefined && proof.email !== null && proof.email.toLowerCase() !== email.toLowerCase()) {
+                    codexNote = `note: signed up with your Codex login (${proof.email}), not --email ${email}; pass --no-codex to use ${email}.\n`;
+                }
             }
-            catch (err) {
-                if (!gone(err))
-                    throw err;
-                if (!ctx.json)
-                    ctx.io.stderr.write(`note: the saved API key ${profile.api_key.key_id} belongs to a project you cannot see; creating a key for your own.\n`);
-                keyCheck = { ok: false, reason: 'another account' };
+            else if (email === undefined) {
+                throw new UsageError(`No Codex login to sign up with: ${proof.message}`, 'shard signup --email you@example.com');
             }
         }
-        if (home) {
-            org = home.org;
-            project = home.project;
+        else if (email === undefined) {
+            throw new UsageError('--no-codex needs an email address.', 'shard signup --no-codex --email you@example.com');
         }
-        else {
-            const orgs = await allOrgs(account);
-            const orgRef = str(values.org);
-            const savedOrg = profile.organization_id ? orgs.find((o) => o.id === profile.organization_id) : undefined;
-            if (orgRef !== undefined)
-                org = await findOrg(account, orgRef);
-            else if (savedOrg)
-                org = savedOrg;
-            else if (orgs.length === 1)
-                org = orgs[0];
-            else if (orgs.length === 0) {
-                org = await account.organizations.create({ name: str(values['org-name'])?.trim() || defaultOrgName(me.user) });
-                created.organization = true;
-            }
-            else
-                throw new UsageError(`You belong to ${orgs.length} organizations; pick one with --org <id|slug>:\n${choices(orgs)}\n`, 'or save a default first: shard orgs use <id|slug>');
-            const projects = created.organization ? [] : await allProjects(account, org.id);
-            const projectRef = str(values.project);
-            const savedProject = profile.project_id ? projects.find((p) => p.id === profile.project_id) : undefined;
-            if (projectRef !== undefined) {
-                const hit = byRef(projects, projectRef);
-                if (!hit)
-                    throw new NotFoundError(`No project "${projectRef}" in ${org.name} (${org.slug}).`, 'list them: shard projects list');
-                project = hit;
-            }
-            else if (savedProject)
-                project = savedProject;
-            else if (projects.length === 1)
-                project = projects[0];
-            else if (projects.length === 0) {
-                project = await account.projects.create(org.id, { name: str(values['project-name'])?.trim() || 'Default' });
-                created.project = true;
+        let latest = null;
+        const { account, result } = await ShardfluxAccount.signup({
+            ...ctx.accountOptions(),
+            ...(idToken !== null ? { codexIdToken: idToken } : { email: email }),
+            ...(name ? { displayName: name } : {}),
+            onSessionToken: (s) => {
+                ctx.addSecret(s.token);
+                latest = s;
+            },
+        });
+        const replaced = ctx.store.profile(ctx.apiUrl).session?.token ?? null;
+        const expiresAt = () => latest?.expiresAt || result.session_expires_at || null;
+        let user = result.user;
+        if (result.status === 'mfa_required') {
+            let factor = factorFlags(values);
+            if (factor === null && ctx.input.interactive)
+                factor = factorOf(await ctx.input.answer('Authenticator code (or a recovery code): '));
+            if (factor === null) {
+                ctx.saveSession({ token: account.sessionToken ?? '', expires_at: expiresAt(), user: null, state: 'pending_mfa' });
+                if (replaced && replaced !== account.sessionToken)
+                    await endQuietly(ctx, replaced);
+                throw new MfaPendingError(`Your Codex login matches an account with two-factor authentication on, so the sign-in waits for your code (10 minutes). The pending session is saved in ${ctx.store.file}.`, 'shard auth mfa --code <code from your authenticator app>');
             }
-            else
-                throw new UsageError(`${org.name} has ${projects.length} projects; pick one with --project <id|slug>:\n${choices(projects)}\n`, 'or save a default first: shard projects use <id|slug>');
+            user = (await account.auth.completeMfa(factor)).user;
+        }
+        if (!user)
+            throw new UsageError('the API signed you up without a user; run shard auth status');
+        const saved = { token: account.sessionToken ?? '', expires_at: expiresAt(), user: { id: user.id, email: user.email }, state: 'active' };
+        const { switched } = ctx.saveSession(saved, user.email);
+        if (replaced && replaced !== saved.token)
+            await endQuietly(ctx, replaced);
+        if (switched && !ctx.json)
+            ctx.io.stderr.write(SWITCHED_NOTE);
+        if (codexNote && !ctx.json)
+            ctx.io.stderr.write(codexNote);
+        const access = result.access;
+        const how = access === 'verified'
+            ? idToken !== null
+                ? 'email verified by your Codex login'
+                : 'email verified'
+            : access === 'provisional'
+                ? 'email not verified yet: workspaces run on the Free plan now; verify to start the trial: shard verify'
+                : 'email not verified yet: verify it to run workspaces: shard verify';
+        let text = `${result.created ? 'Signed up' : 'Signed in'} as ${userLine(user)} (${how}).\nsession: saved in ${ctx.store.file}\n`;
+        const data = { status: 'authenticated', created: result.created, access, user, method: idToken !== null ? 'codex' : 'email', credentials_file: ctx.store.file };
+        if (access !== 'verification_required' && values.setup !== false) {
+            const setup = await runSetup(ctx, values, account);
+            text += setup.text;
+            data.setup = setup.data;
         }
-        const keep = keyCheck?.ok === true && profile.api_key?.project_id === project.id;
-        let key;
-        let permissions = tools;
-        if (keep)
-            key = profile.api_key;
         else {
-            const name = (str(values['key-name'])?.trim() || `shard-cli ${ctx.hostname()}`).slice(0, 200);
-            const res = await account.apiKeys.create(project.id, { name, toolPermissions: tools });
-            ctx.addSecret(res.secret);
-            key = storedKey(res.api_key, res.secret);
-            permissions = res.api_key.tool_permissions;
-            created.api_key = true;
+            const next = access === 'verification_required' ? 'shard verify' : 'shard setup';
+            text += `next: ${next}\n`;
+            data.next = next;
         }
-        ctx.store.update(ctx.apiUrl, (p) => {
-            p.organization_id = org.id;
-            p.project_id = project.id;
-            p.api_key = key;
-        });
-        const check = keep ? keyCheck : await checkKey(ctx, key.token);
-        if (!check?.ok || check.projectId !== project.id)
-            throw new UsageError(`the API key ${key.key_id} was saved but does not authenticate for project ${project.id} (${check && !check.ok ? check.reason : 'another project'})`, 'try again: shard setup --new-key');
-        if (keep) {
-            const k = (await account.apiKeys.list(project.id, { limit: 200 })).data.find((x) => x.id === key.id);
-            if (k)
-                permissions = k.tool_permissions;
+        out(ctx, text, data);
+        return 0;
+    },
+    async verify(ctx, _values, [code]) {
+        const account = ctx.account();
+        let digits = code?.replace(/\s+/g, '');
+        if (digits !== undefined && !/^[0-9]{6}$/.test(digits))
+            throw new UsageError('the code is the 6 digits from the email', 'shard verify 123456');
+        if (digits === undefined) {
+            const sent = await account.auth.requestEmailCode();
+            if (sent.status === 'verified') {
+                out(ctx, 'Your email is already verified.\n', { status: 'verified' });
+                return 0;
+            }
+            if (!ctx.input.interactive) {
+                out(ctx, 'A 6-digit code is on its way to your inbox (valid 15 minutes). Then: shard verify <code>\n', { status: 'accepted', next: 'shard verify <code>' });
+                return 0;
+            }
+            ctx.io.stderr.write('A 6-digit code is on its way to your inbox (valid 15 minutes).\n');
+            digits = ((await ctx.input.answer('Code from the email: ')) ?? '').replace(/\s+/g, '');
+            if (!/^[0-9]{6}$/.test(digits))
+                throw new UsageError('the code is the 6 digits from the email', 'shard verify <code>');
         }
-        const tag = (made) => (made ? 'created' : 'existing');
-        const envNote = ctx.io.env.SHARDFLUX_API_KEY?.trim() ? 'note: SHARDFLUX_API_KEY is set in this environment and wins over the saved key; unset it to use the saved key.\n' : '';
-        out(ctx, (keep ? 'Already set up; the saved API key works.\n' : 'Set up.\n') +
-            kv([
-                ['organization', `${org.name} (${org.slug}, ${org.id}) ${tag(created.organization)}`],
-                ['project', `${project.name} (${project.slug}, ${project.id}) ${tag(created.project)}`],
-                ['api key', `"${key.name}" ${key.key_id} (tools: ${toolsText(permissions)}) ${keep ? 'saved earlier' : 'created'}, saved in ${ctx.store.file}`],
-            ]) +
-            envNote +
-            `next: ${NEXT_WORKSPACE}\n`, {
-            organization: org,
-            project,
-            api_key: { id: key.id, key_id: key.key_id, name: key.name, project_id: key.project_id, tool_permissions: permissions },
-            created,
-            credentials_file: ctx.store.file,
-            next: NEXT_WORKSPACE,
-        });
+        await account.auth.verifyEmailCode(digits);
+        out(ctx, 'Email verified. Your session and API keys keep working; a new account gets its trial now.\n', { status: 'verified' });
         return 0;
     },
     env(ctx, values) {

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.8.1";
+export declare const CLI_VERSION = "0.9.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

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.8.1';
+export const CLI_VERSION = '0.9.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).' },
@@ -32,9 +32,9 @@ const MEMORY_ALLOCATION = {
     'allocation-mode': {
         type: 'string',
         value: '<fixed|elastic>',
-        description: 'elastic: --memory-mib is a promise; the workspace holds --memory-held while idle and the host grows it when a command needs it (needs the elastic memory entitlement). Takes effect at the next VM start. Caps given without it make the workspace fixed; a command without caps keeps the stored layout.',
+        description: 'elastic: --memory-mib is the most the workspace may grow to; it holds --memory-held while idle and grows when a command needs more, and billing counts the memory it holds. fixed: a static allocation of --memory-mib. Send it with every caps flag to keep the mode you chose; a command without caps flags keeps the stored layout. Takes effect at the next VM start (shard ws resize changes a running or suspended workspace).',
     },
-    'memory-held': { type: 'string', value: '<mib>', description: 'With --allocation-mode elastic: memory held while idle, in MiB (at least 512, default 1024, at most --memory-mib).' },
+    'memory-held': { type: 'string', value: '<mib>', description: 'Elastic: memory held while idle, in MiB (at least 512, default 1024, at most --memory-mib).' },
 };
 /** `--timing` (0.3.0+): the SDK's lifecycle timing of the command's open, wait or wake (README "Timing"). */
 const TIMING = {
@@ -61,6 +61,8 @@ const WAIT = {
     ...TIMING,
 };
 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 };
 const PAGE = {
     all: { type: 'boolean', description: 'Fetch every page.' },
@@ -252,6 +254,7 @@ const KEY_COMMANDS = [
     { path: ['workspaces', 'labels'], summary: 'Read or replace workspace labels', positionals: [REF], options: {
             set: { type: 'string', value: '<json>', description: 'Replace all labels; {} clears them.' },
         } },
+    { path: ['workspaces', 'hint'], summary: 'Stage a parked workspace ahead of an imminent tool call', positionals: [REF], options: {} },
     { path: ['workspaces', 'idle'], summary: 'Inspect idle status, set policy or declare a keepalive', positionals: [REF], options: {
             policy: { type: 'string', value: '<policy>', description: 'adaptive, never, fixed:<seconds>, or default to clear the override.' },
             keepalive: { type: 'string', value: '<seconds>', description: 'Declare ongoing work for this many seconds.' },
@@ -266,6 +269,11 @@ const KEY_COMMANDS = [
             'session-id': { type: 'string', value: '<id>', description: 'Caller-chosen id to deduplicate starts.' },
             cwd: { type: 'string', value: '<dir>', description: 'Absolute working directory.' },
             timeout: { type: 'string', value: '<duration>', description: 'Kill the command after this long (e.g. 30m, 2h; none unless set). The workspace stays awake until the command ends or this passes (1 hour when unset).' },
+            'resource-hint': {
+                type: 'string',
+                value: '<auto|light|heavy>',
+                description: 'Processful (0.9.0+): heavy gives an elastic workspace its memory before the command starts (a build, a test suite, an install); light starts it at once; auto (default) decides from the command.',
+            },
         },
         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'],
     },
@@ -310,6 +318,11 @@ const KEY_COMMANDS = [
                 description: 'File-first: the execution’s id (8-128 of A-Z a-z 0-9 . _ : -, starting with a letter or digit; default a fresh ex-<uuid>). Running the same command again with the same id returns its recorded result instead of running it twice, so scripts can repeat the call safely.',
             },
             'output-limit': { type: 'string', value: '<bytes>', description: 'File-first: keep at most this many bytes of stdout and of stderr each (1-16777216; default 1 MiB).' },
+            'resource-hint': {
+                type: 'string',
+                value: '<auto|light|heavy>',
+                description: 'Processful (0.9.0+): heavy gives an elastic workspace its memory before the command starts (a build, a test suite, an install); light starts it at once; auto (default) decides from the command.',
+            },
             burst: {
                 type: 'boolean',
                 description: 'Processful: run this command on a larger, short-lived burst VM on the workspace’s host and apply its file changes back when it exits (needs the burst execution entitlement). Its processes and tmpfs content do not come back; the workspace’s own processes pause meanwhile. Not with --stdin; cannot be canceled.',
@@ -329,6 +342,7 @@ const KEY_COMMANDS = [
             'shard ws exec acme/agent-7 -v --execution-id build-42 --timeout 10m -- bash -lc "make -C /home/user/app"',
             'shard ws exec acme/agent-7 --json -- python3 /home/user/report.py > result.json',
             'shard ws exec acme/demo --burst --burst-vcpus 16 -v -- bash -lc "cd /home/user/app && go build ./..."',
+            'shard ws exec acme/demo --resource-hint heavy -- python3 train.py',
         ],
     },
     {
@@ -351,6 +365,23 @@ const KEY_COMMANDS = [
         positionals: [REF, { name: 'new-key', required: true }],
         options: { ...CAPS, ...MEMORY_ALLOCATION, ...WAIT },
     },
+    {
+        path: ['workspaces', 'resize'],
+        summary: 'Change a workspace’s memory, CPU or disk, running or suspended, without a restart (0.9.0+)',
+        description: 'Memory changes live and disks grow online; a suspended workspace gets its new size when it resumes, before its first call. CPU changes live within the vCPUs the workspace booted with; a larger CPU size applies at the next start. The new caps are stored, so every later start uses them. Prints per resource the change and when it applies: now, on resume or next start. Waits until the resize has finished.',
+        positionals: [REF],
+        options: {
+            memory: { type: 'string', value: '<mib>', description: 'Memory in MiB: the size of a fixed workspace, the most an elastic one may grow to.' },
+            held: { type: 'string', value: '<mib>', description: 'Elastic: the memory held while idle, in MiB (at most the memory size).' },
+            fixed: { type: 'boolean', description: 'Switch to a static allocation of the memory size.' },
+            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).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m); the resize continues server side.' },
+            ...TIMING,
+        },
+        examples: ['shard ws resize acme/demo --memory 6144', 'shard ws resize acme/demo --memory 8192 --cpu 4000 --disk 40', 'shard ws resize acme/demo --elastic --held 1024', 'shard ws resize acme/demo --memory 4096 --fixed --json'],
+    },
     {
         path: ['workspaces', 'delete'],
         summary: 'Delete a workspace (tool access ends now; storage is cleaned up asynchronously)',
@@ -410,6 +441,49 @@ const KEY_COMMANDS = [
         },
         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: ['workspaces', 'port', 'expose'],
+        summary: 'Serve a port of a workspace at its own private HTTPS URL (0.9.0+)',
+        description: 'Requests to the URL reach TCP <port> inside the workspace; a request to a parked or suspended workspace wakes it and is answered once it runs. Every port is private: a request carries a port token (shard ws port token), a browser link’s session (shard ws port link) or arrives on the callback URL (shard ws port callback). The server inside the workspace listens on 0.0.0.0. Idempotent: an exposed port keeps its URL, tokens, links and callback URL. --json prints the API’s port object {port, url, created_at, callback}.',
+        positionals: [REF, PORT],
+        options: {},
+        examples: ['shard ws port expose acme/demo 3000', 'curl -H "Authorization: Bearer $(shard ws port token acme/demo 3000)" "$(shard ws port expose acme/demo 3000 --json | jq -r .url)/"'],
+    },
+    { path: ['workspaces', 'port', 'ls'], summary: 'List the exposed ports of a workspace and their URLs (0.9.0+)', positionals: [REF], options: {} },
+    {
+        path: ['workspaces', 'port', 'close'],
+        summary: 'Close an exposed port: its tokens, links and callback URL stop working at once (0.9.0+)',
+        description: 'Idempotent (also when the port is not exposed). Exposing the port again gives it new tokens, links and callback URL; the URL stays the same.',
+        positionals: [REF, PORT],
+        options: {},
+    },
+    {
+        path: ['workspaces', 'port', 'token'],
+        summary: 'Mint a port token and print it alone on stdout (0.9.0+)',
+        description: 'Send it as `Authorization: Bearer <token>` (or `X-Shardflux-Token: <token>` when the app reads Authorization itself) with requests to the port’s URL. Closing the port revokes it. --json prints {token, expires_at, url}.',
+        positionals: [REF, PORT],
+        options: { ttl: { type: 'string', value: '<duration>', description: 'Lifetime, 1m to 24h (e.g. 15m, 2h; default 1h).' } },
+        examples: ['TOKEN=$(shard ws port token acme/demo 3000 --ttl 15m)', 'shard ws port token acme/demo 3000 --json | jq -r .token'],
+    },
+    {
+        path: ['workspaces', 'port', 'link'],
+        summary: 'Create a link that opens the port in a browser and print it (0.9.0+)',
+        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: {
+            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 /).' },
+        },
+        examples: ['shard ws port link acme/demo 3000 --path /dashboard', 'open "$(shard ws port link acme/demo 3000)"'],
+    },
+    {
+        path: ['workspaces', 'port', 'callback'],
+        summary: 'Create (or replace) the port’s callback URL for webhooks and OAuth redirects, or revoke it (0.9.0+)',
+        description: 'Register the printed URL plus your own path with GitHub, Slack, Stripe or an OAuth provider: a request to <url><rest> reaches /<rest> of the port (query kept) without a token header and wakes the workspace like any request. The URL is shown only once; creating it again replaces it (the previous one stops working). --json prints {url, created_at}.',
+        positionals: [REF, PORT],
+        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'],
+    },
     {
         path: ['files', 'read'],
         summary: 'Print (or save) a file from a workspace',
@@ -785,6 +859,7 @@ const GROUPS = {
     egress: 'Outbound network policies of the project and its workspaces (project API key)',
     volumes: 'Shared volumes: persistent storage attached to workspaces (project API key)',
     workspaces: 'Open, inspect and manage workspaces',
+    'workspaces port': 'Serve ports of a workspace at private HTTPS URLs: expose, list, close, tokens, browser links and callback URLs (0.9.0+)',
     files: 'Read, write, list, search and patch files in a workspace',
     operations: 'Inspect and wait for lifecycle operations',
     executions: 'Fetch the results of file-first executions (the commands "shard ws exec" runs in file-first workspaces)',
@@ -811,6 +886,7 @@ const ALIASES = {
     invite: 'invitations',
     invites: 'invitations',
     volume: 'volumes',
+    ports: 'port',
 };
 /** Groups also reachable under `workspaces` (`shard workspaces files read ...` == `shard files read ...`). */
 const FOLDED = new Set(['files', 'operations', 'executions']);
@@ -1111,7 +1187,7 @@ export const EXIT_CODE_HELP = [
 ];
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
-    { title: 'Account (a user session: shard auth login)', groups: ['auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
+    { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
     { title: 'Workspaces (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'volumes', 'egress'] },
     { title: 'Templates (publish and archive use the session; the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['feedback', 'version'] },

package/dist/commands.d.ts

@@ -100,5 +100,19 @@ export declare function principal(ctx: Ctx): Promise<{
 }>;
 /** The exit code `shard exec` returns for a finished command. */
 export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'>): 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
+ * with its hint like the API's own refusal.
+ */
+/** `<port>` of the port commands: a TCP port number, 1-65535. */
+export declare function portArg(text: string): number;
+/** `--ttl <duration>` of port tokens and links: whole seconds within the API's bounds (undefined: the API's default). */
+export declare function ttlSeconds(values: Values, b: {
+    option: string;
+    min: number;
+    max: number;
+    range: string;
+}): number | undefined;
 /** The project-key commands; handlers.ts adds the account plane's. */
 export declare const KEY_HANDLERS: Record<string, Handler>;