@shardflux/cli 0.1.0 → 0.2.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, FileList, Operation, WorkspaceView } from '@shardflux/sdk';
+import type { AgentSession, DraftState, FileList, Operation, Secret, SecretAccessEvent, SecretVersion, TemplateBuild, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, 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,6 +14,8 @@ 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. */
+export declare function workspaceState(w: WorkspaceView): string;
 export declare function workspaceRow(w: WorkspaceView): string[];
 export declare function workspaceTable(ws: readonly WorkspaceView[]): string;
 export declare function isReady(w: WorkspaceView): boolean;
@@ -23,6 +25,12 @@ export declare function operationTable(ops: readonly Operation[]): string;
 export declare function operationDetail(op: Operation): string;
 export declare function sessionTable(sessions: readonly AgentSession[]): 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). */
+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;
 /**
  * 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.
@@ -30,3 +38,14 @@ export declare function fileTable(list: FileList): string;
 export declare function usageText(summary: unknown): string;
 /** One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. */
 export declare function errorText(e: ErrorInfo, hint?: 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;
+export declare function templateFileTable(rows: readonly TemplateFileEntry[]): string;
+export declare function templateEntryText(e: TemplateFileEntry): string;
+export declare function diffTable(rows: readonly TemplateDiffEntry[]): string;
+export declare function diffSummaryText(summary: unknown): string;
+export declare function changesTable(rows: readonly WorkspaceChange[]): string;
+export declare function draftText(d: TemplateDraft): string;
+export declare function draftStateTable(rows: readonly DraftState[]): string;
+export declare function buildText(b: TemplateBuild): string;

package/dist/format.js

@@ -44,8 +44,21 @@ 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. */
+export function workspaceState(w) {
+    const tags = [];
+    if (w.purpose === 'template_draft')
+        tags.push('draft');
+    else if (w.purpose === 'template_test')
+        tags.push('test instance');
+    else if (w.lifetime === 'session')
+        tags.push('session');
+    if (w.deleted_at)
+        tags.push(w.ended_reason ? `ended: ${w.ended_reason}` : 'deleted');
+    return tags.length ? `${w.observed_state} (${tags.join(', ')})` : w.observed_state;
+}
 export function workspaceRow(w) {
-    const state = w.deleted_at ? `${w.observed_state} (deleted)` : w.observed_state;
+    const state = workspaceState(w);
     return [w.id, w.workspace_key, state, w.desired_state, `${w.template.slug}@${w.template.version}`, operationSummary(w.active_operation), time(w.created_at)];
 }
 export function workspaceTable(ws) {
@@ -69,6 +82,15 @@ export function workspaceDetail(w) {
         ['operation', w.active_operation ? `${operationSummary(w.active_operation)} ${w.active_operation.id}` : '-'],
         ['pending', w.pending_reason ?? '-'],
         ['forked from', w.forked_from_workspace_id ?? '-'],
+        ...(w.lifetime !== undefined
+            ? [
+                ['lifetime', w.lifetime === 'session' ? `session (ends after ${w.idle_timeout_seconds ?? '-'} s idle, or on close)` : 'persistent'],
+                ['purpose', w.purpose],
+                ['disk layout', w.disk_layout],
+                ...(w.origin ? [['origin', w.origin.kind === 'fork' ? `fork of ${w.origin.workspace_id}` : `draft state ${w.origin.checkpoint_id ?? '(capturing)'} of ${w.origin.draft_workspace_id}`]] : []),
+                ...(w.ended_reason ? [['ended', w.ended_reason]] : []),
+            ]
+            : []),
         ['created', time(w.created_at)],
         ['deleted', time(w.deleted_at)],
     ]);
@@ -97,6 +119,38 @@ export function sessionTable(sessions) {
 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]));
 }
+export function secretTable(rows) {
+    return table(['ID', 'NAME', 'SCOPE', 'VERSION', 'TOOLS', 'UPDATED', 'DELETED'], rows.map((s) => [s.id, s.name, s.scope, String(s.current_version), s.permissions.allowed_tools.join(','), time(s.updated_at), time(s.deleted_at)]));
+}
+const idList = (ids, all) => (ids === null ? all : ids.length ? ids.join(', ') : '(none)');
+/** Secret metadata; there is no value to show (values are write-only). */
+export function secretDetail(s) {
+    return kv([
+        ['id', s.id],
+        ['name', s.name],
+        ['scope', s.scope === 'project' ? `project ${s.project_id ?? '-'}` : `organization ${s.organization_id}`],
+        ['description', s.description || '-'],
+        ['version', String(s.current_version)],
+        ['tools', s.permissions.allowed_tools.join(', ')],
+        ...(s.scope === 'organization' ? [['projects', idList(s.permissions.allowed_project_ids, '(every project)')]] : []),
+        ['workspaces', idList(s.permissions.allowed_workspace_ids, '(any)')],
+        ['created', `${time(s.created_at)} by ${s.created_by.type}:${s.created_by.id}`],
+        ['updated', time(s.updated_at)],
+        ['rotated', time(s.rotated_at)],
+        ['deleted', time(s.deleted_at)],
+    ]);
+}
+export function secretVersionTable(rows) {
+    return table(['VERSION', 'STATE', 'CREATED', 'BY', 'DESTROYED', 'REASON'], rows.map((v) => [String(v.version), v.state, time(v.created_at), `${v.created_by.type}:${v.created_by.id}`, time(v.destroyed_at), v.destroyed_reason ?? '-']));
+}
+export function secretAccessTable(rows) {
+    return table(['TIME', 'OUTCOME', 'REASON', 'TOOL', 'VERSION', 'WORKSPACE', 'PRINCIPAL', 'REQUEST'], rows.map((e) => [time(e.created_at), e.outcome, e.reason ?? '-', e.tool, e.secret_version === null ? '-' : String(e.secret_version), e.workspace_id, `${e.principal.type}:${e.principal.id}`, e.request_id ?? '-']));
+}
+export function bindingsText(b) {
+    if (b.secrets.length === 0)
+        return 'No secrets are bound to this workspace.\n';
+    return table(['NAME', 'STATUS', 'SCOPE', 'SECRET'], b.secrets.map((s) => [s.name, s.status, s.scope ?? '-', s.secret_id ?? '-']));
+}
 function isObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -175,3 +229,80 @@ export function errorText(e, hint) {
         : '';
     return `error: ${e.message}${reason} [${meta.join(' ')}]\n${issues}${hint ? `hint: ${hint}\n` : ''}`;
 }
+// ---- Templates v2 (contracts §19) ---------------------------------------------------------------
+export function templateTable(rows) {
+    return table(['SLUG', 'OWNER', 'OPEN VERSION', 'LAYOUTS', 'FILES', 'DRAFT', 'ARCHIVED'], rows.map((t) => {
+        const v = t.open_version;
+        return [
+            t.slug,
+            t.owner,
+            v ? `v${v.version}` : '-',
+            v?.disk_layouts?.join(',') ?? '-',
+            v?.files ? v.files.state : '-',
+            t.draft ? `${t.draft.workspace_key} (${t.draft.observed_state})` : '-',
+            time(t.archived_at),
+        ];
+    }));
+}
+/** Permission bits as the four-digit octal `ls -l` users read (e.g. 0755). */
+export function octal(mode) {
+    return mode.toString(8).padStart(4, '0');
+}
+export function templateFileTable(rows) {
+    return table(['TYPE', 'MODE', 'OWNER', 'SIZE', 'NAME'], rows.map((e) => [e.type, octal(e.mode), `${e.uid}:${e.gid}`, e.type === 'dir' ? `${e.child_count ?? 0} entries` : String(e.size_bytes), e.link_target ? `${e.name} -> ${e.link_target}` : e.name]));
+}
+export function templateEntryText(e) {
+    return kv([
+        ['path', e.path],
+        ['type', e.type],
+        ['size', `${e.size_bytes} bytes`],
+        ['mode', octal(e.mode)],
+        ['owner', `${e.uid}:${e.gid}`],
+        ['sha256', e.sha256 ?? '-'],
+        ['link target', e.link_target ?? '-'],
+        ['hardlink of', e.hardlink_of ?? '-'],
+        ...(e.type === 'dir' ? [['entries', String(e.child_count ?? 0)]] : []),
+    ]);
+}
+function side(x) {
+    if (!x)
+        return '-';
+    return `${x.type} ${x.type === 'symlink' ? `-> ${x.link_target ?? '?'}` : `${x.size_bytes} B`} ${octal(x.mode)} ${x.uid}:${x.gid}`;
+}
+export function diffTable(rows) {
+    return table(['CHANGE', 'BEFORE', 'AFTER', 'PATH'], rows.map((d) => [d.change, side(d.before), side(d.after), d.path]));
+}
+export function diffSummaryText(summary) {
+    if (typeof summary !== 'object' || summary === null)
+        return '';
+    const s = summary;
+    return `added ${s.added}, removed ${s.removed}, changed ${s.changed}, type changed ${s.type_changed}, metadata ${s.metadata}; +${s.bytes_added} / -${s.bytes_removed} bytes\n`;
+}
+export function changesTable(rows) {
+    return table(['CHANGE', 'TYPE', 'SIZE', 'MODE', 'PATH'], rows.map((c) => [c.change, c.type, String(c.size_bytes), c.mode, c.link_target ? `${c.path} -> ${c.link_target}` : c.path]));
+}
+export function draftText(d) {
+    const w = d.workspace;
+    return kv([
+        ['workspace', `${w.workspace_key} (${w.id})`],
+        ['state', `${w.observed_state} (desired ${w.desired_state})`],
+        ['base version', `${d.base_version.slug} v${d.base_version.version} (${d.base_version.id})`],
+        ['states', String(d.states_count)],
+        ['latest state', d.latest_state ? `${d.latest_state.checkpoint_id}${d.latest_state.label ? ` "${d.latest_state.label}"` : ''} ${time(d.latest_state.captured_at)}` : '-'],
+        ['test instances', `${d.test_instances_live} live`],
+        ['created', `${time(d.created_at)} by ${d.created_by.type}${d.created_by.id ? `:${d.created_by.id}` : ''}`],
+    ]);
+}
+export function draftStateTable(rows) {
+    return table(['STATE', 'LABEL', 'CAPTURED', 'BYTES', 'TEST INSTANCES'], rows.map((st) => [st.checkpoint_id, st.label ?? '-', time(st.captured_at), st.bytes === null ? '-' : String(st.bytes), String(st.test_instances)]));
+}
+export function buildText(b) {
+    return kv([
+        ['build', b.id],
+        ['template', `${b.template.slug} v${b.target_version ?? '?'}`],
+        ['state', `${b.state}${b.failure ? ` (${b.failure.code}: ${b.failure.message})` : ''}`],
+        ['registration', b.registration.state],
+        ['source', b.source_kind === 'workspace' ? `workspace ${b.source_workspace_id ?? '-'}${b.source_checkpoint_id ? ` checkpoint ${b.source_checkpoint_id}` : ''}` : 'recipe'],
+        ['version', b.template_version ? `${b.template_version.id}${b.template_version.published ? ' (published)' : ' (unpublished)'}` : '-'],
+    ]) + (b.state === 'published' || b.state === 'failed' || b.state === 'canceled' ? '' : `the build continues server side (--wait follows it; GET /v1/organizations/${b.organization_id}/template-builds/${b.id} reports it)\n`);
+}

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * The executable is src/bin.ts; `run()` drives the same code in-process.
  */
 export { run, abortableSleep } from './main.js';
-export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, topHelp } from './args.js';
+export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, 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';

package/dist/index.js

@@ -3,7 +3,7 @@
  * The executable is src/bin.ts; `run()` drives the same code in-process.
  */
 export { run, abortableSleep } from "./main.js";
-export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, topHelp } from "./args.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";

package/dist/main.js

@@ -5,7 +5,7 @@
  * the whole CLI can be driven by tests; bin.ts wires it to the real process.
  */
 import { SDK_VERSION, Shardflux } from '@shardflux/sdk';
-import { CLI_VERSION, parseCommandLine, resolveApiUrl } from "./args.js";
+import { CLI_VERSION, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { HANDLERS } from "./commands.js";
 import { AuthConfigError, EXIT, InterruptedError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
 import { errorText, json } from "./format.js";
@@ -76,12 +76,16 @@ export async function run(argv, io, opts = {}) {
         const agentLabel = parsed.global.agentLabel ?? io.env.SHARDFLUX_AGENT_LABEL ?? 'cli';
         if (!isLabel(agentLabel))
             throw new UsageError('--agent-label must be 1-100 printable characters');
+        const wake = resolveWake(parsed.global.wake, io.env.SHARDFLUX_NO_WAKE);
+        const wakeTimeoutMs = resolveWakeTimeout(parsed.global.wakeTimeout, io.env.SHARDFLUX_WAKE_TIMEOUT_MS);
         let cloud;
         ctx = {
             io,
             json: parsed.global.json,
             apiUrl,
             agentLabel,
+            wake,
+            wakeTimeoutMs,
             signal,
             cloud() {
                 if (cloud)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "shard: the Shardflux command line. Open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@shardflux/sdk": "^0.5.0"
+    "@shardflux/sdk": "^0.6.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",