@dreamlake/dreamlake-cli 0.1.0 → 0.2.0

package/README.md

@@ -4,36 +4,22 @@
 manages episodes, bindrs, and datasets against a DreamLake server + BSS
 (big-streaming-server).
 
-It is a TypeScript port of the CLI shipped in `dreamlake-py` (`dreamlake.cli`),
-built on Commander + native `fetch`, pure ESM, with the token saved to a flat
-YAML file instead of the system keyring.
+It is a TypeScript port of the CLI shipped in
+[`dreamlake-py`](../dreamlake-workspace/dreamlake-py) (`dreamlake.cli`), built
+on the [`lakeshore`](../lakeshore) conventions (Commander + native `fetch`,
+pure ESM, token saved to a flat YAML file instead of the system keyring).
 
-> The `dreamlake` binary shares its name with the Python `dreamlake` entry
-> point — this CLI is the TypeScript replacement. When both are on a machine,
-> `PATH` order decides which one runs.
+> The compiled `dreamlake` binary shares its name with the Python `dreamlake`
+> entry point — this CLI is the TypeScript replacement. When both are on a
+> machine, `PATH` order decides which one runs.
 
-## Install
-
-Requires Node.js >= 20.
-
-```bash
-npm install -g @dreamlake/dreamlake-cli    # or: pnpm add -g @dreamlake/dreamlake-cli
-
-dreamlake --version
-dreamlake --help
-```
-
-Or run it without installing:
-
-```bash
-npx @dreamlake/dreamlake-cli --help
-```
-
-Then authenticate and go:
+## Install / run
 
 ```bash
-dreamlake login --env prod
-dreamlake list project
+pnpm install
+pnpm cli --help          # dev — runs the TS source through tsx
+pnpm build               # emit dist/
+node bin/dreamlake.js …  # prod — runs compiled dist/ (falls back to tsx in dev)
 ```
 
 ## Auth & environments
@@ -180,12 +166,6 @@ Episode-tracking stack.
 ## Development
 
 ```bash
-pnpm install
-pnpm cli --help          # dev — runs the TS source through tsx
-pnpm test                # tsc --noEmit + node --test (target/glob/kinds/credentials)
-pnpm build               # tsc → dist/
-node bin/dreamlake.js …  # runs compiled dist/ (falls back to tsx when dist/ is absent)
+pnpm test     # tsc --noEmit + node --test (target/glob/kinds/credentials)
+pnpm build    # tsc → dist/
 ```
-
-Publishing: `npm version patch|minor` → `npm publish` (tests and build run
-automatically via `prepublishOnly`/`prepack`) → `git push --follow-tags`.

package/bin/dreamlake.js

@@ -18,15 +18,7 @@ async function run() {
   }
   if (existsSync(srcEntry)) {
     // Register tsx as a module loader, then import the TS source.
-    let tsx;
-    try {
-      tsx = await import("tsx/esm/api");
-    } catch {
-      console.error(
-        "dreamlake: dist/ is missing and tsx is not installed — run `pnpm install && pnpm build` first",
-      );
-      process.exit(2);
-    }
+    const tsx = await import("tsx/esm/api");
     tsx.register();
     await import(pathToFileURL(srcEntry).href);
     return;

package/dist/cli/index.js

@@ -1,7 +1,6 @@
 // `dreamlake` CLI entry. Wires Commander to subcommand modules. Mirrors
 // the command surface of dreamlake-py's `dreamlake.cli` (the data-warehouse
 // CLI), implemented in lakeshore's TypeScript conventions.
-import { createRequire } from "node:module";
 import { Command } from "commander";
 import { authFilePath, BUILTIN_ENVS } from "./auth/credentials.js";
 import { runLogin, runLogout, runProfile, runEnvList, runEnvUse, runEnvRemove, } from "./auth/commands.js";
@@ -14,14 +13,12 @@ import { registerDeleteCommand } from "./delete/index.js";
 import { registerOrgCommand } from "./org/index.js";
 import { registerTeamCommand } from "./team/index.js";
 import { registerPipelineCommand } from "./pipeline/index.js";
-// Resolves to the package root from both src/cli/ (dev) and dist/cli/ (published).
-const { version } = createRequire(import.meta.url)("../../package.json");
+import { registerWorkflowCommand } from "./workflow/index.js";
 async function main(argv) {
     const program = new Command();
     program
         .name("dreamlake")
         .description("DreamLake CLI — upload/download assets and manage episodes, bindrs, and datasets.")
-        .version(version)
         .showHelpAfterError();
     // ─── auth ────────────────────────────────────────────────────────
     //
@@ -89,6 +86,7 @@ async function main(argv) {
     registerOrgCommand(program);
     registerTeamCommand(program);
     registerPipelineCommand(program);
+    registerWorkflowCommand(program);
     await program.parseAsync(argv);
 }
 main(process.argv).catch((err) => {

package/dist/cli/pipeline/index.js

@@ -5,7 +5,7 @@
 //   pipeline version list / version show
 //   pipeline node list / node show / node state
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { resolve, basename } from "node:path";
 import { HttpError, requestJson } from "../client.js";
 import { resolveRemote, resolveToken, resolveNamespace } from "../config.js";
 import { emitJson, fail, ok, renderTable, splitCsv } from "../helpers.js";
@@ -163,18 +163,20 @@ export async function runPipelineUpdate(name, opts) {
     if (!c)
         return 1;
     const body = {};
+    if (opts.rename !== undefined)
+        body.name = opts.rename;
     if (opts.description !== undefined)
         body.description = opts.description;
     if (opts.tags !== undefined)
         body.tags = splitCsv(opts.tags);
-    const sourceCode = opts.source ?? (opts.file ? readFile(opts.file) : undefined);
+    const sourceCode = opts.source ? unescapeSource(opts.source) : (opts.file ? readFile(opts.file) : undefined);
     if (sourceCode) {
         body.sourceCode = sourceCode;
         if (opts.message)
             body.versionMessage = opts.message;
     }
     if (Object.keys(body).length === 0) {
-        fail("nothing to update — use --file, --description, or --tags");
+        fail("nothing to update — use --file, --source, --rename, --description, or --tags");
         return 1;
     }
     try {
@@ -194,6 +196,10 @@ export async function runPipelineUpdate(name, opts) {
             fail(`pipeline '${name}' not found`);
             return 1;
         }
+        if (err instanceof HttpError && err.status === 409) {
+            fail(`pipeline '${opts.rename}' already exists in this namespace`);
+            return 1;
+        }
         fail(err.message);
         return 1;
     }
@@ -348,7 +354,7 @@ export async function runNodeState(name, hash, nodeId, opts) {
             body.artifacts = JSON.parse(opts.artifacts);
         }
         catch {
-            fail("--artifacts must be valid JSON, e.g. '{\"index_html\":\"https://...\"}'");
+            fail("--artifacts must be valid JSON, e.g. '{\"iframe_url\":\"https://...\",\"segments_data\":[]}'");
             return 1;
         }
     }
@@ -369,6 +375,100 @@ export async function runNodeState(name, hash, nodeId, opts) {
         return 1;
     }
 }
+// ─── pipeline workspace upload ────────────────────────────────────────────────
+export async function runWorkspaceUpload(opts) {
+    const token = resolveToken();
+    if (!token) {
+        fail("not authenticated — run 'dreamlake login' first");
+        return 1;
+    }
+    const remote = resolveRemote();
+    const form = new FormData();
+    form.append("workspace_id", opts.workspaceId);
+    try {
+        const distBuf = readFileSync(resolve(opts.dist));
+        form.append("dist", new Blob([distBuf], { type: "application/gzip" }), basename(opts.dist));
+    }
+    catch {
+        fail(`cannot read dist file: ${opts.dist}`);
+        return 1;
+    }
+    if (opts.source) {
+        try {
+            const sourceBuf = readFileSync(resolve(opts.source));
+            form.append("source", new Blob([sourceBuf], { type: "application/gzip" }), basename(opts.source));
+        }
+        catch {
+            fail(`cannot read source file: ${opts.source}`);
+            return 1;
+        }
+    }
+    try {
+        const res = await fetch(new URL("/pipelines/workspace/upload", remote).toString(), {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}` },
+            body: form,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            fail(`Upload failed (${res.status}): ${body}`);
+            return 1;
+        }
+        if (opts.json) {
+            emitJson(await res.json());
+            return 0;
+        }
+        ok(`Workspace ${opts.workspaceId} updated`);
+        return 0;
+    }
+    catch (err) {
+        fail(err.message);
+        return 1;
+    }
+}
+// ─── pipeline workspace host ──────────────────────────────────────────────────
+export async function runWorkspaceHost(opts) {
+    const token = resolveToken();
+    if (!token) {
+        fail("not authenticated — run 'dreamlake login' first");
+        return 1;
+    }
+    const remote = resolveRemote();
+    let distBuf;
+    try {
+        distBuf = readFileSync(resolve(opts.dist));
+    }
+    catch {
+        fail(`cannot read dist file: ${opts.dist}`);
+        return 1;
+    }
+    try {
+        const res = await fetch(new URL("/pipelines/workspace/host", remote).toString(), {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/gzip" },
+            body: distBuf,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            fail(`Host failed (${res.status}): ${body}`);
+            return 1;
+        }
+        const data = await res.json();
+        if (opts.json) {
+            emitJson(data);
+            return 0;
+        }
+        ok("Workspace hosted");
+        process.stdout.write(`  workspace_id:     ${data.workspace_id}\n`);
+        process.stdout.write(`  page_url:         ${data.page_url}\n`);
+        process.stdout.write(`  dist_files_count: ${data.dist_files_count}\n`);
+        return 0;
+    }
+    catch (err) {
+        fail(err.message);
+        return 1;
+    }
+}
 // ─── registration ─────────────────────────────────────────────────────────────
 export function registerPipelineCommand(program) {
     const pipeline = program
@@ -410,6 +510,7 @@ export function registerPipelineCommand(program) {
         .description("update metadata or upload a new version")
         .argument("<name>", "pipeline name")
         .option("--namespace <slug>", "namespace slug (default: active login)")
+        .option("--rename <new-name>", "rename the pipeline (must be unique within namespace)")
         .option("--source <code>", "new Python source code string — triggers parser and creates a new version")
         .option("--file <path>", "new Python source file (alternative to --source)")
         .option("--description <text>", "new description")
@@ -465,6 +566,24 @@ export function registerPipelineCommand(program) {
         .option("--namespace <slug>", "namespace slug (default: active login)")
         .option("--json", "emit JSON (always, this command outputs JSON)")
         .action(async (name, hash, nodeId, opts) => process.exit(await runNodeShow(name, hash, nodeId, opts)));
+    // ── pipeline workspace ──
+    const workspace = pipeline
+        .command("workspace")
+        .description("manage agent workspaces");
+    workspace
+        .command("upload")
+        .description("upload dist.tar.gz (and optionally source.tar.gz) to an agent workspace")
+        .requiredOption("--workspace-id <id>", "agent workspace ID")
+        .requiredOption("--dist <path>", "path to dist.tar.gz (built React output)")
+        .option("--source <path>", "path to source.tar.gz (optional)")
+        .option("--json", "emit JSON response")
+        .action(async (opts) => process.exit(await runWorkspaceUpload(opts)));
+    workspace
+        .command("host")
+        .description("host a dist.tar.gz on the agent server and get back a page_url")
+        .requiredOption("--dist <path>", "path to dist.tar.gz (built React output)")
+        .option("--json", "emit JSON response")
+        .action(async (opts) => process.exit(await runWorkspaceHost(opts)));
     node
         .command("state")
         .description("write back node execution state (for execution engines)")
@@ -473,7 +592,13 @@ export function registerPipelineCommand(program) {
         .argument("<nodeId>", "node ID")
         .requiredOption("--status <status>", "idle | queued | running | waiting | done | error | blocked")
         .option("--error <message>", "error message (use with --status error)")
-        .option("--artifacts <json>", 'JSON object of artifact URLs, e.g. \'{"index_html":"https://..."}\'')
+        .option("--artifacts <json>", [
+        "JSON object written to node artifacts. Supported keys:",
+        "  iframe_url    string  — URL of the human review page (rendered in iframe)",
+        "  source_url    string  — original data source URL",
+        "  segments_data any     — segment annotation data (any JSON value)",
+        "Example: '{\"iframe_url\":\"https://...\",\"segments_data\":[{\"start\":0,\"end\":10}]}'",
+    ].join("\n"))
         .option("--started-at <iso>", "ISO 8601 start time")
         .option("--ended-at <iso>", "ISO 8601 end time")
         .option("--namespace <slug>", "namespace slug (default: active login)")

package/dist/cli/workflow/index.js

@@ -0,0 +1,627 @@
+// `dreamlake workflow ...` — workflow management + run-trace push.
+//
+// Covers the workflow API endpoints:
+//   workflow list / create / show / update / delete
+//   workflow push-run / watch-run   (agent-side run-trace snapshots)
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { HttpError, requestJson } from "../client.js";
+import { resolveRemote, resolveToken, resolveNamespace } from "../config.js";
+import { emitJson, fail, ok, renderTable, splitCsv, warn } from "../helpers.js";
+import { confirm } from "../prompt.js";
+// ─── shared context resolution ────────────────────────────────────────────────
+async function ctx(nsFlag) {
+    const token = resolveToken();
+    if (!token) {
+        fail("not authenticated — run 'dreamlake login' first");
+        return null;
+    }
+    const remote = resolveRemote();
+    const ns = await resolveNamespace(nsFlag, { token, remote });
+    if (!ns) {
+        fail("could not resolve namespace — run 'dreamlake login' or pass --namespace");
+        return null;
+    }
+    return { token, remote, ns };
+}
+function readFile(filePath) {
+    try {
+        return readFileSync(resolve(filePath), "utf8");
+    }
+    catch {
+        throw new Error(`cannot read file: ${filePath}`);
+    }
+}
+// ─── run-file reduction (local wf_*.json → server trace contract) ─────────────
+//
+// The Claude Code Workflow tool writes wf_<runId>.json snapshots under the
+// session's workflows/ dir. `workflowProgress` interleaves `workflow_phase`
+// and `workflow_agent` entries; run totals live at the top level. The file
+// format drifts across CLI versions, so every field is optional — reduce
+// what's there, drop the rest.
+const AGENT_FIELDS = [
+    "index",
+    "label",
+    "phaseIndex",
+    "phaseTitle",
+    "agentId",
+    "model",
+    "state",
+    "queuedAt",
+    "startedAt",
+    "lastProgressAt",
+    "durationMs",
+    "attempt",
+    "tokens",
+    "toolCalls",
+    "lastToolName",
+    "lastToolSummary",
+    "promptPreview",
+    "resultPreview",
+];
+// ─── body-budget guardrails (bounded push size) ──────────────────────────────
+//
+// Every push-run / watch-run PUT must stay under the server's 5MB bodyLimit.
+// An oversized body 413s; for the *terminal* snapshot that means the server-side
+// run is never flipped out of 'running', so the web detail page polls it every
+// few seconds forever. We hold the serialized body under a 4MB budget (headroom
+// below the 5MB limit) and degrade deterministically — least-important data
+// first — rather than ever emit a body we know will be rejected:
+//
+//   1. always: cap each agent's free-text previews to AGENT_PREVIEW_CAP chars.
+//   2. always: keep only the newest log lines that fit LOGS_BUDGET_BYTES.
+//   3. if the whole body is still over budget: drop logs, then replace `result`
+//      with a size marker. status / trace skeleton (phases+agents) / totals
+//      always survive — they are what the detail page needs to render.
+/** Serialized-body ceiling. Below the server's 5MB bodyLimit, with headroom. */
+const BODY_BUDGET_BYTES = 4 * 1024 * 1024;
+/** Per-field cap for free-text agent previews. */
+const AGENT_PREVIEW_CAP = 2000;
+/** Combined byte budget for retained log lines (the newest are kept). */
+const LOGS_BUDGET_BYTES = 512 * 1024;
+/** Agent fields that are free-text and get length-capped. */
+const CAPPED_AGENT_FIELDS = new Set([
+    "promptPreview",
+    "resultPreview",
+    "lastToolSummary",
+]);
+function byteLength(v) {
+    return Buffer.byteLength(JSON.stringify(v), "utf8");
+}
+/** Cap a free-text field to `max` chars, appending an ellipsis when trimmed. */
+function capText(v, max) {
+    return typeof v === "string" && v.length > max ? v.slice(0, max) + "…" : v;
+}
+/**
+ * Keep the LAST log lines that fit within `budget` bytes; when any are dropped
+ * prepend a marker so the reader knows the head was elided. Always keeps at
+ * least the most recent line (even if it alone exceeds the budget) so the tail
+ * of the run is never lost. Returns the input untouched when nothing is dropped.
+ */
+function capLogs(logs, budget) {
+    if (logs.length === 0)
+        return logs;
+    const kept = [];
+    let used = 0;
+    for (let i = logs.length - 1; i >= 0; i--) {
+        const line = logs[i];
+        const cost = Buffer.byteLength(line, "utf8") + 1; // + newline separator
+        if (kept.length > 0 && used + cost > budget)
+            break;
+        kept.push(line);
+        used += cost;
+    }
+    if (kept.length === logs.length)
+        return logs; // nothing dropped — keep as-is
+    kept.reverse();
+    kept.unshift(`[truncated ${logs.length - kept.length} earlier log lines]`);
+    return kept;
+}
+/**
+ * Final guardrail: if the serialized body still exceeds BODY_BUDGET_BYTES after
+ * the per-field/log caps (e.g. a huge `result` or thousands of agents), degrade
+ * further — drop logs entirely, then replace `result` with a size marker. The
+ * status, trace skeleton (phases + agents) and run totals are never touched.
+ */
+function enforceBodyBudget(body, trace) {
+    if (byteLength(body) <= BODY_BUDGET_BYTES)
+        return;
+    // 1. Drop logs — the phase/agent skeleton is worth far more than log tail.
+    if (trace.logs.length > 0) {
+        trace.logs = [];
+        if (byteLength(body) <= BODY_BUDGET_BYTES)
+            return;
+    }
+    // 2. Replace the result payload with a marker of its original size.
+    if (body.result !== undefined) {
+        body.result = { truncated: true, originalBytes: byteLength(body.result) };
+    }
+    // If still over budget here, the agent/phase skeleton itself is oversized;
+    // that is the documented floor — those fields must survive intact even if
+    // the push risks a 413.
+}
+function asRecord(v) {
+    return v && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : null;
+}
+/** Epoch-millis (number) or ISO string → ISO string; anything else → undefined. */
+function isoTime(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return new Date(v).toISOString();
+    if (typeof v === "string" && v)
+        return v;
+    return undefined;
+}
+export function reduceRunFile(raw) {
+    const file = asRecord(raw) ?? {};
+    const progress = Array.isArray(file.workflowProgress) ? file.workflowProgress : [];
+    const phases = [];
+    const agents = [];
+    for (const entry of progress) {
+        const e = asRecord(entry);
+        if (!e)
+            continue;
+        if (e.type === "workflow_phase") {
+            const phase = {};
+            if (e.index !== undefined)
+                phase.index = e.index;
+            if (e.title !== undefined)
+                phase.title = e.title;
+            phases.push(phase);
+        }
+        else if (e.type === "workflow_agent") {
+            const agent = {};
+            for (const f of AGENT_FIELDS) {
+                if (e[f] === undefined)
+                    continue;
+                // Free-text previews are length-capped; everything else copied verbatim.
+                agent[f] = CAPPED_AGENT_FIELDS.has(f)
+                    ? capText(e[f], AGENT_PREVIEW_CAP)
+                    : e[f];
+            }
+            agents.push(agent);
+        }
+    }
+    // Before the first phase starts running, fall back to the declared meta
+    // phases so the graph still renders the skeleton.
+    if (phases.length === 0 && Array.isArray(file.phases)) {
+        file.phases.forEach((p, i) => {
+            const rec = asRecord(p);
+            if (rec?.title !== undefined)
+                phases.push({ index: i + 1, title: rec.title });
+        });
+    }
+    const trace = {
+        phases,
+        agents,
+        logs: capLogs(Array.isArray(file.logs)
+            ? file.logs.filter((l) => typeof l === "string")
+            : [], LOGS_BUDGET_BYTES),
+    };
+    if (typeof file.totalToolCalls === "number")
+        trace.totalToolCalls = file.totalToolCalls;
+    if (typeof file.defaultModel === "string")
+        trace.defaultModel = file.defaultModel;
+    const body = {
+        status: typeof file.status === "string" && file.status ? file.status : "running",
+        trace,
+    };
+    const startTime = isoTime(file.startTime);
+    if (startTime)
+        body.startTime = startTime;
+    if (typeof file.durationMs === "number")
+        body.durationMs = file.durationMs;
+    if (typeof file.agentCount === "number")
+        body.agentCount = file.agentCount;
+    if (typeof file.totalTokens === "number")
+        body.totalTokens = file.totalTokens;
+    if (typeof file.error === "string" && file.error)
+        body.error = file.error;
+    if (file.result !== undefined)
+        body.result = file.result;
+    // Guarantee the body fits under the server bodyLimit before it is ever sent.
+    enforceBodyBudget(body, trace);
+    return {
+        runId: typeof file.runId === "string" && file.runId ? file.runId : undefined,
+        body,
+    };
+}
+function readRunFile(filePath) {
+    const text = readFileSync(resolve(filePath), "utf8");
+    return reduceRunFile(JSON.parse(text));
+}
+// ─── workflow list ────────────────────────────────────────────────────────────
+export async function runWorkflowList(opts) {
+    const c = await ctx(opts.namespace);
+    if (!c)
+        return 1;
+    try {
+        const res = await requestJson(c.remote, `/namespaces/${c.ns}/workflows`, { token: c.token });
+        if (opts.json) {
+            emitJson(res.workflows);
+            return 0;
+        }
+        if (res.workflows.length === 0) {
+            process.stdout.write("No workflows found.\n");
+            return 0;
+        }
+        const rows = res.workflows.map((w) => ({
+            name: w.name,
+            hash: w.currentVersionHash ?? "—",
+            runs: String(w.runCount ?? 0),
+            lastRun: w.latestRun?.status ?? "—",
+            updatedAt: w.updatedAt.slice(0, 10),
+        }));
+        process.stdout.write(renderTable(rows, ["name", "hash", "runs", "lastRun", "updatedAt"]));
+        process.stdout.write(`\n  ${res.workflows.length} workflow(s)\n`);
+        return 0;
+    }
+    catch (err) {
+        fail(err.message);
+        return 1;
+    }
+}
+// ─── workflow create ──────────────────────────────────────────────────────────
+export async function runWorkflowCreate(name, opts) {
+    const c = await ctx(opts.namespace);
+    if (!c)
+        return 1;
+    try {
+        const body = { name };
+        if (opts.description)
+            body.description = opts.description;
+        if (opts.tags)
+            body.tags = splitCsv(opts.tags);
+        if (opts.file) {
+            body.script = readFile(opts.file);
+            if (opts.message)
+                body.versionMessage = opts.message;
+        }
+        const workflow = await requestJson(c.remote, `/namespaces/${c.ns}/workflows`, { method: "POST", token: c.token, json: body });
+        if (opts.json) {
+            emitJson(workflow);
+            return 0;
+        }
+        ok(`Created workflow: ${workflow.name}`);
+        if (workflow.currentVersionHash) {
+            process.stdout.write(`  version: ${workflow.currentVersionHash}\n`);
+            process.stdout.write(`  phases:  ${workflow.meta?.phases?.length ?? 0}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof HttpError && err.status === 409) {
+            fail(`workflow '${name}' already exists in namespace '${c.ns}'`);
+            return 1;
+        }
+        fail(err.message);
+        return 1;
+    }
+}
+// ─── workflow show ────────────────────────────────────────────────────────────
+export async function runWorkflowShow(name, opts) {
+    const c = await ctx(opts.namespace);
+    if (!c)
+        return 1;
+    try {
+        const workflow = await requestJson(c.remote, `/namespaces/${c.ns}/workflows/${name}`, { token: c.token });
+        if (opts.json) {
+            emitJson(workflow);
+            return 0;
+        }
+        process.stdout.write(`Workflow: ${workflow.name}\n`);
+        process.stdout.write(`  version:     ${workflow.currentVersionHash ?? "—"}\n`);
+        process.stdout.write(`  phases:      ${workflow.meta?.phases?.length ?? "—"}\n`);
+        if (workflow.description)
+            process.stdout.write(`  description: ${workflow.description}\n`);
+        if (workflow.tags.length)
+            process.stdout.write(`  tags:        ${workflow.tags.join(", ")}\n`);
+        process.stdout.write(`  created:     ${workflow.createdAt.slice(0, 10)}\n`);
+        process.stdout.write(`  updated:     ${workflow.updatedAt.slice(0, 10)}\n`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof HttpError && err.status === 404) {
+            fail(`workflow '${name}' not found`);
+            return 1;
+        }
+        fail(err.message);
+        return 1;
+    }
+}
+// ─── workflow update ──────────────────────────────────────────────────────────
+export async function runWorkflowUpdate(name, opts) {
+    const c = await ctx(opts.namespace);
+    if (!c)
+        return 1;
+    const body = {};
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.tags !== undefined)
+        body.tags = splitCsv(opts.tags);
+    if (opts.file) {
+        try {
+            body.script = readFile(opts.file);
+        }
+        catch (err) {
+            fail(err.message);
+            return 1;
+        }
+        if (opts.message)
+            body.versionMessage = opts.message;
+    }
+    if (Object.keys(body).length === 0) {
+        fail("nothing to update — use --file, --description, or --tags");
+        return 1;
+    }
+    try {
+        const workflow = await requestJson(c.remote, `/namespaces/${c.ns}/workflows/${name}`, { method: "PATCH", token: c.token, json: body });
+        if (opts.json) {
+            emitJson(workflow);
+            return 0;
+        }
+        ok(`Updated workflow: ${workflow.name}`);
+        if (workflow.currentVersionHash) {
+            process.stdout.write(`  version: ${workflow.currentVersionHash}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof HttpError && err.status === 404) {
+            fail(`workflow '${name}' not found`);
+            return 1;
+        }
+        fail(err.message);
+        return 1;
+    }
+}
+// ─── workflow delete ──────────────────────────────────────────────────────────
+export async function runWorkflowDelete(name, opts) {
+    const c = await ctx(opts.namespace);
+    if (!c)
+        return 1;
+    if (!opts.yes) {
+        const proceed = await confirm(`Delete workflow '${name}'?`, false);
+        if (!proceed) {
+            process.stdout.write("Cancelled.\n");
+            return 0;
+        }
+    }
+    try {
+        await requestJson(c.remote, `/namespaces/${c.ns}/workflows/${name}`, { method: "DELETE", token: c.token });
+        ok(`Deleted workflow: ${name}`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof HttpError && err.status === 404) {
+            fail(`workflow '${name}' not found`);
+            return 1;
+        }
+        fail(err.message);
+        return 1;
+    }
+}
+// ─── workflow push-run ────────────────────────────────────────────────────────
+export async function runWorkflowPushRun(name, filePath, opts) {
+    const c = await ctx(opts.namespace);
+    if (!c)
+        return 1;
+    let reduced;
+    try {
+        reduced = readRunFile(filePath);
+    }
+    catch (err) {
+        fail(`cannot read run file ${filePath}: ${err.message}`);
+        return 1;
+    }
+    if (!reduced.runId) {
+        fail(`run file ${filePath} has no runId`);
+        return 1;
+    }
+    try {
+        const run = await requestJson(c.remote, `/namespaces/${c.ns}/workflows/${name}/runs/${reduced.runId}`, { method: "PUT", token: c.token, json: reduced.body });
+        if (opts.json) {
+            emitJson(run);
+            return 0;
+        }
+        ok(`Pushed run ${reduced.runId} → ${run.status ?? reduced.body.status}`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof HttpError && err.status === 404) {
+            fail(`workflow '${name}' not found`);
+            return 1;
+        }
+        fail(err.message);
+        return 1;
+    }
+}
+/**
+ * Backoff schedule for the *terminal* push. A running snapshot that fails is
+ * harmless — the next tick retries it — but the terminal snapshot is the one
+ * that flips the server run to its final state, and there is no next tick. If
+ * it is dropped on a transient error the server run is stranded as 'running'
+ * and the detail page polls it forever, so it gets its own bounded retry.
+ */
+const TERMINAL_RETRY_DELAYS_MS = [2000, 4000, 8000, 16000, 32000];
+/**
+ * Cold-start grace window. The watcher is often launched *before* the Workflow
+ * tool has written the first wf_*.json (slow orchestration). Until the first
+ * successful read we tolerate a missing/unreadable file for this long, rather
+ * than letting the mid-run 5-strike cap (~25s at --interval 5) kill the watcher
+ * and leave the run with zero snapshots.
+ */
+const STARTUP_GRACE_MS = 120_000;
+/**
+ * Push the terminal snapshot, retrying transient failures with exponential
+ * backoff. Returns 0 once accepted, 1 on a 404 (workflow gone) or after the
+ * retry budget is exhausted.
+ */
+async function pushTerminalSnapshot(c, name, reduced, status, sleep, delays) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await requestJson(c.remote, `/namespaces/${c.ns}/workflows/${name}/runs/${reduced.runId}`, { method: "PUT", token: c.token, json: reduced.body });
+            ok(`pushed ${reduced.runId} → ${status}`);
+            ok(`run ${reduced.runId} finished: ${status}`);
+            return 0;
+        }
+        catch (err) {
+            if (err instanceof HttpError && err.status === 404) {
+                fail(`workflow '${name}' not found`);
+                return 1;
+            }
+            if (attempt >= delays.length) {
+                fail(`final push failed after ${delays.length + 1} attempts: ${err.message}`);
+                return 1;
+            }
+            const delay = delays[attempt];
+            warn(`final push failed (${err.message}) — retry ${attempt + 1}/${delays.length} in ${delay / 1000}s`);
+            await sleep(delay);
+        }
+    }
+}
+export async function runWorkflowWatchRun(name, filePath, opts, deps = {}) {
+    const c = await ctx(opts.namespace);
+    if (!c)
+        return 1;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const terminalDelays = deps.terminalRetryDelaysMs ?? TERMINAL_RETRY_DELAYS_MS;
+    const startupGraceMs = deps.startupGraceMs ?? STARTUP_GRACE_MS;
+    const parsed = Number(opts.interval);
+    const intervalMs = (Number.isFinite(parsed) && parsed > 0 ? parsed : 5) * 1000;
+    // Cold-start budget: how many read attempts fit in the grace window.
+    const startupAttempts = Math.max(1, Math.ceil(startupGraceMs / intervalMs));
+    let hasReadOnce = false; // has the run file ever been read successfully?
+    let readFailures = 0; //   consecutive failures AFTER the first success (mid-run)
+    let startupMisses = 0; //  consecutive misses BEFORE the first success (cold start)
+    for (;;) {
+        let reduced = null;
+        try {
+            reduced = readRunFile(filePath);
+            hasReadOnce = true;
+            readFailures = 0;
+        }
+        catch (err) {
+            if (!hasReadOnce) {
+                // Cold start: the Workflow tool may not have written the run file yet.
+                // Wait out the grace window instead of treating a not-yet-created file
+                // as fatal — otherwise a slow orchestrator start strands the run with
+                // zero snapshots. Log once, quietly, so we don't spam every tick.
+                startupMisses += 1;
+                if (startupMisses === 1)
+                    warn(`waiting for run file ${filePath} …`);
+                if (startupMisses >= startupAttempts) {
+                    fail(`run file ${filePath} did not appear within ${Math.round(startupGraceMs / 1000)}s — giving up: ${err.message}`);
+                    return 1;
+                }
+            }
+            else {
+                // Mid-run: the file existed and now can't be read (corrupt/deleted mid-
+                // write). Retry a few times, but don't spin forever.
+                readFailures += 1;
+                if (readFailures >= 5) {
+                    fail(`cannot read run file ${filePath}: ${err.message}`);
+                    return 1;
+                }
+                warn(`run file not readable (${err.message}) — retrying`);
+            }
+        }
+        if (reduced) {
+            if (!reduced.runId) {
+                fail(`run file ${filePath} has no runId`);
+                return 1;
+            }
+            const status = reduced.body.status;
+            if (status !== "running") {
+                // Terminal snapshot — retry with backoff so a transient failure can't
+                // strand the server run as 'running'.
+                return pushTerminalSnapshot(c, name, reduced, status, sleep, terminalDelays);
+            }
+            try {
+                await requestJson(c.remote, `/namespaces/${c.ns}/workflows/${name}/runs/${reduced.runId}`, { method: "PUT", token: c.token, json: reduced.body });
+                ok(`pushed ${reduced.runId} → ${status}`);
+            }
+            catch (err) {
+                if (err instanceof HttpError && err.status === 404) {
+                    fail(`workflow '${name}' not found`);
+                    return 1;
+                }
+                // A running snapshot is disposable — the next tick will retry it.
+                warn(`push failed (${err.message}) — retrying`);
+            }
+        }
+        await sleep(intervalMs);
+    }
+}
+// ─── registration ─────────────────────────────────────────────────────────────
+export function registerWorkflowCommand(program) {
+    const workflow = program
+        .command("workflow")
+        .description("manage workflows and push run traces");
+    // ── workflow list ──
+    workflow
+        .command("list")
+        .description("list workflows in a namespace")
+        .option("--namespace <slug>", "namespace slug (default: active login)")
+        .option("--json", "emit JSON")
+        .action(async (opts) => process.exit(await runWorkflowList(opts)));
+    // ── workflow create ──
+    workflow
+        .command("create")
+        .description("create a workflow (optionally with an initial version)")
+        .argument("<name>", "workflow name (unique within namespace)")
+        .option("--namespace <slug>", "namespace slug (default: active login)")
+        .option("--file <path>", "workflow JS script — meta is parsed and an initial version created")
+        .option("--description <text>", "description")
+        .option("--tags <csv>", "comma-separated tags")
+        .option("--message <text>", "version message (used with --file)")
+        .option("--json", "emit JSON")
+        .action(async (name, opts) => process.exit(await runWorkflowCreate(name, opts)));
+    // ── workflow show ──
+    workflow
+        .command("show")
+        .description("show workflow detail with current version meta")
+        .argument("<name>", "workflow name")
+        .option("--namespace <slug>", "namespace slug (default: active login)")
+        .option("--json", "emit JSON")
+        .action(async (name, opts) => process.exit(await runWorkflowShow(name, opts)));
+    // ── workflow update ──
+    workflow
+        .command("update")
+        .description("update metadata or upload a new version")
+        .argument("<name>", "workflow name")
+        .option("--namespace <slug>", "namespace slug (default: active login)")
+        .option("--file <path>", "new workflow JS script — creates a new version")
+        .option("--description <text>", "new description")
+        .option("--tags <csv>", "new tags (comma-separated, replaces existing)")
+        .option("--message <text>", "version message (used with --file)")
+        .option("--json", "emit JSON")
+        .action(async (name, opts) => process.exit(await runWorkflowUpdate(name, opts)));
+    // ── workflow delete ──
+    workflow
+        .command("delete")
+        .description("soft-delete a workflow (preserves version history)")
+        .argument("<name>", "workflow name")
+        .option("--namespace <slug>", "namespace slug (default: active login)")
+        .option("--yes", "skip confirmation prompt")
+        .action(async (name, opts) => process.exit(await runWorkflowDelete(name, opts)));
+    // ── workflow push-run ──
+    workflow
+        .command("push-run")
+        .description("push one run-trace snapshot from a local wf_*.json run file")
+        .argument("<name>", "workflow name")
+        .argument("<file>", "path to the local wf_*.json run file")
+        .option("--namespace <slug>", "namespace slug (default: active login)")
+        .option("--json", "emit JSON")
+        .action(async (name, file, opts) => process.exit(await runWorkflowPushRun(name, file, opts)));
+    // ── workflow watch-run ──
+    workflow
+        .command("watch-run")
+        .description("push snapshots until the run file leaves 'running', then a final push")
+        .argument("<name>", "workflow name")
+        .argument("<file>", "path to the local wf_*.json run file")
+        .option("--interval <seconds>", "seconds between pushes", "5")
+        .option("--namespace <slug>", "namespace slug (default: active login)")
+        .action(async (name, file, opts) => process.exit(await runWorkflowWatchRun(name, file, opts)));
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dreamlake/dreamlake-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "dreamlake — data-warehouse CLI. The `dreamlake` command uploads/downloads assets and manages episodes, bindrs, and datasets against a DreamLake server + BSS.",
   "private": false,
-  "license": "MIT",
   "type": "module",
+  "main": "dist/cli/index.js",
   "bin": {
     "dreamlake": "bin/dreamlake.js"
   },
@@ -13,25 +13,6 @@
     "dist",
     "!dist/**/*.map"
   ],
-  "engines": {
-    "node": ">=20"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/dreamlake-ai/dreamlake-cli.git"
-  },
-  "homepage": "https://github.com/dreamlake-ai/dreamlake-cli#readme",
-  "bugs": {
-    "url": "https://github.com/dreamlake-ai/dreamlake-cli/issues"
-  },
-  "keywords": [
-    "dreamlake",
-    "cli",
-    "data-warehouse",
-    "dataset",
-    "robotics"
-  ],
-  "author": "DreamLake AI",
   "publishConfig": {
     "access": "public"
   },
@@ -39,8 +20,6 @@
     "build": "tsc",
     "cli": "tsx src/cli/index.ts",
     "test": "tsc -p tsconfig.json --noEmit && node --import tsx --test src/cli/__tests__/*.test.ts",
-    "prepublishOnly": "npm test",
-    "prepack": "npm run build",
     "docs:dev": "pnpm -C docs dev",
     "docs:build": "pnpm -C docs build",
     "docs:preview": "pnpm -C docs preview"

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 DreamLake AI
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.