primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/dist/src/commands/workflows.d.ts

@@ -0,0 +1,116 @@
+import { Command } from "commander";
+/**
+ * Render the `Step Results` section of `workflows runs status`. Pure
+ * formatting helper — returns lines as strings so it's unit-testable
+ * (the caller console.logs them). For each step, emits:
+ *
+ *   `  <id>: <status-label> <duration>`
+ *
+ * and, when applicable, indented follow-up lines:
+ *
+ * - `error_captured` step with `error` → `    error: <truncated message>`
+ * - forEach output with `errors[]` non-empty →
+ *   `    forEach errors: <N/M> - first: <truncated message>`
+ *
+ * The truncation length matches `runs steps` ERROR column (80 chars,
+ * trailing "..." when truncated). See #688.
+ */
+/**
+ * Stop-polling predicate for the `workflows preview --wait` loop (issues #941,
+ * #2348). True when the run has settled and the wait should stop — as opposed
+ * to a still-in-flight status ("queued"/"running") that keeps the loop going
+ * until the cap.
+ *
+ * Since #2348 the server reconciles every status surface onto the canonical
+ * vocabulary before it goes on the wire, so this reads the one shared set in
+ * `lib/run-status.ts` instead of re-deriving terminality here:
+ *   - "completed" / "failed" / "terminated" — true terminals. "terminated" is
+ *     an aborted preview, a real end state (Codex P2 on #941: it used to be
+ *     omitted, so an abort was misreported as a wait timeout).
+ *   - "apply_pending" / "apply_claimed" — the run finished and is parked
+ *     waiting for a client to apply its result. It never advances on its own,
+ *     so the previous ladder spun here until the 60s cap.
+ *   - "missing" — no live instance to observe; more polling cannot help.
+ *
+ * The raw Cloudflare spellings ("complete"/"errored"/"waiting") are gone: the
+ * server no longer puts them on the wire, and matching them here would have
+ * kept two vocabularies alive.
+ */
+export declare function isPreviewWaitTerminalStatus(s: unknown): boolean;
+/**
+ * Which arm the `workflows preview --wait` render ladder takes (#2636).
+ *
+ * Extracted from the ladder so the branch decision is testable: the point of
+ * the `skipped` arm is that an elided preview — one whose declarative lock was
+ * held under `onContention: "ignore"` — reports that it did not run, instead
+ * of falling through to the timeout branch and exiting 124 as though it were
+ * still going.
+ */
+export declare function previewWaitOutcome(status: unknown): "completed" | "failed" | "terminated" | "skipped" | "apply" | "missing" | "timeout";
+export declare function renderRunStatusStepResults(stepResults: any[]): string[];
+/**
+ * #2771 — how long a step row has been going.
+ *
+ * A step that is still executing is persisted with status `running` and a
+ * `durationMs` of 0 (the column is required; the real value is written when the
+ * step ends). Printing that 0 hides the one number that matters while a run is
+ * in flight — how long the current step has been stuck — so a running row is
+ * measured from its `startedAt` instead. Finished rows keep their stored
+ * duration. Exported for testability.
+ */
+export declare function stepRunDisplayDurationMs(step: any, now?: number): number | null;
+/**
+ * #2771 — the step lines `workflows runs status` should render.
+ *
+ * Cloudflare's instance status carries `stepResults` only once the run reaches
+ * a terminal state, so a live run used to print `Status: running` and nothing
+ * else. The persisted step rows now exist DURING the run, so they are the
+ * fallback: mapped onto the shape `renderRunStatusStepResults` reads, with a
+ * running step's elapsed time in place of its 0 placeholder. The instance's own
+ * results always win when it has them. Exported for testability.
+ */
+export declare function stepResultsForRunStatus(instanceStepResults: any[] | undefined | null, persistedStepRuns: any[] | undefined | null, now?: number): any[];
+/**
+ * #1367 — annotate step-run rows with the inter-step gap: the wall-clock time
+ * between the previous step's `endedAt` and this step's `startedAt`. Sorts by
+ * `startedAt` when every row has a parseable one (tie-break `stepIndex`),
+ * otherwise by `stepIndex` for the whole list — the ordering mode must be
+ * chosen once for all rows, not per pair: a per-pair timestamp-vs-index
+ * fallback is not transitive when some rows lack a timestamp (A<B by index,
+ * B<C by index, C<A by time), and a non-transitive comparator leaves
+ * Array.prototype.sort free to return an arbitrary order, computing gaps
+ * against the wrong predecessor. The first step has no predecessor, so its
+ * `gapMs` is `null`. A gap is only meaningful when both adjacent timestamps
+ * parse and the gap is positive. When the immediate predecessor lacks a valid
+ * `endedAt`, the gap is left `null` rather than measured from an older,
+ * non-adjacent step — otherwise a later step could raise a false stall
+ * warning against a step it does not actually follow. Exported for
+ * testability.
+ */
+export declare function annotateStepGaps(steps: any[]): any[];
+/**
+ * #1367 — compute min / p50 / p95 / max over a set of latency samples (ms).
+ * Ignores non-finite values. Returns `null` when there are no valid samples.
+ * Percentiles use nearest-rank on the sorted samples. Exported for testability.
+ */
+export declare function summarizeLatencyDistribution(values: Array<number | null | undefined>): {
+    count: number;
+    min: number;
+    p50: number;
+    p95: number;
+    max: number;
+} | null;
+/**
+ * Issue #687 (review feedback): render an unambiguous label for a workflow
+ * config slot ("active config", "draft config", etc.) when the slot may be
+ * unnamed. Falls back to a short ID prefix so users staging multiple unnamed
+ * configs can still tell them apart.
+ *
+ *   formatConfigSlotLabel("active config", "v2", "01KRT...")        → 'active config "v2"'
+ *   formatConfigSlotLabel("active config", null, "01KRTABCDXYZ...") → 'active config (01KRTABCDXYZ…)'
+ *   formatConfigSlotLabel("active config", null, null)              → 'active config'
+ *
+ * Exported for testability.
+ */
+export declare function formatConfigSlotLabel(slot: string, configName: string | null | undefined, configId: string | null | undefined, prefixLength?: number): string;
+export declare function registerWorkflowsCommands(program: Command): void;