primitive-admin 1.0.43 → 1.0.45

package/dist/src/commands/workflows.js

@@ -4,8 +4,87 @@ import * as TOML from "@iarna/toml";
 import { lookup as mimeLookup } from "mime-types";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
+import { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
+import { expandWorkflow } from "../lib/workflow-fragments.js";
 import chalk from "chalk";
-import { success, error, info, warn, keyValue, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, } from "../lib/output.js";
+import { success, error, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, progress, progressEnd, } from "../lib/output.js";
+/**
+ * Render the `Step Results` section of `workflows runs status`. Pure
+ * formatting helper — returns lines as strings so it's unit-testable
+ * (the caller console.logs them). For each step, emits:
+ *
+ *   `  <id>: <status-label> <duration>`
+ *
+ * and, when applicable, indented follow-up lines:
+ *
+ * - `error_captured` step with `error` → `    error: <truncated message>`
+ * - forEach output with `errors[]` non-empty →
+ *   `    forEach errors: <N/M> - first: <truncated message>`
+ *
+ * The truncation length matches `runs steps` ERROR column (80 chars,
+ * trailing "..." when truncated). See #688.
+ */
+export function renderRunStatusStepResults(stepResults) {
+    const lines = [];
+    for (const step of stepResults || []) {
+        const statusLabel = step.skipped
+            ? chalk.gray("skipped")
+            : step.status === "error_captured"
+                ? chalk.yellow("error_captured")
+                : step.status === "failed"
+                    ? chalk.red("failed")
+                    : step.status === "completed"
+                        ? chalk.green("completed")
+                        : step.status || "?";
+        const durationLabel = formatDuration(step.durationMs);
+        lines.push(`  ${step.id}: ${statusLabel} ${durationLabel}`);
+        // Single-step error_captured: show the captured error message.
+        if (step.status === "error_captured" && step.error) {
+            const errMsg = typeof step.error === "string" ? step.error : String(step.error);
+            const truncated = errMsg.length > 80 ? errMsg.slice(0, 77) + "..." : errMsg;
+            lines.push(`    ${chalk.dim("error:")} ${chalk.yellow(truncated)}`);
+        }
+        else if (step.status === "error_captured" && step.errorDetails) {
+            // No top-level error but errorDetails present — hint to drill in.
+            lines.push(`    ${chalk.dim("error: <see runs step-detail for full errorDetails>")}`);
+        }
+        // forEach aggregated errors: a one-line summary surfaces the count
+        // of `error_captured` iterations and a sample message (#688).
+        const fo = step.output;
+        if (fo && typeof fo === "object" && Array.isArray(fo.errors) && fo.errors.length > 0) {
+            const total = (Array.isArray(fo.items) ? fo.items.length : 0)
+                || (fo.totalSucceeded ?? 0) + (fo.totalFailed ?? 0);
+            const firstErr = (Array.isArray(fo.errorMessages) && fo.errorMessages.length > 0
+                ? fo.errorMessages[0]
+                : (fo.errors[0]?.error ?? "?"));
+            const firstStr = typeof firstErr === "string" ? firstErr : String(firstErr);
+            const truncated = firstStr.length > 80 ? firstStr.slice(0, 77) + "..." : firstStr;
+            lines.push(`    ${chalk.dim("forEach errors:")} ${chalk.yellow(`${fo.totalFailed ?? fo.errors.length}/${total}`)} ${chalk.dim("- first:")} ${chalk.yellow(truncated)}`);
+        }
+    }
+    return lines;
+}
+/**
+ * Issue #687 (review feedback): render an unambiguous label for a workflow
+ * config slot ("active config", "draft config", etc.) when the slot may be
+ * unnamed. Falls back to a short ID prefix so users staging multiple unnamed
+ * configs can still tell them apart.
+ *
+ *   formatConfigSlotLabel("active config", "v2", "01KRT...")        → 'active config "v2"'
+ *   formatConfigSlotLabel("active config", null, "01KRTABCDXYZ...") → 'active config (01KRTABCDXYZ…)'
+ *   formatConfigSlotLabel("active config", null, null)              → 'active config'
+ *
+ * Exported for testability.
+ */
+export function formatConfigSlotLabel(slot, configName, configId, prefixLength = 12) {
+    if (configName) {
+        return `${slot} "${configName}"`;
+    }
+    if (configId) {
+        return `${slot} (${String(configId).slice(0, prefixLength)}…)`;
+    }
+    return slot;
+}
 export function registerWorkflowsCommands(program) {
     const workflows = program
         .command("workflows")
@@ -70,30 +149,41 @@ Examples:
         const client = new ApiClient();
         let payload;
         if (options.fromFile) {
+            let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                const workflow = tomlData.workflow || tomlData;
-                payload = {
-                    workflowKey: workflow.key || workflow.workflowKey,
-                    name: workflow.name,
-                    description: workflow.description,
-                    steps: tomlData.steps || [],
-                    inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
-                    outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
-                    perUserMaxRunning: workflow.perUserMaxRunning,
-                    perUserMaxQueued: workflow.perUserMaxQueued,
-                    perAppMaxRunning: workflow.perAppMaxRunning,
-                    perAppMaxQueued: workflow.perAppMaxQueued,
-                    queueTtlSeconds: workflow.queueTtlSeconds,
-                    dequeueOrder: workflow.dequeueOrder,
-                    requiresClientApply: workflow.requiresClientApply,
-                };
+                tomlData = TOML.parse(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
                 process.exit(1);
             }
+            // Issue #685: reject misnested headers (e.g. [steps.<id>.request])
+            // before we send anything to the server. These parse to TOML
+            // sub-tables that the runtime silently ignores. We validate
+            // outside the parse try-block so the diagnostic isn't masked by
+            // the generic "Failed to read TOML" handler.
+            const tomlErrors = validateWorkflowToml(tomlData);
+            if (tomlErrors.length > 0) {
+                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+                process.exit(1);
+            }
+            const workflow = tomlData.workflow || tomlData;
+            payload = {
+                workflowKey: workflow.key || workflow.workflowKey,
+                name: workflow.name,
+                description: workflow.description,
+                steps: tomlData.steps || [],
+                inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
+                outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
+                perUserMaxRunning: workflow.perUserMaxRunning,
+                perUserMaxQueued: workflow.perUserMaxQueued,
+                perAppMaxRunning: workflow.perAppMaxRunning,
+                perAppMaxQueued: workflow.perAppMaxQueued,
+                queueTtlSeconds: workflow.queueTtlSeconds,
+                dequeueOrder: workflow.dequeueOrder,
+                requiresClientApply: workflow.requiresClientApply,
+            };
         }
         else {
             if (!options.key || !options.name) {
@@ -142,23 +232,23 @@ Examples:
                 return;
             }
             const wf = result.workflow;
-            keyValue("Workflow ID", wf.workflowId);
-            keyValue("Key", wf.workflowKey);
-            keyValue("Name", wf.name);
-            keyValue("Description", wf.description);
-            keyValue("Status", formatStatus(wf.status));
-            keyValue("Active Config", wf.activeConfigId || "-");
-            keyValue("Latest Revision", wf.latestRevision || "-");
-            keyValue("Client Apply", wf.requiresClientApply !== false ? "yes" : "no");
+            printResult("Workflow ID", wf.workflowId);
+            printResult("Key", wf.workflowKey);
+            printResult("Name", wf.name);
+            printResult("Description", wf.description);
+            printResult("Status", formatStatus(wf.status));
+            printResult("Active Config", wf.activeConfigId || "-");
+            printResult("Latest Revision", wf.latestRevision || "-");
+            printResult("Client Apply", wf.requiresClientApply !== false ? "yes" : "no");
             if (wf.accessRule) {
-                keyValue("Access Rule", wf.accessRule);
+                printResult("Access Rule", wf.accessRule);
             }
             divider();
             info("Queue Settings:");
-            keyValue("  Per User Max Running", wf.perUserMaxRunning);
-            keyValue("  Per User Max Queued", wf.perUserMaxQueued);
-            keyValue("  Per App Max Running", wf.perAppMaxRunning);
-            keyValue("  Dequeue Order", wf.dequeueOrder);
+            printResult("  Per User Max Running", wf.perUserMaxRunning);
+            printResult("  Per User Max Queued", wf.perUserMaxQueued);
+            printResult("  Per App Max Running", wf.perAppMaxRunning);
+            printResult("  Dequeue Order", wf.dequeueOrder);
             if (wf.inputSchema) {
                 divider();
                 info("Input Schema:");
@@ -291,12 +381,39 @@ Examples:
             process.exit(1);
         }
     });
+    // Expand a workflow TOML and print the result (no server contact).
+    //
+    // Authors use this to inspect what `include = [...]` fragments produce
+    // before pushing. Surfaces include-collision and unique-id failures with
+    // helpful messages without going through `sync push`.
+    workflows
+        .command("expand")
+        .description("Expand a workflow TOML's include fragments and print the result")
+        .argument("<file>", "Path to the workflow TOML file")
+        .option("--format <format>", "Output format: json (default) or toml", "json")
+        .action((file, options) => {
+        try {
+            const expanded = expandWorkflow(file);
+            if (options.format === "toml") {
+                // Strip the `include` key (already removed by expander) and emit
+                // valid TOML so the result is round-trippable.
+                console.log(TOML.stringify(expanded));
+            }
+            else {
+                console.log(JSON.stringify(expanded, null, 2));
+            }
+        }
+        catch (err) {
+            error(err?.message ?? String(err));
+            process.exit(1);
+        }
+    });
     // Draft subcommand
     const draft = workflows.command("draft").description("Manage workflow draft");
     // Update draft
     draft
         .command("update")
-        .description("Update workflow draft steps")
+        .description("Update workflow draft steps (deprecated; use 'workflows configs' for staged rollouts)")
         .argument("<workflow-id>", "Workflow ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--from-file <path>", "Load steps from TOML file")
@@ -307,21 +424,27 @@ Examples:
             error("--from-file is required");
             process.exit(1);
         }
-        let payload;
+        let tomlData;
         try {
             const content = readFileSync(options.fromFile, "utf-8");
-            const tomlData = TOML.parse(content);
-            const workflow = tomlData.workflow || tomlData;
-            payload = {
-                steps: tomlData.steps || [],
-                inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
-                outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
-            };
+            tomlData = TOML.parse(content);
         }
         catch (err) {
             error(`Failed to read TOML file: ${err.message}`);
             process.exit(1);
         }
+        // Issue #685: reject misnested headers before pushing.
+        const tomlErrors = validateWorkflowToml(tomlData);
+        if (tomlErrors.length > 0) {
+            error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+            process.exit(1);
+        }
+        const workflow = tomlData.workflow || tomlData;
+        const payload = {
+            steps: tomlData.steps || [],
+            inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
+            outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
+        };
         const client = new ApiClient();
         try {
             const result = await client.updateWorkflowDraft(resolvedAppId, workflowId, payload);
@@ -331,6 +454,10 @@ Examples:
             }
             success("Draft updated.");
             keyValue("Steps", result.draft?.steps?.length || 0);
+            // Issue #687: surface server-side deprecation hint when applicable.
+            if (result.deprecation) {
+                warn(`[deprecated] ${result.deprecation}`);
+            }
         }
         catch (err) {
             error(err.message);
@@ -340,7 +467,7 @@ Examples:
     // Publish workflow
     workflows
         .command("publish")
-        .description("Publish the current draft as a new revision")
+        .description("Publish the current draft as a new revision (deprecated for new-model workflows; use 'workflows configs activate')")
         .argument("<workflow-id>", "Workflow ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
@@ -356,6 +483,10 @@ Examples:
             success("Workflow published.");
             keyValue("Revision ID", result.revision?.revisionId);
             keyValue("Published At", formatDate(result.revision?.publishedAt));
+            // Issue #687: surface server-side deprecation hint when applicable.
+            if (result.deprecation) {
+                warn(`[deprecated] ${result.deprecation}`);
+            }
         }
         catch (err) {
             error(err.message);
@@ -369,12 +500,17 @@ Examples:
         .argument("<workflow-id>", "Workflow ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--config <config-id>", "Use specific configuration")
-        .option("--draft", "Preview the draft version instead of the active config")
+        .option("--draft", "Force preview of the draft version, even if active is newer")
+        .option("--active", "Force preview of the active config, even if a newer draft exists (issue #687)")
         .option("--input <json>", "Root input as JSON")
         .option("--wait", "Wait for completion and show result")
         .option("--json", "Output as JSON")
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        if (options.draft && options.active) {
+            error("--draft and --active are mutually exclusive");
+            process.exit(1);
+        }
         let rootInput;
         if (options.input) {
             try {
@@ -391,8 +527,11 @@ Examples:
                 rootInput,
                 configId: options.config,
                 useDraft: options.draft || false,
+                // Issue #687: --active forces the active config even when a newer
+                // draft exists (the inverse of --draft).
+                preferActive: options.active || false,
             });
-            // Display warning if draft differs from active
+            // Display warning from the server (e.g. "previewing draft because newer than active")
             if (result.warning) {
                 warn(result.warning);
             }
@@ -403,9 +542,23 @@ Examples:
                 }
                 success("Preview started.");
                 keyValue("Instance ID", result.instanceId);
-                if (result.usingDraft) {
+                // Issue #687: name the side we ran so the user always knows which
+                // version produced the output (the "print the source" pattern).
+                const source = result.source;
+                if (source === "draft") {
                     info("Previewing draft version.");
                 }
+                else if (source === "active") {
+                    // Issue #687 (review feedback): when configName is missing,
+                    // fall back to a short ID prefix so users staging multiple
+                    // unnamed configs can disambiguate.
+                    const label = formatConfigSlotLabel("active config", result.configName, result.configId);
+                    info(`Previewing ${label}.`);
+                }
+                else if (source === "config") {
+                    const label = formatConfigSlotLabel("the requested config", result.configName, result.configId);
+                    info(`Previewing ${label}.`);
+                }
                 info("Use 'workflows runs status' to check progress.");
                 return;
             }
@@ -529,9 +682,9 @@ Examples:
                 if (status.stepResults && status.stepResults.length > 0) {
                     divider();
                     info("Step Results:");
-                    status.stepResults.forEach((step) => {
-                        console.log(`  ${step.id}: ${formatDuration(step.durationMs)} ${step.skipped ? "(skipped)" : ""}`);
-                    });
+                    for (const line of renderRunStatusStepResults(status.stepResults)) {
+                        console.log(line);
+                    }
                 }
                 if (status.error) {
                     divider();
@@ -675,6 +828,48 @@ Examples:
             process.exit(1);
         }
     });
+    // Integration call logs for a run (cross-pivot from workflow-run to
+    // integrations.logs — see issue #699).
+    runs
+        .command("logs")
+        .description("List integration calls made by a specific workflow run (cross-pivot of `integrations logs`)")
+        .argument("<run-id>", "Workflow run ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--limit <n>", "Number of logs to show", "100")
+        .option("--json", "Output as JSON")
+        .action(async (runId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const logs = await client.listWorkflowRunIntegrationLogs(resolvedAppId, runId, { limit: parseInt(options.limit) });
+            if (options.json) {
+                json(logs);
+                return;
+            }
+            if (!logs || logs.length === 0) {
+                info("No integration calls found for this run.");
+                return;
+            }
+            console.log(formatTable(logs, [
+                { header: "TIME", key: "timestamp", format: formatDate },
+                { header: "STEP", key: "stepId", format: (v) => v || "" },
+                {
+                    header: "INTEGRATION",
+                    key: "integrationKey",
+                    format: (v) => v || "",
+                },
+                { header: "METHOD", key: "method" },
+                { header: "PATH", key: "path" },
+                { header: "STATUS", key: "status" },
+                { header: "DURATION", key: "durationMs", format: formatDuration },
+                { header: "TRACE", key: "traceId", format: formatId },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // Error summary
     runs
         .command("error")
@@ -925,12 +1120,12 @@ Examples:
                 json(config);
                 return;
             }
-            keyValue("Config ID", config.configId);
-            keyValue("Name", config.configName);
-            keyValue("Description", config.description || "-");
-            keyValue("Status", formatStatus(config.status));
-            keyValue("Created", formatDate(config.createdAt));
-            keyValue("Modified", formatDate(config.modifiedAt));
+            printResult("Config ID", config.configId);
+            printResult("Name", config.configName);
+            printResult("Description", config.description || "-");
+            printResult("Status", formatStatus(config.status));
+            printResult("Created", formatDate(config.createdAt));
+            printResult("Modified", formatDate(config.modifiedAt));
             if (config.steps && config.steps.length > 0) {
                 divider();
                 info(`Steps (${config.steps.length}):`);
@@ -962,15 +1157,22 @@ Examples:
         }
         let steps = [];
         if (options.fromFile) {
+            let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                steps = tomlData.steps || [];
+                tomlData = TOML.parse(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
                 process.exit(1);
             }
+            // Issue #685: reject misnested headers before pushing.
+            const tomlErrors = validateWorkflowToml(tomlData);
+            if (tomlErrors.length > 0) {
+                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+                process.exit(1);
+            }
+            steps = tomlData.steps || [];
         }
         const client = new ApiClient();
         try {
@@ -1010,15 +1212,22 @@ Examples:
         if (options.description !== undefined)
             payload.description = options.description;
         if (options.fromFile) {
+            let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                payload.steps = tomlData.steps || [];
+                tomlData = TOML.parse(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
                 process.exit(1);
             }
+            // Issue #685: reject misnested headers before pushing.
+            const tomlErrors = validateWorkflowToml(tomlData);
+            if (tomlErrors.length > 0) {
+                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+                process.exit(1);
+            }
+            payload.steps = tomlData.steps || [];
         }
         if (Object.keys(payload).length === 0) {
             error("No update options specified. Use --name, --description, or --from-file.");
@@ -1257,9 +1466,9 @@ Examples:
                 json(result);
                 return;
             }
-            keyValue("Test Case ID", result.testCaseId);
-            keyValue("Name", result.name);
-            keyValue("Created", formatDate(result.createdAt));
+            printResult("Test Case ID", result.testCaseId);
+            printResult("Name", result.name);
+            printResult("Created", formatDate(result.createdAt));
             divider();
             info("Input Variables:");
             try {
@@ -1273,7 +1482,7 @@ Examples:
             }
             if (result.expectedOutputPattern) {
                 divider();
-                keyValue("Expected Pattern", result.expectedOutputPattern);
+                printResult("Expected Pattern", result.expectedOutputPattern);
             }
             if (result.expectedOutputContains) {
                 divider();
@@ -1677,9 +1886,10 @@ Examples:
                 while (result.status === "running") {
                     await new Promise((r) => setTimeout(r, 2000));
                     result = await fetchStatus();
-                    process.stdout.write(`\r  Completed: ${result.completed}/${result.results?.length || 0}  `);
+                    // Progress goes to stderr so it can't corrupt JSON on stdout under --json.
+                    progress(`  Completed: ${result.completed}/${result.results?.length || 0}  `);
                 }
-                console.log();
+                progressEnd();
             }
             if (options.json) {
                 json(result);