@shardflux/cli 0.4.1 → 0.5.1

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, SpendPolicy, SuspendRequest, 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;
@@ -26,11 +28,25 @@ export declare function isReady(w: WorkspaceView): boolean;
 export declare function startupText(s: WorkspaceView['startup'] | undefined): string | null;
 /** The failed step's output tail, indented, after the detail block (empty otherwise). */
 export declare function startupTail(s: WorkspaceView['startup'] | undefined): string;
+/** A pending suspend-when-idle request in one line (0.5.1; contracts §20.6). */
+export declare function suspendRequestText(r: SuspendRequest): string;
+/** `shard ws suspend --when-idle`: the recorded request, or the suspend already in progress. */
+export declare function suspendWhenIdleText(w: {
+    key: string;
+    id: string;
+}, r: {
+    suspend_request: SuspendRequest | null;
+    operation: Operation | null;
+}): string;
 export declare function workspaceDetail(w: WorkspaceView): string;
 export declare const OPERATION_HEADERS: readonly ["ID", "KIND", "STATE", "REASON", "CREATED", "COMPLETED"];
 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). */
@@ -38,16 +54,26 @@ export declare function secretDetail(s: Secret): string;
 export declare function secretVersionTable(rows: readonly SecretVersion[]): string;
 export declare function secretAccessTable(rows: readonly SecretAccessEvent[]): string;
 export declare function bindingsText(b: WorkspaceSecretBindings): string;
+/** 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 declare function capMoney(minor: unknown, currency: string): string;
 /**
  * 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 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 +92,60 @@ 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;
+/**
+ * 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 declare function overagePolicyText(p: SpendPolicy, orgName: string, saved?: boolean): string;