primitive-admin 1.1.0-alpha.9 → 1.1.0

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

@@ -0,0 +1,211 @@
+/**
+ * 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.
+ *  - `__workflow_system_access_rule__`: `[workflow] runAs = "system"` with a
+ *    non-empty `accessRule` — dead config the server rejects (#1447/#1258).
+ *    A workflow-level error (not tied to a step): `stepIndex: -1, stepId: null`.
+ *  - `__template_expression__`: a `{{ }}` expression that can never resolve
+ *    (#2689). The field itself is valid — the `hint` carries the expression's
+ *    location and the lint's message.
+ * `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;
+};
+/**
+ * #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 declare function validateWorkflowIdentity(workflow: any): WorkflowTomlError | 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 declare const REMOVED_TEMPLATE_MISSING_MARKER_MESSAGE: string;
+/**
+ * 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 declare function collectWorkflowTomlNotes(tomlData: any): string[];
+/** The runAs / accessRule pair the identity lint reads. */
+export interface WorkflowIdentityFields {
+    runAs?: unknown;
+    accessRule?: unknown;
+}
+/**
+ * #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 declare function effectiveWorkflowIdentity(existing: WorkflowIdentityFields | null | undefined, incoming: WorkflowIdentityFields | null | undefined): WorkflowIdentityFields;
+/**
+ * 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 declare function validateWorkflowToml(tomlData: any, opts?: {
+    skipWorkflowIdentity?: boolean;
+}): 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;
+/**
+ * #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 declare function validateWorkflowExpressionsRawToml(tomlData: any): string[];
+export declare function validateWorkflowExpressionsToml(steps: any[], expressions: {
+    cel?: Record<string, string>;
+} | undefined): string[];