@shardflux/cli 0.3.0 → 0.4.0

package/dist/commands.js

@@ -5,12 +5,16 @@
  * the SDK has no typed method for yet (GET /v1/operations/{id}, usage summary).
  */
 import { randomUUID } from 'node:crypto';
-import { readFile, writeFile } from 'node:fs/promises';
+import { access, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, resolve as resolvePath } from 'node:path';
 import { SDK_VERSION, ShardfluxApiError } from '@shardflux/sdk';
+import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { InterruptedError, NotFoundError, UsageError } from "./errors.js";
+import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
+import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, fileTable, json, kv, operationDetail, operationTable, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, templateEntryText, templateFileTable, templateTable, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, fileTable, languageTable, json, kv, operationDetail, operationTable, packageTable, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, templateDetailText, templateEntryText, templateFileTable, templateTable, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
@@ -154,6 +158,87 @@ function parseVersion(text, what) {
         throw new UsageError(`${what} must be a version number (got "${text}")`);
     return Number(text);
 }
+const SLUG = /^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$/;
+/** `<slug>@<version>`. */
+function parseSlugVersion(text, what) {
+    const at = text.lastIndexOf('@');
+    if (at <= 0)
+        throw new UsageError(`${what} must be <slug>@<version>, e.g. acme-dev@3 (got "${text}")`);
+    const slug = text.slice(0, at);
+    if (!SLUG.test(slug))
+        throw new UsageError(`${what}: "${slug}" is not a template slug`);
+    return { slug, version: parseVersion(text.slice(at + 1), what) };
+}
+const INPUT_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+/**
+ * Open-time text inputs (contracts §24.3) from --input-file (NAME=value lines with # comments, or a JSON object of
+ * strings), then each --input NAME=value (a later one wins). Undefined when neither option is given.
+ */
+async function inputsFrom(ctx, values) {
+    const file = str(values['input-file']);
+    const pairs = strs(values.input);
+    if (file === undefined && pairs.length === 0)
+        return undefined;
+    const out = {};
+    const put = (name, value, where) => {
+        if (!INPUT_NAME.test(name))
+            throw new UsageError(`${where}: "${name}" is not an input name (^[A-Za-z_][A-Za-z0-9_]*$)`);
+        if (/[\r\n\0]/.test(value))
+            throw new UsageError(`${where}: the value of ${name} must be one line without NUL`);
+        out[name] = value;
+    };
+    if (file !== undefined) {
+        const text = Buffer.from(await readInput(ctx, file, 1024 * 1024, '--input-file')).toString('utf8');
+        if (text.trimStart().startsWith('{')) {
+            let doc;
+            try {
+                doc = JSON.parse(text);
+            }
+            catch (e) {
+                throw new UsageError(`--input-file: not valid JSON (${e instanceof Error ? e.message : String(e)})`);
+            }
+            if (typeof doc !== 'object' || doc === null || Array.isArray(doc))
+                throw new UsageError('--input-file: expected a JSON object of NAME: "value"');
+            for (const [k, v] of Object.entries(doc)) {
+                if (typeof v !== 'string')
+                    throw new UsageError(`--input-file: the value of ${k} must be a string`);
+                put(k, v, '--input-file');
+            }
+        }
+        else {
+            for (const [i, raw] of text.split(/\r?\n/).entries()) {
+                const line = raw.trim();
+                if (line === '' || line.startsWith('#'))
+                    continue;
+                const eq = line.indexOf('=');
+                if (eq <= 0)
+                    throw new UsageError(`--input-file line ${i + 1}: expected NAME=value`);
+                put(line.slice(0, eq).trim(), line.slice(eq + 1), `--input-file line ${i + 1}`);
+            }
+        }
+    }
+    for (const p of pairs) {
+        const eq = p.indexOf('=');
+        if (eq <= 0)
+            throw new UsageError(`--input expects NAME=value (got "${p}")`);
+        put(p.slice(0, eq), p.slice(eq + 1), '--input');
+    }
+    return out;
+}
+const BUILD_STATES = ['queued', 'building', 'testing', 'publishing', 'published', 'succeeded', 'failed', 'canceled'];
+/** The exit code of a build the command followed: 6 when it failed, was canceled or could not be registered. */
+function buildExitCode(b) {
+    return b.state === 'failed' || b.state === 'canceled' || b.registration.state === 'failed' ? 6 : 0;
+}
+async function fileExists(path) {
+    return access(path).then(() => true, () => false);
+}
+/** Writes `text` to `path`, refusing to overwrite an existing file without --force. */
+async function writeNew(path, text, force) {
+    if (!force && (await fileExists(path)))
+        throw new UsageError(`${path} exists; pass --force to overwrite it`);
+    await writeFile(path, text);
+}
 /** Waits with the SDK's backoff; Ctrl-C reports the operation that keeps running. */
 async function waitOperation(ctx, operationId, timeoutMs) {
     try {
@@ -279,6 +364,7 @@ export const HANDLERS = {
         const c = caps(values);
         const bind = secretNames(strs(values.secret), '--secret');
         const lifetime = oneOf(values, 'lifetime', LIFETIMES);
+        const inputs = await inputsFrom(ctx, values);
         const timeoutMs = waitTimeout(values);
         const cloud = ctx.cloud();
         // The SDK's waited open: the server holds the request until the workspace is ready (Prefer: wait), then the SDK
@@ -288,6 +374,7 @@ export const HANDLERS = {
             template,
             ...(c ? { caps: c } : {}),
             ...(bind.length ? { secrets: bind } : {}),
+            ...(inputs ? { inputs } : {}),
             ...(lifetime ? { lifetime } : {}),
             agentLabel: ctx.agentLabel,
             wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
@@ -340,6 +427,13 @@ export const HANDLERS = {
         out(ctx, workspaceDetail(ws.data), ws.data);
         return 0;
     },
+    async 'workspaces inputs'(ctx, _values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const inputs = await ws.inputs();
+        const names = Object.keys(inputs);
+        out(ctx, names.length ? kv(names.map((n) => [n, inputs[n]])) : 'No text inputs (secret inputs are bound secrets: shard ws secrets).\n', { inputs });
+        return 0;
+    },
     async 'workspaces exec'(ctx, values, [ref, ...argv]) {
         const env = parseEnvPairs(values.env ?? []);
         const timeout = str(values.timeout);
@@ -504,6 +598,240 @@ export const HANDLERS = {
             ctx.io.stderr.write(`more: shard templates list --cursor ${next}\n`);
         return 0;
     },
+    async 'templates get'(ctx, values, [slug]) {
+        const owner = oneOf(values, 'owner', OWNERS);
+        const detail = await ctx.cloud().templates.get(slug, { ...(owner ? { owner } : {}), ...(values['include-archived'] === true ? { includeArchived: true } : {}) });
+        out(ctx, templateDetailText(detail), detail);
+        return 0;
+    },
+    async 'templates init'(ctx, values) {
+        const baseText = str(values.base);
+        if (!baseText)
+            throw new UsageError('--base <slug[@version]> is required for "shard templates init", e.g. --base ubuntu-24.04');
+        const dest = str(values.out) ?? 'template.yaml';
+        if (values.force !== true && (await fileExists(dest)))
+            throw new UsageError(`${dest} exists; pass --force to overwrite it`);
+        let base;
+        if (baseText.includes('@')) {
+            const { slug, version } = parseSlugVersion(baseText, '--base');
+            base = `${slug}@${version}`;
+        }
+        else {
+            if (!SLUG.test(baseText))
+                throw new UsageError(`--base: "${baseText}" is not a template slug`);
+            const t = await ctx.cloud().templates.get(baseText);
+            const v = t.open_resolves_to?.version ?? t.open_version?.version;
+            if (v === undefined)
+                throw new NotFoundError(`${baseText} has no published version to start from; name one with --base ${baseText}@<version>`);
+            base = `${baseText}@${v}`;
+        }
+        await writeNew(dest, initTemplateYaml(base), values.force === true);
+        const dir = basename(dirname(resolvePath(dest)));
+        const slugHint = SLUG.test(dir.toLowerCase()) ? '' : ' --slug <slug>';
+        out(ctx, `Wrote ${dest} (base ${base}).\nEdit it, then build it with: shard templates build ${dest}${slugHint} --wait\n`, { path: dest, base });
+        return 0;
+    },
+    async 'templates build'(ctx, values, [file]) {
+        const path = resolvePath(file);
+        const given = str(values.slug);
+        const dirName = basename(dirname(path));
+        const slug = given ?? dirName.toLowerCase();
+        if (!SLUG.test(slug))
+            throw new UsageError(given !== undefined ? `--slug "${given}" is not a template slug (lower-case letters, digits, ".", "_" and "-")` : `the directory name "${dirName}" is not a template slug; pass --slug <slug>`);
+        const ack = acknowledged(values);
+        const t = str(values.timeout);
+        const timeoutMs = t === undefined ? DEFAULT_BUILD_WAIT_MS : parseDuration(t, 'timeout');
+        const displayName = str(values['display-name']);
+        const description = str(values.description);
+        const timer = new BuildTimer();
+        const progress = (e) => {
+            timer.record(e);
+            if (!ctx.json)
+                ctx.io.stderr.write(progressLine(e));
+        };
+        if (!ctx.json)
+            ctx.io.stderr.write(`Building ${slug} from ${file}${given === undefined ? ' (template slug from the directory name; --slug to choose)' : ''}\n`);
+        let res;
+        try {
+            res = await ctx.cloud().templates.buildFromFile(path, {
+                templateSlug: slug,
+                ...(displayName !== undefined ? { displayName } : {}),
+                ...(description !== undefined ? { description } : {}),
+                autoPublish: values.publish === true,
+                ...(ack ? { acknowledgedScanFindings: ack } : {}),
+                parseYaml: (text) => parseYaml(text),
+                onProgress: progress,
+                ...(values.wait === true ? { wait: { timeoutMs, signal: ctx.signal } } : {}),
+                signal: ctx.signal,
+            });
+        }
+        catch (err) {
+            timer.finish(null);
+            if (ctx.timing && !ctx.json)
+                ctx.io.stderr.write(buildTimingText(timer));
+            if (ctx.signal.aborted)
+                throw new InterruptedError(timer.buildId ? `Interrupted; build ${timer.buildId} continues server side.` : 'Interrupted.');
+            throw err;
+        }
+        timer.finish(res.build);
+        if (ctx.timing && !ctx.json)
+            ctx.io.stderr.write(buildTimingText(timer));
+        const b = res.build;
+        const next = b.template_version && !b.template_version.published ? `test it with: shard templates test ${b.template.slug}@${b.template_version.version}\n` : '';
+        const machine = { build: b, uploads: res.uploads, ...(ctx.timing ? { timing: buildTimingJson(timer) } : {}) };
+        ctx.io.stdout.write(ctx.json ? json(machine) : `${buildText(b)}${next}`);
+        return values.wait === true ? buildExitCode(b) : 0;
+    },
+    async 'templates export'(ctx, values, [ref]) {
+        const { slug, version } = parseSlugVersion(ref, '<slug@version>');
+        const owner = oneOf(values, 'owner', OWNERS);
+        const exp = await ctx.cloud().templates.versions.recipe(slug, version, owner ? { owner } : {});
+        if (ctx.json) {
+            ctx.io.stdout.write(json(exp));
+            return 0;
+        }
+        if (exp.recipe === null) {
+            throw new NotFoundError(`${slug} v${version} has no recipe to export (${exp.source_kind === 'workspace' ? 'it was saved from a workspace or a draft' : 'a platform version or a version without a recipe'}); its settings: shard templates get ${slug}`);
+        }
+        const text = recipeYaml(exp.recipe, `${slug} v${version}${exp.source_kind ? ` (${exp.source_kind})` : ''}. Build it again with: shard templates build <this file> --slug ${slug}`);
+        const dest = str(values.out);
+        if (dest === undefined)
+            ctx.io.stdout.write(text);
+        else {
+            await writeNew(dest, text, values.force === true);
+            ctx.io.stderr.write(`wrote ${dest}\n`);
+        }
+        return 0;
+    },
+    async 'templates test'(ctx, values, [ref]) {
+        const { slug, version } = parseSlugVersion(ref, '<slug@version>');
+        const c = caps(values);
+        const inputs = await inputsFrom(ctx, values);
+        const timeoutMs = waitTimeout(values);
+        const instanceKey = str(values['instance-key']);
+        let ws = await ctx.cloud().templates.versionTestInstances.create(slug, version, {
+            ...(instanceKey ? { key: instanceKey } : {}),
+            ...(c ? { caps: c } : {}),
+            ...(inputs ? { inputs } : {}),
+            agentLabel: ctx.agentLabel,
+            wait: false,
+        });
+        const op = ws.activeOperation;
+        if (values.wait !== false && !ws.ready && op) {
+            await waitOperation(ctx, op.id, timeoutMs);
+            ws = await ctx.cloud().workspaces.get(ws.id);
+        }
+        const human = ws.ready
+            ? `Test instance ${ws.key} (${ws.id}) of ${slug} v${version} is ready. It ends with: shard ws close ${ws.key}\n${workspaceDetail(ws.data)}`
+            : `Test instance ${ws.key} (${ws.id}) of ${slug} v${version} is ${ws.state}${op ? `; operation ${op.id} ${op.kind} ${op.state}` : ''}.\n${op ? `wait with: shard operations wait ${op.id}\n` : ''}`;
+        out(ctx, human, ws.data);
+        return 0;
+    },
+    async 'templates builds list'(ctx, values) {
+        const cloud = ctx.cloud();
+        const org = (await principal(ctx)).organization_id;
+        const state = oneOf(values, 'state', BUILD_STATES);
+        const template = str(values.template);
+        const limit = listLimit(values, 200);
+        const params = { ...(state ? { state } : {}), ...(template ? { template } : {}) };
+        let rows = [];
+        let next = null;
+        if (values.all === true) {
+            let cursor;
+            do {
+                const page = await cloud.templates.builds.list(org, { ...params, limit: limit ?? 200, ...(cursor ? { cursor } : {}) });
+                rows.push(...page.data);
+                cursor = page.nextCursor ?? undefined;
+                if (ctx.signal.aborted)
+                    throw new InterruptedError('Interrupted.');
+            } while (cursor);
+        }
+        else {
+            const cursor = str(values.cursor);
+            const page = await cloud.templates.builds.list(org, { ...params, ...(limit ? { limit } : {}), ...(cursor ? { cursor } : {}) });
+            rows = page.data;
+            next = page.nextCursor;
+        }
+        out(ctx, rows.length ? buildTable(rows) : 'No template builds.\n', { data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard templates builds list --cursor ${next}\n`);
+        return 0;
+    },
+    async 'templates builds get'(ctx, _values, [id]) {
+        if (!UUID.test(id))
+            throw new UsageError(`<build-id> must be a UUID (got "${id}")`);
+        const org = (await principal(ctx)).organization_id;
+        const b = await ctx.cloud().templates.builds.get(org, id);
+        out(ctx, buildText(b), b);
+        return 0;
+    },
+    async 'templates builds log'(ctx, values, [id]) {
+        if (!UUID.test(id))
+            throw new UsageError(`<build-id> must be a UUID (got "${id}")`);
+        const org = (await principal(ctx)).organization_id;
+        const cloud = ctx.cloud();
+        let text;
+        try {
+            const link = await cloud.templates.builds.logUrl(org, id);
+            const res = await fetch(link.url, { signal: ctx.signal });
+            if (!res.ok)
+                throw new Error(`the log download answered HTTP ${res.status}`);
+            text = new Uint8Array(await res.arrayBuffer());
+        }
+        catch (err) {
+            // Not recorded yet (or expired): the build view's tail is the most there is.
+            if (!(err instanceof ShardfluxApiError && err.status === 404))
+                throw err;
+            const b = await cloud.templates.builds.get(org, id);
+            if (!b.log.tail)
+                throw err;
+            ctx.io.stderr.write(`the full log is not available (${typeof err.details?.reason === 'string' ? err.details.reason : err.code}); the build's log tail follows\n`);
+            text = new TextEncoder().encode(b.log.tail.endsWith('\n') ? b.log.tail : `${b.log.tail}\n`);
+        }
+        const dest = str(values.out);
+        if (dest !== undefined) {
+            await writeFile(dest, text);
+            out(ctx, `wrote ${text.length} bytes to ${dest}\n`, { build_id: id, bytes: text.length, out: dest });
+        }
+        else if (ctx.json)
+            ctx.io.stdout.write(json({ build_id: id, bytes: text.length, log: Buffer.from(text).toString('utf8') }));
+        else
+            ctx.io.stdout.write(text);
+        return 0;
+    },
+    async 'templates builds cancel'(ctx, _values, [id]) {
+        if (!UUID.test(id))
+            throw new UsageError(`<build-id> must be a UUID (got "${id}")`);
+        const org = (await principal(ctx)).organization_id;
+        const b = await ctx.cloud().templates.builds.cancel(org, id);
+        out(ctx, `${b.state === 'canceled' ? 'Canceled' : 'Cancellation requested for'} build ${b.id} (${b.template.slug} v${b.target_version ?? '?'}).\n${buildText(b)}`, b);
+        return 0;
+    },
+    async 'templates languages'(ctx, values) {
+        const base = str(values.base);
+        if (base === undefined)
+            throw new UsageError('--base <slug@version> is required for "shard templates languages", e.g. --base ubuntu-24.04@1');
+        parseSlugVersion(base, '--base');
+        const langs = await ctx.cloud().templates.languages(base);
+        out(ctx, `${languageTable(langs)}platform base ${langs.platform_base}; apt packages need ${langs.apt_hosts.join(', ') || '(no host)'}\n`, langs);
+        return 0;
+    },
+    async 'templates packages search'(ctx, values, [ecosystem, query]) {
+        if (ecosystem !== 'apt' && ecosystem !== 'pip' && ecosystem !== 'npm')
+            throw new UsageError(`<ecosystem> must be apt, pip or npm (got "${ecosystem}")`);
+        const base = str(values.base);
+        if (ecosystem === 'apt' && base === undefined)
+            throw new UsageError('apt needs --base <slug@version> (the base whose package index to search)');
+        if (base !== undefined)
+            parseSlugVersion(base, '--base');
+        if (query.length < 1 || query.length > 100)
+            throw new UsageError('<query> must be 1-100 characters');
+        const limit = listLimit(values, 50);
+        const page = await ctx.cloud().templates.packages.search(ecosystem, query, { ...(base ? { base } : {}), ...(limit ? { limit } : {}) });
+        const note = page.source === 'pypi_names' ? '(pip: names only; the build installs the latest version unless you pin one, e.g. pandas==2.3.2)\n' : '';
+        out(ctx, page.data.length ? `${packageTable(page)}${note}` : `No ${ecosystem} packages match "${query}".\n`, page);
+        return 0;
+    },
     async 'templates files'(ctx, values, [slug, versionText, path]) {
         const version = parseVersion(versionText, '<version>');
         const owner = oneOf(values, 'owner', OWNERS);

package/dist/errors.d.ts

@@ -10,7 +10,7 @@ export declare const EXIT: {
     readonly auth: 4;
     /** Waiting ran out of time (the operation continues server side), or a request timed out. */
     readonly timeout: 5;
-    /** The awaited operation ended `failed` or `canceled`. */
+    /** The awaited operation ended `failed` or `canceled` (the error's `retryable` says whether a retry may succeed). */
     readonly operationFailed: 6;
     /** SIGINT (Ctrl-C). */
     readonly interrupted: 130;

package/dist/errors.js

@@ -3,7 +3,7 @@
  * stderr with the API's error code, message and request id; the process exit
  * code tells scripts what kind of failure it was (README "Exit codes").
  */
-import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from '@shardflux/sdk';
+import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
 export const EXIT = {
     ok: 0,
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -16,7 +16,7 @@ export const EXIT = {
     auth: 4,
     /** Waiting ran out of time (the operation continues server side), or a request timed out. */
     timeout: 5,
-    /** The awaited operation ended `failed` or `canceled`. */
+    /** The awaited operation ended `failed` or `canceled` (the error's `retryable` says whether a retry may succeed). */
     operationFailed: 6,
     /** SIGINT (Ctrl-C). */
     interrupted: 130,
@@ -69,10 +69,22 @@ export function describeError(err) {
     if (err instanceof OperationTimeoutError)
         return { code: 'timeout', message: err.message, operation_id: err.operationId, last_state: err.lastState };
     if (err instanceof OperationFailedError) {
-        return { code: 'operation_failed', message: err.message, operation_id: err.operationId, ...(err.errorCode ? { details: { error_code: err.errorCode } } : {}), operation: err.operation };
+        // retryable: the operation error's own flag (true for capacity_unavailable: nothing was started, retry later).
+        // details.reason: the operation error's reason (e.g. the scheduler's no_ready_hosts), printed after the message.
+        const opDetails = err.operation.error?.details;
+        const reason = typeof opDetails === 'object' && opDetails !== null ? opDetails.reason : undefined;
+        const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
+        return { code: 'operation_failed', message: err.message, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}), operation: err.operation };
     }
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };
+    // Template builds (0.4.0): a template file that cannot be read or packed is a usage error; a wait that ran out names the build.
+    if (err instanceof TemplateFileError)
+        return { code: 'usage', message: err.message };
+    if (err instanceof TemplateBuildTimeoutError)
+        return { code: 'timeout', message: `${err.message}; follow it with: shard templates builds get ${err.build.id}`, last_state: err.build.state };
+    if (err instanceof TemplateUploadError)
+        return { code: 'upload_failed', message: err.message, ...(err.status ? { status: err.status } : {}), details: { sha256: err.sha256, ...(err.code ? { storage_code: err.code } : {}) } };
     if (err instanceof AuthConfigError)
         return { code: 'unauthenticated', message: err.message };
     if (err instanceof NotFoundError)
@@ -95,10 +107,12 @@ export function describeError(err) {
 export function exitCodeFor(err, interrupted = false) {
     if (interrupted || err instanceof InterruptedError)
         return EXIT.interrupted;
-    if (err instanceof UsageError)
+    if (err instanceof UsageError || err instanceof TemplateFileError)
         return EXIT.usage;
     if (err instanceof AuthConfigError)
         return EXIT.auth;
+    if (err instanceof TemplateBuildTimeoutError)
+        return EXIT.timeout;
     if (err instanceof NotFoundError)
         return EXIT.notFound;
     if (err instanceof OperationTimeoutError || isNamed(err, 'TimeoutError'))

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, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateSummary, WorkspaceChange, WorkspaceSecretBindings, WorkspaceView } from '@shardflux/sdk';
+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 { ErrorInfo } from './errors.js';
 export declare function json(value: unknown): string;
 export declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): string;
@@ -19,6 +19,13 @@ 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;
+/**
+ * The startup of a workspace's template version (contracts §24.4) in one line: state, trigger, and for a failure the
+ * step or service, exit code and reason. Null when the version has no start commands or services.
+ */
+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;
 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;
@@ -36,7 +43,10 @@ export declare function bindingsText(b: WorkspaceSecretBindings): string;
  * freshness, then meters and allowances as tables. 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. */
+/**
+ * One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. A failed
+ * operation also shows `retryable=true|false`.
+ */
 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). */
@@ -49,3 +59,10 @@ 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;
+export declare function buildTable(rows: readonly TemplateBuild[]): string;
+export declare function languageTable(l: TemplateLanguages): string;
+export declare function packageTable(page: TemplatePackagePage): string;
+/** A template: identity, what open resolves to, its versions, and the open version's settings. */
+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;

package/dist/format.js

@@ -67,8 +67,43 @@ export function workspaceTable(ws) {
 export function isReady(w) {
     return w.observed_state === 'running' && w.desired_state === 'running' && w.deleted_at === null;
 }
+/** A workspace's origin: a fork, a draft state (draft test instance) or a template version (version test instance). */
+function originText(o) {
+    switch (o.kind) {
+        case 'fork':
+            return `fork of ${o.workspace_id}`;
+        case 'draft_state':
+            return `draft state ${o.checkpoint_id ?? '(capturing)'} of ${o.draft_workspace_id}`;
+        default:
+            return `template ${o.template_id} version ${o.version}`;
+    }
+}
+/**
+ * The startup of a workspace's template version (contracts §24.4) in one line: state, trigger, and for a failure the
+ * step or service, exit code and reason. Null when the version has no start commands or services.
+ */
+export function startupText(s) {
+    if (!s)
+        return null;
+    if (s.state === 'pending')
+        return 'pending (a start is in progress)';
+    const where = s.service ? `service ${s.service}` : s.step ? `step ${s.step}` : null;
+    if (s.state === 'failed') {
+        const exit = s.exit_code !== null ? `, exit ${s.exit_code}` : '';
+        return `failed${where ? ` at ${where}` : ''}${exit}${s.reason ? ` (${s.reason})` : ''}${s.trigger ? `, trigger ${s.trigger}` : ''}; the next open runs it again`;
+    }
+    return `${s.state}${s.trigger ? ` (${s.trigger})` : ''}${s.state === 'running' && where ? `: ${where}` : ''}`;
+}
+/** The failed step's output tail, indented, after the detail block (empty otherwise). */
+export function startupTail(s) {
+    if (!s || s.state !== 'failed' || !s.output_tail)
+        return '';
+    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`;
+}
 export function workspaceDetail(w) {
     const c = w.ceilings;
+    const startup = startupText(w.startup);
     return kv([
         ['id', w.id],
         ['key', w.workspace_key],
@@ -81,19 +116,20 @@ export function workspaceDetail(w) {
         ['caps', pairs(w.caps)],
         ['operation', w.active_operation ? `${operationSummary(w.active_operation)} ${w.active_operation.id}` : '-'],
         ['pending', w.pending_reason ?? '-'],
+        ...(startup ? [['startup', startup]] : []),
         ['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.origin ? [['origin', originText(w.origin)]] : []),
                 ...(w.ended_reason ? [['ended', w.ended_reason]] : []),
             ]
             : []),
         ['created', time(w.created_at)],
         ['deleted', time(w.deleted_at)],
-    ]);
+    ]) + startupTail(w.startup);
 }
 export const OPERATION_HEADERS = ['ID', 'KIND', 'STATE', 'REASON', 'CREATED', 'COMPLETED'];
 export function operationTable(ops) {
@@ -212,7 +248,10 @@ export function usageText(summary) {
         out += `\n${allowances}`;
     return out || json(summary);
 }
-/** One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. */
+/**
+ * One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. A failed
+ * operation also shows `retryable=true|false`.
+ */
 export function errorText(e, hint) {
     const meta = [`code=${e.code}`];
     if (e.status !== undefined)
@@ -223,6 +262,8 @@ export function errorText(e, hint) {
         meta.push(`operation_id=${e.operation_id}`);
     if (e.source === 'cell')
         meta.push('source=cell');
+    if (e.code === 'operation_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('')
@@ -296,13 +337,62 @@ export function draftText(d) {
 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)]));
 }
+function buildSource(b) {
+    if (b.source_kind === 'workspace')
+        return `workspace ${b.source_workspace_id ?? '-'}${b.source_checkpoint_id ? ` checkpoint ${b.source_checkpoint_id}` : ''}`;
+    const v2 = b.provenance.recipe_schema === 'shardflux.template-recipe.v2';
+    return `recipe${v2 ? ' v2' : ''}${b.provenance.recipe_sha256 ? ` (sha256 ${b.provenance.recipe_sha256.slice(0, 12)})` : ''}`;
+}
 export function buildText(b) {
-    return kv([
+    const settled = b.state === 'published' || b.state === 'failed' || b.state === 'canceled' || b.state === 'succeeded';
+    const denied = b.denied_hosts ?? [];
+    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'],
+        ['registration', `${b.registration.state}${b.registration.error ? ` (${b.registration.error.code}: ${b.registration.error.message})` : ''}`],
+        ['source', buildSource(b)],
+        ['network', b.network.mode === 'none' ? 'none' : `allowlist ${b.network.allow_hosts.join(', ') || '(empty)'}`],
+        ...(denied.length ? [['denied hosts', `${denied.join(', ')} (allow one: add it to build.network.extra_hosts and build again)`]] : []),
         ['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`);
+        ['created', time(b.created_at)],
+    ]) + (settled ? '' : `the build continues server side (--wait follows it; shard templates builds get ${b.id} reports it)\n`));
+}
+export function buildTable(rows) {
+    return table(['ID', 'TEMPLATE', 'STATE', 'REGISTRATION', 'SOURCE', 'CREATED'], rows.map((b) => [b.id, `${b.template.slug} v${b.target_version ?? '?'}`, b.state, b.registration.state, b.source_kind === 'workspace' ? 'workspace' : b.provenance.recipe_schema === 'shardflux.template-recipe.v2' ? 'recipe v2' : 'recipe', time(b.created_at)]));
+}
+export function languageTable(l) {
+    return table(['ID', 'NAME', 'VERSION', 'DEFAULT', 'SOURCE', 'HOSTS'], l.data.map((x) => [x.id, x.name, x.version, x.default ? 'yes' : '-', x.included ? `included${x.base_version ? ` (${x.base_version})` : ''}` : x.apt.length ? `apt ${x.apt.join(' ')}` : 'download', x.hosts.join(', ') || '-']));
+}
+export function packageTable(page) {
+    return table(['NAME', 'VERSION', 'SUMMARY'], page.data.map((p) => [p.name, p.version ?? '-', p.summary ? (p.summary.length > 80 ? `${p.summary.slice(0, 79)}…` : p.summary) : '-']));
+}
+/** A template: identity, what open resolves to, its versions, and the open version's settings. */
+export function templateDetailText(t) {
+    const open = t.open_version;
+    const head = kv([
+        ['template', `${t.slug} (${t.name})`],
+        ['owner', `${t.owner}${t.category ? `, ${t.category}` : ''}`],
+        ['open resolves to', t.open_resolves_to ? `v${t.open_resolves_to.version} (${t.open_resolves_to.owner})` : '-'],
+        ['draft', t.draft ? `${t.draft.workspace_key} (${t.draft.observed_state})` : '-'],
+        ['archived', time(t.archived_at)],
+    ]);
+    const versions = t.versions.length
+        ? table(['VERSION', 'STATE', 'SOURCE', 'LAYOUTS', 'CREATED', 'DESCRIPTION'], t.versions.map((v) => [`v${v.version}${v.is_open_version ? ' *' : ''}`, v.state, v.source?.kind ?? '-', v.disk_layouts.join(',') || '-', time(v.created_at), v.description ?? '-']))
+        : 'No versions.\n';
+    return `${head}\n${versions}${open?.settings ? `\nsettings of v${open.version}:\n${settingsText(open.settings)}` : ''}`;
+}
+/** A version's settings (contracts §24.3), one line per part. */
+export function settingsText(s) {
+    const inputs = Object.entries(s.inputs).map(([n, i]) => `${n} (${i.kind}${i.required ? ', required' : ''}${i.default !== null ? `, default ${JSON.stringify(i.default)}` : ''})`);
+    const d = s.defaults;
+    const egress = d.egress ? (d.egress.mode === 'none' ? 'none' : `allowlist ${d.egress.allow_hosts.join(', ')}`) : 'internet (the project policy)';
+    return kv([
+        ['env', Object.keys(s.env).length ? Object.keys(s.env).join(', ') : '-'],
+        ['inputs', inputs.length ? inputs.join('; ') : '-'],
+        ['start', s.start.length ? s.start.map((c) => `${c.name} (${c.when})`).join(', ') : '-'],
+        ['services', Object.keys(s.services).length ? Object.entries(s.services).map(([n, v]) => `${n}${v.ready ? ('port' in v.ready ? ` (ready: port ${v.ready.port})` : ' (ready: command)') : ''}`).join(', ') : '-'],
+        ['lifetime', `${d.lifetime}${d.idle_timeout_seconds ? `, idle ${d.idle_timeout_seconds} s` : ''}`],
+        ['egress', egress],
+    ]).replace(/^/gm, '  ');
 }

package/dist/main.js

@@ -31,6 +31,9 @@ export function abortableSleep(signal) {
 function hintFor(info) {
     if (info.code === 'timeout' && info.operation_id)
         return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
+    if (info.code === 'operation_failed' && info.retryable) {
+        return info.details?.error_code === 'capacity_unavailable' ? 'no host could admit it before its deadline; nothing was started. Retry later.' : 'the operation may succeed if you retry it later.';
+    }
     if (info.code === 'interrupted' && info.operation_id)
         return `keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'unauthenticated' && info.status === undefined)