@shardflux/cli 0.4.1 → 0.5.1

package/dist/format.js

@@ -44,9 +44,15 @@ export function operationSummary(op) {
     return `${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}`;
 }
 export const WORKSPACE_HEADERS = ['ID', 'KEY', 'STATE', 'DESIRED', 'TEMPLATE', 'OPERATION', 'CREATED'];
-/** Observed state plus what sets the workspace apart: session, draft or test instance, and how it ended. */
+/** `file_first` as people write it (`--mode file-first`). */
+export function modeText(mode) {
+    return mode === 'file_first' ? 'file-first' : (mode ?? 'processful');
+}
+/** Observed state plus what sets the workspace apart: file-first, session, draft or test instance, and how it ended. */
 export function workspaceState(w) {
     const tags = [];
+    if (w.mode === 'file_first')
+        tags.push('file-first');
     if (w.purpose === 'template_draft')
         tags.push('draft');
     else if (w.purpose === 'template_test')
@@ -101,21 +107,41 @@ export function startupTail(s) {
     const lines = s.output_tail.replace(/\n$/, '').split('\n');
     return `startup output (last ${Buffer.byteLength(s.output_tail)} bytes):\n${lines.map((l) => `  | ${l}`).join('\n')}\n`;
 }
+/** A pending suspend-when-idle request in one line (0.5.1; contracts §20.6). */
+export function suspendRequestText(r) {
+    return `after ${r.after_seconds} s idle, not before ${time(r.not_before)} (requested ${time(r.requested_at)})`;
+}
+/** `shard ws suspend --when-idle`: the recorded request, or the suspend already in progress. */
+export function suspendWhenIdleText(w, r) {
+    if (r.suspend_request) {
+        const s = r.suspend_request;
+        return (`Suspend when idle: ${w.key} (${w.id}) is suspended once it has been idle for ${s.after_seconds} s, not before ${time(s.not_before)}.\n` +
+            'A running command, an attached stream or a keepalive postpones it; the next tool call or a resume cancels it.\n' +
+            `cancel with: shard workspaces suspend ${w.key} --cancel-when-idle\n`);
+    }
+    const op = r.operation;
+    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`;
+}
 export function workspaceDetail(w) {
     const c = w.ceilings;
     const startup = startupText(w.startup);
+    const suspendRequest = w.idle?.suspend_request;
     return kv([
         ['id', w.id],
         ['key', w.workspace_key],
         ['state', `${w.observed_state} (desired ${w.desired_state})`],
         ['ready', isReady(w) ? 'yes' : 'no'],
         ['template', `${w.template.slug} v${w.template.version} (${w.template.version_id})`],
+        // The mode (0.5.0; contracts §29) when the API reports it; a file-first workspace's state is its tree revision.
+        ...(w.mode !== undefined ? [['mode', modeText(w.mode)]] : []),
+        ...(w.mode === 'file_first' ? [['tree revision', String(w.tree_revision)]] : []),
         ['cell', w.cell_id ? `${w.cell_id} ${w.cell_endpoint ?? '(endpoint unresolved)'}` : '-'],
         ['ceilings', c ? `cpu ${c.cpu_millis}m (${c.sources.cpu_millis}), memory ${c.memory_mib} MiB (${c.sources.memory_mib}), disk ${c.disk_gib} GiB (${c.sources.disk_gib})` : '-'],
         ['grants', pairs(w.grants)],
         ['caps', pairs(w.caps)],
         ['operation', w.active_operation ? `${operationSummary(w.active_operation)} ${w.active_operation.id}` : '-'],
         ['pending', w.pending_reason ?? '-'],
+        ...(suspendRequest ? [['suspend when idle', suspendRequestText(suspendRequest)]] : []),
         ...(startup ? [['startup', startup]] : []),
         ['forked from', w.forked_from_workspace_id ?? '-'],
         ...(w.lifetime !== undefined
@@ -152,6 +178,31 @@ export function operationDetail(op) {
 export function sessionTable(sessions) {
     return table(['ID', 'LABEL', 'PRINCIPAL', 'TOKENS', 'LAST TOKEN', 'REVOKED'], sessions.map((s) => [s.id, s.agent_label, `${s.principal_type}:${s.principal_id}`, String(s.tokens_issued), time(s.last_token_issued_at), time(s.revoked_at)]));
 }
+/** `files stat`: one path's metadata; the revision only when requested and returned. */
+export function fileInfoText(f) {
+    return kv([
+        ['path', f.path],
+        ['type', f.type],
+        ['size', String(f.size)],
+        ['mode', f.mode],
+        ['owner', f.uid !== undefined || f.gid !== undefined ? `${f.uid ?? '-'}:${f.gid ?? '-'}` : '-'],
+        ['modified', time(f.modified_at)],
+        ...(f.symlink_target !== undefined ? [['target', f.symlink_target]] : []),
+        ...(f.revision !== undefined ? [['revision', f.revision]] : []),
+    ]);
+}
+/** `files search`: grep-style `path:line:column: text`, context lines as `path-line- text`. */
+export function searchText(r) {
+    if (r.matches.length === 0)
+        return 'No matches.\n';
+    const lines = [];
+    for (const m of r.matches) {
+        (m.before ?? []).forEach((t, i, all) => lines.push(`${m.path}-${m.line - all.length + i}- ${t}`));
+        lines.push(`${m.path}:${m.line}:${m.column}: ${m.text}`);
+        (m.after ?? []).forEach((t, i) => lines.push(`${m.path}-${m.line + i + 1}- ${t}`));
+    }
+    return `${lines.join('\n')}\n`;
+}
 export function fileTable(list) {
     return table(['TYPE', 'SIZE', 'MODIFIED', 'NAME'], list.entries.map((e) => [e.type, String(e.size), time(e.modified_at), e.name]));
 }
@@ -198,10 +249,66 @@ function objectTable(rows, columns) {
     const cols = columns.filter(([k]) => objs.some((o) => k in o));
     return table(cols.map(([, h]) => h), objs.map((o) => cols.map(([k]) => (k === 'percent_used' && typeof o[k] === 'number' ? `${o[k]}%` : scalar(o[k])))));
 }
-const USAGE_KNOWN = new Set(['plan', 'period', 'measurement', 'allowance_exhausted', 'meters', 'allowances', 'exhausted', 'alert_thresholds']);
+const USAGE_KNOWN = new Set(['plan', 'period', 'measurement', 'allowance_exhausted', 'exhausted_reason', 'egress_override', 'meters', 'allowances', 'exhausted', 'alert_thresholds', 'spend_cap']);
+/** Minor units as money (the overage block): `$3.00` for usd, else `3.00 EUR`. A fractional minor amount (a sub-cent rate) keeps its digits. */
+export function capMoney(minor, currency) {
+    if (typeof minor !== 'number')
+        return '-';
+    const major = minor / 100;
+    const digits = Number.isInteger(minor) ? 2 : Math.min(6, Math.max(2, String(major).split('.')[1]?.length ?? 2));
+    const n = major.toFixed(digits);
+    return currency.toLowerCase() === 'usd' ? `$${n}` : `${n} ${currency.toUpperCase()}`;
+}
+/** What each spend_cap.state means for the reader (API contract: SpendCap.state). */
+const OVERAGE_STATES = {
+    unavailable: 'not available on this plan',
+    off: 'starts are refused once an allowance is used up; an owner or billing member can turn overage on under Usage & billing',
+    paused: 'a plan payment is past due; overage resumes once it is paid',
+    within_allowance: 'on, no usage past the allowances yet',
+    accruing: 'usage past the allowances is charged on the next invoice',
+    warning: '80% or more of the spend cap is used',
+    reached: 'the spend cap is reached: new opens/resumes are refused and running workspaces are suspended',
+};
+/**
+ * The opt-in overage block (0.5.1; `spend_cap` of the summary, SDK 0.10.0): state, cap, charges of the cap, the
+ * projected date the cap is reached, and per allowance the units past it and their amount. Empty without spend_cap
+ * (an API older than overage).
+ */
+function spendCapText(cap) {
+    if (!isObject(cap) || typeof cap.state !== 'string')
+        return '';
+    const cur = typeof cap.currency === 'string' ? cap.currency : 'usd';
+    const rows = [['overage', `${cap.state}${OVERAGE_STATES[cap.state] ? ` (${OVERAGE_STATES[cap.state]})` : ''}`]];
+    if (cap.state === 'unavailable')
+        return kv(rows);
+    const charges = typeof cap.charges_minor === 'number' ? cap.charges_minor : 0;
+    if (cap.state !== 'off') {
+        const plan = typeof cap.max_cap_minor === 'number' ? capMoney(cap.max_cap_minor, cur) : undefined;
+        if (cap.cap_minor === null || cap.cap_minor === undefined)
+            rows.push(['spend cap', `not set: ${capMoney(cap.effective_cap_minor, cur)}${plan ? ' (the plan price)' : ''} applies`]);
+        else if (typeof cap.effective_cap_minor === 'number' && typeof cap.cap_minor === 'number' && cap.effective_cap_minor < cap.cap_minor) {
+            rows.push(['spend cap', `${capMoney(cap.cap_minor, cur)}, lowered to ${capMoney(cap.effective_cap_minor, cur)}${plan ? ' (the plan price)' : ''}`]);
+        }
+        else
+            rows.push(['spend cap', `${capMoney(cap.cap_minor, cur)}${plan ? ` (at most ${plan}, the plan price)` : ''}`]);
+    }
+    if (cap.state !== 'off' || charges > 0) {
+        const percent = typeof cap.percent_of_cap === 'number' ? ` (${cap.percent_of_cap}%)` : '';
+        rows.push(['overage charges', `${capMoney(charges, cur)} of ${capMoney(cap.effective_cap_minor, cur)}${percent}, ${capMoney(cap.remaining_minor, cur)} left; billed on the next invoice`]);
+    }
+    if (typeof cap.projected_reached_at === 'string')
+        rows.push(['cap reached', `${time(cap.projected_reached_at)} (projected at this period's average use)`]);
+    let out = kv(rows);
+    const lines = Array.isArray(cap.lines) ? cap.lines.filter(isObject) : [];
+    if (lines.some((l) => (typeof l.units_over === 'number' && l.units_over > 0) || (typeof l.amount_minor === 'number' && l.amount_minor > 0))) {
+        out += `\n${table(['OVERAGE', 'UNIT', 'PAST ALLOWANCE', 'BILLED', 'RATE', 'AMOUNT'], lines.map((l) => [scalar(l.allowance), scalar(l.unit), scalar(l.units_over), scalar(l.billed_units), capMoney(l.rate_minor, cur), capMoney(l.amount_minor, cur)]))}`;
+    }
+    return out;
+}
 /**
  * The usage summary (GET /v1/organizations/{id}/usage/summary): plan, period, measurement
- * freshness, then meters and allowances as tables. Columns absent from the response are omitted.
+ * freshness, then meters and allowances as tables (cap state `overage` past an allowance while opt-in overage is on),
+ * then the overage block. Columns absent from the response are omitted.
  */
 export function usageText(summary) {
     if (!isObject(summary))
@@ -217,8 +324,10 @@ export function usageText(summary) {
         head.push(['measured through', time(m.measured_through)]);
     if (isObject(s.measurement) && s.measurement.estimate_status !== undefined)
         head.push(['estimate', scalar(s.measurement.estimate_status)]);
-    if (typeof s.allowance_exhausted === 'boolean')
-        head.push(['allowance exhausted', s.allowance_exhausted ? 'yes (new opens/resumes are refused)' : 'no']);
+    if (typeof s.allowance_exhausted === 'boolean') {
+        const reason = typeof s.exhausted_reason === 'string' ? `${s.exhausted_reason}: ` : '';
+        head.push(['allowance exhausted', s.allowance_exhausted ? `yes (${reason}new opens/resumes are refused)` : 'no']);
+    }
     for (const [k, v] of Object.entries(s))
         if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
             head.push([k.replace(/_/g, ' '), scalar(v)]);
@@ -246,13 +355,34 @@ export function usageText(summary) {
     ]);
     if (allowances)
         out += `\n${allowances}`;
+    const overage = spendCapText(s.spend_cap);
+    if (overage)
+        out += `\n${overage}`;
     return out || json(summary);
 }
+/** Request ids and error codes pasted unquoted into the suggested command must be shell-inert. */
+const SHELL_SAFE = /^[A-Za-z0-9._:-]{1,200}$/;
 /**
- * One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. A failed
- * operation also shows `retryable=true|false`.
+ * The `shard feedback` command a failed command suggests (0.5.0+), with the error's request id and code so the founder
+ * can find the logs (a failed operation's or execution's own error code, e.g. capacity_unavailable); the agent fills in
+ * the text.
  */
-export function errorText(e, hint) {
+export function feedbackCommand(e) {
+    const code = (e.code === 'operation_failed' || e.code === 'execution_failed') && typeof e.details?.error_code === 'string' ? e.details.error_code : e.code;
+    const parts = ['shard feedback --category bug'];
+    if (e.request_id && SHELL_SAFE.test(e.request_id))
+        parts.push(`--request-id ${e.request_id}`);
+    if (SHELL_SAFE.test(code))
+        parts.push(`--error-code ${code}`);
+    parts.push('"<what you expected>"');
+    return parts.join(' ');
+}
+/**
+ * One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one, and the
+ * `feedback:` line (the command to report it) when given. A failed operation or execution also shows
+ * `retryable=true|false`.
+ */
+export function errorText(e, hint, feedback) {
     const meta = [`code=${e.code}`];
     if (e.status !== undefined)
         meta.push(`status=${e.status}`);
@@ -260,15 +390,17 @@ export function errorText(e, hint) {
         meta.push(`request_id=${e.request_id}`);
     if (e.operation_id)
         meta.push(`operation_id=${e.operation_id}`);
+    if (e.execution_id)
+        meta.push(`execution_id=${e.execution_id}`);
     if (e.source === 'cell')
         meta.push('source=cell');
-    if (e.code === 'operation_failed' && e.retryable !== undefined)
+    if ((e.code === 'operation_failed' || e.code === 'execution_failed') && e.retryable !== undefined)
         meta.push(`retryable=${e.retryable}`);
     const reason = e.details && typeof e.details.reason === 'string' ? ` (${e.details.reason})` : '';
     const issues = Array.isArray(e.details?.issues)
         ? e.details.issues.filter(isObject).map((i) => `  ${scalar(i.path)}: ${scalar(i.message)}\n`).join('')
         : '';
-    return `error: ${e.message}${reason} [${meta.join(' ')}]\n${issues}${hint ? `hint: ${hint}\n` : ''}`;
+    return `error: ${e.message}${reason} [${meta.join(' ')}]\n${issues}${hint ? `hint: ${hint}\n` : ''}${feedback ? `feedback: ${feedback}\n` : ''}`;
 }
 // ---- Templates v2 (contracts §19) ---------------------------------------------------------------
 export function templateTable(rows) {
@@ -396,3 +528,340 @@ export function settingsText(s) {
         ['egress', egress],
     ]).replace(/^/gm, '  ');
 }
+// ---- File-first executions (0.5.0; contracts §29.8) ----------------------------------------------------------------------
+const CHANGE_LETTER = { added: 'A', modified: 'M', deleted: 'D' };
+/** How many changed paths the human output lists before "... N more" (--json lists every one the result has). */
+export const MAX_CHANGED_SHOWN = 100;
+/**
+ * What an execution changed, one `A|M|D path` line each (the letters of a short VCS status; a directory ends in `/`), at
+ * most `max`; then how many more the result has, and a note when the cell listed only the first 10,000.
+ */
+export function changedText(changed, changedTruncated, max = MAX_CHANGED_SHOWN) {
+    const shown = changed.slice(0, max).map((c) => `${CHANGE_LETTER[c.change] ?? '?'} ${c.path}${c.type === 'directory' ? '/' : ''}\n`);
+    const more = changed.length - shown.length;
+    const tail = more > 0 ? `... ${more} more (--json lists every one)\n` : '';
+    const cut = changedTruncated ? `... and more: the result lists only the first ${changed.length} changes\n` : '';
+    return shown.join('') + tail + cut;
+}
+/** An execution's exit status in words: `exit code 0`, `killed by signal 15`, `killed by signal 9 (timed out)`. */
+function exitStatus(r) {
+    const signal = r.termSignal !== null && r.termSignal > 0 ? `killed by signal ${r.termSignal}` : null;
+    if (r.timedOut)
+        return `${signal ?? 'killed'}, timed out`;
+    if (signal && (r.exitCode === null || r.exitCode < 0))
+        return signal;
+    return `exit code ${r.exitCode ?? '-'}`;
+}
+/** The execution's state: `succeeded (exit code 0)`, `failed: <message> (<reason>)`, `running`. */
+export function executionStateText(r) {
+    if (r.state === 'succeeded')
+        return `succeeded (${exitStatus(r)})`;
+    if (r.state === 'failed' || r.state === 'lost')
+        return `${r.state}${r.error?.message ? `: ${r.error.message}` : ''}${r.errorReason ? ` (${r.errorReason})` : ''}`;
+    return r.state;
+}
+/** `3 -> 4`, `3 (unchanged)`, `3 (nothing published)`, or the base revision a pending execution runs on. */
+function revisionText(r) {
+    if (r.pending)
+        return `${r.baseRevision} (the command runs on it)`;
+    if (r.treeRevision === null)
+        return `${r.baseRevision} (nothing published)`;
+    return r.treeRevision === r.baseRevision ? `${r.baseRevision} (unchanged)` : `${r.baseRevision} -> ${r.treeRevision}`;
+}
+/**
+ * The summary `shard ws exec -v` prints after a file-first command's output, and `shard executions get` with it (on
+ * stderr): execution id, state and exit status, base -> tree revision, `replayed` when true, truncated output, timings
+ * (`key=value`: queue_ms, run_ms, publish_ms, total_ms and the host's), then what changed.
+ */
+export function executionSummary(r, maxChanged = MAX_CHANGED_SHOWN, opts = {}) {
+    const truncated = [r.stdoutTruncated ? 'stdout' : '', r.stderrTruncated ? 'stderr' : ''].filter(Boolean).join(' and ');
+    const rows = [
+        ['execution', r.executionId],
+        ['state', executionStateText(r)],
+        ['revision', revisionText(r)],
+    ];
+    // `executions get` passes replayed: false: every result it reads is a recorded one, so the line would say nothing.
+    if (r.replayed && opts.replayed !== false)
+        rows.push(['replayed', 'yes (the recorded result; the command did not run again)']);
+    if (truncated)
+        rows.push(['truncated', `${truncated} (at the output limit)`]);
+    if (Object.keys(r.timings).length)
+        rows.push(['timings', pairs(r.timings)]);
+    if (!r.pending)
+        rows.push(['changed', r.changed.length === 0 ? 'nothing' : `${r.changed.length}${r.changedTruncated ? '+' : ''} path${r.changed.length === 1 ? '' : 's'}`]);
+    return kv(rows) + changedText(r.changed, r.changedTruncated, maxChanged);
+}
+/** Bytes as UTF-8 text; null when they are not valid UTF-8. */
+function utf8(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The `--json` document of an execution (`shard ws exec` on a file-first workspace, `shard executions get`): the cell's
+ * ExecutionResult with stdout/stderr as UTF-8 text (like the processful exec's), plus `stdout_base64` / `stderr_base64`
+ * with the exact bytes when a stream is not valid UTF-8 (its text then has U+FFFD for the invalid sequences).
+ */
+export function executionJson(r) {
+    const stream = (name, bytes) => {
+        const text = utf8(bytes);
+        return text !== null ? { [name]: text } : { [name]: r.text(name), [`${name}_base64`]: Buffer.from(bytes).toString('base64') };
+    };
+    return {
+        execution_id: r.executionId,
+        state: r.state,
+        exit_code: r.exitCode,
+        term_signal: r.termSignal,
+        timed_out: r.timedOut,
+        base_revision: r.baseRevision,
+        tree_revision: r.treeRevision,
+        changed: r.changed,
+        changed_truncated: r.changedTruncated,
+        ...stream('stdout', r.stdout),
+        stdout_truncated: r.stdoutTruncated,
+        ...stream('stderr', r.stderr),
+        stderr_truncated: r.stderrTruncated,
+        replayed: r.replayed,
+        timings: r.timings,
+        error: r.error,
+        created_at: r.createdAt,
+        finished_at: r.finishedAt,
+    };
+}
+// ---- Account plane (0.5.0) ----------------------------------------------------------------------------------------
+/** "*" for the row that is the saved default, else "" (a narrow first column). */
+const mark = (on) => (on ? '*' : '');
+export function orgTable(rows, defaultId) {
+    return table(['', 'ID', 'SLUG', 'NAME', 'ROLE', 'CREATED'], rows.map((o) => [mark(o.id === defaultId), o.id, o.slug, o.name, o.role ?? '-', time(o.created_at)]));
+}
+export function projectTable(rows, defaultId) {
+    return table(['', 'ID', 'SLUG', 'NAME', 'CREATED'], rows.map((p) => [mark(p.id === defaultId), p.id, p.slug, p.name, time(p.created_at)]));
+}
+/** active, expired or revoked (as the web app shows it). */
+export function keyStatus(k, now = Date.now()) {
+    if (k.revoked_at)
+        return 'revoked';
+    if (k.expires_at && Date.parse(k.expires_at) <= now)
+        return 'expired';
+    return 'active';
+}
+export function toolsText(tools) {
+    if (tools.length === 0)
+        return '(none: read-only)';
+    return tools.length === 6 ? 'all' : tools.join(',');
+}
+export function apiKeyTable(rows, savedId) {
+    return table(['', 'ID', 'KEY ID', 'NAME', 'TOOLS', 'STATUS', 'CREATED', 'EXPIRES', 'LAST USED'], rows.map((k) => [mark(k.id === savedId), k.id, k.key_id, k.name, toolsText(k.tool_permissions), keyStatus(k), time(k.created_at), time(k.expires_at), time(k.last_used_at)]));
+}
+export function memberTable(rows) {
+    return table(['USER', 'EMAIL', 'NAME', 'ROLE', 'JOINED'], rows.map((m) => [m.user_id, m.email, m.display_name ?? '-', m.role, time(m.joined_at)]));
+}
+export function invitationTable(rows) {
+    return table(['ID', 'EMAIL', 'ROLE', 'STATUS', 'EXPIRES', 'CREATED'], rows.map((i) => [i.id, i.email, i.role, i.status, time(i.expires_at), time(i.created_at)]));
+}
+export function authSessionTable(rows) {
+    return table(['', 'ID', 'CLIENT', 'CREATED', 'LAST SEEN', 'EXPIRES', 'IP', 'USER AGENT'], rows.map((s) => [s.current ? '*' : '', s.id, s.client, time(s.created_at), time(s.last_seen_at), time(s.absolute_expires_at), s.client_ip ?? '-', s.user_agent ? (s.user_agent.length > 60 ? `${s.user_agent.slice(0, 59)}…` : s.user_agent) : '-']));
+}
+/** 900 + "usd" -> "9.00 USD" (minor units; zero-decimal currencies shown as whole numbers). */
+/**
+ * A usage time series (GET .../usage or /v1/workspaces/{id}/usage): the range and freshness, then one row per bucket
+ * and meter. `FINAL` is no while the bucket can still change (the ledger finalizes hours after they end).
+ */
+export function usageSeriesText(series) {
+    if (!isObject(series))
+        return json(series);
+    const s = series;
+    const head = [];
+    if (s.workspace_id)
+        head.push(['workspace', scalar(s.workspace_id)]);
+    head.push(['range', `${time(scalar(s.from))} .. ${time(scalar(s.to))}${s.granularity ? ` (by ${scalar(s.granularity)})` : ''}`]);
+    const m = isObject(s.measurement) ? s.measurement : {};
+    if (m.measured_through !== undefined)
+        head.push(['measured through', time(m.measured_through)]);
+    const data = Array.isArray(s.data) ? s.data : [];
+    const rows = data.map((r) => (isObject(r) ? { ...r, start: time(r.start), finalized: r.finalized === true ? 'yes' : 'no' } : r));
+    const table = objectTable(rows, [
+        ['start', 'START'],
+        ['meter', 'METER'],
+        ['raw_quantity', 'RAW'],
+        ['billable_quantity', 'BILLABLE'],
+        ['finalized', 'FINAL'],
+    ]);
+    return `${kv(head)}\n${table || 'no usage in this range\n'}`;
+}
+/** The period estimate (GET .../usage/estimate): the bill so far and where each allowance is heading. */
+export function usageEstimateText(estimate) {
+    if (!isObject(estimate))
+        return json(estimate);
+    const e = estimate;
+    const currency = typeof e.currency === 'string' ? e.currency : 'USD';
+    const amount = (v) => (typeof v === 'number' ? money(v, currency) : '-');
+    const fee = isObject(e.subscription_fee) ? e.subscription_fee.amount_minor : e.subscription_fee;
+    const head = [];
+    if (isObject(e.plan))
+        head.push(['plan', scalar(e.plan.plan_key)]);
+    if (isObject(e.period))
+        head.push(['period', `${time(scalar(e.period.start))} .. ${time(scalar(e.period.end))}`]);
+    head.push(['subscription', amount(fee)], ['usage charges', amount(e.usage_charges_minor)], ['estimated total', amount(e.estimated_total_minor)]);
+    if (typeof e.overage === 'string')
+        head.push(['overage', e.overage]);
+    let out = kv(head);
+    const projections = objectTable(e.projections, [
+        ['allowance', 'ALLOWANCE'],
+        ['unit', 'UNIT'],
+        ['included', 'INCLUDED'],
+        ['used', 'USED'],
+        ['projected_at_period_end', 'PROJECTED'],
+        ['projected_exhaustion_at', 'RUNS OUT'],
+        ['enforcement', 'ENFORCEMENT'],
+    ]);
+    if (projections)
+        out += `\n${projections}`;
+    const notes = Array.isArray(e.notes) ? e.notes.filter((n) => typeof n === 'string') : [];
+    if (notes.length)
+        out += `\n${notes.map((n) => `note: ${n}`).join('\n')}\n`;
+    return out;
+}
+export function money(amountMinor, currency) {
+    const zeroDecimal = new Set(['jpy', 'krw', 'vnd', 'clp', 'isk', 'ugx', 'xaf', 'xof']);
+    const c = currency.toLowerCase();
+    return `${zeroDecimal.has(c) ? String(amountMinor) : (amountMinor / 100).toFixed(2)} ${c.toUpperCase()}`;
+}
+export function planTable(catalog) {
+    const rows = catalog.plans.map((p) => {
+        const prices = p.prices.length ? p.prices.map((x) => `${money(x.amount_minor, x.currency)}/${x.interval}`).join(', ') : 'free';
+        const buy = p.prices.some((x) => x.purchasable) ? 'yes' : '-';
+        return [p.plan_key, p.name, prices, buy];
+    });
+    return `${table(['PLAN', 'NAME', 'PRICE', 'PURCHASABLE'], rows)}catalog ${catalog.catalog_version} (${catalog.mode})\n`;
+}
+export function billingStatusText(s, org) {
+    const sub = s.subscription;
+    const pending = s.pending_checkout;
+    return kv([
+        ['organization', `${org.name} (${org.slug})`],
+        ['plan', s.plan ? `${s.plan.plan_key} (${s.plan.source}, catalog ${s.plan.catalog_version})` : '-'],
+        ['billing state', s.billing_state],
+        ['subscription', sub ? `${sub.status}${sub.plan_key ? ` ${sub.plan_key}` : ''}${sub.cancel_at_period_end ? ', cancels at period end' : ''}` : 'none'],
+        ['period end', sub ? time(sub.current_period_end) : '-'],
+        ...(sub?.grace_until ? [['grace until', time(sub.grace_until)]] : []),
+        ['pending checkout', pending ? `${pending.id} ${pending.plan_key ?? '-'} ${pending.status}${pending.expires_at ? ` (expires ${time(pending.expires_at)})` : ''}` : '-'],
+        ['purchase', s.purchase_available ? 'available (shard billing upgrade <plan>)' : 'not available on this API'],
+    ]);
+}
+export function invoiceTable(rows) {
+    return table(['NUMBER', 'STATUS', 'TOTAL', 'PAID', 'DUE', 'PERIOD', 'CREATED', 'URL'], rows.map((i) => [
+        i.number ?? i.id,
+        i.status ?? '-',
+        money(i.total, i.currency),
+        money(i.amount_paid, i.currency),
+        money(i.amount_remaining, i.currency),
+        i.period_start || i.period_end ? `${time(i.period_start).slice(0, 10)}..${time(i.period_end).slice(0, 10)}` : '-',
+        time(i.created_at),
+        i.hosted_invoice_url ?? '-',
+    ]));
+}
+export function auditTable(rows) {
+    return table(['TIME', 'ACTION', 'OUTCOME', 'ACTOR', 'TARGET', 'REQUEST'], rows.map((e) => [time(e.occurred_at), e.action, e.outcome, `${e.actor.type}${e.actor.id ? `:${e.actor.id}` : ''}`, e.target ? `${e.target.type}${e.target.id ? `:${e.target.id}` : ''}` : '-', e.request_id ?? '-']));
+}
+export function dataExportText(e, out) {
+    return kv([
+        ['export', `${e.kind} ${e.id}`],
+        ['written to', `${out} (${e.size_bytes} bytes, sha256 ${e.sha256})`],
+        ['created', time(e.created_at)],
+        ['expires', `${time(e.expires_at)} (the server copy; download it again before then with the same command)`],
+        // The API's entries are sentences ("Workspace file contents: ... ."): run them together as sentences.
+        ...(e.not_included.length ? [['not included', e.not_included.map((x) => x.trim()).join(' ')]] : []),
+    ]);
+}
+export function volumeTable(rows) {
+    return table(['ID', 'NAME', 'STATE', 'QUOTA', 'SHARED', 'ATTACHED', 'CREATED'], rows.map((v) => [v.id, v.name, `${v.state}${v.deleted_at ? ' (deleted)' : ''}`, `${v.quota_gib} GiB`, v.org_shared ? 'organization' : 'project', String(v.live_attachments), time(v.created_at)]));
+}
+export function volumeDetail(v) {
+    const err = v.error;
+    return kv([
+        ['id', v.id],
+        ['name', v.name],
+        ['state', `${v.state}${v.state_reason ? ` (${v.state_reason})` : ''}`],
+        ['quota', `${v.quota_gib} GiB`],
+        ['shared', v.org_shared ? 'every project of the organization' : `project ${v.project_id}`],
+        ['attachments', String(v.live_attachments)],
+        ['usage', pairs(v.usage)],
+        ['operation', v.active_operation ? `${operationSummary(v.active_operation)} ${v.active_operation.id}` : '-'],
+        ['error', err ? `${scalar(err.code)}${err.message ? `: ${scalar(err.message)}` : ''}` : '-'],
+        ['created', time(v.created_at)],
+        ['deleted', time(v.deleted_at)],
+    ]);
+}
+export function attachmentTable(rows) {
+    return table(['ID', 'WORKSPACE', 'VOLUME', 'MOUNT', 'MODE', 'STATE', 'MOUNTED', 'ATTACHED'], rows.map((a) => [a.id, a.workspace_id, a.volume_id, a.mount_path, a.mode, a.state, a.mounted ? 'yes' : 'no', time(a.attached_at)]));
+}
+function egressPolicyLine(p) {
+    if (!p)
+        return '-';
+    if (p.mode !== 'allowlist')
+        return p.mode;
+    const rules = p.rules.map((r) => `${r.host}:${r.ports.join('/')}`);
+    return `allowlist ${[...rules, ...p.cidrs].join(', ') || '(empty: nothing allowed)'}`;
+}
+export function projectEgressText(p) {
+    const pr = p.propagation;
+    return kv([
+        ['project', p.project_id],
+        ['version', String(p.version)],
+        ['policy', p.policy ? `${egressPolicyLine({ mode: p.policy.mode ?? 'allow_all', rules: p.policy.rules, cidrs: p.policy.cidrs })} (v${p.policy.version})` : 'none (the platform default applies)'],
+        ['effective', `${egressPolicyLine(p.effective)} (${p.effective.source})`],
+        ['override', p.organization_override ? `${p.organization_override.mode}: ${p.organization_override.reason} until ${time(p.organization_override.lifts_at)}` : '-'],
+        ['workspaces', `${pr.workspaces}: ${pr.enforced} enforced, ${pr.pending} pending, ${pr.failed} failed, ${pr.not_enforced} not enforced${pr.truncated ? ' (truncated)' : ''}`],
+    ]);
+}
+export function workspaceEgressText(w) {
+    const e = w.enforcement;
+    return kv([
+        ['workspace', w.workspace_id],
+        ['version', String(w.version)],
+        ['override', w.override ? `${egressPolicyLine(w.override.kind === 'cleared' ? null : { mode: w.override.mode ?? 'allow_all', rules: w.override.rules, cidrs: w.override.cidrs })} (v${w.override.version}${w.override.kind === 'cleared' ? ', cleared' : ''})` : 'none'],
+        ['project policy', w.project_policy ? `${egressPolicyLine({ mode: w.project_policy.mode ?? 'allow_all', rules: w.project_policy.rules, cidrs: w.project_policy.cidrs })} (v${w.project_policy.version})` : 'none'],
+        ['template ceiling', w.template_egress ? `${w.template_egress.mode}${w.template_egress.allow_hosts.length ? ` ${w.template_egress.allow_hosts.join(', ')}` : ''}` : '-'],
+        ['effective', `${egressPolicyLine(w.effective_policy)} (${w.effective.source})`],
+        ['enforcement', `${e.state}${e.reason ? ` (${e.reason})` : ''}; applied v${e.applied_version ?? '-'} of v${e.effective_version ?? '-'}`],
+    ]);
+}
+export function egressVersionTable(rows) {
+    return table(['VERSION', 'KIND', 'POLICY', 'BY', 'CREATED'], rows.map((v) => [String(v.version), v.kind, v.kind === 'cleared' ? '-' : egressPolicyLine({ mode: v.mode ?? 'allow_all', rules: v.rules, cidrs: v.cidrs }), `${v.created_by.type}:${v.created_by.id}`, time(v.created_at)]));
+}
+// ---- Overage settings (0.5.1; shard billing overage) -----------------------------------------------------------
+const RATE_UNITS = { ram_gib_hours: 'RAM GiB-hour', cpu_hours: 'CPU-hour' };
+/**
+ * The spend policy's overage settings for people (GET/PUT /v1/organizations/{id}/spend-policy): the state, the spend
+ * cap and its bounds, the rates, and the next step. `saved` adds the version the change was saved as.
+ */
+export function overagePolicyText(p, orgName, saved = false) {
+    const m = (minor) => capMoney(minor, p.currency);
+    const bound = p.spend_cap_max_minor === null ? '' : `${m(p.spend_cap_min_minor)} to ${m(p.spend_cap_max_minor)}, the plan price`;
+    const cap = p.spend_cap_minor === null ? 'no spend cap set' : `spend cap ${m(p.spend_cap_minor)} per billing period`;
+    const lines = [];
+    switch (p.overage_state) {
+        case 'unavailable':
+            lines.push(`${orgName}: overage is not available on this plan: it needs a paid plan with opt-in overage (shard billing plans).`);
+            break;
+        case 'off':
+            lines.push(`${orgName}: overage is off (${cap}): new opens and resumes are refused once an allowance is used up.`);
+            lines.push(`Turn it on${p.spend_cap_minor === null ? ` with a spend cap${bound ? ` of ${bound}` : ''}: shard billing overage on --cap <dollars>` : ': shard billing overage on'}`);
+            break;
+        case 'paused':
+            lines.push(`${orgName}: overage is on but paused while a plan payment is past due (update the payment method: shard billing portal --open); ${cap}.`);
+            break;
+        default:
+            lines.push(`${orgName}: overage is on, ${cap}${bound ? ` (${bound})` : ''}.`);
+    }
+    if (p.overage_state !== 'unavailable' && p.rates.length > 0) {
+        lines.push(`Rates past the allowances: ${p.rates.map((r) => `${m(r.amount_minor_per_unit)} per ${RATE_UNITS[r.allowance] ?? r.unit}`).join(', ')}, charged on the next invoice (this period: shard usage).`);
+    }
+    if (saved)
+        lines.push(`Saved (policy version ${p.version}).`);
+    return `${lines.join('\n')}\n`;
+}

package/dist/handlers.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from './commands.js';
+export declare const HANDLERS: Record<string, Handler>;

package/dist/handlers.js

@@ -0,0 +1,7 @@
+/**
+ * Every command's handler, keyed by its path ("workspaces open", "auth login"): the project-key commands of
+ * commands.ts and the account plane of account-commands.ts (0.5.0). args.test.ts checks that it matches COMMANDS.
+ */
+import { ACCOUNT_HANDLERS } from "./account-commands.js";
+import { KEY_HANDLERS } from "./commands.js";
+export const HANDLERS = { ...KEY_HANDLERS, ...ACCOUNT_HANDLERS };

package/dist/index.d.ts

@@ -1,13 +1,25 @@
 /**
  * @shardflux/cli — `shard`, the Shardflux command line on @shardflux/sdk.
- * The executable is src/bin.ts; `run()` drives the same code in-process.
+ * The executable is src/bin.ts (`main()`); `run()` drives the same code in-process. A package that embeds the CLI
+ * (the `shardflux` npm bundle) calls `main({ distribution: { package, version } })` so the version check names it.
  */
-export { run, abortableSleep } from './main.js';
-export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, resolveWake, resolveWakeTimeout, topHelp } from './args.js';
+export { run, main, abortableSleep } from './main.js';
+export type { MainOptions, RunOptions } from './main.js';
+export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, HELP_SECTIONS, commandHelp, findCommand, groupHelp, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, resolveWake, resolveWakeTimeout, topHelp } from './args.js';
 export type { CommandSpec, OptionSpec, Parsed, PositionalSpec, Values } from './args.js';
-export { HANDLERS, execExitCode, resolveWorkspace } from './commands.js';
-export type { Ctx, Handler, Io, Writer } from './commands.js';
-export { EXIT, AuthConfigError, InterruptedError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from './errors.js';
+export { HANDLERS } from './handlers.js';
+export { KEY_HANDLERS, execExitCode, resolveWorkspace, whenIdleSeconds } from './commands.js';
+export type { Ctx, Handler, Io, ResolvedApiKey, Writer } from './commands.js';
+export { ACCOUNT_HANDLERS, DEFAULT_API_URL, defaultOrgName, exportLine, parseTime } from './account-commands.js';
+export type { ShellKind } from './account-commands.js';
+export { CREDENTIALS_FILE, CredentialStore, CredentialsFileError, configDir, ensurePrivateDir, parseCredentials, writePrivateFile } from './credentials.js';
+export type { CredentialsDoc, Profile, StoredApiKey, StoredSession, StoredUser } from './credentials.js';
+export { Input } from './input.js';
+export type { StdinLike } from './input.js';
+export { CHECK_INTERVAL_MS, CLI_DISTRIBUTION, NOTICE_WAIT_MS, UPDATE_CHECK_FILE, UpdateCheck, noticeOf, statusFromEntry, updateCheckDisabled, updateView } from './update-check.js';
+export type { Distribution, UpdateView } from './update-check.js';
+export { openUrl, openerFor } from './browser.js';
+export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, ExecutionPendingError, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from './errors.js';
 export type { ErrorInfo } from './errors.js';
-export { errorText, json, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
+export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
 export { TimingRecorder, timingJson, timingText } from './timing.js';

package/dist/index.js

@@ -1,10 +1,17 @@
 /**
  * @shardflux/cli — `shard`, the Shardflux command line on @shardflux/sdk.
- * The executable is src/bin.ts; `run()` drives the same code in-process.
+ * The executable is src/bin.ts (`main()`); `run()` drives the same code in-process. A package that embeds the CLI
+ * (the `shardflux` npm bundle) calls `main({ distribution: { package, version } })` so the version check names it.
  */
-export { run, abortableSleep } from "./main.js";
-export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, resolveWake, resolveWakeTimeout, topHelp } from "./args.js";
-export { HANDLERS, execExitCode, resolveWorkspace } from "./commands.js";
-export { EXIT, AuthConfigError, InterruptedError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
-export { errorText, json, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
+export { run, main, abortableSleep } from "./main.js";
+export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, HELP_SECTIONS, commandHelp, findCommand, groupHelp, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, resolveWake, resolveWakeTimeout, topHelp } from "./args.js";
+export { HANDLERS } from "./handlers.js";
+export { KEY_HANDLERS, execExitCode, resolveWorkspace, whenIdleSeconds } from "./commands.js";
+export { ACCOUNT_HANDLERS, DEFAULT_API_URL, defaultOrgName, exportLine, parseTime } from "./account-commands.js";
+export { CREDENTIALS_FILE, CredentialStore, CredentialsFileError, configDir, ensurePrivateDir, parseCredentials, writePrivateFile } from "./credentials.js";
+export { Input } from "./input.js";
+export { CHECK_INTERVAL_MS, CLI_DISTRIBUTION, NOTICE_WAIT_MS, UPDATE_CHECK_FILE, UpdateCheck, noticeOf, statusFromEntry, updateCheckDisabled, updateView } from "./update-check.js";
+export { openUrl, openerFor } from "./browser.js";
+export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, ExecutionPendingError, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
+export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
 export { TimingRecorder, timingJson, timingText } from "./timing.js";