@pikku/core 0.12.72 → 0.12.74

package/src/services/trigger-service.ts

@@ -1,17 +1,5 @@
-/**
- * Abstract TriggerService interface.
- *
- * Implementations manage trigger subscriptions — listening to external events
- * and dispatching to RPC targets or workflow starts.
- */
 export interface TriggerService {
-  /**
-   * Start all triggers
-   */
   start(): Promise<void>
 
-  /**
-   * Stop all triggers
-   */
   stop(): Promise<void>
 }

package/src/services/typed-secret-service.ts

@@ -17,13 +17,7 @@ export type CredentialMeta = {
 export class TypedSecretService<
   TMap = Record<string, unknown>,
 > implements SecretService {
-  /**
-   * In-process cache of resolved secrets, so callers can read naively without
-   * re-hitting the underlying service on every call. Only successful reads are
-   * cached (a miss throws and isn't stored); `setSecret`/`deleteSecret`
-   * invalidate the key. No TTL — a secret rotated out-of-band won't refresh
-   * until restart (see pikkujs/pikku#964).
-   */
+  // knowledge: decisions/internals/typed-secret-service-caches-for-the-process-lifetime.md
   private cache = new Map<string, unknown>()
 
   constructor(

package/src/services/v8-coverage-service.ts

@@ -1,6 +1,3 @@
-// node:inspector is imported lazily inside start() so this module stays
-// loadable on runtimes without it (e.g. Cloudflare Workers).
-
 export interface CoverageRange {
   startOffset: number
   endOffset: number
@@ -71,9 +68,8 @@ export interface CoverageFunctionMeta {
 export interface CoverageService {
   start(): Promise<void>
   takeCoverage(): Promise<CoverageSnapshot>
-  /** Maps the current snapshot onto function body spans. Provided by the
-   *  process that booted the coverage backend (the pikku CLI) — absent when
-   *  the runtime only exposes raw snapshots. */
+  /** Provided by the process that booted the backend (the pikku CLI); absent
+   *  when the runtime only exposes raw snapshots. */
   takeReport?(
     functionsMeta: Record<string, CoverageFunctionMeta>
   ): Promise<FunctionCoverageReport>
@@ -113,6 +109,7 @@ export class V8CoverageService implements CoverageService {
   }
 
   private async doStart(): Promise<void> {
+    // knowledge: decisions/internals/node-only-builtins-are-imported-dynamically.md
     const inspector = await import('node:inspector')
     this.session = new inspector.Session() as unknown as InspectorSession
     this.session.connect()

package/src/services/variables-service.ts

@@ -1,13 +1,6 @@
 export interface VariablesService {
   get<T = string>(name: string): Promise<T | undefined> | T | undefined
-  /**
-   * Retrieves multiple variables in a single batch operation, mirroring
-   * `SecretService.getSecrets`. Missing variables are omitted rather than
-   * throwing, so the result is typed as `Partial<T>` and callers must handle
-   * keys that may be absent at runtime. Pass a shape as `T` to get a typed
-   * result without casting, e.g.
-   * `await variables.getVariables<{ FOO: string; BAR: string }>(['FOO', 'BAR'])`.
-   */
+  /** Same contract as `SecretService.getSecrets`: missing keys are omitted, hence `Partial<T>`. */
   getVariables<T extends Record<string, unknown> = Record<string, unknown>>(
     names: (keyof T & string)[]
   ): Promise<Partial<T>> | Partial<T>

package/src/services/webhook-service.ts

@@ -2,31 +2,18 @@ import { NotImplementedError } from '../errors/errors.js'
 import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js'
 
 export interface SendWebhookInput {
-  /** The endpoint the webhook is delivered to via HTTP POST. */
   url: string
-  /** Optional event name, sent as the `X-Pikku-Event` header. */
+  /** Sent as the `X-Pikku-Event` header. */
   event?: string
-  /** The payload, JSON-serialized into the request body. */
   data: unknown
-  /** Extra headers merged over the defaults. */
   headers?: Record<string, string>
-  /**
-   * Raw HMAC signing key for this delivery. Overrides the config-level
-   * secret. When present, the body is signed into the signature header.
-   */
+  /** A raw HMAC key, not a secret name — overrides `config.webhook.secret`. */
   secret?: string
-  /** Retry count for failed deliveries. Overrides `config.webhook.retries`. */
+  /** Overrides `config.webhook.retries`. */
   retries?: number
-  /**
-   * Delay between retries (`30000` or `'30s'`). A concrete value selects a
-   * fixed backoff; when omitted, backoff is exponential.
-   */
+  /** A concrete delay (`30000` or `'30s'`) selects fixed backoff; omitted means exponential. */
   retryDelay?: string | number
-  /**
-   * Organization this delivery belongs to. Persisted by a store-backed
-   * implementation (e.g. `KyselyWebhookService`) so deliveries can be
-   * queried per org; ignored by the queue-only default.
-   */
+  /** Persisted only by store-backed implementations; the queue-only default ignores it. */
   organizationId?: string
 }
 
@@ -35,25 +22,15 @@ export interface SendWebhookResult {
 }
 
 export interface WebhookServiceConfig {
-  /** Default retry count for failed deliveries. */
   retries?: number
-  /** Default delay between retries; omitted means exponential backoff. */
+  /** Omitted means exponential backoff. */
   retryDelay?: string | number
-  /**
-   * Name of a secret (resolved through the secret service) used as the
-   * default HMAC signing key for all outgoing webhooks.
-   */
+  /** A secret *name* resolved through the secret service, unlike `SendWebhookInput.secret`. */
   secret?: string
-  /**
-   * Header the body signature is sent in. Defaults to
-   * {@link DEFAULT_WEBHOOK_SIGNATURE_HEADER}.
-   */
   signatureHeader?: string
   /**
-   * SSRF allowlist of hostnames outgoing webhooks may be delivered to. When set,
-   * a delivery target must be on this list. When omitted, obvious private and
-   * internal hosts (loopback, private ranges, cloud metadata) are blocked and
-   * all other public hosts are permitted.
+   * SSRF allowlist. Set: only these hostnames may be delivered to. Omitted:
+   * private/internal hosts are blocked and every other public host is allowed.
    */
   allowedHosts?: string[]
 }
@@ -64,26 +41,21 @@ export interface WebhookJobData {
   body: string
   headers: Record<string, string>
   /**
-   * Delivery-record id, present when a store-backed implementation enqueued
-   * the job. The worker keys its per-attempt records off this (it doubles as
-   * the queue `jobId`), so it's stable across retries.
+   * Present only when a store-backed implementation enqueued the job. Doubles
+   * as the queue `jobId`, so it is stable across retries.
    */
   deliveryId?: string
 }
 
-/** Outcome of one delivery attempt, recorded against a delivery. */
 export interface WebhookAttemptResult {
-  /** HTTP status of the response, absent if the request never completed. */
+  /** Absent when the request never completed. */
   statusCode?: number
-  /** Response body (truncated) — captured on failure for debugging. */
+  /** Truncated; captured on failure only. */
   responseBody?: string
-  /** Network/timeout error message, when the request threw. */
   error?: string
-  /** Whether this attempt was a 2xx success. */
   delivered: boolean
 }
 
-/** A persisted webhook delivery, as surfaced to the console. */
 export interface WebhookDeliveryRecord {
   deliveryId: string
   organizationId: string | null
@@ -96,7 +68,6 @@ export interface WebhookDeliveryRecord {
   deliveredAt: Date | null
 }
 
-/** A single persisted delivery attempt. */
 export interface WebhookAttemptRecord {
   attemptId: string
   deliveryId: string
@@ -107,7 +78,6 @@ export interface WebhookAttemptRecord {
   createdAt: Date
 }
 
-/** A delivery with its full attempt history. */
 export interface WebhookDeliveryWithAttempts {
   delivery: WebhookDeliveryRecord
   attempts: WebhookAttemptRecord[]
@@ -117,38 +87,25 @@ export const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = 'pikku-outgoing-webhooks'
 
 export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = 'X-Pikku-Signature'
 
-/** Fallback when neither the per-call nor `config.webhook.retries` is set. */
 export const DEFAULT_WEBHOOK_RETRIES = 3
 
-/**
- * Outgoing webhook delivery. {@link QueueWebhookService} is the default
- * implementation; apps can extend this to deliver directly, or through a
- * provider such as Svix.
- */
 export abstract class WebhookService {
   abstract send(input: SendWebhookInput): Promise<SendWebhookResult>
 
-  /**
-   * Sign a body with HMAC-SHA256, producing the signature header value
-   * (e.g. `sha256=abc123...`).
-   */
+  /** Produces the header value, `sha256=<hex>`, not the bare digest. */
   protected sign(secret: string, body: string): string {
     return `sha256=${hmacSha256Hex(secret, body)}`
   }
 
-  /**
-   * Verify a signature produced by {@link WebhookService.sign} — for
-   * receivers, which share the signing scheme.
-   */
+  /** Public because receivers verify with it; they share the signing scheme. */
   public verify(secret: string, signature: string, body: string): boolean {
     return timingSafeStringEqual(this.sign(secret, body), signature)
   }
 
   /**
-   * Record a delivery attempt and roll the delivery's status/attempt-count
-   * forward, keyed by the delivery id carried in {@link WebhookJobData}. The
-   * default queue-only service keeps no history, so this throws — a store-backed
-   * implementation (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides it.
+   * The three methods below are optional capability: the default queue-only
+   * service keeps no history and throws, and a store-backed implementation
+   * (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides them.
    */
   public recordAttempt(
     _deliveryId: string,
@@ -159,7 +116,7 @@ export abstract class WebhookService {
     )
   }
 
-  /** List deliveries, most recent first, optionally scoped to an org. */
+  /** Most recent first. */
   public listDeliveries(_opts?: {
     organizationId?: string
     limit?: number
@@ -169,7 +126,6 @@ export abstract class WebhookService {
     )
   }
 
-  /** A single delivery with its attempt history, or null if unknown. */
   public getDelivery(
     _deliveryId: string
   ): Promise<WebhookDeliveryWithAttempts | null> {

package/src/services/workflow-service.ts

@@ -13,13 +13,8 @@ import type {
   ReconstructedRunState,
 } from '../wirings/workflow/run-timeline.js'
 
-/**
- * Interface for workflow orchestration
- * Handles workflow execution, replay, orchestration logic, and run-level state
- */
 export interface WorkflowService {
   wireQueueWorkers?(): void
-  // Run-level state operations
   createRun(
     workflowName: string,
     input: any,
@@ -48,13 +43,10 @@ export interface WorkflowService {
   withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>
   close(): Promise<void>
 
-  // Orchestration operations
   resumeWorkflow(runId: string): Promise<void>
   /**
-   * Record a human decision against a `workflow.approval()` gate and wake the
-   * run. The payload is stored as given and validated on replay, inside the
-   * workflow body — so an invalid one re-closes the gate rather than failing the
-   * run. `reason` addresses the gate's first reach.
+   * The payload is stored as given and validated on replay inside the workflow
+   * body, so an invalid one re-closes the gate rather than failing the run.
    */
   approveStep(runId: string, reason: string, decision: unknown): Promise<void>
   startWorkflow<I>(
@@ -64,13 +56,7 @@ export interface WorkflowService {
     rpcService: any,
     options?: { inline?: boolean; startNode?: string }
   ): Promise<{ runId: string }>
-  /**
-   * Start a run and wait for it to end.
-   *
-   * `pollIntervalMs` is the ceiling on the wait between reads of the run, not a
-   * fixed cadence: polling starts far shorter than this and widens towards it,
-   * so a run that finishes quickly is not held for a whole interval.
-   */
+  /** `pollIntervalMs` is a CEILING on the wait between reads, not a cadence. */
   runToCompletion<I>(
     name: string,
     input: I,
@@ -81,7 +67,6 @@ export interface WorkflowService {
   orchestrateWorkflow(runId: string, rpcService: any): Promise<void>
   executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>
 
-  // Step-level state operations
   insertStepState(
     runId: string,
     stepName: string,
@@ -100,7 +85,6 @@ export interface WorkflowService {
     status: 'pending' | 'running'
   ): Promise<StepState>
 
-  // Step execution
   executeWorkflowStep(
     runId: string,
     stepName: string,
@@ -109,7 +93,6 @@ export interface WorkflowService {
     rpcService: any
   ): Promise<void>
 
-  // Version operations
   upsertWorkflowVersion(
     name: string,
     graphHash: string,

package/src/testing/service-tests.ts

@@ -109,23 +109,19 @@ export function defineServiceTests(config: ServiceTestConfig): void {
           channelName: 'test-channel',
         })
 
-        // initially undefined
         const empty = await store.getState('ch-state')
         assert.equal(empty, undefined)
 
-        // set + get
         const payload = { userId: 'u-7', meta: { foo: 1 } }
         await store.setState('ch-state', payload)
         const got = await store.getState('ch-state')
         assert.deepEqual(got, payload)
 
-        // overwrite
         const next = { userId: 'u-8' }
         await store.setState('ch-state', next)
         const got2 = await store.getState('ch-state')
         assert.deepEqual(got2, next)
 
-        // clear
         await store.clearState('ch-state')
         const after = await store.getState('ch-state')
         assert.equal(after, undefined)
@@ -385,28 +381,6 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         assert.equal(flaky.attempts, 2, 'attempt count surfaces in status')
       })
 
-      test('getNodesWithoutSteps', async () => {
-        const runId = await service.createRun(
-          'graph-workflow',
-          {},
-          false,
-          'hash-7',
-          wire
-        )
-        await service.insertStepState(runId, 'existing-node', 'rpc', {})
-
-        const missing = await service.getNodesWithoutSteps(runId, [
-          'existing-node',
-          'missing-node',
-        ])
-        assert.deepEqual(missing, ['missing-node'])
-      })
-
-      test('getNodesWithoutSteps with empty array', async () => {
-        const result = await service.getNodesWithoutSteps('any-id', [])
-        assert.deepEqual(result, [])
-      })
-
       test('getNodeResults', async () => {
         const runId = await service.createRun(
           'results-workflow',

package/src/time-utils.ts

@@ -18,24 +18,15 @@ export const getRelativeTimeOffset = ({
   value,
   unit,
 }: RelativeTimeInput): number => {
-  return Math.round(value * multipliers[unit]) * 1000 // convert to milliseconds
+  return Math.round(value * multipliers[unit]) * 1000
 }
 
-/**
- * Returns a Unix timestamp (in seconds) offset from now by the given duration.
- * e.g. value = -1 and unit = 'day' => 1 day ago => now - 86400 seconds
- */
 export const getRelativeTimeOffsetFromNow = (
   relativeTime: RelativeTimeInput
 ): Date => {
   return new Date(Date.now() + getRelativeTimeOffset(relativeTime))
 }
 
-/**
- * Get duration in milliseconds from a string or number
- * @param duration
- * @returns
- */
 export const getDurationInMilliseconds = (
   duration: string | number
 ): number => {
@@ -45,13 +36,6 @@ export const getDurationInMilliseconds = (
   return parseDurationString(duration)
 }
 
-/**
- * Parse a duration string to milliseconds
- * Supports formats like: '2s', '5s', '5sec', '5seconds', '5m', '5min', '5minutes', '1h', '1hour', '2d', '2day', '1w', '1week'
- *
- * @param duration - Duration string (e.g., '2s', '5min', '2hours', '1day')
- * @returns Duration in milliseconds
- */
 export const parseDurationString = (duration: string): number => {
   const match = duration.match(
     /^(\d+)(ms|milliseconds?|s|sec|seconds?|m|min|minutes?|h|hour|hours?|d|day|days?|w|week|weeks?|y|year|years?)$/
@@ -66,7 +50,6 @@ export const parseDurationString = (duration: string): number => {
   const value = parseInt(match[1], 10)
   const unitStr = match[2]
 
-  // Handle milliseconds specially
   if (
     unitStr === 'ms' ||
     unitStr === 'millisecond' ||
@@ -75,7 +58,6 @@ export const parseDurationString = (duration: string): number => {
     return value
   }
 
-  // Map string variations to TimeUnit
   let unit: TimeUnit
   if (
     unitStr === 's' ||