@shardflux/cli 0.8.1 → 0.9.0

package/dist/commands.js

@@ -16,7 +16,7 @@ import { updateCheckDisabled } from "./update-check.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, resizeJson, resizeText, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, exposedPortText, portTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, time, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
@@ -67,6 +67,35 @@ function caps(values) {
     return Object.keys(c).length ? c : undefined;
 }
 const ALLOCATION_MODES = ['fixed', 'elastic'];
+/** `--resource-hint` of `workspaces exec` / `exec-start` (0.9.0): the exec's memory hint. */
+const RESOURCE_HINTS = ['auto', 'light', 'heavy'];
+/** The resources of `workspaces resize` (0.9.0): at least one, validated before any request. */
+function resizeParams(values) {
+    const p = {};
+    const memory = str(values.memory);
+    const held = str(values.held);
+    const cpu = str(values.cpu);
+    const disk = str(values.disk);
+    if (values.fixed === true && values.elastic === true)
+        throw new UsageError('--fixed and --elastic cannot be combined');
+    if (held !== undefined && values.fixed === true)
+        throw new UsageError('--held applies to elastic memory (a fixed workspace holds all of its memory)');
+    if (memory !== undefined)
+        p.memoryMib = parsePositiveInt(memory, 'memory', 16_777_216);
+    if (held !== undefined)
+        p.memoryMibHeld = parsePositiveInt(held, 'held', 16_777_216);
+    if (values.fixed === true)
+        p.allocationMode = 'fixed';
+    if (values.elastic === true)
+        p.allocationMode = 'elastic';
+    if (cpu !== undefined)
+        p.cpuMillis = parsePositiveInt(cpu, 'cpu', 1_000_000);
+    if (disk !== undefined)
+        p.diskGib = parsePositiveInt(disk, 'disk', 1_000_000);
+    if (Object.keys(p).length === 0)
+        throw new UsageError('nothing to resize: give --memory, --held, --fixed, --elastic, --cpu or --disk');
+    return p;
+}
 /**
  * The caps of `workspaces open` and `workspaces fork` (0.8.0): the resource caps plus the memory allocation. Given caps
  * replace the stored ones, so they are sent only when a flag was given.
@@ -75,8 +104,9 @@ function workspaceCaps(values) {
     const c = caps(values) ?? {};
     const mode = oneOf(values, 'allocation-mode', ALLOCATION_MODES);
     const held = str(values['memory-held']);
-    if (held !== undefined && mode !== 'elastic')
-        throw new UsageError('--memory-held needs --allocation-mode elastic (a fixed workspace holds all of --memory-mib)');
+    // Without --allocation-mode the API decides whether the workspace is elastic (requires_elastic when it is not).
+    if (held !== undefined && mode === 'fixed')
+        throw new UsageError('--memory-held applies to elastic memory (a fixed workspace holds all of --memory-mib)');
     if (mode !== undefined)
         c.allocation_mode = mode;
     if (held !== undefined)
@@ -566,6 +596,35 @@ function treeRevisionAfter(ws, cell) {
  * 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 function portArg(text) {
+    if (!/^\d{1,5}$/.test(text) || Number(text) < 1 || Number(text) > 65_535)
+        throw new UsageError(`<port> must be a TCP port number between 1 and 65535 (got "${text}")`);
+    return Number(text);
+}
+const PORT_TOKEN_TTL = { option: 'ttl', min: 60, max: 86_400, range: '1m and 24h' };
+const PORT_LINK_TTL = { option: 'ttl', min: 60, max: 604_800, range: '1m and 7d' };
+/** `--ttl <duration>` of port tokens and links: whole seconds within the API's bounds (undefined: the API's default). */
+export function ttlSeconds(values, b) {
+    const text = str(values[b.option]);
+    if (text === undefined)
+        return undefined;
+    const ms = parseDuration(text, b.option);
+    if (ms % 1000 !== 0)
+        throw new UsageError(`--${b.option} must be a whole number of seconds (e.g. 15m, 2h)`);
+    const seconds = ms / 1000;
+    if (seconds < b.min || seconds > b.max)
+        throw new UsageError(`--${b.option} must be between ${b.range} (got "${text}")`);
+    return seconds;
+}
+/** The workspace of a port command; a file-first workspace has no ports (refused before any port request). */
+async function portWorkspace(ctx, ref) {
+    const ws = await resolveWorkspace(ctx, ref);
+    requireProcessful(ws, 'inbound_ports', 'Serving a port');
+    return ws;
+}
+/** A port as the API sends it (`--json`). */
+const portJson = (p) => ({ port: p.port, url: p.url, created_at: p.createdAt, callback: p.callback ? { created_at: p.callback.createdAt } : null });
 function requireProcessful(ws, operation, what) {
     if (ws.mode !== 'file_first')
         return;
@@ -683,6 +742,12 @@ export const KEY_HANDLERS = {
         out(ctx, JSON.stringify(ws.labels, null, 2) + '\n', ws.labels);
         return 0;
     },
+    async 'workspaces hint'(ctx, _values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const result = await ws.cell({ wake: null }).wakeHint(ctx.signal);
+        out(ctx, JSON.stringify(result, null, 2) + '\n', result);
+        return 0;
+    },
     async 'workspaces idle'(ctx, values, [ref]) {
         const ws = await resolveWorkspace(ctx, ref);
         const policy = str(values.policy);
@@ -702,8 +767,10 @@ export const KEY_HANDLERS = {
     async 'workspaces exec-start'(ctx, values, [ref, ...argv]) {
         const timeout = str(values.timeout);
         const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
+        const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
         const ws = await resolveWorkspace(ctx, ref);
         const session = await cellOf(ctx, ws).exec.start({ argv, stdin_open: values['stdin-open'] === true,
+            ...(resourceHint !== undefined ? { resource_hint: resourceHint } : {}),
             ...(str(values['session-id']) ? { session_id: str(values['session-id']) } : {}), ...(str(values.cwd) ? { cwd: str(values.cwd) } : {}),
             ...(timeoutMs !== undefined ? { timeout_ms: timeoutMs } : {}) }, ctx.signal);
         out(ctx, JSON.stringify(session, null, 2) + '\n', session);
@@ -878,6 +945,7 @@ export const KEY_HANDLERS = {
         const outputLimit = limitText === undefined ? undefined : parsePositiveInt(limitText, 'output-limit', MAX_OUTPUT_LIMIT);
         const stdinSource = str(values.stdin);
         const burst = burstOptions(values, stdinSource !== undefined);
+        const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
         const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
         const ws = await resolveWorkspace(ctx, ref);
         const cell = cellOf(ctx, ws);
@@ -885,6 +953,8 @@ export const KEY_HANDLERS = {
         if (ws.mode === 'file_first') {
             if (burst)
                 throw new UsageError(`--burst applies to processful workspaces only; ${ws.key} is ${modeText(ws.mode)}`);
+            if (resourceHint)
+                throw new UsageError(`--resource-hint applies to processful workspaces only; ${ws.key} is ${modeText(ws.mode)} (each execution runs in a fresh VM)`);
             // An execution: answered when the command ended. The id is ours, so Ctrl-C can name it.
             const id = executionId ?? newExecutionId();
             let r;
@@ -920,6 +990,7 @@ export const KEY_HANDLERS = {
                 ...(Object.keys(env).length ? { env } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(stdin !== undefined ? { stdin } : {}),
+                ...(resourceHint !== undefined ? { resourceHint } : {}),
                 ...(burst ?? {}),
                 maxOutputBytes: ctx.json ? MAX_JSON_OUTPUT : 0,
                 ...(ctx.json ? {} : { onOutput: (stream, chunk) => void (stream === 'stderr' ? ctx.io.stderr : ctx.io.stdout).write(chunk) }),
@@ -1642,6 +1713,16 @@ export const KEY_HANDLERS = {
         out(ctx, lifecycleText(`Forking ${source.key} into`, res.workspace, op), { operation: op, workspace: res.workspace.data });
         return 0;
     },
+    // Resize (0.9.0+): PATCH /v1/workspaces/{id}/caps through the SDK, which waits until the resize has finished.
+    async 'workspaces resize'(ctx, values, [ref]) {
+        const params = resizeParams(values);
+        const timeoutMs = waitTimeout(values);
+        const ws = await resolveWorkspace(ctx, ref);
+        requireProcessful(ws, 'resize', 'Resize');
+        const r = await waited(ctx, 'the resize continues server side.', () => ws.resize({ ...params, timeoutMs, signal: ctx.signal }));
+        out(ctx, resizeText(ws, r), resizeJson(r));
+        return 0;
+    },
     async 'workspaces sessions'(ctx, _values, [ref]) {
         const ws = await resolveWorkspace(ctx, ref);
         const sessions = [];
@@ -1654,6 +1735,66 @@ export const KEY_HANDLERS = {
         out(ctx, sessions.length ? sessionTable(sessions) : 'No agent sessions (no tool token was issued for this workspace yet).\n', { data: sessions });
         return 0;
     },
+    // ---- inbound ports (0.9.0; contracts §39.3) ----
+    async 'workspaces port expose'(ctx, _values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        const p = await ws.ports.expose(port);
+        out(ctx, exposedPortText(ws, p), portJson(p));
+        return 0;
+    },
+    async 'workspaces port ls'(ctx, _values, [ref]) {
+        const ws = await portWorkspace(ctx, ref);
+        const ports = await ws.ports.list();
+        out(ctx, portTable(ws, ports), { ports: ports.map(portJson) });
+        return 0;
+    },
+    async 'workspaces port close'(ctx, _values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        await ws.ports.close(port);
+        out(ctx, `Closed port ${port} of ${ws.key} (${ws.id}): its tokens, links and callback URL no longer work.\n`, { workspace_id: ws.id, port, closed: true });
+        return 0;
+    },
+    async 'workspaces port token'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ttl = ttlSeconds(values, PORT_TOKEN_TTL);
+        const ws = await portWorkspace(ctx, ref);
+        const t = await ws.ports.token(port, ttl !== undefined ? { ttlSeconds: ttl } : {});
+        out(ctx, `${t.token}\n`, { token: t.token, expires_at: t.expiresAt, url: t.url });
+        // The token alone on stdout (for $(...)); how to use it on stderr.
+        if (!ctx.json)
+            ctx.io.stderr.write(`Port token for ${t.url}, valid until ${time(t.expiresAt)}: send it as "Authorization: Bearer <token>".\n`);
+        return 0;
+    },
+    async 'workspaces port link'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ttl = ttlSeconds(values, PORT_LINK_TTL);
+        const path = str(values.path);
+        if (path !== undefined && !path.startsWith('/'))
+            throw new UsageError(`--path must start with / (got "${path}")`);
+        const ws = await portWorkspace(ctx, ref);
+        const l = await ws.ports.link(port, { ...(ttl !== undefined ? { ttlSeconds: ttl } : {}), ...(path !== undefined ? { path } : {}) });
+        out(ctx, `${l.url}\n`, { url: l.url, expires_at: l.expiresAt });
+        if (!ctx.json)
+            ctx.io.stderr.write(`Opens port ${port} of ${ws.key} in a browser until ${time(l.expiresAt)}; anyone with the link can open it until then.\n`);
+        return 0;
+    },
+    async 'workspaces port callback'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        if (values.revoke === true) {
+            await ws.ports.revokeCallbackUrl(port);
+            out(ctx, `Revoked the callback URL of port ${port} of ${ws.key} (${ws.id}).\n`, { workspace_id: ws.id, port, revoked: true });
+            return 0;
+        }
+        const c = await ws.ports.createCallbackUrl(port);
+        out(ctx, `${c.url}\n`, { url: c.url, created_at: c.createdAt });
+        if (!ctx.json) {
+            ctx.io.stderr.write(`Callback URL of port ${port} of ${ws.key}: register it plus your own path (e.g. ${c.url}webhooks/github) with your webhook or OAuth provider; a request to it reaches /<path> of the port without a token. It is shown only now; running this again replaces it, --revoke removes it.\n`);
+        }
+        return 0;
+    },
     async 'workspaces secrets'(ctx, values, [ref]) {
         const set = secretNames(strs(values.set), '--set');
         const clear = values.clear === true;

package/dist/format.d.ts

@@ -1,5 +1,14 @@
-import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, TemplateVersion, WorkspaceChange, WorkspaceSecretBindings, WorkspaceMemory, WorkspaceView, MemoryGrow, BurstSummary } from '@shardflux/sdk';
+import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, TemplateVersion, WorkspaceChange, WorkspaceSecretBindings, WorkspaceMemory, WorkspaceView, MemoryGrow, BurstSummary, ResizeResult, ExposePortResult, ExposedPort } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
+/** A workspace as the port commands name it. */
+interface PortWorkspace {
+    key: string;
+    id: string;
+}
+/** `shard ws port expose` (0.9.0): the URL, and how a request gets in. */
+export declare function exposedPortText(w: PortWorkspace, p: ExposePortResult): string;
+/** `shard ws port ls` (0.9.0). */
+export declare function portTable(w: PortWorkspace, ports: readonly ExposedPort[]): string;
 /** A size for people: `512 B`, `10.0 KiB`, `128.0 MiB`, `1.50 GiB`. */
 export declare function byteSize(n: number): string;
 export declare function json(value: unknown): string;
@@ -35,6 +44,17 @@ export declare function suspendWhenIdleText(w: {
     suspend_request: SuspendRequest | null;
     operation: Operation | null;
 }): string;
+/**
+ * `shard ws resize` (0.9.0): per resource the change and when it applies, e.g.
+ * `memory  2048 → 6144 MiB  now` / `cpu     2000 → 4000 millis  next start (boot vCPUs)`, plus what was clamped or
+ * applied in part (requested above a limit, a partial grow, a shrink the guest did not finish).
+ */
+export declare function resizeText(w: {
+    key: string;
+    id: string;
+}, r: ResizeResult): string;
+/** `shard ws resize --json`: the API's result (only the resources the request named), the stored caps, and the operation when one was waited for. */
+export declare function resizeJson(r: ResizeResult): Record<string, unknown>;
 /** `fixed 4096 MiB`, or `elastic: promised 8192 MiB, held 1024 MiB, plugged +2048 MiB` (plugged: above the held floor now). */
 export declare function memoryText(m: WorkspaceMemory): string;
 /** The grow an exec's start waited for: `delivered 1024 -> 4096 MiB in 175 ms`, `partial 1024 -> 3072 of 4096 MiB in 175 ms`. */

package/dist/format.js

@@ -4,6 +4,18 @@
  * these functions only shape what people read.
  */
 import { durabilityOf, isDurable } from '@shardflux/sdk';
+/** `shard ws port expose` (0.9.0): the URL, and how a request gets in. */
+export function exposedPortText(w, p) {
+    return (`${p.created ? `Exposed port ${p.port} of ${w.key} (${w.id})` : `Port ${p.port} of ${w.key} (${w.id}) is exposed`}: ${p.url}\n` +
+        `Requests need a token (shard ws port token ${w.key} ${p.port}), a browser link (shard ws port link ${w.key} ${p.port}) or the callback URL (shard ws port callback ${w.key} ${p.port}).\n` +
+        `The server in the workspace listens on 0.0.0.0:${p.port}.\n`);
+}
+/** `shard ws port ls` (0.9.0). */
+export function portTable(w, ports) {
+    if (ports.length === 0)
+        return `No ports of ${w.key} (${w.id}) are exposed; expose one with: shard ws port expose ${w.key} <port>\n`;
+    return table(['PORT', 'URL', 'EXPOSED', 'CALLBACK URL'], ports.map((p) => [String(p.port), p.url, time(p.createdAt), p.callback ? `created ${time(p.callback.createdAt)}` : '-']));
+}
 /** A size for people: `512 B`, `10.0 KiB`, `128.0 MiB`, `1.50 GiB`. */
 export function byteSize(n) {
     return n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(2)} GiB`;
@@ -133,6 +145,55 @@ export function suspendWhenIdleText(w, r) {
     return `A suspend of ${w.key} (${w.id}) is already in progress (operation ${op.id} ${op.kind} ${op.state}); nothing was scheduled.\nwait with: shard operations wait ${op.id}\n`;
 }
 const mib = (n) => (n === null ? '-' : `${n} MiB`);
+const APPLIES_AT = { now: 'now', resume: 'on resume', next_start: 'next start' };
+const LIMIT_TEXT = { plan: 'plan limit', template: 'template limit', host_capacity: 'host capacity', shrink_stalled: 'the guest kept memory in use' };
+/** Why a resource applies later; `suspended` and `stopped` are what `on resume` / `next start` already say. */
+const deferText = (r) => (r === null || r === 'suspended' || r === 'stopped' ? '' : r === 'boot_vcpus' ? ' (boot vCPUs)' : ` (${r.replace(/_/g, ' ')})`);
+/**
+ * `shard ws resize` (0.9.0): per resource the change and when it applies, e.g.
+ * `memory  2048 → 6144 MiB  now` / `cpu     2000 → 4000 millis  next start (boot vCPUs)`, plus what was clamped or
+ * applied in part (requested above a limit, a partial grow, a shrink the guest did not finish).
+ */
+export function resizeText(w, r) {
+    const rows = [];
+    const row = (name, unit, x, extra = '', converged = null) => {
+        const notes = [];
+        if (x.requested !== null && x.target !== null && x.requested !== x.target)
+            notes.push(`requested ${x.requested} ${unit}${x.limit === 'plan' || x.limit === 'template' ? `, ${LIMIT_TEXT[x.limit]}` : ''}`);
+        if (x.applies_at === 'now' && x.applied !== null && x.applied !== x.target)
+            notes.push(`${x.applied} ${unit} applied${x.limit === 'host_capacity' || x.limit === 'shrink_stalled' ? `: ${LIMIT_TEXT[x.limit]}` : ''}`);
+        else if (converged === false)
+            notes.push('not converged');
+        rows.push([name, `${x.previous ?? '-'} → ${x.target ?? '-'} ${unit}${extra}`, `${APPLIES_AT[x.applies_at]}${deferText(x.reason)}${notes.length ? `; ${notes.join('; ')}` : ''}`]);
+    };
+    const m = r.memory;
+    if (m) {
+        const extra = m.allocation_mode === 'elastic' ? ` elastic${m.held_mib !== null ? `, held ${m.held_mib} MiB` : ''}` : '';
+        row('memory', 'MiB', { applies_at: m.applies_at, requested: m.requested_mib, target: m.target_mib, previous: m.previous_mib, applied: m.applied_mib, limit: m.limit_reason, reason: m.reason }, extra, m.converged);
+    }
+    const c = r.cpu;
+    if (c)
+        row('cpu', 'millis', { applies_at: c.applies_at, requested: c.requested_millis, target: c.target_millis, previous: c.previous_millis, applied: c.applied_millis, limit: c.limit_reason, reason: c.reason });
+    const d = r.disk;
+    if (d)
+        row('disk', 'GiB', { applies_at: d.applies_at, requested: d.requested_gib, target: d.target_gib, previous: d.previous_gib, applied: d.applied_gib, limit: d.limit_reason, reason: d.reason });
+    const width = Math.max(0, ...rows.map(([, change]) => change.length));
+    const lines = rows.map(([name, change, when]) => `${name.padEnd(6)}  ${change.padEnd(width)}  ${when}`);
+    return `Resized ${w.key} (${w.id}), ${r.state}:\n${lines.map((l) => `${l}\n`).join('')}`;
+}
+/** `shard ws resize --json`: the API's result (only the resources the request named), the stored caps, and the operation when one was waited for. */
+export function resizeJson(r) {
+    return {
+        workspace_id: r.workspaceId,
+        operation_id: r.operationId,
+        state: r.state,
+        ...(r.memory ? { memory: r.memory } : {}),
+        ...(r.cpu ? { cpu: r.cpu } : {}),
+        ...(r.disk ? { disk: r.disk } : {}),
+        caps: r.caps,
+        ...(r.operation ? { operation: r.operation } : {}),
+    };
+}
 /** `fixed 4096 MiB`, or `elastic: promised 8192 MiB, held 1024 MiB, plugged +2048 MiB` (plugged: above the held floor now). */
 export function memoryText(m) {
     if (m.allocation_mode !== 'elastic')

package/dist/main.js

@@ -104,6 +104,11 @@ function hintFor(info, cred, file) {
         return 'the workspace cannot be woken right now and the call did not run; retry in a few seconds';
     if (reason === 'host_feature_unavailable')
         return hostFeatureHint(info.details?.feature);
+    // Inbound ports (0.9.0): the next step names the command.
+    if (reason === 'port_not_exposed')
+        return `expose it first: shard ws port expose <id|key> ${typeof info.details?.port === 'number' ? info.details.port : '<port>'}`;
+    if (reason === 'port_limit')
+        return 'close a port first (shard ws port ls <id|key>, then shard ws port close <id|key> <port>)';
     // A processful command that could not start (0.5.1): what to change, from the workspace's reason.
     if (info.code === 'conflict' && reason === 'exec_failed_to_start')
         return startFailureHint(typeof info.details?.error === 'string' ? info.details.error : info.message, false);
@@ -312,6 +317,9 @@ const NO_NUDGE_REASONS = new Set([
     'version_mismatch',
     // A write under an immutable path (0.8.0): the hint says where to change it.
     'read_only_path',
+    // Inbound ports (0.9.0): the hint names the command to expose or close a port.
+    'port_not_exposed',
+    'port_limit',
 ]);
 /**
  * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.13.1"
+    "@shardflux/sdk": "^0.14.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",