@pikku/core 0.12.67 → 0.12.70

package/src/wirings/workflow/workflow.types.ts

@@ -1,5 +1,9 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
-import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
+import type {
+  CorePikkuFunctionConfig,
+  CorePikkuFunctionHook,
+} from '../../function/functions.types.js'
+import type { GroupConcurrencyConfig } from '../queue/queue.types.js'
 
 // Re-export WorkflowService from services module
 export type { WorkflowService } from '../../services/workflow-service.js'
@@ -37,12 +41,23 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
+  ScenarioStepInvocation,
+  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
   PikkuScenarioWire,
 } from './dsl/workflow-dsl.types.js'
 
+// Re-export scenario step types
+export type {
+  ScenarioStepPhase,
+  ScenarioStepOptions,
+  PikkuScenarioStepWire,
+  PikkuBrowserWire,
+  ScenarioBrowserProvider,
+} from './scenario-step.types.js'
+
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js'
 
 export interface WorkflowRunWire {
@@ -62,6 +77,44 @@ export interface WorkflowServiceConfig {
   sleeperRPCName: string
 }
 
+/**
+ * How a workflow service spreads its jobs across queues.
+ *
+ * Passed to the service constructor rather than read from `config.workflow`:
+ * the queues are wired during construction, before singleton services (and so
+ * before `config`) exist.
+ */
+export interface WorkflowQueueOptions {
+  /**
+   * - `'per-workflow'` (default) — each workflow gets its own
+   *   `wf-orchestrator-*` / `wf-step-*` queue. Complete isolation, and it's
+   *   what lets serverless providers deploy one unit per workflow. Costs one
+   *   set of pollers per queue, which adds up on pull-based backends.
+   * - `'shared-groups'` — every workflow shares the orchestrator/step-worker
+   *   queues and stays isolated via {@link queueGroupConcurrency}, so no
+   *   workflow can occupy more than its share. One set of pollers total.
+   *   Only for single-process (monolith) runtimes; a per-unit serverless
+   *   deploy needs the per-workflow queues to route to its units.
+   */
+  queueStrategy?: 'per-workflow' | 'shared-groups'
+  /**
+   * Total concurrent workflow jobs per node under `'shared-groups'`.
+   * Defaults to 20.
+   */
+  queueConcurrency?: number
+  /**
+   * How many jobs of one workflow may run at once under `'shared-groups'`.
+   * Defaults to 2. Tiers are keyed by workflow name, so a specific workflow
+   * can be given its own limit without any extra wiring.
+   *
+   * Note tiers can only lower a workflow's limit, not raise it above
+   * `default`: the backend's pre-fetch exclusion is applied per group using
+   * `default` alone. To give one workflow more room, raise `default` and
+   * restrict the others by tier.
+   */
+  queueGroupConcurrency?: number | GroupConcurrencyConfig
+}
+
 export interface WorkflowPlannedStep {
   /** Durable step key — matches the runtime step name stored in the DB */
   stepName: string
@@ -290,6 +343,82 @@ export type CoreWorkflow<
   tags?: string[]
 }
 
+/**
+ * A scenario as a feature references it: either the scenario itself, or the
+ * scenario paired with the input to run it with. The paired form is gherkin's
+ * `Examples:` — the same scenario run once per row, written as an ordinary
+ * loop rather than a table.
+ */
+export type CoreFeatureScenario =
+  | CorePikkuFunctionConfig<any, any, any>
+  | { scenario: CorePikkuFunctionConfig<any, any, any>; data: unknown }
+
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * Hooks run **once around the whole group** (`before → a → b → c → after`),
+ * not per scenario — per-scenario setup is the scenario's own `before`. That
+ * is the one thing a feature deliberately cannot express: gherkin's
+ * `Background:` runs per scenario.
+ */
+export type CoreFeature = {
+  /** Human-readable name. The export identifier is the id. */
+  name: string
+  description?: string
+  tags?: string[]
+  /** Readonly because `pikkuFeature`'s `const` generic infers a readonly tuple. */
+  scenarios: readonly CoreFeatureScenario[]
+  before?: CorePikkuFunctionHook
+  after?: CorePikkuFunctionHook
+}
+
+/** One entry of a feature's scenario list, as extracted from the source. */
+export type FeatureMetaEntry = {
+  /** The scenario's declared export name — its key in `WorkflowsMeta`. */
+  scenario: string
+  /** The input this entry runs the scenario with — gherkin's `Examples:`. */
+  data?: unknown
+}
+
+/**
+ * A feature as the console reads it: the document structure around a group of
+ * scenarios. Generated to `scenarios/features.gen.json` and read off disk, so
+ * nothing app-facing has to import the scenario bootstrap to describe one.
+ */
+export type FeatureMeta = {
+  /** The export identifier. */
+  id: string
+  name: string
+  description?: string
+  tags: string[]
+  /** In declared order — a feature's reading order is its declaration order. */
+  entries: FeatureMetaEntry[]
+  /**
+   * Entries that could not be read statically (a spread, a `.map()`). Their
+   * membership is only known once the scenario bootstrap has been evaluated,
+   * so a non-zero count means this listing is partial.
+   */
+  unresolvedEntries: number
+  /** Hooks are runtime-only; only their presence is knowable from meta. */
+  hasBefore: boolean
+  hasAfter: boolean
+}
+
+export type FeaturesMeta = Record<string, FeatureMeta>
+
+/** One planned scenario run, resolved from a feature's scenario list. */
+export type FeaturePlanEntry = {
+  featureId: string
+  featureName: string
+  scenarioName: string
+  /** The input this entry runs the scenario with, if the feature supplied one. */
+  data?: unknown
+  /** The scenario's own tags unioned with the containing feature's. */
+  tags: string[]
+}
+
 /**
  * Workflow client interface
  */
@@ -332,6 +461,13 @@ export type WorkflowsMeta = Record<
     expose?: boolean
     /** True for pikkuScenario workflows (complex + actor steps). */
     scenario?: boolean
+    /**
+     * Why a scenario is held out of a default run. Stating the reason in code
+     * keeps the quarantine next to the scenario it applies to, rather than in
+     * a CI invocation nobody reads. Naming the scenario with `--flows` runs it
+     * regardless.
+     */
+    skip?: string
     /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[]
   }