@pikku/core 0.12.64 → 0.12.67

package/src/wirings/gateway/gateway.types.ts

@@ -4,11 +4,7 @@ import type {
   CorePikkuMiddlewareGroup,
   CoreSingletonServices,
 } from '../../types/core.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePermissionGroup,
-  CorePikkuPermission,
-} from '../../function/functions.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { PikkuHTTPRequest } from '../http/http.types.js'
 
 /**
@@ -124,7 +120,6 @@ export type GatewayTransportType = 'webhook' | 'websocket' | 'listener'
  */
 export type CoreGateway<
   PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>,
-  PikkuPermission extends CorePikkuPermission = CorePikkuPermission,
   PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware,
 > = Partial<
   Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>
@@ -143,11 +138,14 @@ export type CoreGateway<
   func: PikkuFunctionConfig
   /** Optional middleware chain (e.g., auth) */
   middleware?: CorePikkuMiddlewareGroup<any, any>
-  /** Optional permissions */
-  permissions?: CorePermissionGroup | PikkuPermission[]
   /** Optional tags for categorization */
   tags?: string[]
-  /** Whether authentication is required (default: true) */
+  /**
+   * Whether the handler requires a session. Left unset, the handler's own
+   * `auth` governs, and a gateway handler is sessionless by default — inbound
+   * gateway traffic is platform-authenticated by the adapter, not
+   * session-bearing. Set `true` to require a session for every message.
+   */
   auth?: boolean
 }
 

package/src/wirings/http/http.types.ts

@@ -126,8 +126,10 @@ export type CoreHTTPFunctionWiring<
   > = CorePikkuFunctionSessionless<In, Out>,
   PikkuPermission extends CorePikkuPermission<In, any, any> =
     CorePikkuPermission<In, any, any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any> =
-    CorePikkuMiddleware<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
 > =
   | (CoreHTTPFunction & {
       route: R
@@ -287,7 +289,7 @@ export type HTTPRouteConfig<
     | CorePikkuFunction<any, any, any, any, any>
     | CorePikkuFunctionSessionless<any, any, any, any, any>,
   PikkuPermission extends CorePikkuPermission<any, any, any> =
-    CorePikkuPermission<any>,
+    CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
     any,
     any
@@ -313,7 +315,7 @@ export type HTTPRouteConfig<
  */
 export type HTTPRoutesGroupConfig<
   PikkuPermission extends CorePikkuPermission<any, any, any> =
-    CorePikkuPermission<any>,
+    CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
     any,
     any

package/src/wirings/scope/scope.test.ts

@@ -62,6 +62,31 @@ describe('flattenScopeDefinitions', () => {
       ['admin', 'admin:users', 'billing']
     )
   })
+
+  // An addon and its host app may both contribute the same root. Codegen writes
+  // these ids into an object literal, where a repeat is a TypeScript error.
+  test('a root declared twice is flattened once', () => {
+    const tree = { users: { scopes: { ban: {} } } }
+    const definitions: ScopeDefinitions = [
+      { name: 'admin', description: 'Administration', scopes: tree },
+      { name: 'admin', description: 'Administration', scopes: tree },
+    ]
+
+    assert.deepEqual(
+      flattenScopeDefinitions(definitions).map((s) => s.id),
+      ['admin', 'admin:users', 'admin:users:ban']
+    )
+  })
+
+  test('the first description of a repeated scope wins', () => {
+    assert.deepEqual(
+      flattenScopeDefinitions([
+        { name: 'admin', description: 'Administration' },
+        { name: 'admin', description: 'Something else' },
+      ]),
+      [{ id: 'admin', description: 'Administration' }]
+    )
+  })
 })
 
 describe('validateAndBuildScopeDefinitionsMeta', () => {

package/src/wirings/scope/validate-scope-definitions.ts

@@ -52,6 +52,14 @@ const flattenNodes = (
  * Flattens declared scope trees into the full list of grantable scope ids,
  * depth-first. Every node is emitted, including intermediate ones.
  *
+ * Ids are unique. A root may legitimately be declared more than once — an addon
+ * and its host app both contributing the same `admin` tree, say — and
+ * {@link validateAndBuildScopeDefinitionsMeta} already guarantees those
+ * declarations are identical, so the second one is redundant rather than
+ * conflicting. Collapsing it here keeps every consumer honest: codegen emits an
+ * object literal keyed by id (duplicates are a TypeScript error), and a
+ * ScopeService syncs one row per scope instead of re-writing the same one.
+ *
  * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
  * the declared set into its store.
  */
@@ -63,7 +71,14 @@ export const flattenScopeDefinitions = (
     out.push({ id: def.name, description: def.description })
     flattenNodes(def.scopes, def.name, out)
   }
-  return out
+  const seen = new Set<string>()
+  return out.filter((scope) => {
+    if (seen.has(scope.id)) {
+      return false
+    }
+    seen.add(scope.id)
+    return true
+  })
 }
 
 /**

package/src/wirings/secret/secret.types.ts

@@ -4,6 +4,13 @@ export type CoreSecret<T = unknown> = {
   description?: string
   secretId: string
   schema: T
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   /**
    * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
    * Stored in the generated secrets metadata so consumers can tell when a
@@ -27,6 +34,13 @@ export type SecretDefinitionMeta = {
   description?: string
   secretId: string
   schema?: Record<string, unknown> | string
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   oauth2?: OAuth2CredentialConfig
   rotationPeriod?: string
   sourceFile?: string

package/src/wirings/secret/validate-secret-definitions.ts

@@ -58,6 +58,7 @@ export function validateAndBuildSecretDefinitionsMeta(
           schema: def.schema,
           oauth2: def.oauth2,
           rotationPeriod: def.rotationPeriod,
+          docsUrl: def.docsUrl,
           sourceFile: def.sourceFile,
         }
       }
@@ -75,6 +76,7 @@ export function validateAndBuildSecretDefinitionsMeta(
         schema: def.schema,
         oauth2: def.oauth2,
         rotationPeriod: def.rotationPeriod,
+        docsUrl: def.docsUrl,
         sourceFile: def.sourceFile,
       }
     }

package/src/wirings/variable/validate-variable-definitions.ts

@@ -45,6 +45,7 @@ export function validateAndBuildVariableDefinitionsMeta(
           description: def.description,
           variableId: def.variableId,
           schema: def.schema,
+          docsUrl: def.docsUrl,
           sourceFile: def.sourceFile,
         }
       }
@@ -60,6 +61,7 @@ export function validateAndBuildVariableDefinitionsMeta(
         description: def.description,
         variableId: def.variableId,
         schema: def.schema,
+        docsUrl: def.docsUrl,
         sourceFile: def.sourceFile,
       }
     }

package/src/wirings/variable/variable.types.ts

@@ -4,6 +4,13 @@ export type CoreVariable<T = unknown> = {
   description?: string
   variableId: string
   schema: T
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
 }
 
 export type VariableDefinitionMeta = {
@@ -12,6 +19,13 @@ export type VariableDefinitionMeta = {
   description?: string
   variableId: string
   schema?: Record<string, unknown> | string
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   sourceFile?: string
 }
 

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

@@ -18,6 +18,13 @@ export interface WorkflowStepOptions {
   retries?: number
   /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
   retryDelay?: string | number
+  /**
+   * RPC to invoke for compensation when this step fails after exhausting its
+   * retries. Mirrors a graph node's `onError`: the handler receives
+   * `{ error: { message } }` and the original error is still thrown, so the
+   * workflow fails — this is compensation, not recovery.
+   */
+  onError?: string
   /**
    * Run this step as an actor (scenarios). The RPC is sent through the
    * actor's authenticated client over the REAL transport — never dispatched
@@ -224,16 +231,20 @@ export interface ParallelGroupStepMeta {
  */
 export interface FanoutStepMeta {
   type: 'fanout'
-  /** Step name for this fanout */
-  stepName: string
+  /**
+   * Step name for this fanout. Optional: a fanout is not itself a cached step,
+   * and node ids are step names — borrowing a body step's name would give the
+   * loop and that step the same id, collapsing one onto the other.
+   */
+  stepName?: string
   /** Source array variable name */
   sourceVar: string
   /** Iterator variable name */
   itemVar: string
   /** Execution mode */
   mode: 'parallel' | 'sequential'
-  /** Child step to execute per iteration */
-  child: RpcStepMeta
+  /** Steps to execute inline per iteration, in order */
+  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>
   /** Time between iterations (sequential mode only) */
   timeBetween?: string
 }
@@ -245,6 +256,12 @@ export interface ReturnStepMeta {
   type: 'return'
   /** Output bindings */
   outputs: Record<string, OutputBinding>
+  /**
+   * Variables spread into the returned object (`return { ...r }`), or the sole
+   * returned variable (`return r`). Their fields are not enumerable statically,
+   * so they are recorded by name rather than expanded into `outputs`.
+   */
+  spread?: string[]
 }
 
 /**
@@ -271,6 +288,13 @@ export interface SleepStepMeta {
   stepName: string
   /** Sleep duration */
   duration: string | number
+  /**
+   * Source text of a duration only known at runtime (e.g. a loop variable).
+   * The closure evaluates it, so it is legal DSL; it is kept separate from
+   * `duration` so regenerated code emits it raw rather than as a string
+   * literal, exactly as `expression` does on a set step.
+   */
+  expression?: string
 }
 
 /**
@@ -291,8 +315,14 @@ export interface SetStepMeta {
   type: 'set'
   /** Variable name to set (must be in context) */
   variable: string
-  /** Value to assign (literal or expression) */
-  value: unknown
+  /** Literal value to assign. Mutually exclusive with `expression`. */
+  value?: unknown
+  /**
+   * Source text of a non-literal assignment (e.g. `count + 1`). Kept separate
+   * from `value` so regenerated code can emit it raw — a string `value` is a
+   * string literal, an `expression` is code.
+   */
+  expression?: string
 }
 
 /**

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -1825,6 +1825,30 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
   }
 
+  /**
+   * Run a failed step's compensation handler as a durable step of its own.
+   *
+   * Durable rather than a bare invoke so a replay does not compensate twice —
+   * a handler is typically a refund or a rollback. `onError` is deliberately
+   * not forwarded: a compensation handler cannot itself compensate.
+   */
+  private async runStepCompensation(
+    runId: string,
+    stepName: string,
+    onErrorRpcName: string,
+    rpcService: any,
+    error: Error
+  ): Promise<void> {
+    await this.rpcStep(
+      runId,
+      `${stepName}:onError`,
+      onErrorRpcName,
+      { error: { message: error.message } },
+      rpcService,
+      { retries: 0 }
+    )
+  }
+
   private async rpcStep(
     runId: string,
     logicalStepName: string,
@@ -1844,6 +1868,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
       retryDelay: stepOptions?.retryDelay,
       actor: stepOptions?.actor,
+      onError: stepOptions?.onError,
     }
     // Check if step already exists
     let stepState: StepState
@@ -1872,6 +1897,17 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         stepState.error?.message ||
           `Step '${stepName}' failed after exhausting all retries`
       )
+      // Compensation, mirroring a graph node's onError: run the handler, then
+      // still throw — the workflow fails either way.
+      if (resolvedStepOptions.onError) {
+        await this.runStepCompensation(
+          runId,
+          stepName,
+          resolvedStepOptions.onError,
+          rpcService,
+          error
+        )
+      }
       // Preserve original error properties if available
       if (stepState.error) {
         Object.assign(error, stepState.error)

package/src/wirings/workflow/workflow-on-error.test.ts

@@ -0,0 +1,154 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+
+/**
+ * Drive the real failure branch: a step that is already terminally failed must
+ * invoke its onError handler and still throw. Only the nested compensation
+ * call is intercepted, so the branch under test is the production one.
+ */
+class TestWorkflowService extends InMemoryWorkflowService {
+  public compensations: Array<{ rpcName: string; data: any }> = []
+  public dispatches = 0
+  private pretendDispatchSucceeds = false
+
+  public alwaysDispatch() {
+    this.pretendDispatchSucceeds = true
+  }
+
+  protected override async dispatchStep(...args: any[]): Promise<boolean> {
+    this.dispatches++
+    if (this.pretendDispatchSucceeds) {
+      return true
+    }
+    return (super.dispatchStep as any)(...args)
+  }
+
+  public async callFailedStep(
+    runId: string,
+    stepName: string,
+    onError?: string
+  ) {
+    const self = this as any
+    const realRpcStep = self.rpcStep.bind(self)
+    let depth = 0
+    self.rpcStep = async (...args: any[]) => {
+      if (depth++ > 0) {
+        this.compensations.push({ rpcName: args[2], data: args[3] })
+        return { compensated: true }
+      }
+      return realRpcStep(...args)
+    }
+    return self.rpcStep(runId, stepName, 'chargeCard', {}, {}, { onError })
+  }
+}
+
+/**
+ * Seed a step in a non-terminal state, as a replay would find one that is
+ * waiting on the queue rather than one that has failed.
+ */
+async function seedPendingStep(ws: TestWorkflowService, stepName: string) {
+  const runId = await ws.createRun('wf', {}, true, 'hash', {
+    type: 'inline',
+  } as any)
+  const step = await ws.insertStepState(runId, stepName, 'chargeCard', {})
+  return { runId, step }
+}
+
+async function seedFailedStep(ws: TestWorkflowService, stepName: string) {
+  const runId = await ws.createRun('wf', {}, true, 'hash', {
+    type: 'inline',
+  } as any)
+  const step = await ws.insertStepState(runId, stepName, 'chargeCard', {})
+  await (ws as any).updateStepStateImpl?.(runId, stepName, {
+    status: 'failed',
+    error: { message: 'card declined' },
+  })
+  const raw = (ws as any).steps ?? (ws as any).stepStates
+  if (raw?.get) {
+    const key = [...raw.keys()].find((k: string) => k.includes(stepName))
+    if (key) {
+      raw.set(key, {
+        ...raw.get(key),
+        status: 'failed',
+        error: { message: 'card declined' },
+      })
+    }
+  }
+  return { runId, step }
+}
+
+describe('workflow onError — compensation on terminal step failure', () => {
+  test('a failed step runs its handler and still throws the original error', async () => {
+    const ws = new TestWorkflowService()
+    const { runId } = await seedFailedStep(ws, 'Charge')
+
+    await assert.rejects(
+      () => ws.callFailedStep(runId, 'Charge', 'refundOrder'),
+      /card declined/,
+      'compensation must not swallow the failure — the workflow still fails'
+    )
+
+    assert.equal(
+      ws.compensations.length,
+      1,
+      'the onError handler must have been invoked'
+    )
+    assert.equal(ws.compensations[0].rpcName, 'refundOrder')
+    assert.deepEqual(
+      ws.compensations[0].data,
+      { error: { message: 'card declined' } },
+      'the handler receives the failure reason, as a graph onError node does'
+    )
+  })
+
+  test('a step still sitting on the queue pauses without compensating', async () => {
+    const ws = new TestWorkflowService()
+    const { runId, step } = await seedPendingStep(ws, 'Charge')
+    await ws.setStepScheduled(step.stepId)
+
+    await assert.rejects(
+      () => ws.callFailedStep(runId, 'Charge', 'refundOrder'),
+      (error: Error) => error.name === 'WorkflowAsyncException',
+      'a scheduled step must pause the workflow, not fail it'
+    )
+
+    assert.equal(
+      ws.compensations.length,
+      0,
+      'compensating a step that has not run yet would refund a charge that was never made'
+    )
+  })
+
+  test('the pause thrown right after dispatch does not compensate', async () => {
+    const ws = new TestWorkflowService()
+    ws.alwaysDispatch()
+    const { runId } = await seedPendingStep(ws, 'Charge')
+
+    await assert.rejects(
+      () => ws.callFailedStep(runId, 'Charge', 'refundOrder'),
+      (error: Error) => error.name === 'WorkflowAsyncException',
+      'a freshly dispatched step pauses the workflow'
+    )
+
+    assert.equal(ws.dispatches, 1, 'the step should have been dispatched once')
+    assert.equal(
+      ws.compensations.length,
+      0,
+      'queued is not failed — the handler must not run'
+    )
+  })
+
+  test('a failed step with no onError simply throws', async () => {
+    const ws = new TestWorkflowService()
+    const { runId } = await seedFailedStep(ws, 'Charge')
+
+    await assert.rejects(() => ws.callFailedStep(runId, 'Charge', undefined))
+    assert.equal(
+      ws.compensations.length,
+      0,
+      'no handler configured means nothing to compensate'
+    )
+  })
+})

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

@@ -286,8 +286,6 @@ export type CoreWorkflow<
   func: PikkuFunctionConfig
   /** Middleware chain for this workflow */
   middleware?: PikkuFunctionConfig['middleware']
-  /** Permission requirements */
-  permissions?: PikkuFunctionConfig['permissions']
   /** Tags for organization and filtering */
   tags?: string[]
 }