@shardflux/cli 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -3,7 +3,35 @@
 Every command and option the README shows is available from the version named here. Below 1.0, a minor release may
 break compatibility; breaking changes are marked **Breaking**.
 
-## 0.3.1 (not yet published; npm `latest` is 0.3.0)
+## 0.4.0 (not yet published; npm `latest` is 0.3.1)
+
+Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
+
+### Template editor (contracts §24)
+
+- `shard templates build <file> [--slug] [--display-name] [--description] [--publish] [--acknowledge PATH]... [--wait]
+  [--timeout] [--timing]`: builds a template from template.yaml. Local `from` files and folders are uploaded (folders
+  as the reproducible tar the SDKs pack; bytes the organization has are not sent again), then the recipe v2 build is
+  created. Progress on stderr; `--wait` follows the build (exit 6 failed or canceled, 5 timeout); `--timing` prints
+  packing, uploads, the request, the wait and the build's queued and run time (a `timing` field with `--json`). The
+  slug defaults to the directory holding the file. The version stays unpublished unless `--publish`.
+- `shard templates init --base <slug[@version]> [--out] [--force]`: a starter template.yaml.
+- `shard templates export <slug>@<version> [--out]`: the template.yaml a version was built from (exit 3 for a version
+  without a recipe).
+- `shard templates get <slug>`: versions, what open resolves to, the open version's settings.
+- `shard templates test <slug>@<version> [--input NAME=value]...`: a test instance of a version, published or not.
+- `shard templates builds list|get|log|cancel`.
+- `shard templates languages --base <slug>@<version>` and `shard templates packages search <apt|pip|npm> <query>`.
+- `shard workspaces open --input NAME=value` (repeatable) and `--input-file` (NAME=value lines or a JSON object);
+  `shard workspaces inputs <ws>`.
+- `shard workspaces get` (and the ready output of `open`) shows the startup of the template's start commands and
+  services; a failed step shows its exit code, reason and output tail.
+- A template file `shard` cannot read or pack is a usage error (exit 2); a storage refusal of an upload is
+  `upload_failed` (exit 1); a build wait that runs out is `timeout` (exit 5).
+- `buildText` names a recipe v2 build's recipe sha256, its build network and denied hosts, and points at
+  `shard templates builds get`.
+
+## 0.3.1 (2026-09-28)
 
 Needs `@shardflux/sdk` 0.6.2 or later.
 

package/README.md

@@ -56,9 +56,10 @@ every run.
 | `login`, `whoami` | Show the principal behind the key. |
 | `version` | Print the CLI and SDK versions. |
 | `usage [--org <id>]` | Usage summary for the current period: plan, meters and allowances. |
-| `workspaces open <key> --template <slug> [--secret NAME]... [--lifetime persistent\|session] [--cpu-millis N --memory-mib N --disk-gib N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. |
+| `workspaces open <key> --template <slug> [--secret NAME]... [--input NAME=value]... [--input-file F] [--lifetime persistent\|session] [--cpu-millis N --memory-mib N --disk-gib N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready (the template's start commands and services included) unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--input` (0.4.0+) passes the template's text inputs (replacing those of an existing workspace); `--input-file` reads `NAME=value` lines or a JSON object. `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. |
 | `workspaces list [--state S] [--prefix P] [--lifetime persistent\|session\|any] [--purpose standard\|template_draft\|template_test\|any] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. By default only persistent standard workspaces are listed. |
-| `workspaces get <id\|key>` | One workspace (deleted ones included). |
+| `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. |
+| `workspaces inputs <id\|key>` | The workspace's text inputs (0.4.0+). |
 | `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. |
 | `files read <id\|key> <path> [--out F]` | Raw bytes to stdout, or to a local file. |
 | `files write <id\|key> <path> [--from F\|-] [--append] [--no-parents]` | Atomic write. The default source is stdin. |
@@ -79,6 +80,14 @@ every run.
 | `secrets versions <id\|NAME>`, `secrets delete <id\|NAME> --yes`, `secrets access-log <id\|NAME>` | Versions, deletion (also removes the name from every workspace binding), and the access log. |
 | `operations list <id\|key> [--state S] [--kind K]`, `operations get <op>`, `operations wait <op> [--timeout T] [--timing]` | Operations. |
 | `templates list [--owner platform\|organization] [--include-archived] [--all]` | Templates the project can open, with their open version, layouts, file list state and draft. |
+| `templates get <slug> [--owner O] [--include-archived]` | One template (0.4.0+): its versions, what open resolves to, and the open version's settings (env, inputs, start commands, services, defaults). |
+| `templates init --base <slug[@version]> [--out F] [--force]` | Write a starter `template.yaml` on a base (0.4.0+). |
+| `templates build <file> [--slug S] [--display-name N] [--description T] [--publish] [--acknowledge PATH]... [--wait] [--timeout 30m] [--timing]` | Build a template from `template.yaml` (0.4.0+): local files and folders are uploaded, then the build is created. See [Build a template](#build-a-template-from-templateyaml). |
+| `templates export <slug>@<version> [--out F] [--force]` | The `template.yaml` a version was built from, ready to build again (0.4.0+). |
+| `templates test <slug>@<version> [--input NAME=value]... [--instance-key K] [caps] [--no-wait] [--timing]` | A test instance of a version, published or not: a session workspace that runs its start commands and services (0.4.0+). |
+| `templates builds list [--template S] [--state S] [--all]`, `templates builds get\|log\|cancel <build-id>` | The organization's template builds, one build, its full log (`--out F`), or cancel it (0.4.0+). |
+| `templates languages --base <slug>@<version>` | The languages and versions a base offers `build.languages` (0.4.0+). |
+| `templates packages search <apt\|pip\|npm> <query> [--base slug@version] [--limit N]` | Package names for `build.packages` (0.4.0+). apt searches the base's index and needs `--base`. |
 | `templates files <slug> <version> [path] [--stat] [--owner O] [--all] [--limit N]` | One directory of a version's file tree, or one entry with `--stat`. |
 | `templates diff <slug> --from <version\|base> --to <version> [--prefix P] [--change K] [--all]` | Diff two versions: added, removed, changed, type_changed, metadata. The totals come first. |
 | `templates draft open <slug> [--base slug@version] [caps] [--no-wait]` | Open the template's draft, a layered workspace you edit with `workspaces exec`/`files`. |
@@ -94,6 +103,51 @@ is a UUID. Otherwise, or if no workspace has that id, it is matched as an exact
 and purpose, so sessions, drafts and test instances resolve too. The live workspace wins over tombstones that ended
 sessions left with the same key.
 
+## Build a template from template.yaml
+
+(0.4.0+) A template is a recipe v2: a base, what the build adds (languages, packages, files, build steps) and the
+settings a workspace gets when it opens (environment, inputs, start commands, services). `template.yaml` is that
+document; a file entry may name a local `from` path (relative to the file), which `shard` uploads.
+
+```sh
+shard templates init --base ubuntu-24.04            # writes template.yaml on the base's current version
+$EDITOR template.yaml
+shard templates languages --base ubuntu-24.04@1    # what build.languages offers there
+shard templates packages search apt ffmpeg --base ubuntu-24.04@1
+shard templates build template.yaml --slug acme-dev --wait --timing
+shard templates test acme-dev@1 --input PROJECT_NAME=demo
+shard templates build template.yaml --slug acme-dev --publish --wait
+shard ws open acme/main --template acme-dev --input PROJECT_NAME=acme
+```
+
+```yaml
+base: ubuntu-24.04@1
+build:
+  languages: [{ id: python }]
+  packages: { apt: [jq], pip: { packages: [pandas==2.3.2] } }
+  files:
+    - { from: ./app, to: /home/user/app, owner: user }              # a folder: uploaded as a tar
+    - { from: ./settings.toml, to: /home/user/.config/acme/settings.toml, owner: user, mode: "0600" }
+  steps:
+    - { name: install, run: pip install -e /home/user/app, user: user }
+settings:
+  env: { APP_ENV: development }
+  inputs: { PROJECT_NAME: { kind: text, required: true } }
+  start: [{ name: seed, when: create, run: python -m app.seed, user: user, cwd: /home/user/app }]
+```
+
+- Folders are packed as a reproducible tar (the same bytes as the SDKs pack), so the same folder gives the same
+  upload and the same `recipe_sha256`. Bytes the organization already has are not sent again. Progress lines go to
+  stderr (`packed`, `uploaded` or `already uploaded`, then the build's states with `--wait`).
+- The version stays unpublished unless you pass `--publish`: try it with `shard templates test <slug>@<version>`.
+  Without `--slug` the template slug is the name of the directory holding the file.
+- `--wait` follows the build until it is registered or fails (exit 6 when it failed or was canceled, 5 when
+  `--timeout` ran out; the build continues). A build whose network refused a host lists it under `denied hosts`: add
+  it to `build.network.extra_hosts` and build again.
+- `--timing` prints where the time went: packing, uploads, the request, the wait, and the build's queued and run time.
+- A file `shard` cannot read or pack (a symlink that leaves the folder, a device) is refused before any request (exit
+  2). The API's refusals (`upload_missing`, `language_unavailable`, `invalid_settings`, ...) exit 2 with the reason.
+
 ## Suspended workspaces
 
 `workspaces exec`, `files read|write|ls` and `workspaces changes` wake a suspended workspace: they
@@ -154,7 +208,8 @@ Here the time went to waiting for a host with capacity; the network and the VM s
 
 Which call is timed:
 
-- `workspaces open` and `templates draft open|test`: the open, including the wait unless `--no-wait`.
+- `workspaces open`, `templates test` and `templates draft open|test`: the open, including the wait unless `--no-wait`.
+- `templates build` (0.4.0+): packing, uploads, the request and the wait, then the build's own queued and run time.
 - `workspaces suspend|resume|fork|delete|close|reset` and `templates draft state|discard`: with `--wait`, the request
   and the whole wait; without it, the request.
 - `operations wait`: the wait.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.3.1";
+export declare const CLI_VERSION = "0.4.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -10,7 +10,7 @@
  */
 import { parseArgs } from 'node:util';
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.3.1';
+export const CLI_VERSION = '0.4.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -58,6 +58,17 @@ const SAVE = {
     wait: { type: 'boolean', description: 'Wait until the build is published and registered (or fails).' },
     timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 30m). The build continues server side.' },
 };
+/** Open-time text inputs of a template version (0.4.0; contracts §24.3). */
+const INPUTS = {
+    input: {
+        type: 'string',
+        multiple: true,
+        value: '<NAME=value>',
+        description: 'Text input of the template version (repeatable): in the environment of every exec, terminal, start command and service. Replaces the inputs of an existing workspace; omit to leave them unchanged. Not for credentials: those are secret inputs (stored secrets).',
+    },
+    'input-file': { type: 'string', value: '<file>', description: 'Read text inputs from a file: NAME=value lines (# comments), or a JSON object. --input wins for a name in both.' },
+};
+const BUILD_ID = { name: 'build-id', required: true };
 const LIFETIME_FILTER = {
     lifetime: { type: 'string', value: '<persistent|session|any>', description: 'Lifetime filter (default persistent: sessions are hidden).' },
     purpose: { type: 'string', value: '<standard|template_draft|template_test|any>', description: 'Purpose filter (default standard: template drafts and test instances are hidden).' },
@@ -109,14 +120,16 @@ export const COMMANDS = [
                 value: '<persistent|session>',
                 description: 'session: the workspace is discarded when the session ends ("shard ws close" or the idle timeout) and the key then opens a new one. Default: the template’s default, else persistent.',
             },
+            ...INPUTS,
             ...CAPS,
-            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
+            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once). Ready includes the template’s start commands and services.' },
             timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m). The start continues server side; one waiting for capacity gives up 15 minutes after it began (capacity_unavailable, retryable).' },
             ...TIMING,
         },
         examples: [
             'shard workspaces open acme/demo --template python-node-browser',
             'shard ws open job-42 --template python-node-browser --lifetime session',
+            'shard ws open acme/demo --template acme-notebook --input PROJECT_NAME=demo --input LOG_LEVEL=debug',
             'shard ws open acme/demo --template python-node-browser --secret OPENAI_API_KEY --secret DATABASE_URL',
             'shard ws open acme/demo --template python-node-browser --no-wait --json',
             'shard ws open acme/demo --template python-node-browser --timing',
@@ -136,7 +149,8 @@ export const COMMANDS = [
             cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
         },
     },
-    { path: ['workspaces', 'get'], summary: 'Show one workspace', positionals: [REF], options: {} },
+    { path: ['workspaces', 'get'], summary: 'Show one workspace (state, template, startup)', positionals: [REF], options: {} },
+    { path: ['workspaces', 'inputs'], summary: 'Show the text inputs of a workspace (secret inputs are bound secrets: shard ws secrets)', positionals: [REF], options: {} },
     {
         path: ['workspaces', 'exec'],
         summary: 'Run a command in a workspace; streams its output and exits with its exit code',
@@ -326,6 +340,109 @@ export const COMMANDS = [
             limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
         },
     },
+    {
+        path: ['templates', 'get'],
+        summary: 'Show a template: its versions, what open resolves to, and the settings of its open version',
+        positionals: [SLUG],
+        options: {
+            owner: { type: 'string', value: '<platform|organization>', description: 'Pick the platform template even when an organization template shadows its slug.' },
+            'include-archived': { type: 'boolean', description: 'Include archived versions.' },
+        },
+    },
+    {
+        path: ['templates', 'init'],
+        summary: 'Write a template.yaml that starts from a base template',
+        description: 'The file is the recipe v2 document (contracts §24.1): languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
+        positionals: [],
+        options: {
+            base: { type: 'string', value: '<slug[@version]>', description: 'Base template (required), e.g. ubuntu-24.04; without @version, the version open resolves to now.' },
+            out: { type: 'string', value: '<file>', description: 'Where to write it (default template.yaml).' },
+            force: { type: 'boolean', description: 'Overwrite an existing file.' },
+        },
+        examples: ['shard templates init --base ubuntu-24.04', 'shard templates init --base python-node-browser@7 --out acme/template.yaml'],
+    },
+    {
+        path: ['templates', 'build'],
+        summary: 'Build a template from template.yaml: upload its local files and folders, then build it',
+        description: 'Folders named by "from" are packed as a reproducible tar and uploaded with files unless the organization already has the same bytes. The version stays unpublished (test it with "shard templates test") unless --publish. Progress goes to stderr.',
+        positionals: [{ name: 'file', required: true }],
+        options: {
+            slug: { type: 'string', value: '<slug>', description: 'Organization template to build into (default: the name of the directory holding the file). Created by the first build.' },
+            'display-name': { type: 'string', value: '<name>', description: 'Template name when this build creates the template.' },
+            description: { type: 'string', value: '<text>', description: 'Version description.' },
+            publish: { type: 'boolean', description: 'Publish the version once it is registered (new workspaces of the slug then use it). Default: leave it unpublished.' },
+            acknowledge: { type: 'string', multiple: true, value: '<path>', description: 'Absolute path the credential scan may report without failing the build (repeatable, up to 200).' },
+            wait: { type: 'boolean', description: 'Wait until the build is registered (or fails).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 30m). The build continues server side.' },
+            timing: { type: 'boolean', description: 'Print where the time went on stderr: packing, uploads, the request, the wait, and the build’s queued and run time (with --json: a "timing" field).' },
+        },
+        examples: ['shard templates build template.yaml --wait', 'shard templates build acme/template.yaml --slug acme-dev --publish --wait --timing'],
+    },
+    {
+        path: ['templates', 'export'],
+        summary: 'Print (or save) the template.yaml a version was built from, ready to build again',
+        description: 'Versions saved from a workspace (or a draft) and platform versions have no recipe: change their settings through a draft publish instead.',
+        positionals: [{ name: 'slug@version', required: true }],
+        options: {
+            out: { type: 'string', value: '<file>', description: 'Write to this file instead of stdout.' },
+            force: { type: 'boolean', description: 'Overwrite an existing --out file.' },
+            owner: { type: 'string', value: '<platform|organization>', description: 'Pick the platform template even when an organization template shadows its slug.' },
+        },
+        examples: ['shard templates export acme-dev@3 --out template.yaml'],
+    },
+    {
+        path: ['templates', 'test'],
+        summary: 'Open a test instance of a version, published or not (a disposable session workspace)',
+        description: 'Runs the version’s start commands and services like a new workspace. It ends with "shard ws close <key>" or when idle. Owners, admins and API keys with a tool permission.',
+        positionals: [{ name: 'slug@version', required: true }],
+        options: {
+            'instance-key': { type: 'string', value: '<key>', description: 'Workspace key of the test instance (default sf:test:<slug>:<random>).' },
+            ...INPUTS,
+            ...CAPS,
+            wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m).' },
+            ...TIMING,
+        },
+        examples: ['shard templates test acme-dev@4 --input PROJECT_NAME=demo'],
+    },
+    {
+        path: ['templates', 'builds', 'list'],
+        summary: 'List the organization’s template builds, newest first',
+        positionals: [],
+        options: {
+            template: { type: 'string', value: '<slug>', description: 'Only builds of this template.' },
+            state: { type: 'string', value: '<state>', description: 'queued, building, testing, publishing, published, failed or canceled.' },
+            ...PAGE,
+            limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 50).' },
+        },
+    },
+    { path: ['templates', 'builds', 'get'], summary: 'Show one template build (state, registration, denied hosts, failure)', positionals: [BUILD_ID], options: {} },
+    {
+        path: ['templates', 'builds', 'log'],
+        summary: 'Print (or save) a build’s full log',
+        positionals: [BUILD_ID],
+        options: { out: { type: 'string', value: '<file>', description: 'Write to this file instead of stdout.' } },
+    },
+    { path: ['templates', 'builds', 'cancel'], summary: 'Cancel a template build (queued: at once; running: honoured until publishing starts)', positionals: [BUILD_ID], options: {} },
+    {
+        path: ['templates', 'languages'],
+        summary: 'List the languages (and versions) a base offers a template.yaml',
+        description: 'included: the base already has that version (nothing is installed). A version the base has another version of is left out. HOSTS is what an auto build network allows for it.',
+        positionals: [],
+        options: { base: { type: 'string', value: '<slug@version>', description: 'The base (required), e.g. ubuntu-24.04@1.' } },
+        examples: ['shard templates languages --base ubuntu-24.04@1'],
+    },
+    {
+        path: ['templates', 'packages', 'search'],
+        summary: 'Search apt, pip or npm package names for a template.yaml',
+        description: 'apt searches the package index of a base (--base, required); pip returns names only; npm searches the registry.',
+        positionals: [{ name: 'ecosystem', required: true }, { name: 'query', required: true }],
+        options: {
+            base: { type: 'string', value: '<slug@version>', description: 'The base whose apt index to search (apt only).' },
+            limit: { type: 'string', value: '<n>', description: 'Results, 1-50 (default 20).' },
+        },
+        examples: ['shard templates packages search apt jq --base ubuntu-24.04@1', 'shard templates packages search npm typescript'],
+    },
     {
         path: ['templates', 'files'],
         summary: 'List one directory of a template version’s file tree (or show one entry with --stat)',
@@ -420,7 +537,7 @@ const GROUPS = {
     files: 'Read, write and list files in a workspace',
     operations: 'Inspect and wait for lifecycle operations',
     secrets: 'Manage secrets (values are write-only) and bind them to workspaces',
-    templates: 'Browse templates (file tree, diff) and develop organization templates in a draft',
+    templates: 'Build templates from template.yaml, test and export versions, browse templates (file tree, diff) and develop them in a draft',
 };
 const ALIASES = { ws: 'workspaces', workspace: 'workspaces', ops: 'operations', operation: 'operations', file: 'files', secret: 'secrets', template: 'templates' };
 /** Canonical command words: aliases resolved, `workspaces files|operations` folded to the top-level group. */

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.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. */
@@ -78,6 +78,13 @@ export function describeError(err) {
     }
     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)
@@ -100,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;
@@ -52,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

@@ -78,8 +78,32 @@ function originText(o) {
             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],
@@ -92,6 +116,7 @@ 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
             ? [
@@ -104,7 +129,7 @@ export function workspaceDetail(w) {
             : []),
         ['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) {
@@ -312,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/template-yaml.d.ts

@@ -0,0 +1,7 @@
+/** A recipe as template.yaml, with `header` as the comment above the document. */
+export declare function recipeYaml(recipe: unknown, header?: string): string;
+/**
+ * The starter template.yaml on `base` (`<slug>@<version>`): every section present, with commented examples and one
+ * placeholder step (the API refuses a recipe that builds nothing). It parses to a valid recipe v2 and builds as it is.
+ */
+export declare function initTemplateYaml(base: string): string;

package/dist/template-yaml.js

@@ -0,0 +1,62 @@
+/**
+ * template.yaml text (contracts §24.1: the recipe v2 document in YAML; only clients parse YAML): the starter file of
+ * `shard templates init` and the export of a version (`shard templates export`), written like the dashboard's
+ * Template file section (keys in the recipe's order, long scripts as block literals, no line folding).
+ */
+import { Document } from 'yaml';
+/** A recipe as template.yaml, with `header` as the comment above the document. */
+export function recipeYaml(recipe, header) {
+    const doc = new Document(recipe);
+    if (header)
+        doc.commentBefore = ` ${header}`;
+    return doc.toString({ lineWidth: 0, minContentWidth: 0, blockQuote: 'literal' });
+}
+/**
+ * The starter template.yaml on `base` (`<slug>@<version>`): every section present, with commented examples and one
+ * placeholder step (the API refuses a recipe that builds nothing). It parses to a valid recipe v2 and builds as it is.
+ */
+export function initTemplateYaml(base) {
+    return `# A Shardflux template (recipe v2). Build it with: shard templates build template.yaml --wait
+# build: what goes into the template (languages, packages, files, steps). settings: what a workspace gets when it opens.
+schema: shardflux.template-recipe.v2
+base: ${base}
+build:
+  # Languages from the platform's table: python, node, go, rust, java (version omitted: the base's default).
+  languages: []
+  #   - id: python
+  #   - id: node
+  #     version: "22"
+  packages:
+    apt: []              # e.g. [jq, ffmpeg]
+    pip:
+      packages: []       # installed into /opt/venv, e.g. [pandas==2.3.2]
+      requirements: []   # absolute paths of requirements files copied in by files, e.g. [/home/user/app/requirements.txt]
+    npm: []              # installed globally, e.g. [typescript@5.9.2]
+  # Local files and folders ("from", relative to this file) are uploaded by shard templates build; a folder is copied
+  # into "to" (kind tar), a file to the path "to" (kind file).
+  files: []
+  #   - from: ./app
+  #     to: /home/user/app
+  #     owner: user
+  #   - from: ./config/settings.toml
+  #     to: /home/user/.config/app/settings.toml
+  #     owner: user
+  #     mode: "0600"
+  # Build steps run after languages, packages and files, in this order (as root unless user is set). A recipe must
+  # build something (a language, a package, a file or a step): replace this one with your own.
+  steps:
+    - name: hello
+      run: echo "built from template.yaml" > /etc/motd
+  #   - name: install-deps
+  #     run: npm ci
+  #     user: user
+  #     cwd: /home/user/app
+  network:
+    build: auto          # auto: the hosts the recipe needs (plus extra_hosts); none; or allowlist with allow_hosts
+settings:
+  env: {}                # e.g. {APP_ENV: development}
+  inputs: {}             # open-time inputs, e.g. {PROJECT_NAME: {kind: text, required: true}, OPENAI_API_KEY: {kind: secret}}
+  start: []              # start commands, e.g. [{name: seed, when: create, run: "python seed.py", user: user}]
+  services: {}           # e.g. {web: {run: "npm start", user: user, cwd: /home/user/app, ready: {port: 3000}}}
+`;
+}

package/dist/timing.d.ts

@@ -1,4 +1,4 @@
-import type { LifecycleTiming, ProgressListener } from '@shardflux/sdk';
+import type { BuildFromFileEvent, LifecycleTiming, ProgressListener, TemplateBuild } from '@shardflux/sdk';
 export declare class TimingRecorder {
     /** The timing of the last traced call that ended (token fetches are not lifecycle calls and are skipped). */
     last: LifecycleTiming | null;
@@ -15,3 +15,31 @@ export declare class TimingRecorder {
 export declare function timingText(t: LifecycleTiming): string;
 /** The `--json` form: the SDK's LifecycleTiming with the CLI's snake_case keys (the rest of its JSON is the API's). */
 export declare function timingJson(t: LifecycleTiming | null): Record<string, unknown> | null;
+/**
+ * Where a template build's time went, from the SDK's build-from-file progress events: reading and packing the local
+ * files, the uploads, the build request, and the wait; plus the build's own queued and run time from its view
+ * (created_at, started_at, completed_at).
+ */
+export declare class BuildTimer {
+    #private;
+    packMs: number;
+    uploadMs: number;
+    files: number;
+    sent: number;
+    bytesSent: number;
+    buildId: string | null;
+    record(e: BuildFromFileEvent): void;
+    finish(build: TemplateBuild | null): void;
+    get totalMs(): number;
+    /** From the last upload (or the start, reading the file) to the created build: the organization lookup and the POST. */
+    get requestMs(): number | null;
+    get waitMs(): number | null;
+    get server(): {
+        queuedMs: number | null;
+        runMs: number | null;
+    };
+}
+/** One stderr line per build-from-file progress event. */
+export declare function progressLine(e: BuildFromFileEvent): string;
+export declare function buildTimingText(t: BuildTimer): string;
+export declare function buildTimingJson(t: BuildTimer): Record<string, unknown>;

package/dist/timing.js

@@ -63,3 +63,99 @@ export function timingJson(t) {
         outside_server_ms: t.outsideServerMs,
     };
 }
+// ---- `shard templates build --timing` (0.4.0) ---------------------------------------------------------------------------
+/**
+ * Where a template build's time went, from the SDK's build-from-file progress events: reading and packing the local
+ * files, the uploads, the build request, and the wait; plus the build's own queued and run time from its view
+ * (created_at, started_at, completed_at).
+ */
+export class BuildTimer {
+    #t0 = performance.now();
+    packMs = 0;
+    uploadMs = 0;
+    files = 0;
+    sent = 0;
+    bytesSent = 0;
+    buildId = null;
+    #requestDoneAt = null;
+    #prepareDoneAt = null;
+    #endAt = null;
+    #build = null;
+    record(e) {
+        const now = performance.now();
+        if (e.type === 'pack') {
+            this.packMs += e.ms;
+            this.files += 1;
+            this.#prepareDoneAt = now;
+        }
+        else if (e.type === 'upload') {
+            this.uploadMs += e.ms;
+            if (e.uploaded) {
+                this.sent += 1;
+                this.bytesSent += e.size;
+            }
+            this.#prepareDoneAt = now;
+        }
+        else if (this.#requestDoneAt === null) {
+            this.#requestDoneAt = now;
+            this.buildId = e.build.id;
+            this.#build = e.build;
+        }
+        else
+            this.#build = e.build;
+    }
+    finish(build) {
+        this.#endAt = performance.now();
+        if (build)
+            this.#build = build;
+    }
+    get totalMs() {
+        return (this.#endAt ?? performance.now()) - this.#t0;
+    }
+    /** From the last upload (or the start, reading the file) to the created build: the organization lookup and the POST. */
+    get requestMs() {
+        return this.#requestDoneAt === null ? null : this.#requestDoneAt - (this.#prepareDoneAt ?? this.#t0);
+    }
+    get waitMs() {
+        return this.#requestDoneAt === null || this.#endAt === null ? null : this.#endAt - this.#requestDoneAt;
+    }
+    get server() {
+        const b = this.#build;
+        const ms = (a, z) => (a && z ? Math.max(0, Date.parse(z) - Date.parse(a)) : null);
+        return { queuedMs: ms(b?.created_at, b?.started_at), runMs: ms(b?.started_at, b?.completed_at) };
+    }
+}
+const fmtMs = (ms) => (ms === null ? '-' : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`);
+const short = (sha) => sha.slice(0, 12);
+const bytes = (n) => (n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(2)} GiB`);
+/** One stderr line per build-from-file progress event. */
+export function progressLine(e) {
+    if (e.type === 'pack')
+        return e.kind === 'tar' && e.entries !== null ? `packed ${e.from} (${e.entries} entries, ${bytes(e.size)}, sha256 ${short(e.sha256)}) in ${fmtMs(e.ms)}\n` : `read ${e.from} (${bytes(e.size)}, sha256 ${short(e.sha256)}) in ${fmtMs(e.ms)}\n`;
+    if (e.type === 'upload')
+        return e.uploaded ? `uploaded sha256:${short(e.sha256)} (${bytes(e.size)}) in ${fmtMs(e.ms)}\n` : `sha256:${short(e.sha256)} is already uploaded\n`;
+    const b = e.build;
+    return `build ${b.id}: ${b.state}${b.state === 'published' ? `, registration ${b.registration.state}` : ''}${b.failure ? ` (${b.failure.code})` : ''}\n`;
+}
+export function buildTimingText(t) {
+    const s = t.server;
+    const uploads = t.files ? `, upload ${fmtMs(t.uploadMs)} (${t.sent} of ${t.files} sent, ${bytes(t.bytesSent)})` : '';
+    const lines = [`timing: templates build ${fmtMs(t.totalMs)}${t.buildId ? ` (build ${t.buildId})` : ''}`, `  pack ${fmtMs(t.packMs)}${uploads}, request ${fmtMs(t.requestMs)}${t.waitMs !== null && t.waitMs > 1 ? `, wait ${fmtMs(t.waitMs)}` : ''}`];
+    if (s.queuedMs !== null || s.runMs !== null)
+        lines.push(`  server: queued ${fmtMs(s.queuedMs)}, run ${fmtMs(s.runMs)}`);
+    return `${lines.join('\n')}\n`;
+}
+export function buildTimingJson(t) {
+    const r = (v) => (v === null ? null : Math.round(v * 10) / 10);
+    return {
+        action: 'template_build',
+        build_id: t.buildId,
+        total_ms: r(t.totalMs),
+        pack_ms: r(t.packMs),
+        upload_ms: r(t.uploadMs),
+        request_ms: r(t.requestMs),
+        wait_ms: r(t.waitMs),
+        uploads: { files: t.files, sent: t.sent, bytes_sent: t.bytesSent },
+        server: { queued_ms: t.server.queuedMs, run_ms: t.server.runMs },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.3.1",
+  "version": "0.4.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",
@@ -39,7 +39,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@shardflux/sdk": "^0.6.2"
+    "yaml": "2.9.1",
+    "@shardflux/sdk": "^0.7.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",