@tuongaz/seeflow 0.1.77 → 0.1.80

package/src/cli-ops.ts

@@ -1,5 +1,11 @@
 import { type Operations, createOperations } from './operations.ts';
-import { createRegistry } from './registry.ts';
+import { type ScanError, scanProject } from './project-scanner.ts';
+import {
+  type FlowEntry,
+  type Registry,
+  createRegistry,
+  manifestOnlyEntryFilter,
+} from './registry.ts';
 
 /**
  * Build a single Operations handle for in-process CLI use.
@@ -14,5 +20,53 @@ import { createRegistry } from './registry.ts';
  * is undefined in the CLI.
  */
 export function createCliOperations(): Operations {
-  return createOperations({ registry: createRegistry() });
+  return createOperations({
+    registry: createRegistry({ isLoadableEntry: manifestOnlyEntryFilter }),
+  });
+}
+
+export interface RegisterProjectOpts {
+  /** Absolute (or relative) path of the project root that contains a
+   *  `seeflow.json` manifest plus one `flows/<id>/flow.json` per declared flow. */
+  repoPath: string;
+  /** Registry handle to upsert into. Defaults to a fresh `createRegistry()` —
+   *  long-lived consumers (the server's seed path, the in-process CLI ops)
+   *  should pass their own to share state across calls. */
+  registry?: Registry;
+}
+
+export type RegisterProjectOutcome =
+  | { kind: 'ok'; projectSlug: string; entries: FlowEntry[] }
+  | ScanError;
+
+/**
+ * Scan a project root and register every flow declared in its `seeflow.json`.
+ * Produces one `FlowEntry` per `ScannedFlow` — `projectSlug` is shared across
+ * the resulting entries, `flowSlug` mirrors the manifest entry id, and the
+ * entry whose id matches `manifest.defaultFlow` is marked `isDefault: true`.
+ *
+ * The legacy single-flow `ops.registerFlow` path in operations.ts still backs
+ * the `/api/flows/register` HTTP endpoint until US-007 rewrites the route
+ * tree. `registerProject` is the manifest-driven replacement the CLI uses
+ * from US-004 onward.
+ */
+export function registerProject(opts: RegisterProjectOpts): RegisterProjectOutcome {
+  const registry = opts.registry ?? createRegistry({ isLoadableEntry: manifestOnlyEntryFilter });
+  const scan = scanProject(opts.repoPath);
+  if (scan.kind !== 'ok') return scan;
+
+  const entries: FlowEntry[] = scan.flows.map((flow) =>
+    registry.upsert({
+      name: flow.name,
+      description: scan.manifest.description,
+      repoPath: opts.repoPath,
+      flowPath: flow.flowPath,
+      projectSlug: scan.projectSlug,
+      flowSlug: flow.id,
+      isDefault: flow.isDefault,
+      icon: flow.icon,
+    }),
+  );
+
+  return { kind: 'ok', projectSlug: scan.projectSlug, entries };
 }

package/src/cli.ts

@@ -1,10 +1,18 @@
 #!/usr/bin/env bun
 import { closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { drainStdin, loadBody, printError, printOk, printOutcome } from './cli-helpers.ts';
+import {
+  drainStdin,
+  loadBody,
+  parseProjectFlow,
+  printError,
+  printOk,
+  printOutcome,
+} from './cli-helpers.ts';
 import { COMMAND_MANIFEST, renderCommandHelp, renderCommandList } from './cli-manifest.ts';
-import { createCliOperations } from './cli-ops.ts';
+import { createCliOperations, registerProject } from './cli-ops.ts';
 import { createEventBus } from './events.ts';
+import { JqError, applyJq } from './jq-filter.ts';
 import type { LayoutOptions } from './layout.ts';
 import {
   ConnectorPatchBodySchema,
@@ -14,7 +22,7 @@ import {
 } from './operations.ts';
 import { PROJECT_FLOW_FILENAME, seeflowHome } from './paths.ts';
 import { defaultProcessSpawner } from './process-spawner.ts';
-import { type Registry, createRegistry } from './registry.ts';
+import { type Registry, createRegistry, manifestOnlyEntryFilter } from './registry.ts';
 import {
   DEFAULT_CONFIG,
   clearPid,
@@ -60,6 +68,53 @@ const requireArg = (idx: number, name: string): string => {
   return v as string;
 };
 
+/**
+ * Walk argv (after the subcommand at argv[0]) and return non-flag positionals
+ * in order. Skips `--name value` and `--name=value` pairs so callers can mix
+ * positional arguments freely with --project/--flow (US-020). Boolean-style
+ * `--name` flags (e.g. `--no-start`, `--stdin`) are detected because the next
+ * argv entry either starts with `--` or is out of bounds.
+ */
+const positionalArgs = (): string[] => {
+  const out: string[] = [];
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i] as string;
+    if (arg.startsWith('--')) {
+      // `--name=value` is self-contained; `--name value` consumes the next slot
+      // only when that slot is not itself another flag (boolean flag otherwise).
+      if (!arg.includes('=')) {
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) i++;
+      }
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+};
+
+const requirePositional = (idx: number, name: string): string => {
+  const v = positionalArgs()[idx];
+  if (!v) printError(`Missing required positional argument: ${name}`);
+  return v as string;
+};
+
+/**
+ * Resolve the (project, flow) pair every flow-scoped CLI verb expects (US-020).
+ * Surfaces clear `Missing required flag: --project|--flow` errors through
+ * `printError` instead of throwing — matches the rest of the CLI's exit
+ * behaviour. The returned `slug` (`${project}/${flow}`) is what the in-process
+ * `ops.*` calls accept via `registry.resolve(idOrSlug)`.
+ */
+const requireProjectFlow = (): { project: string; flow: string; slug: string } => {
+  try {
+    const { project, flow } = parseProjectFlow(argv);
+    return { project, flow, slug: `${project}/${flow}` };
+  } catch (err) {
+    printError(err instanceof Error ? err.message : String(err));
+  }
+};
+
 async function studioUrlOrDie(noStart: boolean): Promise<{ url: string; port: number }> {
   const config = readConfig();
   const overrideUrl = process.env.SEEFLOW_STUDIO_URL?.replace(/\/+$/, '');
@@ -131,6 +186,10 @@ if (argv.includes('--version') || argv.includes('-v')) {
   await runFlowsGet();
 } else if (sub === 'flows:graph') {
   await runFlowsGraph();
+} else if (sub === 'flows:create') {
+  await runFlowsCreate();
+} else if (sub === 'flows:rename') {
+  await runFlowsRename();
 } else if (sub === 'flows:delete') {
   await runFlowsDelete();
 } else if (sub === 'flows:layout') {
@@ -186,23 +245,25 @@ Commands (work without a running studio):
   stop                 Stop a background studio instance
   register             Register a demo repo, writing to ~/.seeflow/registry.json (alias of flows:register)
   flows:register       Register a demo repo
-  projects:create      Create a new project (--path <dir> --name <name> [--description <text>])
+  projects:create      Scaffold a new project (writes <path>/seeflow.json + <path>/flows/main/flow.json) — (--path <dir> --name <name> [--description <text>])
   flows:list           List registered flows
   flows:summary        List registered flows (id + name + description only)
-  flows:get <id>       Get flow details
-  flows:graph <id>     List nodes + connectors without inlined file content
-  flows:delete <id>    Unregister a flow
-  flows:layout <id>    Apply ELK layout, writing style.json (--json/--file/--stdin optional)
-  flow:add-bulk <id>   Add many nodes + connectors atomically (--json/--file/--stdin; body { nodes?, connectors? })
-  nodes:add <id>       Add a node (--json/--file/--stdin)
-  nodes:get <id> <n>   Get a node with detail / html content inlined
-  nodes:patch <id> <n> Patch a node (--json/--file/--stdin)
-  nodes:move <id> <n>  Move a node (--x N --y N)
-  nodes:reorder <id> <n> Reorder a node (--op forward|backward|toFront|toBack|toIndex [--index N])
-  nodes:delete <id> <n> Delete a node
-  connectors:add <id>  Add a connector (--json/--file/--stdin)
-  connectors:patch <id> <connId>  Patch a connector (--json/--file/--stdin)
-  connectors:delete <id> <connId> Delete a connector
+  flows:get            Get flow details (--project <p> --flow <f>)
+  flows:graph          List nodes + connectors without inlined file content (--project <p> --flow <f>)
+  flows:create         Create a new flow within a project (--project <p> --flow <id> --name <n> [--icon <i>])
+  flows:rename         Rename a flow id/name/icon (--project <p> --flow <id> [--new-id <x>] [--name <n>] [--icon <i>])
+  flows:delete         Delete a flow (--project <p> --flow <f> [--new-default <other>])
+  flows:layout         Apply ELK layout, writing style.json (--project <p> --flow <f>) [--json/--file/--stdin]
+  flow:add-bulk        Add many nodes + connectors atomically (--project <p> --flow <f>) [--json/--file/--stdin; body { nodes?, connectors? }]
+  nodes:add            Add a node (--project <p> --flow <f>) [--json/--file/--stdin]
+  nodes:get <n>        Get a node with detail / html content inlined (--project <p> --flow <f>)
+  nodes:patch <n>      Patch a node (--project <p> --flow <f>) [--json/--file/--stdin]
+  nodes:move <n>       Move a node (--project <p> --flow <f> --x N --y N)
+  nodes:reorder <n>    Reorder a node (--project <p> --flow <f> --op forward|backward|toFront|toBack|toIndex [--index N])
+  nodes:delete <n>     Delete a node (--project <p> --flow <f>)
+  connectors:add       Add a connector (--project <p> --flow <f>) [--json/--file/--stdin]
+  connectors:patch <connId>  Patch a connector (--project <p> --flow <f>) [--json/--file/--stdin]
+  connectors:delete <connId> Delete a connector (--project <p> --flow <f>)
   validate             Schema-validate a flow.json (--file <file> [--style <file>])
   schema [<category>]  Get the flow.json schema. No arg → category index;
                        category arg → full JSON Schema(s) for that category
@@ -213,10 +274,10 @@ Commands (work without a running studio):
                        'ids connector 12').
 
 Commands (require a running studio):
-  flows:play <id> <n>  Trigger a play on node <n>
+  flows:play <n>       Trigger a play on node <n> (--project <p> --flow <f>)
   emit <id> <n> <st>   Broadcast a status event for node <n> (st: running|done|error)
                        [--run-id <id>] [--payload <json>] [--studio-url <url>]
-  e2e <id>             End-to-end validate a registered flow (--skip-nodes a,b)
+  e2e                  End-to-end validate a registered flow (--project <p> --flow <f> [--skip-nodes a,b])
 
 Meta:
   version              Print the CLI version
@@ -318,7 +379,7 @@ async function runStart() {
   // persist the chosen address so other subcommands can find us
   writeConfig({ port, host: config.host });
 
-  const registry = createRegistry();
+  const registry = createRegistry({ isLoadableEntry: manifestOnlyEntryFilter });
   const events = createEventBus();
   const statusRunner = createStatusRunner({ registry, events, spawner: defaultProcessSpawner });
   const server = serve({ port, hostname: config.host, registry, events, statusRunner });
@@ -355,7 +416,6 @@ async function seedExamples(registry: Registry) {
 
 async function seedExample(registry: Registry, exampleName: string) {
   const destDir = join(seeflowHome(), exampleName);
-  const flowPath = PROJECT_FLOW_FILENAME;
 
   // Always sync from source so that schema changes and example updates are
   // reflected on every startup, even when the dest directory already exists.
@@ -363,23 +423,14 @@ async function seedExample(registry: Registry, exampleName: string) {
   if (!existsSync(srcDir)) return;
   cpSync(srcDir, destDir, { recursive: true });
 
-  if (registry.getByRepoPathAndFlowPath(destDir, flowPath)) return;
-
-  const flowFile = join(destDir, flowPath);
-  if (!existsSync(flowFile)) return;
-
-  let demo: unknown;
-  try {
-    demo = await Bun.file(flowFile).json();
-  } catch {
+  const outcome = registerProject({ repoPath: destDir, registry });
+  if (outcome.kind !== 'ok') {
+    console.warn(`Skipped example ${exampleName}: ${JSON.stringify(outcome)}`);
     return;
   }
-
-  const parsed = FlowSchema.safeParse(demo);
-  if (!parsed.success) return;
-
-  registry.upsert({ name: parsed.data.name, repoPath: destDir, flowPath });
-  console.log(`Seeded example: ${parsed.data.name} → ${destDir}`);
+  for (const entry of outcome.entries) {
+    console.log(`Seeded example: ${entry.name} → ${destDir} (${entry.slug})`);
+  }
 }
 
 async function spawnDaemon(port: number, host: string) {
@@ -666,28 +717,96 @@ async function runFlowsSummary() {
 }
 
 async function runFlowsGet() {
-  const flowId = requireArg(1, '<flowId>');
+  const { slug } = requireProjectFlow();
   const ops = createCliOperations();
-  const result = await ops.getFlow(flowId);
+  const result = await ops.getFlow(slug);
   printOutcome(result);
 }
 
 async function runFlowsGraph() {
-  const flowId = requireArg(1, '<flowId>');
+  const { slug } = requireProjectFlow();
   const ops = createCliOperations();
-  const result = await ops.getFlowGraph(flowId);
+  const result = await ops.getFlowGraph(slug);
   printOutcome(result);
 }
 
 async function runFlowsDelete() {
-  const flowId = requireArg(1, '<flowId>');
-  const ops = createCliOperations();
-  const result = ops.deleteFlow(flowId);
-  printOutcome(result);
+  await runFlowsDeleteManifest();
+}
+
+async function runFlowsCreate() {
+  const project = flagValue('project');
+  if (!project) printError('Missing required flag: --project');
+  const flow = flagValue('flow');
+  if (!flow) printError('Missing required flag: --flow');
+  const name = flagValue('name');
+  if (!name) printError('Missing required flag: --name');
+  const icon = flagValue('icon');
+
+  const body: { id: string; name: string; icon?: string } = {
+    id: flow as string,
+    name: name as string,
+  };
+  if (icon !== undefined) body.icon = icon;
+
+  const { url } = await studioUrlOrDie(hasFlag('no-start'));
+  const res = await postJson(
+    `${url}/api/projects/${encodeURIComponent(project as string)}/flows`,
+    body,
+  );
+  const out = (await handleResponse(res)) as object;
+  printOk(out);
+}
+
+async function runFlowsRename() {
+  const project = flagValue('project');
+  if (!project) printError('Missing required flag: --project');
+  const flow = flagValue('flow');
+  if (!flow) printError('Missing required flag: --flow');
+  const newId = flagValue('new-id');
+  const name = flagValue('name');
+  const icon = flagValue('icon');
+  if (newId === undefined && name === undefined && icon === undefined) {
+    printError('flows:rename requires at least one of --new-id, --name, --icon');
+  }
+
+  const body: { id?: string; name?: string; icon?: string } = {};
+  if (newId !== undefined) body.id = newId;
+  if (name !== undefined) body.name = name;
+  if (icon !== undefined) body.icon = icon;
+
+  const { url } = await studioUrlOrDie(hasFlag('no-start'));
+  const res = await fetch(
+    `${url}/api/projects/${encodeURIComponent(project as string)}/flows/${encodeURIComponent(flow as string)}`,
+    {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    },
+  );
+  const out = (await handleResponse(res)) as object;
+  printOk(out);
+}
+
+async function runFlowsDeleteManifest() {
+  const project = flagValue('project');
+  if (!project) printError('Missing required flag: --project');
+  const flow = flagValue('flow');
+  if (!flow) printError('Missing required flag: --flow');
+  const newDefault = flagValue('new-default');
+
+  const query = newDefault !== undefined ? `?newDefault=${encodeURIComponent(newDefault)}` : '';
+  const { url } = await studioUrlOrDie(hasFlag('no-start'));
+  const res = await fetch(
+    `${url}/api/projects/${encodeURIComponent(project as string)}/flows/${encodeURIComponent(flow as string)}${query}`,
+    { method: 'DELETE' },
+  );
+  const out = (await handleResponse(res)) as object;
+  printOk(out);
 }
 
 async function runFlowsLayout() {
-  const flowId = requireArg(1, '<flowId>');
+  const { slug } = requireProjectFlow();
   // Body is optional — `{ options? }` shape if provided. Empty when omitted.
   let options: LayoutOptions | undefined;
   if (hasFlag('json') || hasFlag('file') || hasFlag('stdin')) {
@@ -695,16 +814,16 @@ async function runFlowsLayout() {
     options = body?.options;
   }
   const ops = createCliOperations();
-  const result = await ops.applyLayout(flowId, options);
+  const result = await ops.applyLayout(slug, options);
   printOutcome(result);
 }
 
 async function runFlowsPlay() {
-  const flowId = requireArg(1, '<flowId>');
-  const nodeId = requireArg(2, '<nodeId>');
+  const { project, flow } = requireProjectFlow();
+  const nodeId = requirePositional(0, '<nodeId>');
   const { url } = await studioUrlOrDie(hasFlag('no-start'));
   const res = await postJson(
-    `${url}/api/flows/${encodeURIComponent(flowId)}/play/${encodeURIComponent(nodeId)}`,
+    `${url}/api/projects/${encodeURIComponent(project)}/flows/${encodeURIComponent(flow)}/play/${encodeURIComponent(nodeId)}`,
     {},
   );
   const out = (await handleResponse(res)) as object;
@@ -751,52 +870,52 @@ async function runEmit() {
 }
 
 async function runNodesAdd() {
-  const flowId = requireArg(1, '<flowId>');
+  const { slug } = requireProjectFlow();
   const body = await bodyFromFlags();
   if (!body || typeof body !== 'object' || Array.isArray(body)) {
     printError('Body must be an object');
   }
   const ops = createCliOperations();
-  const result = await ops.addNode(flowId, body as Record<string, unknown>);
+  const result = await ops.addNode(slug, body as Record<string, unknown>);
   printOutcome(result);
 }
 
 async function runFlowAddBulk() {
-  const flowId = requireArg(1, '<flowId>');
+  const { slug } = requireProjectFlow();
   const body = await bodyFromFlags();
   const parsed = FlowBulkBodySchema.safeParse(body);
   if (!parsed.success) {
     printError(`Invalid flow:add-bulk body: ${JSON.stringify(parsed.error.issues)}`);
   }
   const ops = createCliOperations();
-  const result = await ops.addBulk(flowId, parsed.data);
+  const result = await ops.addBulk(slug, parsed.data);
   printOutcome(result);
 }
 
 async function runNodesGet() {
-  const flowId = requireArg(1, '<flowId>');
-  const nodeId = requireArg(2, '<nodeId>');
+  const { slug } = requireProjectFlow();
+  const nodeId = requirePositional(0, '<nodeId>');
   const ops = createCliOperations();
-  const result = await ops.getNode(flowId, nodeId);
+  const result = await ops.getNode(slug, nodeId);
   printOutcome(result);
 }
 
 async function runNodesPatch() {
-  const flowId = requireArg(1, '<flowId>');
-  const nodeId = requireArg(2, '<nodeId>');
+  const { slug } = requireProjectFlow();
+  const nodeId = requirePositional(0, '<nodeId>');
   const body = await bodyFromFlags();
   const parsed = NodePatchBodySchema.safeParse(body);
   if (!parsed.success) {
     printError(`Invalid nodes:patch body: ${JSON.stringify(parsed.error.issues)}`);
   }
   const ops = createCliOperations();
-  const result = await ops.patchNode(flowId, nodeId, parsed.data);
+  const result = await ops.patchNode(slug, nodeId, parsed.data);
   printOutcome(result);
 }
 
 async function runNodesMove() {
-  const flowId = requireArg(1, '<flowId>');
-  const nodeId = requireArg(2, '<nodeId>');
+  const { slug } = requireProjectFlow();
+  const nodeId = requirePositional(0, '<nodeId>');
   const xRaw = flagValue('x');
   const yRaw = flagValue('y');
   if (xRaw === undefined || yRaw === undefined) {
@@ -808,13 +927,13 @@ async function runNodesMove() {
     printError('--x and --y must be finite numbers');
   }
   const ops = createCliOperations();
-  const result = await ops.moveNode(flowId, nodeId, { x, y });
+  const result = await ops.moveNode(slug, nodeId, { x, y });
   printOutcome(result);
 }
 
 async function runNodesReorder() {
-  const flowId = requireArg(1, '<flowId>');
-  const nodeId = requireArg(2, '<nodeId>');
+  const { slug } = requireProjectFlow();
+  const nodeId = requirePositional(0, '<nodeId>');
   const op = flagValue('op');
   if (!op) printError('nodes:reorder requires --op forward|backward|toFront|toBack|toIndex');
   let raw: Record<string, unknown> = { op };
@@ -832,47 +951,47 @@ async function runNodesReorder() {
     printError(`Invalid nodes:reorder body: ${JSON.stringify(parsed.error.issues)}`);
   }
   const ops = createCliOperations();
-  const result = await ops.reorderNode(flowId, nodeId, parsed.data);
+  const result = await ops.reorderNode(slug, nodeId, parsed.data);
   printOutcome(result);
 }
 
 async function runNodesDelete() {
-  const flowId = requireArg(1, '<flowId>');
-  const nodeId = requireArg(2, '<nodeId>');
+  const { slug } = requireProjectFlow();
+  const nodeId = requirePositional(0, '<nodeId>');
   const ops = createCliOperations();
-  const result = await ops.deleteNode(flowId, nodeId);
+  const result = await ops.deleteNode(slug, nodeId);
   printOutcome(result);
 }
 
 async function runConnectorsAdd() {
-  const flowId = requireArg(1, '<flowId>');
+  const { slug } = requireProjectFlow();
   const body = await bodyFromFlags();
   if (!body || typeof body !== 'object' || Array.isArray(body)) {
     printError('Body must be an object');
   }
   const ops = createCliOperations();
-  const result = await ops.addConnector(flowId, body as Record<string, unknown>);
+  const result = await ops.addConnector(slug, body as Record<string, unknown>);
   printOutcome(result);
 }
 
 async function runConnectorsPatch() {
-  const flowId = requireArg(1, '<flowId>');
-  const connId = requireArg(2, '<connectorId>');
+  const { slug } = requireProjectFlow();
+  const connId = requirePositional(0, '<connectorId>');
   const body = await bodyFromFlags();
   const parsed = ConnectorPatchBodySchema.safeParse(body);
   if (!parsed.success) {
     printError(`Invalid connectors:patch body: ${JSON.stringify(parsed.error.issues)}`);
   }
   const ops = createCliOperations();
-  const result = await ops.patchConnector(flowId, connId, parsed.data);
+  const result = await ops.patchConnector(slug, connId, parsed.data);
   printOutcome(result);
 }
 
 async function runConnectorsDelete() {
-  const flowId = requireArg(1, '<flowId>');
-  const connId = requireArg(2, '<connectorId>');
+  const { slug } = requireProjectFlow();
+  const connId = requirePositional(0, '<connectorId>');
   const ops = createCliOperations();
-  const result = await ops.deleteConnector(flowId, connId);
+  const result = await ops.deleteConnector(slug, connId);
   printOutcome(result);
 }
 
@@ -906,9 +1025,14 @@ async function runValidate() {
 
 async function runSchema() {
   const category = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
+  const jqFilter = flagValue('jq');
   const { listSchemaCategories, getSchemaCategory } = await import('./schema-catalog.ts');
   if (!category) {
-    printOk({ categories: listSchemaCategories() });
+    const base = { categories: listSchemaCategories() };
+    if (jqFilter !== undefined) {
+      printOk({ result: applyJqOrDie(base, jqFilter) });
+    }
+    printOk(base);
   }
   const payload = getSchemaCategory(category as string);
   if (!payload) {
@@ -917,16 +1041,39 @@ async function runSchema() {
     process.stderr.write(`${JSON.stringify({ error: message, code: 'notFound', available })}\n`);
     process.exit(3);
   }
-  printOk({ name: category, schemas: payload.schemas, notes: payload.notes });
+  const base = { name: category, schemas: payload.schemas, notes: payload.notes };
+  if (jqFilter !== undefined) {
+    printOk({ name: category, result: applyJqOrDie(base, jqFilter) });
+  }
+  printOk(base);
+}
+
+// Apply a --jq filter and unwrap a single-result stream into the value
+// itself; multi-output streams (from `[]` or `|`) come through as arrays
+// so downstream consumers can tell `.foo[]` (multiple) apart from `.foo`
+// (single value that happens to be an array). On parse / type errors exits
+// with code 2 (badJq).
+function applyJqOrDie(input: unknown, filterStr: string): unknown {
+  try {
+    const stream = applyJq(input, filterStr);
+    if (stream.length === 1) return stream[0];
+    return stream;
+  } catch (err) {
+    if (err instanceof JqError) {
+      process.stderr.write(`${JSON.stringify({ error: err.message, code: 'badJq' })}\n`);
+      process.exit(2);
+    }
+    throw err;
+  }
 }
 
 async function runE2e() {
-  const flowId = requireArg(1, '<flowId>');
+  const { project, flow } = requireProjectFlow();
   const skipNodesRaw = flagValue('skip-nodes');
   const skipNodes = skipNodesRaw ? skipNodesRaw.split(',').filter(Boolean) : [];
   const { url } = await studioUrlOrDie(hasFlag('no-start'));
   const { validateEndToEnd } = await import('./cli-e2e.ts');
-  const report = await validateEndToEnd({ flowId, url, skipNodes });
+  const report = await validateEndToEnd({ project, flow, url, skipNodes });
   if (!report.ok) {
     process.stderr.write(`${JSON.stringify(report)}\n`);
     process.exit(1);