primitive-admin 1.1.0-alpha.6 → 1.1.0-alpha.60

package/dist/src/lib/watch.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared poll-based tailing helpers for `--watch` / `--follow` (#1969).
+ *
+ * Two render modes over one abortable poll loop:
+ *   - `--watch`  → periodic full-snapshot redraw (a repeated `list`/`get`).
+ *   - `--follow` → append-only tail: fetch rows after an opaque server-owned
+ *                  `resumeAfter` checkpoint each tick.
+ *
+ * The loop is endpoint-agnostic. `--follow` consumers supply a {@link FollowSource}
+ * that knows how to fetch the page after a checkpoint; `--watch` consumers supply
+ * a `snapshot()` and a renderer. The renderer is injected (there is no `json`
+ * flag in the options) so this file never decides output shape or clears the
+ * terminal — that is entirely the caller's renderer.
+ *
+ * `--follow` is near-lossless observed-version tailing: it re-emits a row when a
+ * newer version is observed, holds no per-item dedup state, and asserts only
+ * forward progress — never a total-order or exactly-once property (the
+ * underlying GSI sorts by `modifiedAt` alone and is eventually consistent). See
+ * the design in #1969.
+ *
+ * Unit-tested against fake sources (the `cli/src/lib/paginate.ts` pattern) with
+ * no server.
+ */
+/** Interval floor: reject anything below this (prevents a request storm). */
+export declare const MIN_INTERVAL_SECONDS = 1;
+/** Default poll interval when `--interval` is omitted. */
+export declare const DEFAULT_INTERVAL_SECONDS = 2;
+/**
+ * Default cap on how many pages `followLoop` drains within a single tick when a
+ * burst is larger than one page. Bounds the within-tick work and, with the
+ * non-advancing-checkpoint guard, prevents an infinite drain.
+ */
+export declare const DEFAULT_MAX_PAGES_PER_TICK = 20;
+/**
+ * Validate an `--interval` value (in seconds). Returns the interval in seconds,
+ * or throws with a clear message for a missing/NaN/sub-floor value. Command
+ * handlers call this and surface the error; the library loops take a validated
+ * `intervalMs`.
+ */
+export declare function parseIntervalSeconds(raw: string | undefined): number;
+/**
+ * Sleep for `ms`, resolving early (never rejecting) if `signal` aborts. The
+ * timer and abort listener are always cleaned up, so a resolved delay leaves no
+ * dangling timer. Used by every poll loop so Ctrl-C stops promptly between
+ * ticks.
+ */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+/** Error policy for the poll loops: keep polling, or throw out of the loop. */
+export type PollErrorPolicy = "continue" | "throw";
+export interface PollUntilOptions<T> {
+    /** Validated poll interval in milliseconds. */
+    intervalMs: number;
+    /** Abort signal (Ctrl-C at the command level). */
+    signal: AbortSignal;
+    /** What to do when `probe` throws. Default `"throw"`. */
+    onError?: PollErrorPolicy;
+    /** Called with each probed value (e.g. to report progress). */
+    onValue?: (value: T) => void;
+}
+/**
+ * Delay-then-probe until `done(value)` is true or the signal aborts. Returns
+ * the last probed value. Delay-first (not probe-first) so a caller that already
+ * holds a fresh value — the batch-status loops — keeps its "poll every N
+ * seconds" cadence with no extra immediate request.
+ */
+export declare function pollUntil<T>(probe: () => Promise<T>, done: (value: T) => boolean, options: PollUntilOptions<T>): Promise<T>;
+/** One page of follow results, carrying the opaque next checkpoint. */
+export interface FollowPage<T> {
+    items: T[];
+    /** More rows remain past this page right now (drives the within-tick drain). */
+    hasMore: boolean;
+    /** Opaque server-owned checkpoint; always present, even on an empty page. */
+    resumeAfter: string;
+}
+/**
+ * A source of follow pages. `fetchAfter(undefined)` is the bootstrap poll — it
+ * establishes the baseline checkpoint and its items are NOT emitted (tail
+ * semantics: "show me what happens from now"). `fetchAfter(<token>)` returns the
+ * bounded page after that checkpoint.
+ */
+export interface FollowSource<T> {
+    fetchAfter: (resumeAfter: string | undefined) => Promise<FollowPage<T>>;
+    /**
+     * Max pages to drain within one tick when a burst exceeds one page. Defaults
+     * to {@link DEFAULT_MAX_PAGES_PER_TICK}. The drain also stops early if the
+     * checkpoint fails to advance (non-advancing-checkpoint guard).
+     */
+    maxPagesPerTick?: number;
+}
+export interface FollowOptions<T> {
+    intervalMs: number;
+    signal: AbortSignal;
+    /** What to do when a poll throws. Default `"continue"` (keep tailing). */
+    onError?: PollErrorPolicy;
+    /** Render newly-observed rows (server-ascending; no client sort). */
+    render: (items: T[]) => void;
+}
+export interface WatchOptions<T> {
+    intervalMs: number;
+    signal: AbortSignal;
+    /** What to do when a poll throws. Default `"continue"`. */
+    onError?: PollErrorPolicy;
+    /**
+     * Render the full snapshot. The renderer owns any clearing/redraw — the loop
+     * never clears the terminal itself.
+     */
+    render: (items: T[]) => void;
+}
+/**
+ * Append-only tail. Bootstraps the baseline checkpoint (emitting nothing), then
+ * each tick drains forward while `hasMore` (bounded by `maxPagesPerTick`,
+ * stopping if the checkpoint fails to advance), rendering rows server-ascending.
+ * Holds no per-item state — the only carried state is the single opaque
+ * `resumeAfter` string.
+ */
+export declare function followLoop<T>(source: FollowSource<T>, options: FollowOptions<T>): Promise<void>;
+/**
+ * Snapshot redraw. Each tick fetches the full current snapshot and hands it to
+ * the renderer, which owns any clearing/redraw. No checkpoint, no dedup.
+ */
+export declare function watchLoop<T>(snapshot: () => Promise<T[]>, options: WatchOptions<T>): Promise<void>;

package/dist/src/lib/watch.js

@@ -0,0 +1,169 @@
+/**
+ * Shared poll-based tailing helpers for `--watch` / `--follow` (#1969).
+ *
+ * Two render modes over one abortable poll loop:
+ *   - `--watch`  → periodic full-snapshot redraw (a repeated `list`/`get`).
+ *   - `--follow` → append-only tail: fetch rows after an opaque server-owned
+ *                  `resumeAfter` checkpoint each tick.
+ *
+ * The loop is endpoint-agnostic. `--follow` consumers supply a {@link FollowSource}
+ * that knows how to fetch the page after a checkpoint; `--watch` consumers supply
+ * a `snapshot()` and a renderer. The renderer is injected (there is no `json`
+ * flag in the options) so this file never decides output shape or clears the
+ * terminal — that is entirely the caller's renderer.
+ *
+ * `--follow` is near-lossless observed-version tailing: it re-emits a row when a
+ * newer version is observed, holds no per-item dedup state, and asserts only
+ * forward progress — never a total-order or exactly-once property (the
+ * underlying GSI sorts by `modifiedAt` alone and is eventually consistent). See
+ * the design in #1969.
+ *
+ * Unit-tested against fake sources (the `cli/src/lib/paginate.ts` pattern) with
+ * no server.
+ */
+/** Interval floor: reject anything below this (prevents a request storm). */
+export const MIN_INTERVAL_SECONDS = 1;
+/** Default poll interval when `--interval` is omitted. */
+export const DEFAULT_INTERVAL_SECONDS = 2;
+/**
+ * Default cap on how many pages `followLoop` drains within a single tick when a
+ * burst is larger than one page. Bounds the within-tick work and, with the
+ * non-advancing-checkpoint guard, prevents an infinite drain.
+ */
+export const DEFAULT_MAX_PAGES_PER_TICK = 20;
+/**
+ * Validate an `--interval` value (in seconds). Returns the interval in seconds,
+ * or throws with a clear message for a missing/NaN/sub-floor value. Command
+ * handlers call this and surface the error; the library loops take a validated
+ * `intervalMs`.
+ */
+export function parseIntervalSeconds(raw) {
+    if (raw === undefined)
+        return DEFAULT_INTERVAL_SECONDS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < MIN_INTERVAL_SECONDS) {
+        throw new Error(`--interval must be a number of seconds >= ${MIN_INTERVAL_SECONDS}`);
+    }
+    return n;
+}
+/**
+ * Sleep for `ms`, resolving early (never rejecting) if `signal` aborts. The
+ * timer and abort listener are always cleaned up, so a resolved delay leaves no
+ * dangling timer. Used by every poll loop so Ctrl-C stops promptly between
+ * ticks.
+ */
+export function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            cleanup();
+            resolve();
+        };
+        const cleanup = () => signal?.removeEventListener("abort", onAbort);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Delay-then-probe until `done(value)` is true or the signal aborts. Returns
+ * the last probed value. Delay-first (not probe-first) so a caller that already
+ * holds a fresh value — the batch-status loops — keeps its "poll every N
+ * seconds" cadence with no extra immediate request.
+ */
+export async function pollUntil(probe, done, options) {
+    const onError = options.onError ?? "throw";
+    let last;
+    let haveValue = false;
+    while (!options.signal.aborted) {
+        await delay(options.intervalMs, options.signal);
+        if (options.signal.aborted)
+            break;
+        try {
+            last = await probe();
+            haveValue = true;
+        }
+        catch (err) {
+            if (onError === "continue")
+                continue;
+            throw err;
+        }
+        options.onValue?.(last);
+        if (done(last))
+            return last;
+    }
+    // Aborted before `done`: return the last probed value (probe once if we never
+    // got one, so the return type holds).
+    if (!haveValue)
+        last = await probe();
+    return last;
+}
+/**
+ * Append-only tail. Bootstraps the baseline checkpoint (emitting nothing), then
+ * each tick drains forward while `hasMore` (bounded by `maxPagesPerTick`,
+ * stopping if the checkpoint fails to advance), rendering rows server-ascending.
+ * Holds no per-item state — the only carried state is the single opaque
+ * `resumeAfter` string.
+ */
+export async function followLoop(source, options) {
+    const onError = options.onError ?? "continue";
+    const maxPages = source.maxPagesPerTick ?? DEFAULT_MAX_PAGES_PER_TICK;
+    // Bootstrap: establish the baseline; do not emit its rows.
+    let resumeAfter;
+    try {
+        resumeAfter = (await source.fetchAfter(undefined)).resumeAfter;
+    }
+    catch (err) {
+        if (onError !== "continue")
+            throw err;
+        resumeAfter = ""; // fall through to polling; the next tick retries
+    }
+    while (!options.signal.aborted) {
+        try {
+            let pages = 0;
+            while (pages < maxPages && !options.signal.aborted) {
+                const page = await source.fetchAfter(resumeAfter || undefined);
+                if (page.items.length > 0)
+                    options.render(page.items);
+                const advanced = page.resumeAfter !== resumeAfter;
+                resumeAfter = page.resumeAfter;
+                pages++;
+                // Stop the within-tick drain when the burst is drained, or if the
+                // checkpoint didn't advance (guards against an endless drain).
+                if (!page.hasMore || !advanced)
+                    break;
+            }
+        }
+        catch (err) {
+            if (onError !== "continue")
+                throw err;
+            // continue: swallow and retry next tick
+        }
+        await delay(options.intervalMs, options.signal);
+    }
+}
+/**
+ * Snapshot redraw. Each tick fetches the full current snapshot and hands it to
+ * the renderer, which owns any clearing/redraw. No checkpoint, no dedup.
+ */
+export async function watchLoop(snapshot, options) {
+    const onError = options.onError ?? "continue";
+    while (!options.signal.aborted) {
+        try {
+            const items = await snapshot();
+            options.render(items);
+        }
+        catch (err) {
+            if (onError !== "continue")
+                throw err;
+        }
+        await delay(options.intervalMs, options.signal);
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/src/lib/watch.js.map

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

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

@@ -0,0 +1,51 @@
+/**
+ * Shared "apply a TOML body to an existing workflow" helper.
+ *
+ * Extracted from the `sync push` update-existing path (#1249, Fork 4) so that
+ * both `sync push` and `workflows update --from-file` push a revised body the
+ * same way. A second inlined copy would regress #807: the update is
+ * ordering-sensitive and a naive metadata-then-body sequence rejects valid
+ * sync-callable edits.
+ *
+ * Ordering invariant (#807 / codex review):
+ *   1. metadata PATCH — WITHOUT `syncCallable`. The server re-validates
+ *      `syncCallable: true` against the workflow's CURRENTLY-active server
+ *      steps (`loadCurrentActiveSteps`, src/admin-api.ts:4734), not the steps
+ *      being pushed in the same call. So enabling sync-callable in the first
+ *      PATCH would validate against the stale active steps and be rejected.
+ *   2. body write — steps to the active config (config-model) or the legacy
+ *      draft slot (no active config).
+ *   3. a SECOND `syncCallable` PATCH — issued AFTER the new steps are active,
+ *      so it validates against the new (compatible) steps.
+ */
+import type { ApiClient } from "./api-client.js";
+import { safeJsonParse } from "./workflow-payload.js";
+export { safeJsonParse };
+export interface ApplyWorkflowBodyOptions {
+    /** Optimistic-concurrency guard for the metadata + syncCallable PATCHes. */
+    expectedModifiedAt?: string;
+    /**
+     * Active config to overwrite in place (config-model workflows). When absent,
+     * the body falls back to the legacy draft slot — non-live for config-model
+     * workflows, which the server rejects with 409 WORKFLOW_CONFIG_MODEL.
+     */
+    activeConfigId?: string;
+    /** When true, skip the optimistic-concurrency check (mirrors `--force`). */
+    force?: boolean;
+}
+export interface ApplyWorkflowBodyResult {
+    /** The freshest workflow `modifiedAt` after all PATCHes (for sync state). */
+    latestModifiedAt?: string;
+    /** Which slot the steps landed in: "active config" or "draft (legacy)". */
+    updateSlotLabel: string;
+    /** A fresh `getWorkflow` result so callers can read back configs/state. */
+    fullWorkflow: any;
+}
+/**
+ * Apply a parsed workflow body (metadata + steps) to an existing workflow,
+ * preserving the key/id. `workflow` is the TOML's `[workflow]` table (already
+ * merged with any explicit CLI flag overrides by the caller); `steps` is the
+ * TOML's `steps` array. The function performs the three-step ordered update
+ * and returns the latest `modifiedAt`, the slot label, and a fresh workflow.
+ */
+export declare function applyWorkflowBody(client: ApiClient, appId: string, workflowId: string, workflow: any, steps: any[], opts?: ApplyWorkflowBodyOptions): Promise<ApplyWorkflowBodyResult>;

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

@@ -0,0 +1,89 @@
+/**
+ * Shared "apply a TOML body to an existing workflow" helper.
+ *
+ * Extracted from the `sync push` update-existing path (#1249, Fork 4) so that
+ * both `sync push` and `workflows update --from-file` push a revised body the
+ * same way. A second inlined copy would regress #807: the update is
+ * ordering-sensitive and a naive metadata-then-body sequence rejects valid
+ * sync-callable edits.
+ *
+ * Ordering invariant (#807 / codex review):
+ *   1. metadata PATCH — WITHOUT `syncCallable`. The server re-validates
+ *      `syncCallable: true` against the workflow's CURRENTLY-active server
+ *      steps (`loadCurrentActiveSteps`, src/admin-api.ts:4734), not the steps
+ *      being pushed in the same call. So enabling sync-callable in the first
+ *      PATCH would validate against the stale active steps and be rejected.
+ *   2. body write — steps to the active config (config-model) or the legacy
+ *      draft slot (no active config).
+ *   3. a SECOND `syncCallable` PATCH — issued AFTER the new steps are active,
+ *      so it validates against the new (compatible) steps.
+ */
+import { buildWorkflowPayloadFromToml, safeJsonParse } from "./workflow-payload.js";
+// #1177: `safeJsonParse` now lives in the shared `workflow-payload` lib module
+// (the builder needs it too); re-exported here so existing importers of this
+// module keep working. Both `cli/src/lib` modules; no dep-direction problem.
+export { safeJsonParse };
+/**
+ * Apply a parsed workflow body (metadata + steps) to an existing workflow,
+ * preserving the key/id. `workflow` is the TOML's `[workflow]` table (already
+ * merged with any explicit CLI flag overrides by the caller); `steps` is the
+ * TOML's `steps` array. The function performs the three-step ordered update
+ * and returns the latest `modifiedAt`, the slot label, and a fresh workflow.
+ */
+export async function applyWorkflowBody(client, appId, workflowId, workflow, steps, opts = {}) {
+    const { expectedModifiedAt, activeConfigId, force } = opts;
+    // 1. Metadata PATCH — note: NO `syncCallable` here (deferred to step 3). The
+    //    shared builder (#1177, `mode: "update"`) omits `syncCallable` for exactly
+    //    this reason and applies the presence-aware clear-vs-leave semantics for
+    //    `accessRule` / `runAs` / `capabilities` / schemas. `requiresClientApply`
+    //    has no step-dependent validation, so the builder keeps it here. The
+    //    `metadataManifest` declared-access manifest (#1304) is call-site-specific
+    //    and attached below, not owned by the shared builder.
+    const updated = await client.updateWorkflow(appId, workflowId, {
+        ...buildWorkflowPayloadFromToml(workflow, { mode: "update" }),
+        // #1304 (P-C): declared-access manifest. Absent key → undefined (server's
+        // hasOwnProperty guard leaves it untouched); a parsed value/null is
+        // forwarded so a pull → push round-trips it (null clears). `sync push`
+        // always attaches this (null when the TOML drops `[metadata]`); the
+        // `workflows update --from-file` caller may leave it undefined.
+        metadataManifest: workflow.metadataManifest !== undefined ? workflow.metadataManifest : undefined,
+    }, expectedModifiedAt);
+    // The first PATCH bumps `modifiedAt`; the syncCallable PATCH (if any) bumps
+    // it again. The config/step update does NOT touch the workflow definition's
+    // `modifiedAt`.
+    let latestModifiedAt = updated?.workflow?.modifiedAt;
+    // 2. Body write — active config (config-model) or legacy draft slot. #1614 —
+    //    the named `expr.*` definitions live on the same R2 steps payload as the
+    //    steps, so they travel with the steps write here (not the metadata PATCH
+    //    above). Attached by the caller onto `workflow.expressions` (structural,
+    //    like `metadataManifest`); absent → undefined so a workflow without
+    //    definitions round-trips a clean drop.
+    const expressions = workflow.expressions ?? undefined;
+    let updateSlotLabel = "active config";
+    if (activeConfigId) {
+        await client.updateWorkflowConfig(appId, workflowId, activeConfigId, {
+            steps,
+            expressions,
+        });
+    }
+    else {
+        await client.updateWorkflowDraft(appId, workflowId, {
+            steps,
+            expressions,
+            inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
+        });
+        updateSlotLabel = "draft (legacy)";
+    }
+    // 3. Deferred `syncCallable` PATCH — now that the new steps are active (#807).
+    //    Only sent when the TOML actually carries the key; an absent key stays
+    //    `undefined` and the call is skipped, preserving no-clobber discipline.
+    if (workflow.syncCallable !== undefined) {
+        const syncCallableUpdated = await client.updateWorkflow(appId, workflowId, { syncCallable: workflow.syncCallable }, force ? undefined : latestModifiedAt);
+        if (syncCallableUpdated?.workflow?.modifiedAt) {
+            latestModifiedAt = syncCallableUpdated.workflow.modifiedAt;
+        }
+    }
+    const fullWorkflow = await client.getWorkflow(appId, workflowId);
+    return { latestModifiedAt, updateSlotLabel, fullWorkflow };
+}
+//# sourceMappingURL=workflow-apply.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-apply.js","sourceRoot":"","sources":["../../../src/lib/workflow-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,4BAA4B,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEpF,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,OAAO,EAAE,aAAa,EAAE,CAAC;AAwBzB;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAiB,EACjB,KAAa,EACb,UAAkB,EAClB,QAAa,EACb,KAAY,EACZ,OAAiC,EAAE;IAEnC,MAAM,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IAE3D,6EAA6E;IAC7E,+EAA+E;IAC/E,6EAA6E;IAC7E,8EAA8E;IAC9E,yEAAyE;IACzE,+EAA+E;IAC/E,0DAA0D;IAC1D,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,cAAc,CACzC,KAAK,EACL,UAAU,EACV;QACE,GAAG,4BAA4B,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC7D,0EAA0E;QAC1E,oEAAoE;QACpE,uEAAuE;QACvE,oEAAoE;QACpE,gEAAgE;QAChE,gBAAgB,EACd,QAAQ,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;KAClF,EACD,kBAAkB,CACnB,CAAC;IAEF,4EAA4E;IAC5E,4EAA4E;IAC5E,gBAAgB;IAChB,IAAI,gBAAgB,GAAuB,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAC;IAEzE,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,wEAAwE;IACxE,2CAA2C;IAC3C,MAAM,WAAW,GAAI,QAAgB,CAAC,WAAW,IAAI,SAAS,CAAC;IAC/D,IAAI,eAAe,GAAG,eAAe,CAAC;IACtC,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE;YACnE,KAAK;YACL,WAAW;SACZ,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE;YAClD,KAAK;YACL,WAAW;YACX,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI;SAC/E,CAAC,CAAC;QACH,eAAe,GAAG,gBAAgB,CAAC;IACrC,CAAC;IAED,+EAA+E;IAC/E,2EAA2E;IAC3E,4EAA4E;IAC5E,IAAI,QAAQ,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,mBAAmB,GAAG,MAAM,MAAM,CAAC,cAAc,CACrD,KAAK,EACL,UAAU,EACV,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,EACvC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CACrC,CAAC;QACF,IAAI,mBAAmB,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;YAC9C,gBAAgB,GAAG,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACjE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;AAC7D,CAAC"}

package/dist/src/lib/workflow-codegen/generated-schema-descriptor.d.ts

@@ -0,0 +1,129 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Vendored byte-for-byte from the canonical server module
+ * `src/workflows/schema-descriptor.ts` — the SAME interpretation the server
+ * validator (`validateValue`) enforces. The CLI cannot import server `src/`
+ * at runtime, so `workflows codegen`'s type converter imports this committed
+ * copy instead.
+ *
+ * Regenerate with:
+ *   node cli/scripts/gen-workflow-schema-descriptor.mjs   (runs at CLI prebuild)
+ *
+ * A CI freshness guard
+ * (`cli/scripts/gen-workflow-schema-descriptor.mjs --check`, also asserted by
+ * `cli/tests/unit/workflow-codegen-descriptor-drift-guard.test.ts`) fails if
+ * this committed copy does not match the source — see issue #1442 / #998.
+ */
+/**
+ * Canonical interpretation of the JSON-Schema subset the workflow platform
+ * supports (issue #1442).
+ *
+ * The server validator (`validateValue` in `schema-validation.ts`) and the CLI
+ * `workflows codegen` type converter (`workflow-codegen/schemaToTs.ts`) must
+ * agree EXACTLY on how a workflow `inputSchema`/`outputSchema` is interpreted —
+ * otherwise a generated `<Key>Input` type promises a shape the runtime does not
+ * enforce (or rejects a value the runtime accepts). Previously the converter
+ * re-derived those interpretation decisions by hand, which drifts from the
+ * validator over time.
+ *
+ * This module is the single source of that interpretation. Both consumers read
+ * from `describeSchema` + `isType`:
+ *
+ *   - the type gate is checked before `enum` (a value failing `type` is
+ *     rejected before `enum` is consulted);
+ *   - a type UNION (`type: ["string","null"]`) never descends into
+ *     `properties`/`items` — only the exact string types `"object"`/`"array"`
+ *     do;
+ *   - `integer` means `Number.isInteger`;
+ *   - `additionalProperties` only closes an object; it is not a nested schema.
+ *
+ * It is deliberately dependency-free (no imports) so the CLI can vendor a
+ * byte-for-byte copy as a committed artifact via
+ * `cli/scripts/gen-workflow-schema-descriptor.mjs` (the #998 gen-allowlist
+ * pattern). A drift-guard test runs that generator in `--check` mode, so a
+ * change here that isn't regenerated into the CLI artifact fails CI. The CLI
+ * never imports server `src/` at runtime — only the build-time generator reads
+ * this file.
+ */
+/** Does a value satisfy a JSON-schema `type` name? `integer` = `Number.isInteger`. */
+export declare function isType(value: any, type: string): boolean;
+/**
+ * The interpretation of a single schema node, normalized so both the validator
+ * and the type converter can consume it without re-reading raw schema fields.
+ */
+export interface SchemaDescriptor {
+    /** True when `schema.type` is an array (a type union). */
+    isUnion: boolean;
+    /** `schema.type` when it is a single string; null for a union or absent type. */
+    singularType: string | null;
+    /**
+     * The declared type(s) normalized to an array. An array `type` is kept as-is;
+     * a single string becomes a one-element array; an absent/falsy type is `[]`
+     * (no type gate). Matches the validator's `allowedTypes` normalization.
+     */
+    types: string[];
+    /** The `enum` array when present, else null. */
+    enumValues: any[] | null;
+    /**
+     * Object descent info — non-null ONLY when `schema.type` is exactly the
+     * string `"object"` AND `properties` is a declared object (matching the
+     * validator's `schema.type === "object" && schema.properties` descent gate).
+     * A type UNION containing `"object"` never descends.
+     */
+    object: {
+        /** The raw `properties` map (child schemas). May be empty `{}`. */
+        properties: Record<string, any>;
+        /** The raw `required` list (unfiltered, as the validator reads it). */
+        required: any[];
+        /** True when `additionalProperties === false` (a closed object). */
+        additionalPropertiesClosed: boolean;
+    } | null;
+    /**
+     * Array descent info — non-null ONLY when `schema.type` is exactly the string
+     * `"array"` AND `items` is present (matching the validator's
+     * `schema.type === "array" && schema.items` descent gate).
+     */
+    array: {
+        /** The raw `items` schema (may be a tuple array the validator no-ops on). */
+        items: any;
+    } | null;
+    /**
+     * Discriminated-union (tagged-union) interpretation of a `oneOf` node (#1511).
+     *
+     * Populated ONLY when the node carries a `oneOf` (or `anyOf`) array whose
+     * members are ALL `type: "object"` — a clearly-intended tagged union. A
+     * `oneOf`/`anyOf` with any non-object member is NOT a tagged union: `oneOf`
+     * stays `null` here and is ignored (renders `unknown` / validates
+     * permissively) exactly as before, preserving backward compatibility.
+     *
+     *   - `kind: "valid"` — a clean discriminated union: ≥2 object members sharing
+     *     exactly one discriminator property declared as a single-literal `enum`
+     *     in every member with distinct literals across members. The validator
+     *     branch-selects by `discriminant` and validates only the matched member;
+     *     the type converter renders the `|`-union of member object types.
+     *   - `kind: "invalid"` — an all-object-member union that LOOKS like a tagged
+     *     union but is defective (fewer than 2 members, no/ambiguous discriminator,
+     *     or `anyOf` — unsupported in v1). `reason` is the codegen error message.
+     *     The runtime validator ignores this (stays permissive); the codegen
+     *     converter throws `reason` (Fork 3 = strict, resolved by the maintainer).
+     */
+    oneOf: {
+        kind: "valid";
+        /** The auto-detected discriminator property name. */
+        discriminant: string;
+        /** One entry per member: its discriminant literal + raw member schema. */
+        members: Array<{
+            discriminantValue: any;
+            schema: any;
+        }>;
+    } | {
+        kind: "invalid";
+        reason: string;
+    } | null;
+}
+/**
+ * Interpret a parsed schema node. A non-object schema (null, array, scalar)
+ * enforces nothing → the empty descriptor.
+ */
+export declare function describeSchema(schema: any): SchemaDescriptor;