primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/workflow-toml-validator.js

@@ -0,0 +1,770 @@
+/**
+ * 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`.
+ */
+import { GENERATED_ALLOWLISTED_FIELDS, GENERATED_KNOWN_KINDS, } from "./generated-allowlist.js";
+// #2689 — the static `{{ }}` template lint, generated verbatim from the server
+// module `src/workflows/runner/template-static-lint.ts` (see
+// `cli/scripts/gen-template-lint.mjs`) so push-time and save-time verdicts are
+// produced by the same code rather than a hand mirror.
+import { lintWorkflowStepTemplates } from "./generated-template-lint.js";
+// #3374 — the `runAs = "system"` + `accessRule` predicate is the server's own,
+// vendored from `src/config-surface/workflow-rules.ts`; this module renders
+// the CLI's hint from its answer rather than restating the conjunction.
+import { checkWorkflowSystemAccessRule } from "./generated-config-surfaces.js";
+/**
+ * Universal-and-consumed allowlist of top-level fields permitted on a step
+ * (known kinds). Generated from the runners; see header.
+ */
+const ALLOWLISTED_FIELDS = new Set(GENERATED_ALLOWLISTED_FIELDS);
+/**
+ * The set of step kinds the CLI knows about (the server's registered kinds at
+ * generation time). A step whose `kind` is NOT in this set has its per-field
+ * allowlist check skipped — the kind-agnostic footgun detector still runs.
+ */
+const KNOWN_KINDS = new Set(GENERATED_KNOWN_KINDS);
+/**
+ * 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 const ALLOWLISTED_FIELDS_FOR_DRIFT_GUARD = ALLOWLISTED_FIELDS;
+/**
+ * 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 const KNOWN_KINDS_FOR_DRIFT_GUARD = KNOWN_KINDS;
+/**
+ * #1447 workflow-identity predicate, extracted (codex review, 2026-07-15) so
+ * command sites that apply command-line metadata overrides can re-run it
+ * against the merged/effective workflow rather than only the parsed file.
+ *
+ * `runAs = "system"` + a non-empty `accessRule` is dead config: a system run
+ * can only be started by the system and never evaluates its accessRule, so any
+ * non-empty rule is inert. The server rejects this at save time (#1258,
+ * `src/workflows/config/workflow-save-rules.ts`); catching it locally puts the
+ * refusal in the PREFLIGHT, which aborts before the first mutating call, rather
+ * than mid-apply after earlier entities have been written (#1418 drift).
+ *
+ * "All-or-nothing", which this comment used to claim, was never what push
+ * offers and is corrected here (#3320): the preflight is all-or-nothing, and
+ * the apply stage that follows it is incremental and convergent with no
+ * rollback. See `config push --help`.
+ *
+ * Delegates the decision to the server's own predicate,
+ * `checkWorkflowSystemAccessRule` (#3374, vendored from
+ * `src/config-surface/workflow-rules.ts`): the sentinel is returned exactly
+ * when it reports a violation — `runAs === "system"` with a non-empty string
+ * `accessRule`. Default/unset/empty/whitespace-only runAs or accessRule (and a
+ * bare non-string boolean accessRule) return `null`. Only the HINT is this
+ * module's: it names the preflight remedy, where the server's sentence names
+ * the save-time one.
+ *
+ * @param workflow The workflow-metadata object — the `[workflow]` table, or
+ *   for commands that accept unwrapped root-level metadata, the root TOML
+ *   object (`tomlData.workflow || tomlData`). Non-object inputs return `null`.
+ */
+export function validateWorkflowIdentity(workflow) {
+    if (workflow === null ||
+        typeof workflow !== "object" ||
+        Array.isArray(workflow)) {
+        return null;
+    }
+    const violation = checkWorkflowSystemAccessRule({
+        runAs: workflow.runAs,
+        accessRule: workflow.accessRule,
+    });
+    if (violation) {
+        return {
+            stepIndex: -1,
+            stepId: null,
+            field: "__workflow_system_access_rule__",
+            hint: 'accessRule has no effect when runAs = "system" (system runs skip ' +
+                "accessRule; gate callers with syncCallable + caller-mode, or see #1433)",
+        };
+    }
+    return null;
+}
+/**
+ * #2643 — `templateMissingMarker` was removed from the platform. A workflow
+ * TOML that still sets it is rejected here, before the push, with the same
+ * sentence the server returns, rather than being silently dropped.
+ */
+export const REMOVED_TEMPLATE_MISSING_MARKER_MESSAGE = "templateMissingMarker is no longer supported. An unresolved template " +
+    "reference now fails the step on every workflow; mark individual " +
+    "expressions optional with `{{ x | default: '' }}` instead.";
+/**
+ * #2645 — named workflow configs moved to sidecar files
+ * (`workflows/<key>.configs/<name>.toml`), so an inline `[[configs]]` list is
+ * no longer read by anything.
+ *
+ * It fails the push rather than being ignored. A pull taken before this change
+ * wrote those blocks, and push now applies only the sidecars: tolerating the
+ * list would leave the file describing configurations the server does not have
+ * — silently, since the content hash deliberately excludes the legacy list, so
+ * the object would not even report as Modified. The whole point of authoring
+ * configuration in TOML is that the committed file describes the server.
+ */
+const RETIRED_INLINE_CONFIGS_MESSAGE = "`[[configs]]` is no longer read from a workflow file (#2645). Named " +
+    "configurations are authored one per file at " +
+    "`workflows/<key>.configs/<name>.toml`, and `[workflow].activeConfigName` " +
+    "selects the live one. Move each entry's body to its own sidecar file and " +
+    "delete the `[[configs]]` blocks.";
+function validateRetiredInlineConfigs(tomlData) {
+    const configs = tomlData?.configs;
+    if (!Array.isArray(configs) || configs.length === 0)
+        return null;
+    return {
+        stepIndex: -1,
+        stepId: null,
+        field: "__workflow_inline_configs__",
+        hint: RETIRED_INLINE_CONFIGS_MESSAGE,
+    };
+}
+function validateRemovedWorkflowFields(workflow) {
+    if (!workflow || typeof workflow !== "object")
+        return null;
+    if (!Object.prototype.hasOwnProperty.call(workflow, "templateMissingMarker")) {
+        return null;
+    }
+    return {
+        stepIndex: -1,
+        stepId: null,
+        field: "__workflow_removed_field__",
+        hint: REMOVED_TEMPLATE_MISSING_MARKER_MESSAGE,
+    };
+}
+/**
+ * Non-blocking notes for a workflow TOML — things worth saying on a push that
+ * are not errors.
+ *
+ * #2643: `strict` / `strictParams` are accepted and ignored, because the
+ * failure they used to opt into now applies to every workflow. A definition
+ * that sets them keeps working unchanged, so this is a note, not an error.
+ */
+export function collectWorkflowTomlNotes(tomlData) {
+    const notes = [];
+    const steps = tomlData?.steps;
+    if (!Array.isArray(steps))
+        return notes;
+    const usesStrict = steps.some((step) => step &&
+        typeof step === "object" &&
+        (Object.prototype.hasOwnProperty.call(step, "strict") ||
+            Object.prototype.hasOwnProperty.call(step, "strictParams")));
+    if (usesStrict) {
+        notes.push("Note: `strict` / `strictParams` no longer do anything — an unresolved " +
+            "template reference fails the step on every workflow (#2643). The keys " +
+            "are still accepted, so you can remove them at your convenience.");
+    }
+    return notes;
+}
+/**
+ * #1447 (maintainer decision, 2026-07-21): compute the EFFECTIVE workflow
+ * identity that an `update --from-file` push will leave on the server — the
+ * merge of the persisted record with the incoming file/flags.
+ *
+ * The merge exists for a caller whose push OMITS one side of the
+ * runAs/accessRule pair and lets the server retain it. Linting the incoming
+ * payload alone misses the case where the OTHER side is already `system` / a
+ * stored rule: an existing `runAs="system"` workflow plus a file adding only an
+ * `accessRule`, or a file flipping a workflow with a stored rule to
+ * `runAs="system"`. Both pass a payload-only lint and are then rejected by the
+ * server's PATCH. Merging the two before `validateWorkflowIdentity` catches
+ * them locally at zero extra cost — the persisted record is already fetched at
+ * the call site.
+ *
+ * NOT `config push`, since #2743: its update is always-send, so the file alone IS
+ * the effective config (an omitted `accessRule` clears the stored rule rather
+ * than inheriting it) and its push-time lint of the file is exact. The merge
+ * semantics below are unchanged for any caller that does omit fields: a field
+ * PRESENT in `incoming` (including an empty-string clear) overrides the stored
+ * value; an ABSENT field (undefined) falls back to what the server keeps.
+ */
+export function effectiveWorkflowIdentity(existing, incoming) {
+    const ex = existing ?? {};
+    const inc = incoming ?? {};
+    return {
+        runAs: inc.runAs !== undefined ? inc.runAs : ex.runAs,
+        accessRule: inc.accessRule !== undefined ? inc.accessRule : ex.accessRule,
+    };
+}
+/**
+ * Walk a parsed workflow TOML document and return all unknown-field errors.
+ *
+ * @param tomlData The output of `parseConfigToml()` for a workflow TOML file.
+ * @param opts.skipWorkflowIdentity When true, suppress the #1447 workflow
+ *   identity check (`runAs="system"` + non-empty `accessRule`). Callers that
+ *   merge command-line overrides after parsing re-run `validateWorkflowIdentity`
+ *   against the effective metadata themselves.
+ * @returns An array of error objects, one per offending field. Empty if no
+ *   errors were found.
+ */
+export function validateWorkflowToml(tomlData, opts) {
+    const errors = [];
+    if (tomlData === null || tomlData === undefined) {
+        return errors;
+    }
+    // #1447 — workflow-level identity lint: `runAs = "system"` + a non-empty
+    // `accessRule` is dead config. See `validateWorkflowIdentity` for the
+    // predicate. This runs BEFORE the `steps` early-returns below so a file
+    // carrying the bad combo but with missing/malformed `[[steps]]` is still
+    // flagged.
+    //
+    // Metadata shape (codex review, 2026-07-15): read the workflow table with
+    // the same `tomlData.workflow || tomlData` fallback the consuming commands
+    // use (`workflows create/update --from-file`), so an UNWRAPPED root-level
+    // TOML carrying `runAs`/`accessRule` is checked too — not only the wrapped
+    // `[workflow]` form.
+    //
+    // `skipWorkflowIdentity` (codex review, 2026-07-15): callers that apply
+    // command-line metadata overrides AFTER parsing (e.g. `workflows update
+    // --from-file` with `--access-rule`) pass this to suppress the identity
+    // check on the raw file, then re-run `validateWorkflowIdentity` against the
+    // merged/effective metadata themselves. Otherwise `--access-rule ""` could
+    // not repair an offending file, and an override-introduced accessRule would
+    // escape the lint. Structural checks (#685 misnest, etc.) still run.
+    if (!opts?.skipWorkflowIdentity) {
+        const identityError = validateWorkflowIdentity(tomlData.workflow || tomlData);
+        if (identityError)
+            errors.push(identityError);
+    }
+    // #2643 — a `[workflow]` key the platform has removed. Checked with the same
+    // `tomlData.workflow || tomlData` fallback as the identity lint so the
+    // unwrapped root-level form is caught too, and BEFORE the `steps`
+    // early-returns so a metadata-only file is still flagged.
+    const removedFieldError = validateRemovedWorkflowFields(tomlData.workflow || tomlData);
+    if (removedFieldError)
+        errors.push(removedFieldError);
+    // #2645 — an inline `[[configs]]` list, which named configs left behind when
+    // they moved to sidecar files. Read from the document root (not the
+    // `[workflow]` table) and before the `steps` early-returns, so a
+    // configs-only file is flagged too.
+    const inlineConfigsError = validateRetiredInlineConfigs(tomlData);
+    if (inlineConfigsError)
+        errors.push(inlineConfigsError);
+    const steps = tomlData.steps;
+    // No steps section at all → nothing to validate. This is fine for
+    // partial TOML files (some commands accept a metadata-only file).
+    if (steps === undefined || steps === null) {
+        return errors;
+    }
+    // `steps` is a table instead of an array. This typically means the user
+    // wrote `[steps.foo]` with no preceding `[[steps]]` array marker, so
+    // TOML resolved `steps` to a table. The runtime expects an array — flag
+    // it with a clear shape diagnostic.
+    if (!Array.isArray(steps)) {
+        if (typeof steps === "object") {
+            errors.push({
+                stepIndex: -1,
+                stepId: null,
+                field: "__steps_shape__",
+                hint: 'The `steps` section is a table, not an array. Workflow TOML expects `[[steps]]` array markers — add `[[steps]]` before any `[steps.<field>]` blocks.',
+            });
+        }
+        else {
+            errors.push({
+                stepIndex: -1,
+                stepId: null,
+                field: "__steps_shape__",
+                hint: `The \`steps\` section must be an array of step tables (received: ${typeof steps}).`,
+            });
+        }
+        return errors;
+    }
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        // Defensive: array entry isn't an object. Should be near-impossible with
+        // valid `[[steps]]` syntax, but possible if the user writes `steps =
+        // ["a", "b"]`. Surface it so the user gets a diagnostic instead of a
+        // silent skip.
+        if (step === null || typeof step !== "object" || Array.isArray(step)) {
+            errors.push({
+                stepIndex: i,
+                stepId: null,
+                field: "__step_shape__",
+                hint: `Each entry in \`steps[]\` must be a table. Got: ${step === null ? "null" : Array.isArray(step) ? "array" : typeof step}.`,
+            });
+            continue;
+        }
+        validateStepObject(step, i, /* parentStepId */ null, errors);
+        // Codex finding 2 (PR #762, 2026-05-15): a `collect` step's nested
+        // `step` field is itself a step definition that the collect runner
+        // executes. The outer-step allowlist accepts `step` as a top-level
+        // field, but that's a structural pass-through — we need to recurse
+        // into the inner step's keys to catch the same misnested-header
+        // footgun (e.g. `[steps.step.call.request]` parses as `step.step =
+        // { call: { request: {...} } }`, with `call` as an unknown inner
+        // field; without the recursion this slips through). We only recurse
+        // for `kind === "collect"` — other kinds with a `step`-named field
+        // (none today) would need their own audit.
+        if (step.kind === "collect" &&
+            step.step !== null &&
+            typeof step.step === "object" &&
+            !Array.isArray(step.step)) {
+            const outerStepId = typeof step.id === "string" ? step.id : null;
+            validateStepObject(step.step, i, outerStepId, errors);
+        }
+    }
+    // #2689 — statically-dead `{{ }}` expressions (unknown root, undeclared
+    // `steps.<id>` / `outputs.<name>`) are guaranteed run-time failures since
+    // #2643. Reject them here so `config push` reports them before anything is
+    // pushed, instead of after a deploy-and-run cycle.
+    //
+    // `knownKinds` carries the #998 skew posture into the lint: an old CLI must
+    // not judge a NEWER server's step kind, whose runner may bind template roots
+    // this copy of the lint has never heard of. The server-side check in
+    // `validateWorkflowSteps` scans every step and stays authoritative.
+    for (const finding of lintWorkflowStepTemplates(steps, {
+        knownKinds: KNOWN_KINDS,
+    })) {
+        errors.push({
+            stepIndex: finding.stepIndex,
+            stepId: finding.stepId,
+            field: "__template_expression__",
+            hint: `${finding.location}: ${finding.message}`,
+        });
+    }
+    return errors;
+}
+/**
+ * Validate a single step object's top-level keys against the allowlist and
+ * push any errors found onto `errors`. Used for both the top-level
+ * `steps[]` walk and the recursive `collect.step` walk.
+ *
+ * When `parentStepId` is set, the step being validated is the inner step
+ * of a `collect`. Errors carry the outer-step context so the rendered
+ * diagnostic can point operators at the right slot in the TOML.
+ */
+function validateStepObject(step, stepIndex, parentStepId, errors) {
+    const stepId = typeof step.id === "string" ? step.id : null;
+    // #998: kind-membership branch. The CLI ships independently and may run
+    // against a NEWER server that registered a step kind the CLI's generated
+    // known-kind set doesn't have. For such an UNKNOWN kind we skip the
+    // per-field allowlist check (so a valid new-kind field is never falsely
+    // rejected — the recurring #685/#802/#971 failure) while STILL running the
+    // kind-agnostic misnested-header footgun detector below. For a KNOWN kind
+    // the full allowlist check applies as before. A missing/non-string `kind`
+    // is treated as known so the legacy strict check still catches obviously
+    // malformed steps (the runtime would reject a kindless step anyway).
+    const kind = typeof step.kind === "string" ? step.kind : null;
+    const isKnownKind = kind === null || KNOWN_KINDS.has(kind);
+    for (const key of Object.keys(step)) {
+        const value = step[key];
+        // Codex finding 1 (PR #762, 2026-05-15): self-id misnesting must be
+        // checked BEFORE the allowlist skip. When the step's `id` happens to
+        // match an allowlisted field name (e.g. `id = "query"`,
+        // `id = "request"`, `id = "input"`, `id = "output"`), TOML's
+        // `[steps.<id>.<sub-field>]` misnest produces a sub-table on the step
+        // keyed by the id — the same shape the validator was meant to catch.
+        // The allowlist would otherwise skip it as "expected per-kind field".
+        // Heuristic: when `step[step.id]` is a non-array table, this is
+        // (effectively always) the misnest pattern. Scalars are fine (the
+        // user really did mean to set the scalar field).
+        //
+        // Codex finding (PR #819, 2026-05-21): the heuristic over-fires for the
+        // `switch` step kind. A switch legitimately named `id = "default"` has a
+        // real `[steps.default]` fallback that parses as a non-array table at
+        // `step.default` — structurally identical to the misnest shape, but it's
+        // the field's *valid* form. (Likewise `id = "cases"`.) For these ids the
+        // footgun and the legitimate declaration are indistinguishable, so the
+        // heuristic must defer to the allowlist. Carve-out scope is narrow on
+        // purpose: only `kind === "switch"` with key `cases`/`default`. Every
+        // other (kind, id) collision — e.g. `id = "query"` on a database step —
+        // is still treated as the footgun, preserving finding 1's safety net.
+        const isSwitchFallbackField = step.kind === "switch" && (key === "cases" || key === "default");
+        const isSelfIdMisnest = stepId !== null &&
+            key === stepId &&
+            value !== null &&
+            typeof value === "object" &&
+            !Array.isArray(value) &&
+            !isSwitchFallbackField;
+        // Known kind → full allowlist check (an allowlisted field passes).
+        // Unknown kind → skip the per-field allowlist check entirely: only the
+        // structural footgun (self-id misnest) below can flag a field. The
+        // footgun check is kind-agnostic, so it fires on every step regardless.
+        if (!isSelfIdMisnest && (!isKnownKind || ALLOWLISTED_FIELDS.has(key)))
+            continue;
+        // Two failure modes are common enough to call out specifically in
+        // the hint:
+        //
+        // 1) `[steps.<id>.<field>]` under `[[steps]]` — TOML places the
+        //    sub-table under `steps[N][<id>]`. We detect this when the
+        //    unknown field name equals the step's own id (including the
+        //    self-id-allowlist-collision case above). We use the first
+        //    sub-key of the offending value (e.g. `request`) to build a
+        //    concrete corrected-form example so the user sees exactly what
+        //    to rewrite, not just an abstract `<field>`.
+        //
+        // 2) Any other unknown top-level field — covered by the generic hint.
+        let hint;
+        if (stepId !== null && key === stepId) {
+            const subKey = value && typeof value === "object" && !Array.isArray(value)
+                ? Object.keys(value)[0]
+                : null;
+            const exampleSub = subKey ?? "request";
+            hint =
+                `This is usually caused by writing [steps.${stepId}.${exampleSub}] instead of [steps.${exampleSub}]. ` +
+                    `TOML can't address an array element by id — use [steps.${exampleSub}] (refers to the most recent step).`;
+        }
+        else {
+            hint =
+                `\`${key}\` is not a recognized step field. ` +
+                    `If you meant to write a nested config block on this step, use [steps.${key}] (which refers to the most recent step) instead of [steps.<id>.${key}].`;
+        }
+        errors.push({
+            stepIndex,
+            stepId,
+            field: key,
+            hint,
+            parentStepId,
+        });
+    }
+    // #1252 — form-urlencoded body conflict. `[steps.request.form]` encodes an
+    // `application/x-www-form-urlencoded` body; it cannot coexist with a
+    // `request.body` or a raw/multipart `bodyMode`. The runtime rejects the same
+    // combination, but catching it at push time gives a clearer, earlier
+    // diagnostic. (`request.form` itself needs no allowlist entry — the validator
+    // only checks top-level step fields, and `request` is already allowlisted.)
+    if (step.kind === "integration.call" &&
+        step.request !== null &&
+        typeof step.request === "object" &&
+        !Array.isArray(step.request)) {
+        const req = step.request;
+        const hasForm = req.form !== undefined && req.form !== null;
+        if (hasForm) {
+            if (req.body !== undefined && req.body !== null) {
+                errors.push({
+                    stepIndex,
+                    stepId,
+                    field: "request.form",
+                    hint: "`request.form` (application/x-www-form-urlencoded) cannot be combined with `request.body`. " +
+                        "Use one request body — either the JSON `body` or the `form` table.",
+                    parentStepId,
+                });
+            }
+            const mode = step.bodyMode;
+            if (mode === "raw" || mode === "multipart") {
+                errors.push({
+                    stepIndex,
+                    stepId,
+                    field: "request.form",
+                    hint: `\`request.form\` (application/x-www-form-urlencoded) cannot be combined with bodyMode "${mode}". ` +
+                        "Remove `form` or the `bodyMode`.",
+                    parentStepId,
+                });
+            }
+        }
+    }
+}
+/**
+ * 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 function formatWorkflowTomlErrors(filePath, errors) {
+    if (errors.length === 0)
+        return "";
+    const lines = [`Error in ${filePath}:`];
+    for (const err of errors) {
+        if (err.field === "__steps_shape__") {
+            lines.push(`  ${err.hint}`);
+            continue;
+        }
+        if (err.field === "__step_shape__") {
+            lines.push(`  steps[${err.stepIndex}] is malformed: ${err.hint}`);
+            continue;
+        }
+        // #2689 — a statically-dead `{{ }}` expression. The offending FIELD is
+        // fine; its contents are not, so the "unknown field" wording would be
+        // actively misleading. Render the step slot plus the lint's message, which
+        // already names the expression, the problem and the fix.
+        if (err.field === "__template_expression__") {
+            const idPart = err.stepId ? ` (id="${err.stepId}")` : "";
+            lines.push(`  steps[${err.stepIndex}]${idPart}:`);
+            lines.push(`  ${err.hint}`);
+            continue;
+        }
+        // #1447 — workflow-level error, not tied to a step. Render the bare hint
+        // (no `steps[N]` prefix) under the file header.
+        if (err.field === "__workflow_system_access_rule__" ||
+            err.field === "__workflow_removed_field__") {
+            lines.push(`  ${err.hint}`);
+            continue;
+        }
+        // For errors inside a `collect` step's nested inner step (codex review,
+        // 2026-05-15), use a `steps[N].step` slot prefix so operators see that
+        // the offending field is on the inner step, not the outer collect.
+        // The outer step's id (if any) is also included in the prefix so the
+        // diagnostic can be cross-referenced against the parent's TOML header.
+        //
+        // #971: top-level errors carry `parentStepId: null` (set explicitly at the
+        // top-level `validateStepObject` call); only genuine collect-inner errors
+        // carry a real id (or `undefined` if a future caller omits it). Use a
+        // non-null check so BOTH `null` and `undefined` top-level errors render as
+        // a bare `steps[N]` without the `(inside collect step)` suffix. The prior
+        // `!== undefined` check treated `null` as inner (`null !== undefined` is
+        // `true`), mislabeling every top-level error as inside a collect step (a
+        // regression from PR #762).
+        const isInnerStep = err.parentStepId != null;
+        const slot = isInnerStep
+            ? `steps[${err.stepIndex}].step`
+            : `steps[${err.stepIndex}]`;
+        const idPart = err.stepId ? ` (id="${err.stepId}")` : "";
+        const parentPart = isInnerStep && err.parentStepId
+            ? ` (inside collect step id="${err.parentStepId}")`
+            : isInnerStep
+                ? ` (inside collect step)`
+                : "";
+        lines.push(`  ${slot}${idPart}${parentPart} has unknown field "${err.field}".`);
+        lines.push(`  ${err.hint}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * #1614 — client-side mirror of the server's `validateWorkflowExpressions`
+ * (`src/workflows/definition-store.ts`) for named `expr.*` CEL guards. Returns
+ * structural errors so `config push` fails fast with the same class of diagnostic
+ * the server would 400 on:
+ *   1. every `expr.<name>` reference — in a definition body OR a step guard
+ *      (`runIf` / `successWhen` / switch `when`) — names a DECLARED definition;
+ *   2. the definition reference graph is a DAG (no cycles);
+ *   3. each definition body is a non-empty string.
+ *
+ * The CLI has no CEL parser, so full CEL parse validation stays server-side
+ * (the authoritative check) — this mirror catches the common undeclared-name
+ * and cycle mistakes before a network round-trip, matching how the CLI does
+ * structural checks and the server does authoritative validation elsewhere.
+ */
+/**
+ * #1614 — validate the RAW `[expr.cel]` table shape BEFORE
+ * `parseWorkflowExpressionsToml` filters it. That parser drops any entry whose
+ * body is not a string, so a mistyped `ready = true` would vanish and, with no
+ * references left to fail on, `config push` would succeed while omitting the whole
+ * expression table. Surface non-string / empty / wrong-typed bodies (and a
+ * non-table `cel`) as a hard CLI validation error instead. Mirrors the server's
+ * `validateRawExpressionsShape` (`src/workflows/definition-store.ts`).
+ *
+ * `tomlData.expr.cel` is the parsed `[expr.cel]` table.
+ */
+export function validateWorkflowExpressionsRawToml(tomlData) {
+    const errors = [];
+    const cel = tomlData?.expr?.cel;
+    if (cel === undefined || cel === null)
+        return errors;
+    if (typeof cel !== "object" || Array.isArray(cel)) {
+        errors.push("[expr.cel] must be a table mapping each name to a CEL string");
+        return errors;
+    }
+    for (const [name, body] of Object.entries(cel)) {
+        if (typeof body !== "string" || !body.trim()) {
+            errors.push(`expr.cel.${name}: definition body must be a non-empty CEL string`);
+        }
+    }
+    return errors;
+}
+export function validateWorkflowExpressionsToml(steps, expressions) {
+    const errors = [];
+    const cel = expressions?.cel;
+    const declared = new Set(cel ? Object.keys(cel) : []);
+    const refsFromDef = new Map();
+    if (cel) {
+        for (const [name, body] of Object.entries(cel)) {
+            if (typeof body !== "string" || !body.trim()) {
+                errors.push(`expr.cel.${name}: definition body must be a non-empty CEL string`);
+                refsFromDef.set(name, new Set());
+                continue;
+            }
+            const refs = extractExprRefs(body);
+            refsFromDef.set(name, refs);
+            for (const ref of refs) {
+                if (!declared.has(ref)) {
+                    errors.push(`expr.cel.${name} references undeclared expr.${ref}`);
+                }
+            }
+        }
+    }
+    if (Array.isArray(steps)) {
+        steps.forEach((step, index) => {
+            for (const guard of collectGuardExpressions(step)) {
+                for (const ref of extractExprRefs(guard.expr)) {
+                    if (!declared.has(ref)) {
+                        errors.push(`steps[${index}].${guard.field} references undeclared expr.${ref}`);
+                    }
+                }
+            }
+        });
+    }
+    const cycle = findExprCycle(declared, refsFromDef);
+    if (cycle) {
+        errors.push(`expr.cel definitions form a cycle: ${cycle.join(" -> ")}`);
+    }
+    return errors;
+}
+function collectGuardExpressions(step) {
+    const out = [];
+    if (!step || typeof step !== "object")
+        return out;
+    if (typeof step.runIf === "string" && step.runIf.trim()) {
+        out.push({ field: "runIf", expr: step.runIf });
+    }
+    if (typeof step.successWhen === "string" && step.successWhen.trim()) {
+        out.push({ field: "successWhen", expr: step.successWhen });
+    }
+    if (Array.isArray(step.cases)) {
+        step.cases.forEach((c, ci) => {
+            if (c && typeof c.when === "string" && c.when.trim()) {
+                out.push({ field: `cases[${ci}].when`, expr: c.when });
+            }
+        });
+    }
+    return out;
+}
+/**
+ * Scan a CEL string for `expr.<name>` / `expr['name']` / `expr["name"]`
+ * references, skipping quoted string literals. Mirrors the server's
+ * `extractExprRefs`.
+ */
+function extractExprRefs(expression) {
+    const refs = new Set();
+    if (!expression)
+        return refs;
+    const len = expression.length;
+    let i = 0;
+    // #1614 — match the server's `isIdentChar` exactly (includes `$`) so a
+    // `$`-containing expr name (`expr.a$b`) is not falsely flagged as an
+    // undeclared reference by the CLI mirror when the server would accept it.
+    const isIdent = (ch) => !!ch && /[A-Za-z0-9_$]/.test(ch);
+    const skipStr = (start) => {
+        const quote = expression[start];
+        let k = start + 1;
+        while (k < len) {
+            if (expression[k] === "\\") {
+                k += 2;
+                continue;
+            }
+            if (expression[k] === quote)
+                return k + 1;
+            k++;
+        }
+        return len;
+    };
+    while (i < len) {
+        const ch = expression[i];
+        if (ch === "'" || ch === '"') {
+            i = skipStr(i);
+            continue;
+        }
+        if (ch === "e" &&
+            expression.slice(i, i + 4) === "expr" &&
+            (i === 0 || !isIdent(expression[i - 1]))) {
+            let j = i + 4;
+            if (expression[j] === ".") {
+                j++;
+                const start = j;
+                while (j < len && isIdent(expression[j]))
+                    j++;
+                if (j > start)
+                    refs.add(expression.slice(start, j));
+                i = j;
+                continue;
+            }
+            if (expression[j] === "[") {
+                let k = j + 1;
+                while (k < len && expression[k] === " ")
+                    k++;
+                const q = expression[k];
+                if (q === "'" || q === '"') {
+                    const s = k + 1;
+                    let e = s;
+                    while (e < len && expression[e] !== q)
+                        e++;
+                    if (e < len) {
+                        refs.add(expression.slice(s, e));
+                        i = e + 1;
+                        continue;
+                    }
+                }
+            }
+            i = j;
+            continue;
+        }
+        i++;
+    }
+    return refs;
+}
+/** DFS cycle detection over the declared `expr.*` reference graph. */
+function findExprCycle(declared, refs) {
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const color = new Map();
+    for (const n of declared)
+        color.set(n, WHITE);
+    const stack = [];
+    let found = null;
+    const dfs = (n) => {
+        color.set(n, GRAY);
+        stack.push(n);
+        for (const m of refs.get(n) ?? []) {
+            if (!declared.has(m))
+                continue;
+            if (color.get(m) === GRAY) {
+                const idx = stack.indexOf(m);
+                found = stack.slice(idx).concat(m);
+                return true;
+            }
+            if (color.get(m) === WHITE && dfs(m))
+                return true;
+        }
+        stack.pop();
+        color.set(n, BLACK);
+        return false;
+    };
+    for (const n of declared) {
+        if (color.get(n) === WHITE && dfs(n))
+            break;
+    }
+    return found;
+}
+//# sourceMappingURL=workflow-toml-validator.js.map