@shardflux/cli 0.4.1 → 0.5.0

package/dist/format.d.ts

@@ -3,7 +3,7 @@
  * `--json` output is the API's own objects (see README "JSON output"), so
  * these functions only shape what people read.
  */
-import type { AgentSession, DraftState, FileList, Operation, Secret, SecretAccessEvent, SecretVersion, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, WorkspaceChange, WorkspaceSecretBindings, WorkspaceView } 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, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, WorkspaceChange, WorkspaceSecretBindings, WorkspaceView } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
 export declare function json(value: unknown): string;
 export declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): string;
@@ -14,7 +14,9 @@ export declare function time(iso: string | null | undefined): string;
 export declare function pairs(obj: Record<string, unknown> | null | undefined): string;
 export declare function operationSummary(op: Operation | null | undefined): string;
 export declare const WORKSPACE_HEADERS: readonly ["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 declare function modeText(mode: WorkspaceView['mode'] | undefined): string;
+/** Observed state plus what sets the workspace apart: file-first, session, draft or test instance, and how it ended. */
 export declare function workspaceState(w: WorkspaceView): string;
 export declare function workspaceRow(w: WorkspaceView): string[];
 export declare function workspaceTable(ws: readonly WorkspaceView[]): string;
@@ -31,6 +33,10 @@ export declare const OPERATION_HEADERS: readonly ["ID", "KIND", "STATE", "REASON
 export declare function operationTable(ops: readonly Operation[]): string;
 export declare function operationDetail(op: Operation): string;
 export declare function sessionTable(sessions: readonly AgentSession[]): string;
+/** `files stat`: one path's metadata; the revision only when requested and returned. */
+export declare function fileInfoText(f: FileInfo): string;
+/** `files search`: grep-style `path:line:column: text`, context lines as `path-line- text`. */
+export declare function searchText(r: FileSearchResponse): string;
 export declare function fileTable(list: FileList): string;
 export declare function secretTable(rows: readonly Secret[]): string;
 /** Secret metadata; there is no value to show (values are write-only). */
@@ -44,10 +50,17 @@ export declare function bindingsText(b: WorkspaceSecretBindings): string;
  */
 export declare function usageText(summary: unknown): string;
 /**
- * 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 declare function errorText(e: ErrorInfo, hint?: string): string;
+export declare function feedbackCommand(e: ErrorInfo): string;
+/**
+ * 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 declare function errorText(e: ErrorInfo, hint?: string, feedback?: string): string;
 export declare function templateTable(rows: readonly TemplateSummary[]): string;
 /** Permission bits as the four-digit octal `ls -l` users read (e.g. 0755). */
 export declare function octal(mode: number): string;
@@ -66,3 +79,55 @@ export declare function packageTable(page: TemplatePackagePage): string;
 export declare function templateDetailText(t: TemplateDetail): string;
 /** A version's settings (contracts §24.3), one line per part. */
 export declare function settingsText(s: TemplateSettings): string;
+/** How many changed paths the human output lists before "... N more" (--json lists every one the result has). */
+export declare 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 declare function changedText(changed: readonly ExecutionChange[], changedTruncated: boolean, max?: number): string;
+/** The execution's state: `succeeded (exit code 0)`, `failed: <message> (<reason>)`, `running`. */
+export declare function executionStateText(r: ExecutionResult): string;
+/**
+ * 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 declare function executionSummary(r: ExecutionResult, maxChanged?: number, opts?: {
+    replayed?: boolean;
+}): string;
+/**
+ * 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 declare function executionJson(r: ExecutionResult): Record<string, unknown>;
+export declare function orgTable(rows: readonly Organization[], defaultId: string | null): string;
+export declare function projectTable(rows: readonly Project[], defaultId: string | null): string;
+/** active, expired or revoked (as the web app shows it). */
+export declare function keyStatus(k: Pick<ApiKey, 'revoked_at' | 'expires_at'>, now?: number): 'active' | 'expired' | 'revoked';
+export declare function toolsText(tools: readonly string[]): string;
+export declare function apiKeyTable(rows: readonly ApiKey[], savedId: string | null): string;
+export declare function memberTable(rows: readonly Member[]): string;
+export declare function invitationTable(rows: readonly Invitation[]): string;
+export declare function authSessionTable(rows: readonly AuthSessionInfo[]): string;
+/** 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 declare function usageSeriesText(series: unknown): string;
+/** The period estimate (GET .../usage/estimate): the bill so far and where each allowance is heading. */
+export declare function usageEstimateText(estimate: unknown): string;
+export declare function money(amountMinor: number, currency: string): string;
+export declare function planTable(catalog: BillingCatalog): string;
+export declare function billingStatusText(s: BillingSubscription, org: Pick<Organization, 'name' | 'slug'>): string;
+export declare function invoiceTable(rows: readonly BillingInvoicePage['data'][number][]): string;
+export declare function auditTable(rows: readonly AuditEvent[]): string;
+export declare function dataExportText(e: DataExport, out: string): string;
+export declare function volumeTable(rows: readonly Volume[]): string;
+export declare function volumeDetail(v: Volume): string;
+export declare function attachmentTable(rows: readonly VolumeAttachment[]): string;
+export declare function projectEgressText(p: ProjectEgressPolicy): string;
+export declare function workspaceEgressText(w: WorkspaceEgressPolicy): string;
+export declare function egressVersionTable(rows: readonly EgressPolicyVersion[]): string;

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')
@@ -110,6 +116,9 @@ export function workspaceDetail(w) {
         ['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)],
@@ -152,6 +161,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]));
 }
@@ -248,11 +282,29 @@ export function usageText(summary) {
         out += `\n${allowances}`;
     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}$/;
+/**
+ * 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 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. A failed
- * operation also shows `retryable=true|false`.
+ * 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) {
+export function errorText(e, hint, feedback) {
     const meta = [`code=${e.code}`];
     if (e.status !== undefined)
         meta.push(`status=${e.status}`);
@@ -260,15 +312,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 +450,308 @@ 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)]));
+}

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 } 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, 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 } 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, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
 export { TimingRecorder, timingJson, timingText } from "./timing.js";

package/dist/input.d.ts

@@ -0,0 +1,25 @@
+export interface StdinLike extends AsyncIterable<Buffer | string> {
+    isTTY?: boolean;
+    /** tty.ReadStream#setRawMode: needed to read a secret on a terminal without echoing it. */
+    setRawMode?: (raw: boolean) => unknown;
+}
+export interface ErrWriter {
+    write(chunk: string | Uint8Array): boolean;
+}
+export declare class Input {
+    #private;
+    constructor(stdin: StdinLike, stderr: ErrWriter);
+    /** True when standard input is a terminal `shard` can prompt on. */
+    get interactive(): boolean;
+    /** The next line of piped input without its line ending, or null at the end of input. */
+    line(): Promise<string | null>;
+    /**
+     * A secret: a no-echo prompt on a terminal, else the next piped line. `what` names it in errors ("the password").
+     * An empty secret is refused.
+     */
+    secret(prompt: string, what: string, pipeHint: string): Promise<string>;
+    /** A new password: asked twice (and compared) on a terminal, one piped line otherwise. */
+    newPassword(prompt: string, what: string, pipeHint: string): Promise<string>;
+    /** A visible answer to a question on a terminal (e.g. an authenticator code), else the next piped line. */
+    answer(prompt: string): Promise<string | null>;
+}