primitive-admin 1.0.63 → 1.0.64

package/dist/src/commands/workflows.js

@@ -1,4 +1,3 @@
-import { Option } from "commander";
 import { readFileSync, writeFileSync, readdirSync, } from "fs";
 import * as path from "path";
 import { stringifyConfigToml } from "../lib/config-toml.js";
@@ -6,17 +5,18 @@ import { generateWorkflowTypes, } from "../lib/workflow-codegen/generator.js";
 import { generateWorkflowSwiftTypes } from "../lib/swift-codegen/generator.js";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
+import { resolveWorkflowSelector } from "../lib/block-selector.js";
 import { formatAccessRuleForDisplay } from "../lib/access-rule-display.js";
 import { resolveCodegenSourceDir } from "../lib/codegen-shared/resolveCodegenSourceDir.js";
-import { resolveSyncDirOverride } from "../lib/sync-dir-selector.js";
 import { expandWorkflow } from "../lib/workflow-fragments.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import { parseStatusFilter } from "../lib/object-status-filter.js";
-import { buildWorkflowRunEnvelope, buildWorkflowStepEnvelope, collectWorkflowFailures, describeEmptyRunPage, describeFailureSweep, formatFailureCodeCell, formatFailureErrorCell, formatFailureStepCell, selectFailedStepRow, toWorkflowRunInspectionRow, DEFAULT_FAILURE_SWEEP_MAX_SCAN, FAILURE_SWEEP_MAX_REQUESTS, SERVER_SCAN_ROWS_PER_REQUEST, } from "../lib/log-inspection.js";
+import { buildWorkflowRunEnvelope, buildWorkflowRunListEnvelope, buildWorkflowStepEnvelope, collectWorkflowFailures, describeEmptyRunPage, describeFailureSweep, formatFailureCodeCell, formatFailureErrorCell, formatFailureStepCell, selectFailedStepRow, toWorkflowRunInspectionRow, DEFAULT_FAILURE_SWEEP_MAX_SCAN, FAILURE_SWEEP_MAX_REQUESTS, SERVER_SCAN_ROWS_PER_REQUEST, } from "../lib/log-inspection.js";
 import chalk from "chalk";
 import { success, error, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, formatDuration, json, jsonLine, divider, dim, progress, progressEnd, } from "../lib/output.js";
 import { pollUntil, followLoop, watchLoop, parseIntervalSeconds, } from "../lib/watch.js";
 import { APPLY_RUN_STATUSES, RUN_STATUS_LIST, SETTLED_RUN_STATUSES, } from "../lib/run-status.js";
+import { requireTestCaseInputVariables } from "../lib/test-case-variables.js";
 /**
  * Render the `Step Results` section of `workflows runs status`. Pure
  * formatting helper — returns lines as strings so it's unit-testable
@@ -121,25 +121,15 @@ export function renderRunStatusStepResults(stepResults) {
     }
     return lines;
 }
-/**
- * #2771 — how long a step row has been going.
- *
- * A step that is still executing is persisted with status `running` and a
- * `durationMs` of 0 (the column is required; the real value is written when the
- * step ends). Printing that 0 hides the one number that matters while a run is
- * in flight — how long the current step has been stuck — so a running row is
- * measured from its `startedAt` instead. Finished rows keep their stored
- * duration. Exported for testability.
- */
-export function stepRunDisplayDurationMs(step, now = Date.now()) {
-    const stored = typeof step?.durationMs === "number" ? step.durationMs : null;
-    if (step?.status !== "running")
-        return stored;
-    const started = step?.startedAt ? new Date(step.startedAt).getTime() : NaN;
-    if (Number.isNaN(started))
-        return stored;
-    return Math.max(0, now - started);
-}
+// #3348 — the step table, the gap annotation and the running-step duration now
+// live in `lib/step-run-table.ts`, shared with `functions runs steps`: a
+// function run's steps are the same rows, and the two views must not be two
+// tables that merely resemble each other. Re-exported from here because this is
+// where the two helpers were first exported for testability.
+export { annotateStepGaps, stepRunDisplayDurationMs, } from "../lib/step-run-table.js";
+import { renderStepRunTable, stepRunDisplayDurationMs, } from "../lib/step-run-table.js";
+import { normalizeCliListEnvelope, wholeListEnvelope, } from "../lib/paginate.js";
+import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, } from "../lib/list-options.js";
 /**
  * #2771 — the step lines `workflows runs status` should render.
  *
@@ -163,53 +153,6 @@ export function stepResultsForRunStatus(instanceStepResults, persistedStepRuns,
         output: row?.output,
     }));
 }
-/**
- * #1367 — annotate step-run rows with the inter-step gap: the wall-clock time
- * between the previous step's `endedAt` and this step's `startedAt`. Sorts by
- * `startedAt` when every row has a parseable one (tie-break `stepIndex`),
- * otherwise by `stepIndex` for the whole list — the ordering mode must be
- * chosen once for all rows, not per pair: a per-pair timestamp-vs-index
- * fallback is not transitive when some rows lack a timestamp (A<B by index,
- * B<C by index, C<A by time), and a non-transitive comparator leaves
- * Array.prototype.sort free to return an arbitrary order, computing gaps
- * against the wrong predecessor. The first step has no predecessor, so its
- * `gapMs` is `null`. A gap is only meaningful when both adjacent timestamps
- * parse and the gap is positive. When the immediate predecessor lacks a valid
- * `endedAt`, the gap is left `null` rather than measured from an older,
- * non-adjacent step — otherwise a later step could raise a false stall
- * warning against a step it does not actually follow. Exported for
- * testability.
- */
-export function annotateStepGaps(steps) {
-    const rows = [...(steps || [])];
-    const allTimed = rows.every((r) => r?.startedAt && !Number.isNaN(new Date(r.startedAt).getTime()));
-    rows.sort((a, b) => {
-        if (allTimed) {
-            const sa = new Date(a.startedAt).getTime();
-            const sb = new Date(b.startedAt).getTime();
-            if (sa !== sb)
-                return sa - sb;
-        }
-        return (a?.stepIndex ?? 0) - (b?.stepIndex ?? 0);
-    });
-    let prevEnded = null;
-    for (const row of rows) {
-        const started = row?.startedAt ? new Date(row.startedAt).getTime() : NaN;
-        if (prevEnded != null && !Number.isNaN(started)) {
-            const gap = started - prevEnded;
-            row.gapMs = gap > 0 ? gap : 0;
-        }
-        else {
-            row.gapMs = null;
-        }
-        // Only genuinely adjacent steps yield a gap: if this step lacks a valid
-        // `endedAt`, clear the predecessor so the NEXT step's gap is left null
-        // instead of being measured from a non-adjacent earlier step.
-        const ended = row?.endedAt ? new Date(row.endedAt).getTime() : NaN;
-        prevEnded = Number.isNaN(ended) ? null : ended;
-    }
-    return rows;
-}
 /**
  * #1367 — compute min / p50 / p95 / max over a set of latency samples (ms).
  * Ignores non-finite values. Returns `null` when there are no valid samples.
@@ -253,6 +196,17 @@ export function formatConfigSlotLabel(slot, configName, configId, prefixLength =
     }
     return slot;
 }
+/**
+ * Resolve a workflow reference — its server id, or the author-chosen key its
+ * TOML file is named for — for the `tests` verbs (#3249).
+ *
+ * The key is what an operator has: `workflows/<key>.toml` is the object and
+ * `workflows/<key>.tests/` its cases. The resolution lives in
+ * `block-selector.ts`, shared with `prompts`.
+ */
+async function resolveWorkflowId(client, appId, ref) {
+    return (await resolveWorkflowSelector(client, appId, ref)).blockId;
+}
 export function registerWorkflowsCommands(program) {
     const workflows = program
         .command("workflows")
@@ -296,8 +250,11 @@ overview — the endpoint behind the retired overview command never existed.
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
         .option("--status <status>", "Filter by status: active, inactive, archived")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
+        const limit = parsePageLimit(options.limit);
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
@@ -305,19 +262,22 @@ overview — the endpoint behind the retired overview command never existed.
             // empty list a canonical filter would produce. #2887 added `archived`:
             // the delete flow writes one now, so asking for the retired rows is a
             // question with an answer rather than a 400.
-            const { items } = await client.listWorkflows(resolvedAppId, {
+            const page = normalizeCliListEnvelope(await client.listWorkflows(resolvedAppId, {
                 status: parseStatusFilter("workflows", options.status, [
                     "active",
                     "inactive",
                     "archived",
                 ]),
-            });
+                limit,
+                cursor: options.cursor,
+            }));
+            const items = page.items;
             if (options.json) {
-                json(items);
+                json(page);
                 return;
             }
-            if (!items || items.length === 0) {
-                info("No workflows found.");
+            if (items.length === 0) {
+                printEmptyPage(page, "workflows");
                 return;
             }
             console.log(formatTable(items, [
@@ -327,6 +287,7 @@ overview — the endpoint behind the retired overview command never existed.
                 { header: "STATUS", key: "status", format: formatStatus },
                 { header: "MODIFIED", key: "modifiedAt", format: formatDate },
             ]));
+            printPageHint(page);
         }
         catch (err) {
             error(err.message);
@@ -988,10 +949,11 @@ Reclaiming the key means hard-deleting the row and its cascade:
                 });
                 const { items } = page;
                 if (options.json) {
-                    // #1316 envelope with the shared inspection item shape — never a
-                    // bare array — preserving nextCursor/hasMore + the deprecated
-                    // `cursor` dual-emit alias (behaviors 6, 7).
-                    json(buildWorkflowRunEnvelope(items, page));
+                    // The CLI's one list envelope with the shared inspection item
+                    // shape — never a bare array, and since #3646 no `nextCursor:
+                    // null` and no deprecated `cursor` alias either, because this is a
+                    // `list` verb like any other (behaviors 6, 7).
+                    json(buildWorkflowRunListEnvelope(items, page));
                     return;
                 }
                 // The cursor hint prints whether or not this page had rows: a
@@ -1105,7 +1067,7 @@ Reclaiming the key means hard-deleting the row and its cascade:
                     signal: controller.signal,
                     render: (items) => {
                         if (options.json) {
-                            json(buildWorkflowRunEnvelope(items, lastPage));
+                            json(buildWorkflowRunListEnvelope(items, lastPage));
                             return;
                         }
                         // Renderer owns the redraw: clear the screen, then print.
@@ -1225,49 +1187,7 @@ Reclaiming the key means hard-deleting the row and its cascade:
                 info("No step runs found.");
                 return;
             }
-            // #1367 — inter-step gap: idle time between one step ending and the
-            // next starting. Only surfaced above a 1s threshold so normal
-            // back-to-back steps stay quiet; a large gap flags a mid-run stall.
-            const STEP_GAP_THRESHOLD_MS = 1000;
-            // #2771 — an in-flight run also returns the step executing right now
-            // (status `running`, duration not written yet). Show its elapsed time
-            // so a step stuck retrying is visible as such.
-            const rows = annotateStepGaps(items).map((row) => ({
-                ...row,
-                displayDurationMs: stepRunDisplayDurationMs(row),
-            }));
-            console.log(formatTable(rows, [
-                { header: "STEP", key: "stepId" },
-                { header: "KIND", key: "stepKind" },
-                {
-                    header: "STATUS",
-                    key: "status",
-                    format: (v) => v === "completed" ? chalk.green(v) :
-                        v === "failed" ? chalk.red(v) :
-                            v === "skipped" ? chalk.gray(v) :
-                                v === "error_captured" ? chalk.yellow(v) :
-                                    // #2771 — the step executing right now.
-                                    v === "running" ? chalk.cyan(v) : v,
-                },
-                {
-                    header: "GAP",
-                    key: "gapMs",
-                    format: (v) => typeof v === "number" && v >= STEP_GAP_THRESHOLD_MS
-                        ? chalk.yellow(formatDuration(v))
-                        : chalk.dim("-"),
-                },
-                { header: "DURATION", key: "displayDurationMs", format: formatDuration },
-                {
-                    header: "TOKENS",
-                    key: "totalTokens",
-                    format: (v) => v ? String(v).replace(/\B(?=(\d{3})+(?!\d))/g, ",") : "-",
-                },
-                {
-                    header: "ERROR",
-                    key: "error",
-                    format: (v) => v ? (v.length > 60 ? v.slice(0, 57) + "..." : v) : "",
-                },
-            ]));
+            console.log(renderStepRunTable(items));
         }
         catch (err) {
             error(err.message);
@@ -1617,7 +1537,7 @@ Reclaiming the key means hard-deleting the row and its cascade:
         try {
             const { items } = await client.listIterations(resolvedAppId);
             if (options.json) {
-                json(items);
+                json(wholeListEnvelope(items));
                 return;
             }
             if (!items || items.length === 0) {
@@ -1735,7 +1655,7 @@ activeConfigName in workflows/<key>.toml, then run 'primitive config push'.
         try {
             const { items } = await client.listWorkflowConfigs(resolvedAppId, workflowId);
             if (options.json) {
-                json(items);
+                json(wholeListEnvelope(items));
                 return;
             }
             if (!items || items.length === 0) {
@@ -1809,29 +1729,44 @@ Test cases are authored in TOML at workflows/<key>.tests/<name>.toml and applied
 with \`primitive config push\` (issue #2769); \`config fields workflow\` lists the
 fields. Deleting a case is removing its file and running \`config push --prune\`.
 
+Every verb here takes the workflow's KEY or its ID (#3249). An identifier
+that names no workflow in the app fails; "No test cases found." only ever
+means the workflow exists and has no cases.
+
 Examples:
-  $ primitive workflows tests list <workflow-id>
-  $ primitive workflows tests run <workflow-id> <test-case-id>
-  $ primitive workflows tests run-all <workflow-id>
-  $ primitive workflows tests run-all <workflow-id> --test-cases 01ABC,01DEF,01GHI
+  $ primitive workflows tests list <workflow>
+  $ primitive workflows tests run <workflow> <test-case-id>
+  $ primitive workflows tests run-all <workflow>
+  $ primitive workflows tests run-all <workflow> --test-cases 01ABC,01DEF,01GHI
 `);
     tests
         .command("list")
         .description("List test cases for a workflow")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
         .option("--json", "Output as JSON")
-        .action(async (workflowId, options) => {
+        .action(async (workflow, options) => {
+        const limit = parsePageLimit(options.limit);
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const { items } = await client.listTestCases(resolvedAppId, "workflow", workflowId);
+            // #3249 — resolve BEFORE listing: the test-case endpoint answers an
+            // unknown block with an empty page, so an unresolved identifier would
+            // print "No test cases found." and exit 0.
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
+            const page = normalizeCliListEnvelope(await client.listTestCases(resolvedAppId, "workflow", workflowId, {
+                limit,
+                cursor: options.cursor,
+            }));
+            const items = page.items;
             if (options.json) {
-                json(items);
+                json(page);
                 return;
             }
-            if (!items || items.length === 0) {
-                info("No test cases found.");
+            if (items.length === 0) {
+                printEmptyPage(page, "test cases");
                 return;
             }
             console.log(formatTable(items, [
@@ -1839,6 +1774,7 @@ Examples:
                 { header: "NAME", key: "name" },
                 { header: "CREATED", key: "createdAt", format: formatDate },
             ]));
+            printPageHint(page);
         }
         catch (err) {
             error(err.message);
@@ -1849,14 +1785,15 @@ Examples:
     tests
         .command("get")
         .description("Get test case details")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .argument("<test-case-id>", "Test Case ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, testCaseId, options) => {
+        .action(async (workflow, testCaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             const result = await client.getTestCase(resolvedAppId, "workflow", workflowId, testCaseId);
             if (options.json) {
                 json(result);
@@ -1916,23 +1853,21 @@ Examples:
     tests
         .command("run")
         .description("Run a single test case")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .argument("<test-case-id>", "Test Case ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, testCaseId, options) => {
+        .action(async (workflow, testCaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             // Get test case to retrieve its variables
             const testCase = await client.getTestCase(resolvedAppId, "workflow", workflowId, testCaseId);
-            let variables = {};
-            try {
-                variables = JSON.parse(testCase.inputVariables || "{}");
-            }
-            catch {
-                // Use empty object if parsing fails
-            }
+            // #3158 — the case's stored input IS the run's input, and the server
+            // hands it back parsed; `JSON.parse` on that object threw and the run
+            // went ahead with `{}`, disagreeing with `run-all` over the same case.
+            const variables = requireTestCaseInputVariables(testCase.inputVariables, testCaseId);
             const result = await client.executeBlockTest(resolvedAppId, "workflow", workflowId, {
                 variables,
                 testCaseId,
@@ -1985,14 +1920,17 @@ Examples:
     tests
         .command("run-all")
         .description("Run all test cases for a workflow, or a specific subset")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--test-cases <ids>", "Comma-separated list of test case IDs to run (runs only these)")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, options) => {
+        .action(async (workflow, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            // #3249 — resolve first, so `Total Tests: 0` can only ever mean the
+            // workflow exists and has no cases, never that the identifier was wrong.
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             // Parse test case IDs if provided
             let testCaseIds;
             if (options.testCases) {
@@ -2049,15 +1987,16 @@ Examples:
     tests
         .command("runs")
         .description("List recent test runs for a workflow")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--limit <n>", "Maximum number of runs to show", "20")
         .option("--group <group>", "Filter by comparison group")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, options) => {
+        .action(async (workflow, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             const { items } = await client.listTestRuns(resolvedAppId, "workflow", workflowId, {
                 limit: parseInt(options.limit),
                 comparisonGroup: options.group,
@@ -2099,23 +2038,24 @@ Examples:
         .description("Run tests in parallel using workflow-based execution")
         .addHelpText("after", `
 Examples:
-  $ primitive workflows tests batch start <workflow-id>
-  $ primitive workflows tests batch start <workflow-id> --test-cases 01ABC,01DEF
-  $ primitive workflows tests batch status <workflow-id> <batch-id>
-  $ primitive workflows tests batch cancel <workflow-id> <batch-id>
+  $ primitive workflows tests batch start <workflow>
+  $ primitive workflows tests batch start <workflow> --test-cases 01ABC,01DEF
+  $ primitive workflows tests batch status <workflow> <batch-id>
+  $ primitive workflows tests batch cancel <workflow> <batch-id>
 `);
     // Start batch tests
     batch
         .command("start")
         .description("Start parallel batch test execution")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--test-cases <ids>", "Comma-separated list of test case IDs to run")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, options) => {
+        .action(async (workflow, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             let testCaseIds;
             if (options.testCases) {
                 testCaseIds = options.testCases.split(",").map((id) => id.trim()).filter(Boolean);
@@ -2151,15 +2091,16 @@ Examples:
     batch
         .command("status")
         .description("Get status of a batch test execution")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .argument("<batch-id>", "Batch ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--wait", "Wait for completion (polls every 2 seconds)")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, batchId, options) => {
+        .action(async (workflow, batchId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             const fetchStatus = async () => {
                 return client.getBatchTestStatus(resolvedAppId, "workflow", workflowId, batchId);
             };
@@ -2216,12 +2157,12 @@ Examples:
     batch
         .command("cancel")
         .description("Cancel a running batch test execution")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .argument("<batch-id>", "Batch ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, batchId, options) => {
+        .action(async (workflow, batchId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
             let confirm;
@@ -2239,6 +2180,7 @@ Examples:
         }
         const client = new ApiClient();
         try {
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             // First get current status to get instance IDs
             const status = await client.getBatchTestStatus(resolvedAppId, "workflow", workflowId, batchId);
             // Get instance IDs that are still running
@@ -2278,24 +2220,25 @@ with \`primitive config push\` (#2769); removing one and running
 \`config push --prune\` deletes it server-side. These verbs read server state.
 
 Examples:
-  $ primitive workflows tests attachments list <workflow-id> <test-case-id>
-  $ primitive workflows tests attachments download <workflow-id> <test-case-id> document.pdf
+  $ primitive workflows tests attachments list <workflow> <test-case-id>
+  $ primitive workflows tests attachments download <workflow> <test-case-id> document.pdf
 `);
     // List attachments
     attachments
         .command("list")
         .description("List attachments for a test case")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .argument("<test-case-id>", "Test Case ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, testCaseId, options) => {
+        .action(async (workflow, testCaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             const result = await client.listTestCaseAttachments(resolvedAppId, "workflow", workflowId, testCaseId);
             if (options.json) {
-                json(result.attachments);
+                json(wholeListEnvelope(result.attachments));
                 return;
             }
             if (!result.attachments || result.attachments.length === 0) {
@@ -2321,15 +2264,16 @@ Examples:
     attachments
         .command("download")
         .description("Download a file attachment from a test case")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow>", "Workflow key or ID")
         .argument("<test-case-id>", "Test Case ID")
         .argument("<filename>", "Name of the file to download")
         .argument("[output-path]", "Output path (defaults to current directory)")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .action(async (workflowId, testCaseId, filename, outputPath, options) => {
+        .action(async (workflow, testCaseId, filename, outputPath, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const workflowId = await resolveWorkflowId(client, resolvedAppId, workflow);
             const result = await client.downloadTestCaseAttachment(resolvedAppId, "workflow", workflowId, testCaseId, filename);
             const finalPath = outputPath || filename;
             writeFileSync(finalPath, result.data);
@@ -2349,9 +2293,6 @@ Examples:
         .command("codegen")
         .description("Generate typed client signatures from the local workflows/*.toml schemas. TypeScript (default): one <key>.generated.ts per workflow (<Key>Input/<Key>Output types + a <key>(client) invoker factory). Swift (--lang swift): one <key>.generated.swift per workflow (<Key>Input/<Key>Output Codable types).\n\nFormatting: the emitted TypeScript is already formatted the way Prettier's DEFAULT config formats it, so a `codegen` -> `prettier --write` -> `codegen --check` pipeline stays green. If your project uses a NON-default Prettier config (a different printWidth, trailingComma, or quote style), Prettier will reformat the generated files and `--check` will then fail: add the generated directory to `.prettierignore` and commit the raw emission instead.")
         .argument("[workflow-key]", "Generate for a single workflow (defaults to every workflows/*.toml found)")
-        .option("--app <app-id>", "App ID")
-        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
-        .addOption(new Option("--sync-dir <path>", "Deprecated alias of --dir").hideHelp())
         .option("-o, --output <dir>", "Output directory for the generated files (defaults to <config-dir>/workflows/generated/)")
         .option("--lang <lang>", "Target language for the generated types: 'ts' (default) or 'swift'.", "ts")
         .option("--check", "Exit non-zero if generated output is out of date (CI guard); does not write. Compares byte-for-byte, so the file on disk must match the emission exactly.")
@@ -2365,17 +2306,10 @@ Examples:
                 error(`Unknown --lang "${options.lang}". Use "ts" or "swift".`);
                 process.exit(1);
             }
-            // 1. Resolve the single source workflows/ directory via the shared
-            //    active-environment resolver (issue #1510). Honors --dir /
-            //    --app overrides, resolves the active env
-            //    (--env → PRIMITIVE_ENV → defaultEnvironment → single-env), and
-            //    preserves the legacy per-app scan fallback in bare-dir mode.
+            // 1. The single source workflows/ directory: the environment's, and
+            //    only ever the environment's (#1510, #3154).
             const workflowsSourceDir = resolveCodegenSourceDir({
                 subdir: "workflows",
-                options: {
-                    app: options.app,
-                    syncDir: resolveSyncDirOverride(options, "workflows codegen"),
-                },
             });
             // 2. Collect the source .toml files (one per workflow), filtered to a
             //    single workflow when an argument is given. Match on the file stem;
@@ -2396,7 +2330,7 @@ Examples:
             }
             if (inputs.length === 0) {
                 error(workflowKey
-                    ? `No workflows/${workflowKey}.toml found under .primitive/sync/.`
+                    ? `No workflows/${workflowKey}.toml found under primitive/<env>/.`
                     : "No workflows/*.toml files found to generate from.");
                 process.exit(1);
             }