primitive-admin 1.0.44 → 1.0.46

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

@@ -0,0 +1,183 @@
+/**
+ * Validator: every `$params.X` reference inside an operation's
+ * `definition` must correspond to a declared param in
+ * `[[operations.params]]` (or the legacy JSON-string params object).
+ *
+ * Background (issue #752): a typo like `$params.proectId` used to
+ * silently no-op at runtime. With native TOML, we can catch these at
+ * `sync push` time with the file path and line number of the
+ * operation block where the bad reference appears.
+ *
+ * Design notes:
+ *   - Line attribution is per-operation, not per-reference. We don't
+ *     parse `definition` line-by-line; we just locate the
+ *     `[[operations]]` header for the named op in the raw source and
+ *     report that line. This is the load-bearing UX (jump to the
+ *     offending op block); pinpointing the exact `$params.X` reference
+ *     inside a sub-table would require swapping the TOML parser, which
+ *     the issue explicitly leaves to implementer judgement.
+ *   - We intentionally diverge from the server-side `collectParamRefs`
+ *     in `database-type-operations-controller.ts:1163`. The server pushes
+ *     the full path (e.g. `"X.Y"` for `$params.X.Y`); the CLI extracts
+ *     only the first segment (`"X"`). Net effect: the CLI validator is
+ *     more lenient than the server — `$params.X.Y` passes the CLI check
+ *     when `X` alone is declared in `[[operations.params]]`, even though
+ *     the server treats the full path as the lookup key. The server
+ *     remains authoritative; the CLI's first-segment extraction is a
+ *     pragmatic choice so authors can declare structured params (e.g.
+ *     `config: { type: "object" }`) and reference sub-fields like
+ *     `$params.config.subKey` without listing every sub-field
+ *     individually (review feedback r3246635661).
+ */
+/**
+ * Walk an arbitrary JSON-ish value and collect `$params.X` references
+ * found in string-valued leaves, returning only the first dotted segment
+ * (`"X"` for `$params.X.Y`). Intentionally more lenient than the
+ * server-side helper, which pushes the full path — see the module
+ * doc-comment for the rationale.
+ */
+export function collectParamRefs(value) {
+    const refs = [];
+    if (typeof value === "string") {
+        const match = value.match(/^\$params\.(.+)$/);
+        if (match) {
+            const first = match[1].split(/[.\[]/)[0];
+            if (first)
+                refs.push(first);
+        }
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value) {
+            refs.push(...collectParamRefs(item));
+        }
+    }
+    else if (value !== null && typeof value === "object") {
+        for (const v of Object.values(value)) {
+            refs.push(...collectParamRefs(v));
+        }
+    }
+    return refs;
+}
+/**
+ * Normalize a `params` value (object, array, or JSON string) into the
+ * set of declared param names.
+ */
+export function declaredParamNames(params) {
+    const names = new Set();
+    if (params == null)
+        return names;
+    let value = params;
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return names;
+        }
+    }
+    if (Array.isArray(value)) {
+        for (const row of value) {
+            if (row && typeof row === "object" && typeof row.name === "string") {
+                names.add(row.name);
+            }
+        }
+    }
+    else if (typeof value === "object" && value !== null) {
+        for (const key of Object.keys(value)) {
+            names.add(key);
+        }
+    }
+    return names;
+}
+/**
+ * Find the 1-indexed line number in `rawToml` where the `[[operations]]`
+ * block declaring `opName` starts. Returns 0 if not found.
+ *
+ * Implementation: walk in source order, track the most recent
+ * `[[operations]]` header, and when we see a `name = "<opName>"` line
+ * before the next `[[operations]]` or top-level header, return that
+ * header's line.
+ */
+export function locateOperationLine(rawToml, opName) {
+    const lines = rawToml.split(/\r?\n/);
+    let lastOpHeader = 0;
+    let armed = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line === "[[operations]]") {
+            lastOpHeader = i + 1;
+            armed = true;
+            continue;
+        }
+        if (!armed)
+            continue;
+        // Another array-of-tables / top-level table → not this op anymore.
+        if (line.startsWith("[[") && line !== "[[operations]]" && !line.startsWith("[[operations.")) {
+            armed = false;
+            continue;
+        }
+        if (line.startsWith("[") && !line.startsWith("[[") && !line.startsWith("[operations.")) {
+            armed = false;
+            continue;
+        }
+        const m = line.match(/^name\s*=\s*["'](.+)["']\s*$/);
+        if (m && m[1] === opName) {
+            return lastOpHeader;
+        }
+    }
+    return 0;
+}
+/**
+ * Validate `$params` references across every operation in a parsed
+ * database-type config.
+ *
+ * Errors (blocking):
+ *   - A `$params.X` reference inside `definition` where `X` is not
+ *     declared in `[[operations.params]]`.
+ *
+ * Warnings (soft, not blocking):
+ *   - A param declared in `[[operations.params]]` that is not referenced
+ *     anywhere in `definition`. Authors may be staging a deprecation.
+ */
+export function validateOperations(opts) {
+    const errors = [];
+    const warnings = [];
+    for (const op of opts.operations) {
+        if (!op || !op.name)
+            continue;
+        const declared = declaredParamNames(op.params);
+        const refs = new Set(collectParamRefs(op.definition));
+        const line = locateOperationLine(opts.rawToml, op.name);
+        for (const ref of refs) {
+            if (!declared.has(ref)) {
+                errors.push({
+                    file: opts.filePath,
+                    line,
+                    op: op.name,
+                    message: `$params.${ref} not declared in [[operations.params]] for operation '${op.name}'`,
+                });
+            }
+        }
+        for (const name of declared) {
+            if (!refs.has(name)) {
+                warnings.push({
+                    file: opts.filePath,
+                    line,
+                    op: op.name,
+                    message: `param '${name}' declared but not referenced in operation '${op.name}'`,
+                });
+            }
+        }
+    }
+    return { errors, warnings };
+}
+/**
+ * Format a validation issue as `<file>:<line>: <message>`.
+ */
+export function formatIssue(issue) {
+    if (issue.line > 0) {
+        return `${issue.file}:${issue.line}: ${issue.message}`;
+    }
+    return `${issue.file}: ${issue.message}`;
+}
+//# sourceMappingURL=toml-params-validator.js.map

package/dist/src/lib/toml-params-validator.js.map

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

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.js

@@ -0,0 +1,343 @@
+/**
+ * Push-time validator for workflow TOML files (issue #685).
+ *
+ * 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[]` and reports any
+ * top-level field not in the universal-and-consumed allowlist. The allowlist
+ * is the union of:
+ *  - Universal step fields declared on `BaseStepDefinition` in
+ *    `src/workflows/runner/types.ts`
+ *  - The top-level fields each step runner in `src/workflows/steps/`
+ *    actually reads
+ *
+ * The list is universal-only (not per-kind) by design: the CLI doesn't know
+ * which step kinds exist on a given server version, and a per-kind list
+ * would couple the CLI tightly to the runtime. A universal allowlist
+ * catches the misnested-header footgun cleanly while staying tolerant of
+ * future step kinds that consume top-level fields already in the union.
+ *
+ * Maintenance: when a new step kind starts reading a new top-level field,
+ * add the field name to `ALLOWLISTED_FIELDS` below. See `cli/README.md`
+ * for the maintenance note.
+ */
+/**
+ * Universal-only allowlist of top-level fields permitted on a step.
+ *
+ * Membership combines:
+ *  1) Universal fields on `BaseStepDefinition` in
+ *     `src/workflows/runner/types.ts` and the runner engine's reads of
+ *     `stepDef.*`.
+ *  2) The union of top-level fields actually consumed by step runners in
+ *     `src/workflows/steps/` (audited 2026-05-15).
+ *
+ * Keep this sorted to make diffs reviewable.
+ */
+const ALLOWLISTED_FIELDS = new Set([
+    // Universal (BaseStepDefinition + engine).
+    "as",
+    "concurrency",
+    "continueOnError",
+    "description",
+    "forEach",
+    "id",
+    "kind",
+    "maxItems",
+    "name",
+    "runIf",
+    "saveAs",
+    "selector",
+    "strict",
+    "successWhen",
+    "timeout",
+    // Per-kind, union across runners.
+    "_testSteps", // workflow.call test-mode override
+    "action",
+    "appId",
+    "asBase64",
+    "attachments",
+    "blobId",
+    "bodyMode",
+    "bucketId",
+    "bucketKey",
+    "cacheTtlSeconds",
+    "cases", // switch: array of { when, output } (#802)
+    "configId",
+    "content",
+    "contentBase64",
+    "contentType",
+    "context",
+    "cursor",
+    "cursorField",
+    "databaseId",
+    "default", // switch: { output } fallback branch (#802)
+    "direction",
+    "dryRun",
+    "durationMs",
+    "email",
+    "events",
+    "expiresInSeconds",
+    "feature",
+    "filename",
+    "filters",
+    "groupBy",
+    "groupId",
+    "groupType",
+    "htmlBody",
+    "includeUserDetails",
+    "input",
+    "integrationKey",
+    "itemsField",
+    "limit",
+    "maxPages",
+    "message",
+    "messages",
+    "metrics",
+    "model",
+    "modelOverride",
+    "ms",
+    "multipartFields",
+    "onPartialFailure",
+    "operationName",
+    "output",
+    "page",
+    "params",
+    "payload",
+    "plugins",
+    "prompt",
+    "promptKey",
+    "query",
+    "queryType",
+    "request",
+    "route",
+    "runs",
+    "sort",
+    "step", // collect: nested inner step definition
+    "subject",
+    "tags",
+    "temperature",
+    "templateType",
+    "textBody",
+    "thinkingLevel",
+    "to",
+    "tools",
+    "tool_choice",
+    "top_p",
+    "toUserId",
+    "type",
+    "user",
+    "userId",
+    "userUlid",
+    "variables",
+    "windowDays",
+    "workflowKey",
+]);
+/**
+ * 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 function validateWorkflowToml(tomlData) {
+    const errors = [];
+    if (tomlData === null || tomlData === undefined) {
+        return errors;
+    }
+    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);
+        }
+    }
+    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;
+    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;
+        if (!isSelfIdMisnest && 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,
+        });
+    }
+}
+/**
+ * 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;
+        }
+        // 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.
+        const isInnerStep = err.parentStepId !== undefined;
+        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");
+}
+//# sourceMappingURL=workflow-toml-validator.js.map