@pikku/core 0.12.67 → 0.12.70

package/src/wirings/cli/command-parser.test.ts

@@ -74,6 +74,20 @@ const testMeta: CLIMeta = {
           positionals: [{ name: 'name', required: false }],
           options: {},
         },
+        serve: {
+          pikkuFuncId: 'serveFunc',
+          positionals: [],
+          options: {
+            browser: {
+              description: 'Open a browser',
+              default: true,
+            },
+            port: {
+              description: 'Port to listen on',
+              default: 8080,
+            },
+          },
+        },
       },
     },
   },
@@ -103,6 +117,52 @@ describe('Command Parser', () => {
       assert.strictEqual(result.errors.length, 0)
     })
 
+    test('should turn a boolean option off with --no-<flag>', () => {
+      const result = parseCLIArguments(
+        ['serve', '--no-browser'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.strictEqual(result.options.browser, false)
+      assert.strictEqual(result.errors.length, 0)
+      assert.deepStrictEqual(
+        result.warnings ?? [],
+        [],
+        '--no-browser is the negation of a known option, not an unknown one'
+      )
+    })
+
+    test('should leave a boolean option at its default when not negated', () => {
+      const result = parseCLIArguments(['serve'], 'test-cli', testMeta)
+
+      assert.strictEqual(result.options.browser, true)
+    })
+
+    test('should not consume the next argument when negating', () => {
+      const result = parseCLIArguments(
+        ['serve', '--no-browser', '--port', '4077'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.strictEqual(result.options.browser, false)
+      assert.strictEqual(result.options.port, 4077)
+    })
+
+    test('should still warn about an unknown --no-<flag>', () => {
+      const result = parseCLIArguments(
+        ['serve', '--no-telemetry'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.ok(
+        (result.warnings ?? []).length > 0,
+        'negating an option that does not exist is a typo, not a feature'
+      )
+    })
+
     test('should parse command with short flag', () => {
       const result = parseCLIArguments(
         ['greet', 'Alice', '-l'],

package/src/wirings/cli/command-parser.ts

@@ -210,8 +210,19 @@ export function parseCLIArguments(
 
     if (arg.startsWith('--')) {
       // Long option (--from-plan → fromPlan)
+      const negatedKey = arg.startsWith('--no-')
+        ? toCamelCase(arg.slice(5))
+        : undefined
       const equalIndex = arg.indexOf('=')
-      if (equalIndex > 0) {
+      if (
+        negatedKey &&
+        typeof availableOptions[negatedKey]?.default === 'boolean'
+      ) {
+        // --no-<flag> turns a boolean option off. Only options that declare a
+        // boolean default can be negated, so a literal `--no-something` option
+        // name still parses as itself.
+        optionArgs[negatedKey] = false
+      } else if (equalIndex > 0) {
         // --option=value format
         const key = toCamelCase(arg.slice(2, equalIndex))
         const optionDef = availableOptions[key]

package/src/wirings/queue/index.ts

@@ -1,6 +1,8 @@
 export type {
   ConfigValidationResult,
   CoreQueueWorker,
+  GroupConcurrencyConfig,
+  JobGroup,
   JobOptions,
   PikkuJobConfig,
   PikkuWorkerConfig,

package/src/wirings/queue/queue.types.ts

@@ -31,6 +31,36 @@ export interface PikkuWorkerConfig {
   maxStalledCount?: number
   /** Condition to start processor at instance creation */
   autorun?: boolean
+  /**
+   * Cap how many jobs of any one group ({@link JobOptions.group}) may run at
+   * once, so a single group can't occupy the whole worker. Lets one shared
+   * queue stay fair across producers instead of splitting it into one queue
+   * per producer — which multiplies polling cost on pull-based backends.
+   * Must not exceed {@link batchSize}.
+   */
+  groupConcurrency?: number | GroupConcurrencyConfig
+}
+
+/**
+ * Per-group concurrency limits, optionally varied by tier so slow groups can
+ * be allowed more (or fewer) slots than the default.
+ */
+export interface GroupConcurrencyConfig {
+  /** Limit applied to any group without a matching tier */
+  default: number
+  /** Per-tier overrides, keyed by {@link JobGroup.tier} */
+  tiers?: Record<string, number>
+}
+
+/**
+ * Fairness key for a job. Jobs sharing an `id` count against the same
+ * {@link PikkuWorkerConfig.groupConcurrency} limit.
+ */
+export interface JobGroup {
+  /** Group this job belongs to (e.g. a workflow name) */
+  id: string
+  /** Optional tier selecting a per-tier limit */
+  tier?: string
 }
 
 /**
@@ -113,6 +143,8 @@ export interface JobOptions {
   jobId?: string
   /** Pikku user ID to propagate to the queue worker for credential resolution */
   pikkuUserId?: string
+  /** Fairness key — counts against the worker's {@link PikkuWorkerConfig.groupConcurrency} */
+  group?: JobGroup
 }
 
 /**

package/src/wirings/rpc/rpc-runner.test.ts

@@ -29,11 +29,13 @@ const registerFunction = (
     expose,
     pikkuFuncId,
     tags,
+    scenarioStep,
   }: {
     packageName?: string | null
     expose?: boolean
     pikkuFuncId?: string
     tags?: string[]
+    scenarioStep?: boolean
   } = {}
 ) => {
   addFunction(funcName, { func } as never, packageName)
@@ -44,6 +46,7 @@ const registerFunction = (
     permissions: [],
     expose,
     tags,
+    scenarioStep,
   } as never
 }
 
@@ -312,6 +315,27 @@ describe('ContextAwareRPCService.rpcExposed', () => {
     )
   })
 
+  test('a scenario step is not callable over the network, even if marked exposed', async () => {
+    // A step may drive a browser or assert against fixtures, so it is a step
+    // RPC — dispatched by name inside a run, never reachable from outside it.
+    pikkuState(null, 'rpc', 'meta').seesAddonCard = 'seesAddonCard'
+    registerFunction('seesAddonCard', async () => ({ visible: true }), {
+      expose: true,
+      scenarioStep: true,
+    })
+
+    const service = new ContextAwareRPCService(
+      createServices(),
+      {} as never,
+      {}
+    )
+
+    await assert.rejects(
+      () => service.rpcExposed('seesAddonCard', {}),
+      RPCNotFoundError
+    )
+  })
+
   test('runs exposed addon functions', async () => {
     pikkuState(null, 'addons', 'packages').set('addon', {
       package: '@addon/pkg',
@@ -669,7 +693,9 @@ describe('wireRemoteAddon dispatch', () => {
         {}
       )
 
-      const result = await service.rpc('registry:getOpenApi', { name: 'stripe' })
+      const result = await service.rpc('registry:getOpenApi', {
+        name: 'stripe',
+      })
 
       assert.deepEqual(result, { echoed: 42 })
       assert.equal(calls.length, 1)
@@ -713,10 +739,7 @@ describe('wireRemoteAddon dispatch', () => {
       )
 
       await service.rpc('registry:getOpenApi', {})
-      assert.equal(
-        calls[0]!.init.headers.authorization,
-        'Bearer user-token-9'
-      )
+      assert.equal(calls[0]!.init.headers.authorization, 'Bearer user-token-9')
     } finally {
       restoreFetch()
     }

package/src/wirings/rpc/rpc-runner.ts

@@ -165,7 +165,7 @@ export class ContextAwareRPCService {
     if (!functionMeta) {
       throw new RPCNotFoundError(funcName)
     }
-    if (!functionMeta.expose) {
+    if (!functionMeta.expose || functionMeta.scenarioStep) {
       throw new RPCNotFoundError(funcName)
     }
     return await this.rpc(funcName, data)

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

@@ -7,6 +7,10 @@ import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 import type { WorkflowRun } from '../workflow.types.js'
 import type { ScenarioActor } from '../../../services/scenario-actors-service.js'
+import type {
+  ScenarioStepOptions,
+  ScenarioStepPhase,
+} from '../scenario-step.types.js'
 
 /**
  * Workflow step options
@@ -79,6 +83,19 @@ export type WorkflowWireDoInline = <T>(
   options?: WorkflowStepOptions
 ) => Promise<T>
 
+/**
+ * Type signature for scenario.step/given/when/then - used by inspector.
+ *
+ * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
+ * an imported symbol, so the extractor reads it as a literal.
+ */
+export type ScenarioStepInvocation = <TOutput = any, TInput = any>(
+  stepName: string,
+  stepFunc: string,
+  data?: TInput,
+  options?: ScenarioStepOptions
+) => Promise<TOutput>
+
 /**
  * Type signature for workflow.sleep() - used by inspector
  */
@@ -180,6 +197,34 @@ export interface RpcStepMeta {
   expectEventually?: boolean
 }
 
+/**
+ * Scenario step metadata — a call to `scenario.step/given/when/then`.
+ *
+ * Distinct from RpcStepMeta on purpose: a step runs locally through
+ * runPikkuFunc and must never be treated as dispatchable on the queue/replay
+ * path, nor registered as a callable RPC (a browser-driving step must not be
+ * network-invocable).
+ */
+export interface ScenarioStepMeta {
+  type: 'scenarioStep'
+  /** Cache key (first argument), ordinal-suffixed by the engine when repeated */
+  stepName: string
+  /** Registered name of the step function being run */
+  stepFunc: string
+  /** Which keyword the reporter prefixes — given/when/then, or none for `step` */
+  phase: ScenarioStepPhase
+  /** Output variable name (if assigned) */
+  outputVar?: string
+  /** Input source mappings, or 'passthrough' when entire data is passed */
+  inputs?: Record<string, InputSource> | 'passthrough'
+  /** Step options */
+  options?: WorkflowStepOptions
+  /** Scenario actor name this step runs as ({ actor: actors.x }) */
+  actor?: string
+  /** Mirrors the step function's `browser: true` declaration */
+  browser?: boolean
+}
+
 /**
  * Simple condition expression (leaf node)
  */
@@ -223,7 +268,7 @@ export interface BranchStepMeta {
 export interface ParallelGroupStepMeta {
   type: 'parallel'
   /** Child steps to execute in parallel */
-  children: RpcStepMeta[]
+  children: Array<RpcStepMeta | ScenarioStepMeta>
 }
 
 /**
@@ -244,7 +289,7 @@ export interface FanoutStepMeta {
   /** Execution mode */
   mode: 'parallel' | 'sequential'
   /** Steps to execute inline per iteration, in order */
-  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>
+  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta | ScenarioStepMeta>
   /** Time between iterations (sequential mode only) */
   timeBetween?: string
 }
@@ -409,6 +454,7 @@ export interface ArrayPredicateStepMeta {
  */
 export type WorkflowStepMeta =
   | RpcStepMeta
+  | ScenarioStepMeta
   | BranchStepMeta
   | ParallelGroupStepMeta
   | FanoutStepMeta
@@ -509,5 +555,43 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     options?: WorkflowExpectServiceOptions
   ) => Promise<void>
 
+  /**
+   * Run a registered scenario step. Shaped exactly like `do`'s RPC form —
+   * `(stepName, target, data, options)` — so the inspector reads the target as
+   * a string literal rather than resolving an imported symbol.
+   *
+   * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
+   */
+  step(
+    stepName: string,
+    stepFunc: string,
+    data?: any,
+    options?: ScenarioStepOptions
+  ): Promise<any>
+
+  /** `step` with a "Given" prefix in the rendered prose */
+  given(
+    stepName: string,
+    stepFunc: string,
+    data?: any,
+    options?: ScenarioStepOptions
+  ): Promise<any>
+
+  /** `step` with a "When" prefix in the rendered prose */
+  when(
+    stepName: string,
+    stepFunc: string,
+    data?: any,
+    options?: ScenarioStepOptions
+  ): Promise<any>
+
+  /** `step` with a "Then" prefix in the rendered prose */
+  then(
+    stepName: string,
+    stepFunc: string,
+    data?: any,
+    options?: ScenarioStepOptions
+  ): Promise<any>
+
   runScheduledTask: (name: string) => Promise<unknown>
 }

package/src/wirings/workflow/feature.test.ts

@@ -0,0 +1,131 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveFeatureScenarios } from './feature.js'
+import type { CoreFeature, CoreWorkflow } from './workflow.types.js'
+
+const scenario = (tags: string[] = []) =>
+  ({ tags, func: async () => ({}) }) as any
+
+const registered = (entries: Array<[string, any]>): Map<string, CoreWorkflow> =>
+  new Map(entries.map(([name, func]) => [name, { name, func }]))
+
+describe('resolveFeatureScenarios', () => {
+  test('resolves imported identifiers to the names they are registered under', () => {
+    const lazyLoad = scenario()
+    const roundTrip = scenario()
+    const features = new Map<string, CoreFeature>([
+      [
+        'credentialFeature',
+        {
+          name: 'Credential API',
+          scenarios: [lazyLoad, roundTrip],
+        },
+      ],
+    ])
+
+    const { entries, unresolved } = resolveFeatureScenarios(
+      features,
+      registered([
+        ['credentialLazyLoadScenario', lazyLoad],
+        ['credentialRoundTripScenario', roundTrip],
+      ])
+    )
+
+    assert.deepEqual(unresolved, [])
+    assert.deepEqual(
+      entries.map((e) => e.scenarioName),
+      ['credentialLazyLoadScenario', 'credentialRoundTripScenario']
+    )
+    assert.equal(entries[0]!.featureName, 'Credential API')
+    assert.equal(entries[0]!.featureId, 'credentialFeature')
+  })
+
+  test('keeps declaration order, including repeats of the same scenario', () => {
+    const roundTrip = scenario()
+    const features = new Map<string, CoreFeature>([
+      [
+        'credentialFeature',
+        {
+          name: 'Credential API',
+          scenarios: ['stripe', 'google', 'hmac-key'].map((name) => ({
+            scenario: roundTrip,
+            data: { name },
+          })),
+        },
+      ],
+    ])
+
+    const { entries } = resolveFeatureScenarios(
+      features,
+      registered([['credentialRoundTripScenario', roundTrip]])
+    )
+
+    assert.equal(entries.length, 3, 'a mapped loop is three separate runs')
+    assert.deepEqual(
+      entries.map((e) => e.data),
+      [{ name: 'stripe' }, { name: 'google' }, { name: 'hmac-key' }]
+    )
+    assert.ok(
+      entries.every((e) => e.scenarioName === 'credentialRoundTripScenario')
+    )
+  })
+
+  test('a bare reference carries no data', () => {
+    const lazyLoad = scenario()
+    const { entries } = resolveFeatureScenarios(
+      new Map([['f', { name: 'F', scenarios: [lazyLoad] } as CoreFeature]]),
+      registered([['lazyLoadScenario', lazyLoad]])
+    )
+    assert.equal(entries[0]!.data, undefined)
+  })
+
+  test("a scenario's effective tags union its own with the feature's", () => {
+    const lazyLoad = scenario(['scenario', 'credential'])
+    const { entries } = resolveFeatureScenarios(
+      new Map([
+        [
+          'f',
+          {
+            name: 'F',
+            tags: ['nightly', 'credential'],
+            scenarios: [lazyLoad],
+          } as CoreFeature,
+        ],
+      ]),
+      registered([['lazyLoadScenario', lazyLoad]])
+    )
+    assert.deepEqual(entries[0]!.tags, ['scenario', 'credential', 'nightly'])
+  })
+
+  test('an unregistered scenario is reported, never silently matched by shape', () => {
+    const registeredScenario = scenario()
+    const lookalike = scenario()
+    const { entries, unresolved } = resolveFeatureScenarios(
+      new Map([
+        [
+          'f',
+          {
+            name: 'F',
+            scenarios: [registeredScenario, lookalike],
+          } as CoreFeature,
+        ],
+      ]),
+      registered([['realScenario', registeredScenario]])
+    )
+    assert.deepEqual(
+      entries.map((e) => e.scenarioName),
+      ['realScenario']
+    )
+    assert.deepEqual(unresolved, [{ featureId: 'f', index: 1 }])
+  })
+
+  test('a feature with no scenarios contributes nothing', () => {
+    const { entries, unresolved } = resolveFeatureScenarios(
+      new Map([['f', { name: 'F', scenarios: [] } as CoreFeature]]),
+      registered([])
+    )
+    assert.deepEqual(entries, [])
+    assert.deepEqual(unresolved, [])
+  })
+})

package/src/wirings/workflow/feature.ts

@@ -0,0 +1,78 @@
+import { pikkuState } from '../../pikku-state.js'
+import type {
+  CoreFeature,
+  CoreWorkflow,
+  FeaturePlanEntry,
+} from './workflow.types.js'
+
+/**
+ * Register a feature under the name it is exported as. Called from generated
+ * wiring, the same way `addWorkflow` is.
+ */
+export const addFeature = (
+  featureId: string,
+  feature: CoreFeature,
+  packageName: string | null = null
+) => {
+  pikkuState(packageName, 'workflows', 'features').set(featureId, feature)
+}
+
+/**
+ * Resolve every feature's scenario references back to the names their
+ * scenarios are registered under.
+ *
+ * Matching is by **object identity**: `pikkuScenario` returns its config
+ * verbatim and `addWorkflow` registers that same object, so a feature holding
+ * the imported identifier holds the very object that was registered. Nothing
+ * is matched by shape, by name, or by any other guess — which is also why a
+ * scenario built inline inside a feature (and therefore never registered)
+ * comes back as unresolved rather than silently running as something else.
+ *
+ * Entries are returned in declaration order, features in registration order.
+ * A scenario's effective tags are its own plus the containing feature's, so
+ * `--tags credential` selects through the feature.
+ */
+export const resolveFeatureScenarios = (
+  features: Map<string, CoreFeature>,
+  registrations: Map<string, CoreWorkflow>
+): {
+  entries: FeaturePlanEntry[]
+  unresolved: Array<{ featureId: string; index: number }>
+} => {
+  const nameByConfig = new Map<unknown, string>()
+  for (const [name, registration] of registrations) {
+    nameByConfig.set(registration.func, name)
+  }
+
+  const entries: FeaturePlanEntry[] = []
+  const unresolved: Array<{ featureId: string; index: number }> = []
+
+  for (const [featureId, feature] of features) {
+    const scenarios = feature.scenarios ?? []
+    for (let index = 0; index < scenarios.length; index++) {
+      const entry = scenarios[index]!
+      const paired =
+        typeof entry === 'object' && entry !== null && 'scenario' in entry
+      const config = paired ? (entry as any).scenario : entry
+      const scenarioName = nameByConfig.get(config)
+      if (!scenarioName) {
+        unresolved.push({ featureId, index })
+        continue
+      }
+      entries.push({
+        featureId,
+        featureName: feature.name ?? featureId,
+        scenarioName,
+        data: paired ? (entry as any).data : undefined,
+        tags: [
+          ...new Set([
+            ...((registrations.get(scenarioName)?.func as any)?.tags ?? []),
+            ...(feature.tags ?? []),
+          ]),
+        ],
+      })
+    }
+  }
+
+  return { entries, unresolved }
+}

package/src/wirings/workflow/index.ts

@@ -11,6 +11,11 @@ export {
   WorkflowApprovalResolvedError,
   DEFAULT_STEP_RETRIES,
 } from './pikku-workflow-service.js'
+export type {
+  RunLifecycleContext,
+  WorkflowRunEngine,
+  WorkflowRunExtension,
+} from './pikku-workflow-service.js'
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js'
 
 // Time-travel: reconstruct run state at any point from durable history
@@ -29,6 +34,7 @@ export type {
 
 // Internal registration functions (used by generated code)
 export { addWorkflow } from './dsl/workflow-runner.js'
+export { addFeature, resolveFeatureScenarios } from './feature.js'
 
 // Graph helpers (template, pikkuWorkflowGraph)
 export { template, type TemplateString } from './graph/template.js'
@@ -59,6 +65,7 @@ export type {
 // Re-export all types from workflow.types
 export type {
   WorkflowService,
+  WorkflowQueueOptions,
   WorkflowServiceConfig,
   WorkflowPlannedStep,
   WorkflowRunWire,
@@ -71,6 +78,12 @@ export type {
   WorkflowRunService,
   WorkflowRunMirror,
   CoreWorkflow,
+  CoreFeature,
+  CoreFeatureScenario,
+  FeatureMeta,
+  FeatureMetaEntry,
+  FeaturesMeta,
+  FeaturePlanEntry,
   PikkuWorkflow,
   ContextVariable,
   WorkflowContext,
@@ -112,8 +125,69 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
+  ScenarioStepInvocation,
+  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
   PikkuScenarioWire,
 } from './workflow.types.js'
+
+/* ------------------------------------------------------------------ *
+ * Scenarios — writing a step
+ *
+ * What a step file imports. Everything here is reached from inside a
+ * `pikkuScenarioStep` body.
+ * ------------------------------------------------------------------ */
+
+// The step's own wire, and the shape of what it was given
+export type {
+  ScenarioStepPhase,
+  ScenarioStepOptions,
+  PikkuScenarioStepWire,
+  ScenarioEnvironment,
+} from './scenario-step.types.js'
+
+// Narrows the optional halves of the step wire, with a message that says what to do
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
+
+// Waits for the target to catch up, without every step writing the loop again
+export { pollUntil, type PollOptions } from './scenario-poll.js'
+
+// Persists cookies across a step's requests, the way a browser would
+export { createCookieJar } from './scenario-cookie-jar.js'
+export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
+
+// What the transport answered — an actor's `invokeRaw`, or a route reached
+// directly — and the one way to POST JSON at a route and keep its status
+export type {
+  ScenarioHttpResponse,
+  ScenarioJsonRequest,
+} from '../../services/scenario-actors-service.js'
+export {
+  readScenarioHttpResponse,
+  postScenarioJson,
+} from '../../services/scenario-actors-service.js'
+
+/* ------------------------------------------------------------------ *
+ * Scenarios — driving a browser
+ *
+ * How a step names an element, and what a driver package
+ * (`@pikku/playwright`, or another) implements.
+ * ------------------------------------------------------------------ */
+
+export type {
+  PikkuBrowserWire,
+  TestIdSelector,
+  ScenarioBrowserProvider,
+  ScenarioBrowserFailure,
+} from './scenario-step.types.js'
+
+/* ------------------------------------------------------------------ *
+ * Scenarios — reporting a run
+ *
+ * Used by the CLI reporter and the console, so the two render the same
+ * sentence for the same step. A step body needs none of it.
+ * ------------------------------------------------------------------ */
+
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js'