primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.41

package/dist/src/lib/workflow-apply.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared "apply a TOML body to an existing workflow" helper.
+ *
+ * Extracted from the `sync push` update-existing path (#1249, Fork 4) so that
+ * both `sync push` and `workflows update --from-file` push a revised body the
+ * same way. A second inlined copy would regress #807: the update is
+ * ordering-sensitive and a naive metadata-then-body sequence rejects valid
+ * sync-callable edits.
+ *
+ * Ordering invariant (#807 / codex review):
+ *   1. metadata PATCH — WITHOUT `syncCallable`. The server re-validates
+ *      `syncCallable: true` against the workflow's CURRENTLY-active server
+ *      steps (`loadCurrentActiveSteps`, src/admin-api.ts:4734), not the steps
+ *      being pushed in the same call. So enabling sync-callable in the first
+ *      PATCH would validate against the stale active steps and be rejected.
+ *   2. body write — steps to the active config (config-model) or the legacy
+ *      draft slot (no active config).
+ *   3. a SECOND `syncCallable` PATCH — issued AFTER the new steps are active,
+ *      so it validates against the new (compatible) steps.
+ */
+import type { ApiClient } from "./api-client.js";
+/**
+ * Safely parse a JSON field that may be a string or already an object. TOML can
+ * parse inline tables as objects, so we accept both. (Same semantics as the
+ * `safeJsonParse` in sync.ts — kept here so the shared apply helper owns its
+ * own parse decision without importing back into a command module.)
+ */
+export declare function safeJsonParse(value: any): any;
+export interface ApplyWorkflowBodyOptions {
+    /** Optimistic-concurrency guard for the metadata + syncCallable PATCHes. */
+    expectedModifiedAt?: string;
+    /**
+     * Active config to overwrite in place (config-model workflows). When absent,
+     * the body falls back to the legacy draft slot — non-live for config-model
+     * workflows, which the server rejects with 409 WORKFLOW_CONFIG_MODEL.
+     */
+    activeConfigId?: string;
+    /** When true, skip the optimistic-concurrency check (mirrors `--force`). */
+    force?: boolean;
+}
+export interface ApplyWorkflowBodyResult {
+    /** The freshest workflow `modifiedAt` after all PATCHes (for sync state). */
+    latestModifiedAt?: string;
+    /** Which slot the steps landed in: "active config" or "draft (legacy)". */
+    updateSlotLabel: string;
+    /** A fresh `getWorkflow` result so callers can read back configs/state. */
+    fullWorkflow: any;
+}
+/**
+ * Apply a parsed workflow body (metadata + steps) to an existing workflow,
+ * preserving the key/id. `workflow` is the TOML's `[workflow]` table (already
+ * merged with any explicit CLI flag overrides by the caller); `steps` is the
+ * TOML's `steps` array. The function performs the three-step ordered update
+ * and returns the latest `modifiedAt`, the slot label, and a fresh workflow.
+ */
+export declare function applyWorkflowBody(client: ApiClient, appId: string, workflowId: string, workflow: any, steps: any[], opts?: ApplyWorkflowBodyOptions): Promise<ApplyWorkflowBodyResult>;
+/**
+ * Fork 2 (#1249): a TOML pushed at a specific `<id>` may also declare a `key` /
+ * `workflowKey`. If it differs from the target's actual key, that's almost
+ * certainly the wrong file — error rather than silently ignoring it. An absent
+ * TOML key is advisory and allowed (the operation targets `<id>`).
+ *
+ * Returns an error message string when there is a mismatch, otherwise null.
+ * Pure function for unit testing.
+ */
+export declare function workflowKeyMismatchError(tomlWorkflow: any, existingWorkflowKey: string | undefined): string | null;

package/dist/src/lib/workflow-apply.js

@@ -0,0 +1,117 @@
+/**
+ * Shared "apply a TOML body to an existing workflow" helper.
+ *
+ * Extracted from the `sync push` update-existing path (#1249, Fork 4) so that
+ * both `sync push` and `workflows update --from-file` push a revised body the
+ * same way. A second inlined copy would regress #807: the update is
+ * ordering-sensitive and a naive metadata-then-body sequence rejects valid
+ * sync-callable edits.
+ *
+ * Ordering invariant (#807 / codex review):
+ *   1. metadata PATCH — WITHOUT `syncCallable`. The server re-validates
+ *      `syncCallable: true` against the workflow's CURRENTLY-active server
+ *      steps (`loadCurrentActiveSteps`, src/admin-api.ts:4734), not the steps
+ *      being pushed in the same call. So enabling sync-callable in the first
+ *      PATCH would validate against the stale active steps and be rejected.
+ *   2. body write — steps to the active config (config-model) or the legacy
+ *      draft slot (no active config).
+ *   3. a SECOND `syncCallable` PATCH — issued AFTER the new steps are active,
+ *      so it validates against the new (compatible) steps.
+ */
+/**
+ * Safely parse a JSON field that may be a string or already an object. TOML can
+ * parse inline tables as objects, so we accept both. (Same semantics as the
+ * `safeJsonParse` in sync.ts — kept here so the shared apply helper owns its
+ * own parse decision without importing back into a command module.)
+ */
+export function safeJsonParse(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return JSON.parse(value);
+    return value; // Already an object (TOML parsed it as a table)
+}
+/**
+ * Apply a parsed workflow body (metadata + steps) to an existing workflow,
+ * preserving the key/id. `workflow` is the TOML's `[workflow]` table (already
+ * merged with any explicit CLI flag overrides by the caller); `steps` is the
+ * TOML's `steps` array. The function performs the three-step ordered update
+ * and returns the latest `modifiedAt`, the slot label, and a fresh workflow.
+ */
+export async function applyWorkflowBody(client, appId, workflowId, workflow, steps, opts = {}) {
+    const { expectedModifiedAt, activeConfigId, force } = opts;
+    // 1. Metadata PATCH — note: NO `syncCallable` here (deferred to step 3).
+    //    `requiresClientApply` has no step-dependent validation, so it stays.
+    const updated = await client.updateWorkflow(appId, workflowId, {
+        name: workflow.name,
+        description: workflow.description,
+        status: workflow.status,
+        accessRule: workflow.accessRule !== undefined ? workflow.accessRule || null : undefined,
+        // #1081 — workflow principal mode. Absent key → undefined (server leaves
+        // it untouched); explicit value/empty is forwarded so it round-trips.
+        runAs: workflow.runAs !== undefined ? workflow.runAs || null : undefined,
+        // #1233 — opt-in capability grants. Absent key → undefined (server's
+        // hasOwnProperty guard leaves it untouched); an explicit array is
+        // forwarded so a pull → push round-trips it. Mirrors `runAs` above so
+        // both `sync push` and `workflows update --from-file` apply it the same.
+        capabilities: workflow.capabilities !== undefined ? workflow.capabilities : undefined,
+        perUserMaxRunning: workflow.perUserMaxRunning,
+        perUserMaxQueued: workflow.perUserMaxQueued,
+        dequeueOrder: workflow.dequeueOrder,
+        requiresClientApply: workflow.requiresClientApply,
+        inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
+        outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : null,
+        // #1304 (P-C): declared-access manifest. Absent key → undefined (server's
+        // hasOwnProperty guard leaves it untouched); a parsed value/null is
+        // forwarded so a pull → push round-trips it (null clears). `sync push`
+        // always attaches this (null when the TOML drops `[metadata]`); the
+        // `workflows update --from-file` caller may leave it undefined.
+        metadataManifest: workflow.metadataManifest !== undefined ? workflow.metadataManifest : undefined,
+    }, expectedModifiedAt);
+    // The first PATCH bumps `modifiedAt`; the syncCallable PATCH (if any) bumps
+    // it again. The config/step update does NOT touch the workflow definition's
+    // `modifiedAt`.
+    let latestModifiedAt = updated?.workflow?.modifiedAt;
+    // 2. Body write — active config (config-model) or legacy draft slot.
+    let updateSlotLabel = "active config";
+    if (activeConfigId) {
+        await client.updateWorkflowConfig(appId, workflowId, activeConfigId, { steps });
+    }
+    else {
+        await client.updateWorkflowDraft(appId, workflowId, {
+            steps,
+            inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
+        });
+        updateSlotLabel = "draft (legacy)";
+    }
+    // 3. Deferred `syncCallable` PATCH — now that the new steps are active (#807).
+    //    Only sent when the TOML actually carries the key; an absent key stays
+    //    `undefined` and the call is skipped, preserving no-clobber discipline.
+    if (workflow.syncCallable !== undefined) {
+        const syncCallableUpdated = await client.updateWorkflow(appId, workflowId, { syncCallable: workflow.syncCallable }, force ? undefined : latestModifiedAt);
+        if (syncCallableUpdated?.workflow?.modifiedAt) {
+            latestModifiedAt = syncCallableUpdated.workflow.modifiedAt;
+        }
+    }
+    const fullWorkflow = await client.getWorkflow(appId, workflowId);
+    return { latestModifiedAt, updateSlotLabel, fullWorkflow };
+}
+/**
+ * Fork 2 (#1249): a TOML pushed at a specific `<id>` may also declare a `key` /
+ * `workflowKey`. If it differs from the target's actual key, that's almost
+ * certainly the wrong file — error rather than silently ignoring it. An absent
+ * TOML key is advisory and allowed (the operation targets `<id>`).
+ *
+ * Returns an error message string when there is a mismatch, otherwise null.
+ * Pure function for unit testing.
+ */
+export function workflowKeyMismatchError(tomlWorkflow, existingWorkflowKey) {
+    const tomlKey = tomlWorkflow?.key ?? tomlWorkflow?.workflowKey;
+    if (tomlKey && existingWorkflowKey && tomlKey !== existingWorkflowKey) {
+        return (`TOML workflow key "${tomlKey}" does not match the target workflow's key ` +
+            `"${existingWorkflowKey}". This usually means you pointed --from-file at the ` +
+            `wrong workflow id. Remove the key from the TOML or target the matching id.`);
+    }
+    return null;
+}
+//# sourceMappingURL=workflow-apply.js.map

package/dist/src/lib/workflow-apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-apply.js","sourceRoot":"","sources":["../../../src/lib/workflow-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAU;IACtC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,KAAK,CAAC,CAAC,gDAAgD;AAChE,CAAC;AAwBD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAiB,EACjB,KAAa,EACb,UAAkB,EAClB,QAAa,EACb,KAAY,EACZ,OAAiC,EAAE;IAEnC,MAAM,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IAE3D,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,cAAc,CACzC,KAAK,EACL,UAAU,EACV;QACE,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,UAAU,EACR,QAAQ,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS;QAC7E,yEAAyE;QACzE,sEAAsE;QACtE,KAAK,EAAE,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS;QACxE,qEAAqE;QACrE,kEAAkE;QAClE,sEAAsE;QACtE,yEAAyE;QACzE,YAAY,EACV,QAAQ,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;QACzE,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;QAC7C,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;QAC3C,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,mBAAmB,EAAE,QAAQ,CAAC,mBAAmB;QACjD,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI;QAC9E,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI;QACjF,0EAA0E;QAC1E,oEAAoE;QACpE,uEAAuE;QACvE,oEAAoE;QACpE,gEAAgE;QAChE,gBAAgB,EACd,QAAQ,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;KAClF,EACD,kBAAkB,CACnB,CAAC;IAEF,4EAA4E;IAC5E,4EAA4E;IAC5E,gBAAgB;IAChB,IAAI,gBAAgB,GAAuB,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAC;IAEzE,qEAAqE;IACrE,IAAI,eAAe,GAAG,eAAe,CAAC;IACtC,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE;YAClD,KAAK;YACL,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI;SAC/E,CAAC,CAAC;QACH,eAAe,GAAG,gBAAgB,CAAC;IACrC,CAAC;IAED,+EAA+E;IAC/E,2EAA2E;IAC3E,4EAA4E;IAC5E,IAAI,QAAQ,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,mBAAmB,GAAG,MAAM,MAAM,CAAC,cAAc,CACrD,KAAK,EACL,UAAU,EACV,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,EACvC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CACrC,CAAC;QACF,IAAI,mBAAmB,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;YAC9C,gBAAgB,GAAG,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACjE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,YAAiB,EACjB,mBAAuC;IAEvC,MAAM,OAAO,GAAG,YAAY,EAAE,GAAG,IAAI,YAAY,EAAE,WAAW,CAAC;IAC/D,IAAI,OAAO,IAAI,mBAAmB,IAAI,OAAO,KAAK,mBAAmB,EAAE,CAAC;QACtE,OAAO,CACL,sBAAsB,OAAO,6CAA6C;YAC1E,IAAI,mBAAmB,uDAAuD;YAC9E,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/lib/workflow-fragments.d.ts

@@ -0,0 +1,41 @@
+/**
+ * CLI-only workflow fragment expansion.
+ *
+ * Workflows may declare `include = ["fragment-name", ...]` at the top of
+ * their TOML. The CLI expands those references into a fully-flattened
+ * `[[steps]]` list before push — the server never sees fragments and
+ * stores only the canonical, expanded JSON.
+ *
+ * Pinned decisions (#744):
+ *   - CLI-only. No server-side WorkflowFragment model.
+ *   - Fragments live at <workflowDir>/../workflow-fragments/<name>.toml.
+ *   - Fragment files are `[[steps]]` lists only — no `[workflow]` block.
+ *   - No recursive includes in v1 (fragments cannot themselves `include`).
+ *   - Unique step ids validated post-expansion; collisions name both
+ *     locations in the error message.
+ *
+ * Wiring: `parseTomlFile()` in `cli/src/commands/sync.ts` calls
+ * `expandWorkflowTomlData()` after parsing. All 24 push parse sites in
+ * sync.ts route through that single seam, so the expansion is uniform.
+ * The standalone `expandWorkflow(filePath)` helper backs the
+ * `primitive workflows expand` subcommand for debugging.
+ */
+export interface ExpandedWorkflow {
+    workflow?: Record<string, any>;
+    steps: Array<Record<string, any>>;
+    include?: undefined;
+    [key: string]: any;
+}
+/**
+ * Read and expand a workflow TOML file from disk. Returns the parsed
+ * TOML with all `include` fragments spliced in. If the file has no
+ * `include` key, the parsed TOML is returned unchanged.
+ */
+export declare function expandWorkflow(workflowPath: string): ExpandedWorkflow;
+/**
+ * Expand the `include` key of an already-parsed TOML object. Resolves
+ * fragment files relative to `<workflowPath>/../../workflow-fragments/`.
+ * Use this when the TOML has already been parsed elsewhere (e.g. inside
+ * `parseTomlFile()`).
+ */
+export declare function expandWorkflowTomlData(parsed: Record<string, any>, workflowPath: string): ExpandedWorkflow;

package/dist/src/lib/workflow-fragments.js

@@ -0,0 +1,121 @@
+/**
+ * CLI-only workflow fragment expansion.
+ *
+ * Workflows may declare `include = ["fragment-name", ...]` at the top of
+ * their TOML. The CLI expands those references into a fully-flattened
+ * `[[steps]]` list before push — the server never sees fragments and
+ * stores only the canonical, expanded JSON.
+ *
+ * Pinned decisions (#744):
+ *   - CLI-only. No server-side WorkflowFragment model.
+ *   - Fragments live at <workflowDir>/../workflow-fragments/<name>.toml.
+ *   - Fragment files are `[[steps]]` lists only — no `[workflow]` block.
+ *   - No recursive includes in v1 (fragments cannot themselves `include`).
+ *   - Unique step ids validated post-expansion; collisions name both
+ *     locations in the error message.
+ *
+ * Wiring: `parseTomlFile()` in `cli/src/commands/sync.ts` calls
+ * `expandWorkflowTomlData()` after parsing. All 24 push parse sites in
+ * sync.ts route through that single seam, so the expansion is uniform.
+ * The standalone `expandWorkflow(filePath)` helper backs the
+ * `primitive workflows expand` subcommand for debugging.
+ */
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, basename } from "path";
+import * as TOML from "@iarna/toml";
+/**
+ * Read and expand a workflow TOML file from disk. Returns the parsed
+ * TOML with all `include` fragments spliced in. If the file has no
+ * `include` key, the parsed TOML is returned unchanged.
+ */
+export function expandWorkflow(workflowPath) {
+    const content = readFileSync(workflowPath, "utf-8");
+    const parsed = TOML.parse(content);
+    return expandWorkflowTomlData(parsed, workflowPath);
+}
+/**
+ * Expand the `include` key of an already-parsed TOML object. Resolves
+ * fragment files relative to `<workflowPath>/../../workflow-fragments/`.
+ * Use this when the TOML has already been parsed elsewhere (e.g. inside
+ * `parseTomlFile()`).
+ */
+export function expandWorkflowTomlData(parsed, workflowPath) {
+    // Fast path: nothing to expand. Preserve the original shape exactly —
+    // including the absence of a `steps` field, since not every TOML file
+    // routed through `parseTomlFile()` represents a workflow.
+    if (!("include" in parsed)) {
+        return parsed;
+    }
+    const includeList = parsed.include;
+    if (!Array.isArray(includeList)) {
+        throw new Error(`Workflow '${workflowPath}' has an 'include' key but it is not an array. Use \`include = ["fragment-name"]\`.`);
+    }
+    // Resolve fragments directory: sibling of workflow's parent directory.
+    // E.g. workflow at  config/workflows/foo.toml
+    //      fragments at config/workflow-fragments/<name>.toml
+    const fragmentsDir = join(dirname(workflowPath), "..", "workflow-fragments");
+    const workflowOwnSteps = Array.isArray(parsed.steps)
+        ? parsed.steps
+        : [];
+    const allOriginated = [];
+    for (const fragmentName of includeList) {
+        if (typeof fragmentName !== "string" || fragmentName.length === 0) {
+            throw new Error(`Workflow '${workflowPath}' has an invalid include entry: ${JSON.stringify(fragmentName)}. Each entry must be a fragment name string.`);
+        }
+        const fragmentPath = join(fragmentsDir, `${fragmentName}.toml`);
+        const fragment = readFragmentSafely(fragmentPath, workflowPath, fragmentName);
+        for (const step of fragment.steps) {
+            allOriginated.push({ step, origin: `fragment '${fragmentName}'` });
+        }
+    }
+    for (const step of workflowOwnSteps) {
+        allOriginated.push({ step, origin: `workflow '${basename(workflowPath)}'` });
+    }
+    assertUniqueStepIds(allOriginated, workflowPath);
+    // Build the expanded object: drop `include`, replace `steps` with the
+    // concatenated list. Preserve all other top-level keys (workflow,
+    // triggers, configs, etc.) exactly as parsed.
+    const result = { ...parsed };
+    delete result.include;
+    result.steps = allOriginated.map((o) => o.step);
+    return result;
+}
+function readFragmentSafely(fragmentPath, workflowPath, fragmentName) {
+    if (!existsSync(fragmentPath)) {
+        throw new Error(`Workflow '${workflowPath}' includes fragment '${fragmentName}' but the file does not exist at '${fragmentPath}'.`);
+    }
+    let parsed;
+    try {
+        const content = readFileSync(fragmentPath, "utf-8");
+        parsed = TOML.parse(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse fragment '${fragmentName}' at '${fragmentPath}': ${err?.message ?? err}`);
+    }
+    if ("include" in parsed) {
+        throw new Error(`Fragment '${fragmentName}' at '${fragmentPath}' contains its own 'include' key — recursive includes are not supported in v1. Inline the steps directly into this fragment.`);
+    }
+    if ("workflow" in parsed) {
+        throw new Error(`Fragment '${fragmentName}' at '${fragmentPath}' contains a [workflow] block. Fragment files must be [[steps]] lists only.`);
+    }
+    const steps = Array.isArray(parsed.steps)
+        ? parsed.steps
+        : [];
+    return { steps };
+}
+function assertUniqueStepIds(originated, workflowPath) {
+    const seen = new Map();
+    for (const { step, origin } of originated) {
+        const id = step?.id;
+        if (id === undefined || id === null)
+            continue; // let downstream code complain about missing ids
+        if (typeof id !== "string")
+            continue;
+        if (seen.has(id)) {
+            const firstOrigin = seen.get(id);
+            throw new Error(`Step id '${id}' appears twice when expanding workflow '${workflowPath}': first in ${firstOrigin}, then in ${origin}.`);
+        }
+        seen.set(id, origin);
+    }
+}
+//# sourceMappingURL=workflow-fragments.js.map

package/dist/src/lib/workflow-fragments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-fragments.js","sourceRoot":"","sources":["../../../src/lib/workflow-fragments.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/workflow-toml-validator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Push-time validator for workflow TOML files (issue #685, #998).
+ *
+ * Detects the common footgun where a user writes `[steps.<id>.<field>]` under
+ * an open `[[steps]]` array. TOML parses that as a sub-table on the
+ * most-recent step keyed by the step's id (e.g. `steps[0]["refresh-each"]`),
+ * not as the intended `steps[0].request`. The result is a step with an
+ * unrecognized top-level field — the runtime silently ignores it, and the
+ * step then runs with an empty `request` block.
+ *
+ * The validator walks every step in `tomlData.steps[]`. For a step whose
+ * `kind` the CLI KNOWS about, it reports any top-level field not in the
+ * generated allowlist. For an UNKNOWN kind (an old CLI run against a newer
+ * server that registered a step kind the CLI doesn't have), it SKIPS the
+ * per-field allowlist check — but still runs the kind-agnostic
+ * misnested-header footgun detector. This is the #998 fix: the recurring
+ * "newer server kind → false-reject of valid fields" failure (#685/#802/#971
+ * were all false rejections) becomes "unvalidated, not rejected."
+ *
+ * ── Source of truth (#998) ───────────────────────────────────────────────
+ * The allowlist field union and the known-kind set are GENERATED from the
+ * server step runners (`src/workflows/steps/*.ts`) and the universal
+ * `BaseStepDefinition` shape into the committed
+ * `cli/src/lib/generated-allowlist.ts` artifact (the CLI does NOT import
+ * server `src/` at runtime — only the build-time generator does). The union is
+ * derived from what each runner READS, not what the `*StepDefinition` TYPE
+ * declares — types over-declare and would weaken the footgun detector. A CI
+ * freshness guard (`gen-allowlist.mjs --check`, also asserted by the #985
+ * drift-guard test) keeps the committed artifact in sync with the runners, so
+ * the hand-edit drift class (#685/#802/#971) cannot recur for the same-version
+ * case. Regenerate with `node cli/scripts/gen-allowlist.mjs`.
+ */
+/**
+ * Read-only view of `ALLOWLISTED_FIELDS` for the drift-guard test (#985).
+ *
+ * Exported so `cli/tests/unit/workflow-toml-validator-drift-guard.test.ts` can
+ * assert this set stays a superset of every top-level field the step runners
+ * in `src/workflows/steps/*.ts` actually read — checking the *live* set the
+ * validator enforces rather than a copy that could itself drift. Not part of
+ * the public validator API; consumed only by the guard.
+ */
+export declare const ALLOWLISTED_FIELDS_FOR_DRIFT_GUARD: ReadonlySet<string>;
+/**
+ * Read-only view of `KNOWN_KINDS` for the drift-guard test (#998). Lets the
+ * guard assert the generated known-kind set matches a fresh scan.
+ */
+export declare const KNOWN_KINDS_FOR_DRIFT_GUARD: ReadonlySet<string>;
+/**
+ * A single offending field on a step.
+ *
+ * `stepIndex` is the array index in `steps[]`.
+ * `stepId` is the value of the step's `id` field, if any (string).
+ * `field` is the unknown top-level key; uses sentinel names for shape
+ * errors:
+ *  - `__steps_shape__`: `steps` is not an array (table or scalar).
+ *  - `__step_shape__`: a step is not an object.
+ * `hint` is a short, user-facing explanation (used by
+ * `formatWorkflowTomlErrors` to render the multi-line diagnostic).
+ * `parentStepId` is set when this error came from a `collect` step's
+ * nested inner `step` definition (codex review, 2026-05-15): the outer
+ * `stepIndex` points at the array index, `parentStepId` carries the
+ * outer step's id (if any), and `stepId` carries the inner step's id.
+ * It's `null` for top-level errors (the renderer treats both `null` and
+ * `undefined` as top-level — see `formatWorkflowTomlErrors`).
+ */
+export type WorkflowTomlError = {
+    stepIndex: number;
+    stepId: string | null;
+    field: string;
+    hint: string;
+    parentStepId?: string | null;
+};
+/**
+ * Walk a parsed workflow TOML document and return all unknown-field errors.
+ *
+ * @param tomlData The output of `TOML.parse()` for a workflow TOML file.
+ * @returns An array of error objects, one per offending field. Empty if no
+ *   errors were found.
+ */
+export declare function validateWorkflowToml(tomlData: any): WorkflowTomlError[];
+/**
+ * Render a multi-line diagnostic for a list of errors. Designed for the
+ * shape called out in the issue:
+ *
+ *   Error in workflows/refresh.toml:
+ *     steps[0] (id="refresh-each") has unknown field "refresh-each".
+ *     This is usually caused by writing [steps.refresh-each.request] instead of [steps.request].
+ *     TOML can't address an array element by id — use [steps.request] (refers to the most recent step).
+ *
+ * @param filePath The TOML file path (or display name) to include in the
+ *   header.
+ * @param errors The error list from `validateWorkflowToml`.
+ * @returns A multi-line string ready to print to stderr.
+ */
+export declare function formatWorkflowTomlErrors(filePath: string, errors: WorkflowTomlError[]): string;