primitive-admin 1.0.49 → 1.0.50

package/dist/src/lib/token-inject.js

@@ -0,0 +1,204 @@
+/**
+ * Pure helpers for the `primitive tokens inject` command (issue #420).
+ *
+ * Kept separate from the commander wrapper in `commands/tokens.ts` so the
+ * snippet building, shared-secret generation, and one-shot localhost server
+ * can be unit-tested without a live backend or a spawned CLI process.
+ */
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+/** Default TTL for injected tokens — short-lived per the #420 design (30 minutes). */
+export const DEFAULT_INJECT_TTL = "30m";
+/** Lowest port the `--serve` one-shot server is allowed to bind. */
+const MIN_SERVE_PORT = 30001;
+/** How many random ports to try before giving up on collisions. */
+const SERVE_PORT_ATTEMPTS = 5;
+/**
+ * Escape a token for safe embedding inside a single-quoted JS string literal.
+ * Tokens are `prim_<base64url>` so they normally need no escaping, but we are
+ * defensive in case the source ever changes.
+ */
+function escapeForJsSingleQuote(value) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+/**
+ * Build the browser console one-liner that applies a token via the
+ * `window.__PRIMITIVE_SET_TOKEN__` hook installed by `<DevTools>`.
+ */
+export function buildSnippet(token) {
+    return `window.__PRIMITIVE_SET_TOKEN__('${escapeForJsSingleQuote(token)}')`;
+}
+/** Render the output for a given `--print` mode. */
+export function buildPrintOutput(mode, token) {
+    switch (mode) {
+        case "snippet":
+            return buildSnippet(token);
+        case "token":
+            return token;
+        case "env":
+            return `VITE_PRIMITIVE_DEV_TOKEN=${token}`;
+        default:
+            throw new Error(`Invalid --print mode: ${mode}. Expected one of: snippet, env, token.`);
+    }
+}
+/** Generate a random, URL-safe shared secret for the `--serve` endpoint. */
+export function generateSharedSecret() {
+    return randomBytes(16).toString("hex");
+}
+/** A random integer in [min, max]. */
+function randomPort() {
+    // 30001..65535
+    const span = 65535 - MIN_SERVE_PORT;
+    return MIN_SERVE_PORT + Math.floor(Math.random() * span);
+}
+/**
+ * Copy text to the system clipboard using whatever native tool is available.
+ * No new npm dependency — shells out to `pbcopy` (macOS), `xclip`/`xsel`
+ * (Linux), or `clip` (Windows). Returns `true` on success, `false` if no
+ * clipboard tool is available or the copy failed (caller degrades gracefully).
+ */
+export function copyToClipboard(text) {
+    const candidates = process.platform === "darwin"
+        ? [{ cmd: "pbcopy", args: [] }]
+        : process.platform === "win32"
+            ? [{ cmd: "clip", args: [] }]
+            : [
+                { cmd: "xclip", args: ["-selection", "clipboard"] },
+                { cmd: "xsel", args: ["--clipboard", "--input"] },
+                { cmd: "wl-copy", args: [] },
+            ];
+    for (const { cmd, args } of candidates) {
+        try {
+            const res = spawnSync(cmd, args, { input: text });
+            if (res.error)
+                continue; // command not found — try next
+            if (res.status === 0)
+                return true;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return false;
+}
+/**
+ * CORS headers for the one-shot token response. `--serve` is documented to be
+ * read via `fetch('http://127.0.0.1:PORT/...')` FROM the app's browser console,
+ * which is a cross-origin request. Without `Access-Control-Allow-Origin` the
+ * browser blocks `r.text()`, so the advertised browser-injection flow fails.
+ * We echo back the request `Origin` (falling back to `*`) and allow `GET`.
+ *
+ * Note: these headers do NOT weaken the loopback-bind + shared-secret model.
+ * CORS only governs whether the browser exposes the RESPONSE to page JS; the
+ * 127.0.0.1 bind and the unguessable per-run secret are what gate access.
+ */
+function corsHeaders(reqOrigin) {
+    return {
+        "Access-Control-Allow-Origin": reqOrigin ?? "*",
+        "Access-Control-Allow-Methods": "GET, OPTIONS",
+        "Access-Control-Allow-Headers": "*",
+        Vary: "Origin",
+    };
+}
+/**
+ * Boot a one-shot HTTP server bound to `127.0.0.1` that serves `token` exactly
+ * once, then shuts down. Security model:
+ *   - binds loopback only (never 0.0.0.0)
+ *   - requires a random shared-secret `?key=` query param; requests without the
+ *     correct secret get 403 and do NOT consume the one-shot read
+ *   - returns CORS headers so the documented cross-origin browser `fetch` can
+ *     actually read the response; a CORS preflight (`OPTIONS`) is answered 204
+ *     WITHOUT consuming the one-shot read or shutting the server down
+ *   - the one-shot consumption + shutdown happen ONLY on the authorized `GET`
+ *     that actually delivers the token (correct secret) — never on a preflight,
+ *     a secret-rejected request, or a wrong path
+ *   - retries random ports >30000 on collision (>= 5 attempts)
+ */
+export async function serveTokenOnce(token, opts = {}) {
+    const secret = generateSharedSecret();
+    const path = opts.path ?? "/token";
+    let resolveDone;
+    const done = new Promise((resolve) => {
+        resolveDone = resolve;
+    });
+    let served = false;
+    const server = createServer((req, res) => {
+        const reqUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+        const cors = corsHeaders(req.headers.origin);
+        // CORS preflight: the browser sends an OPTIONS before the cross-origin GET.
+        // Answer it with the CORS headers and 204, but do NOT consume the one-shot
+        // read or shut the server down — the real GET still needs to deliver the
+        // token afterward.
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, cors);
+            res.end();
+            return;
+        }
+        if (reqUrl.pathname !== path) {
+            res.writeHead(404, { "Content-Type": "text/plain", ...cors });
+            res.end("Not found");
+            return;
+        }
+        // Reject any request missing the correct shared secret. Does not consume
+        // the one-shot read, so a racing process cannot lock the dev out.
+        if (reqUrl.searchParams.get("key") !== secret) {
+            res.writeHead(403, { "Content-Type": "text/plain", ...cors });
+            res.end("Forbidden");
+            return;
+        }
+        if (served) {
+            res.writeHead(410, { "Content-Type": "text/plain", ...cors });
+            res.end("Token already served");
+            return;
+        }
+        // Authorized GET with the correct secret: this is the only path that
+        // consumes the one-shot read and shuts the server down.
+        served = true;
+        res.writeHead(200, { "Content-Type": "text/plain", ...cors });
+        res.end(token);
+        // Close after the response flushes so the single read completes cleanly.
+        res.on("finish", () => {
+            server.close(() => resolveDone());
+        });
+    });
+    const port = await listenWithRetry(server);
+    const url = `http://127.0.0.1:${port}${path}?key=${secret}`;
+    const stop = () => {
+        try {
+            server.close();
+        }
+        catch {
+            // already closed
+        }
+    };
+    return { url, secret, port, done, stop };
+}
+/** Try random ports > 30000 until one binds, up to SERVE_PORT_ATTEMPTS times. */
+function listenWithRetry(server) {
+    return new Promise((resolve, reject) => {
+        let attempts = 0;
+        const tryListen = () => {
+            attempts += 1;
+            const port = randomPort();
+            const onError = (err) => {
+                server.removeListener("listening", onListening);
+                if (err.code === "EADDRINUSE" && attempts < SERVE_PORT_ATTEMPTS) {
+                    tryListen();
+                }
+                else {
+                    reject(new Error(`Failed to bind a local port for --serve after ${attempts} attempt(s): ${err.message}`));
+                }
+            };
+            const onListening = () => {
+                server.removeListener("error", onError);
+                resolve(port);
+            };
+            server.once("error", onError);
+            server.once("listening", onListening);
+            server.listen(port, "127.0.0.1");
+        };
+        tryListen();
+    });
+}
+//# sourceMappingURL=token-inject.js.map

package/dist/src/lib/token-inject.js.map

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

package/dist/src/lib/toml-database-config.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Helpers for emitting `DatabaseTypeOperation` configs as native TOML.
+ *
+ * Background (issue #752): historically `sync pull` serialized
+ * `definition` and `params` as JSON strings stuffed into a single TOML
+ * field, which produced unreviewable 800-char one-liners. This module
+ * lets us emit them as nested TOML tables when they're representable,
+ * while preserving the existing file's shape so we don't generate
+ * surprise diffs.
+ *
+ * Three responsibilities:
+ *   1. `detectExistingOperationForms()` — read the raw TOML source and
+ *      decide, per operation name, whether the file uses JSON-string
+ *      form ("legacy") or nested-table form ("native") for each of
+ *      `definition` and `params`. This drives form preservation on
+ *      `sync pull`.
+ *   2. `canEmitNative()` — recursively check whether a JS value is
+ *      representable as a TOML value. Returns a reason string if not.
+ *      Mainly catches `null` and mixed-type arrays, which `@iarna/toml`
+ *      either rejects or silently mangles.
+ *   3. `buildDatabaseTypeTomlData()` — builds the JS object that we
+ *      hand to `TOML.stringify`. Per operation, decides JSON-string vs
+ *      native based on (existing form, can-emit, override mode).
+ */
+export type FieldForm = "native" | "legacy";
+export interface OperationFormHints {
+    /** Map of op name → existing form for `definition`. Missing op = "default". */
+    definition: Map<string, FieldForm>;
+    /** Map of op name → existing form for `params`. Missing op = "default". */
+    params: Map<string, FieldForm>;
+}
+/**
+ * Inspect the raw TOML source for a database-type file and decide which
+ * form each operation's `definition`/`params` currently use.
+ *
+ * Detection is intentionally simple: we walk `[[operations]]` blocks in
+ * source order and, for each one, look for either a `definition = '...'`
+ * line (legacy) or an `[operations.definition]` / `[operations.definition.X]`
+ * sub-header (native).
+ */
+export declare function detectExistingOperationForms(rawToml: string): OperationFormHints;
+/**
+ * Recursively check whether a JS value can be safely serialized to TOML
+ * using `@iarna/toml`. Returns null if OK, a reason string otherwise.
+ *
+ * Things TOML can't represent (in `@iarna/toml`):
+ *   - `null` (TOML has no null).
+ *   - Arrays containing values of different "TOML types" (e.g. mixed
+ *     string and number). Spec-wise TOML 1.0 actually allows this, but
+ *     `@iarna/toml` is strict and throws.
+ *   - `undefined` (different from null but equally not representable).
+ */
+export declare function canEmitNative(value: any): string | null;
+/**
+ * Normalize a `params` value into a sorted array of
+ * `{ name, type, required, ... }` rows, suitable for emitting as
+ * `[[operations.params]]`. Accepts both shapes the wire/parser supports:
+ *   - object form: `{ projectId: { type: "string", required: true } }`
+ *   - array form:  `[{ name: "projectId", type: "string", required: true }]`
+ */
+export declare function normalizeParamsToArray(params: any): any[] | null;
+export interface BuildOptions {
+    /** Per-op form hints derived from `detectExistingOperationForms`. */
+    hints?: OperationFormHints;
+    /**
+     * Override the default form for ops with no hint. Used by `sync pull`
+     * to keep behavior backwards-compatible if we ever flip the default,
+     * and by `sync migrate-toml` to force native everywhere.
+     */
+    defaultForm?: FieldForm;
+    /** Sink for human-readable fallback messages. */
+    logger?: (message: string) => void;
+    /**
+     * Server `DatabaseTypeSubscription` rows to emit as `[[subscriptions]]`
+     * blocks (issue #803). Already sanitized by the controller's
+     * `sanitizeSubscription` (so `select`/`emit` are arrays and `params` is an
+     * object). Omitted on the `migrate-toml` path (no subscriptions to merge).
+     */
+    subscriptions?: any[];
+}
+/**
+ * Build the JS object to pass to `TOML.stringify` for a database-type
+ * config file. Per operation:
+ *   - If the chosen form is "native" AND `definition` is TOML-emittable,
+ *     emit `[operations.definition]` (nested table).
+ *   - Else emit `definition = '<json string>'` and log a message.
+ *   - Same logic independently for `params`, but the native form for
+ *     params is `[[operations.params]]` (array-of-tables).
+ */
+export declare function buildDatabaseTypeTomlData(typeConfig: any, operations: any[], ruleSetIdToName: Map<string, string>, options?: BuildOptions): any;
+/**
+ * Thrown when a `[[subscriptions]]` block declares both `accessRule` and
+ * `access` with different values. We never silently drop the field
+ * (issue #803 maintainer decision): prefer `access` when they agree, error
+ * when they conflict so the operator fixes the source of truth.
+ */
+export declare class SubscriptionAccessKeyConflictError extends Error {
+    subscriptionKey: string | undefined;
+    constructor(subscriptionKey: string | undefined);
+}
+/**
+ * Resolve the subscription `access` CEL expression from a TOML row.
+ *
+ * The server's wire key is `access`; the issue author (and the guides) used
+ * `accessRule`. We accept both: prefer `access` when present, fall back to
+ * `accessRule`, and never silently drop the field. If both are present with
+ * different values, throw so the conflict is surfaced rather than guessed.
+ */
+export declare function resolveSubscriptionAccess(sub: any): string | undefined;
+/**
+ * Normalize a `[[subscriptions]]` TOML row into the server's wire shape.
+ *
+ * Mirrors `normalizeOperationFromToml`. Maps the `accessRule`→`access`
+ * alias (issue #803), and passes `select` / `emit` / `params` through in
+ * native form — the server stores them as JSON strings and re-parses on
+ * read (`sanitizeSubscription`), so the parse → push → pull round-trip is
+ * symmetric with operations' `definition` / `params`.
+ *
+ * `filter` stays required server-side; we forward whatever is present (or
+ * undefined) and let the controller's clean named 400 surface.
+ */
+export declare function normalizeSubscriptionFromToml(sub: any): any;
+/**
+ * After parsing TOML, normalize the `definition` and `params` of each
+ * operation row into the JS objects the server expects. Handles both
+ * native and legacy forms transparently. The server payload is the
+ * source of truth; native TOML is purely a source-control affordance.
+ *
+ * Mirrors `parseDatabaseTypeToml` in `sync.ts`, but is broken out here
+ * so the migrate-toml command can call it without re-implementing.
+ */
+export declare function normalizeOperationFromToml(op: any): any;

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

@@ -0,0 +1,95 @@
+/**
+ * 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).
+ */
+export interface ValidationIssue {
+    file: string;
+    line: number;
+    op: string;
+    message: string;
+}
+export interface ValidationResult {
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+/**
+ * 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 declare function collectParamRefs(value: any): string[];
+/**
+ * Normalize a `params` value (object, array, or JSON string) into the
+ * set of declared param names.
+ */
+export declare function declaredParamNames(params: any): Set<string>;
+/**
+ * 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 declare function locateOperationLine(rawToml: string, opName: string): number;
+export interface ValidateOptions {
+    filePath: string;
+    rawToml: string;
+    /**
+     * Operations as parsed for the wire (definition/params already in JS
+     * object form). The validator works against the parsed shape so it's
+     * indifferent to native vs JSON-string source.
+     */
+    operations: Array<{
+        name: string;
+        definition: any;
+        params?: any;
+    }>;
+}
+/**
+ * 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 declare function validateOperations(opts: ValidateOptions): ValidationResult;
+/**
+ * Format a validation issue as `<file>:<line>: <message>`.
+ */
+export declare function formatIssue(issue: ValidationIssue): string;

package/dist/src/lib/version-check.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Checks if a newer version of the CLI is available on npm.
+ *
+ * - Stable versions (e.g. "1.0.22") check the "latest" dist-tag
+ * - Prerelease versions (e.g. "1.0.23-alpha.3") check their channel's
+ *   dist-tag (e.g. "alpha"), falling back to "latest" if that tag doesn't exist
+ *
+ * Caches results per dist-tag for 4 hours. Fails silently on any error.
+ */
+export declare function checkForUpdate(currentVersion: string): Promise<void>;

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-toml-validator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+/**
+ * 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>;
+/**
+ * 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;