@shardflux/cli 0.3.0 → 0.4.0

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.0",
+  "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.1"
+    "yaml": "2.9.1",
+    "@shardflux/sdk": "^0.7.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",