@pikku/core 0.12.72 → 0.12.77

package/src/services/system-role-guard.ts

@@ -0,0 +1,71 @@
+import {
+  SystemRoleImmutableError,
+  SystemRoleShadowedError,
+} from '../errors/errors.js'
+import type { Role } from './scope-service.js'
+
+/**
+ * The guards a {@link ScopeService} implementation must apply before mutating
+ * a role.
+ *
+ * Shared rather than left to each implementation because the rule is a
+ * contract, not a policy: a store that lets the console delete `buyer` makes
+ * every persona and scenario written against `buyer` silently stop testing
+ * what it claims to, and nothing fails at the point of the mistake. Two
+ * implementations disagreeing about that would be worse than either rule.
+ *
+ * `isSystemRole` is passed in rather than a role list, so an implementation can
+ * answer it from a column, a cached set, or a query, whichever is cheap.
+ */
+export type IsSystemRole = (name: string) => boolean | Promise<boolean>
+
+/**
+ * Refuses a destructive or re-scoping operation against a declared role.
+ *
+ * @param operation a verb phrase for the message, e.g. `'delete role'`.
+ */
+export const assertRoleIsMutable = async (
+  name: string,
+  isSystemRole: IsSystemRole,
+  operation: string
+): Promise<void> => {
+  if (await isSystemRole(name)) {
+    throw new SystemRoleImmutableError(name, operation)
+  }
+}
+
+/**
+ * Refuses a new custom role that would shadow a declared one.
+ */
+export const assertRoleNameAvailable = async (
+  name: string,
+  isSystemRole: IsSystemRole
+): Promise<void> => {
+  if (await isSystemRole(name)) {
+    throw new SystemRoleShadowedError(name)
+  }
+}
+
+/**
+ * Why the console must render a role as locked, or `null` when it is editable.
+ *
+ * Returned rather than a boolean so the UI shows a reason instead of a
+ * disabled button with no explanation — the difference between a user filing a
+ * bug and a user editing the declaration.
+ */
+export const roleLockReason = (role: Role): string | null => {
+  if (!role.system) {
+    return null
+  }
+  if (role.declared === false) {
+    return (
+      `'${role.name}' was declared in code and that declaration has been removed. ` +
+      `It is inert: still held by its current members, not offered for new grants. ` +
+      `Run 'pikku roles prune' to remove it.`
+    )
+  }
+  return (
+    `'${role.name}' is declared in code with defineSystemRole. ` +
+    `Edit the declaration to change what it grants.`
+  )
+}

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

@@ -1,4 +1,5 @@
-import type { SecretService } from './secret-service.js'
+import type { SecretValue } from '../secret-value.js'
+import type { SecretService, SecretValues } from './secret-service.js'
 
 export interface CredentialStatus {
   secretId: string
@@ -17,13 +18,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(
@@ -31,8 +26,10 @@ export class TypedSecretService<
     private credentialsMeta: Record<string, CredentialMeta>
   ) {}
 
-  async getSecret<K extends keyof TMap & string>(key: K): Promise<TMap[K]>
-  async getSecret<T = string>(key: string): Promise<T>
+  async getSecret<K extends keyof TMap & string>(
+    key: K
+  ): Promise<SecretValue<TMap[K]>>
+  async getSecret<T = string>(key: string): Promise<SecretValue<T>>
   async getSecret(key: string): Promise<unknown> {
     if (this.cache.has(key)) {
       return this.cache.get(key)
@@ -64,12 +61,12 @@ export class TypedSecretService<
 
   async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
     keys: (keyof T & string)[]
-  ): Promise<Partial<T>> {
-    const result: Partial<T> = {}
+  ): Promise<Partial<SecretValues<T>>> {
+    const result: Partial<SecretValues<T>> = {}
     const missing: (keyof T & string)[] = []
     for (const key of keys) {
       if (this.cache.has(key)) {
-        result[key] = this.cache.get(key) as T[keyof T & string]
+        result[key] = this.cache.get(key) as SecretValues<T>[keyof T & string]
       } else {
         missing.push(key)
       }
@@ -78,7 +75,8 @@ export class TypedSecretService<
       const fetched = await this.secrets.getSecrets<T>(missing)
       for (const [key, value] of Object.entries(fetched)) {
         this.cache.set(key, value)
-        result[key as keyof T & string] = value as T[keyof T & string]
+        result[key as keyof T & string] = value as SecretValues<T>[keyof T &
+          string]
       }
     }
     return result

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

@@ -1,32 +1,20 @@
 import { NotImplementedError } from '../errors/errors.js'
 import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js'
+import type { Safe } from '../secret-value.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 +23,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 +42,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 +69,6 @@ export interface WebhookDeliveryRecord {
   deliveredAt: Date | null
 }
 
-/** A single persisted delivery attempt. */
 export interface WebhookAttemptRecord {
   attemptId: string
   deliveryId: string
@@ -107,7 +79,6 @@ export interface WebhookAttemptRecord {
   createdAt: Date
 }
 
-/** A delivery with its full attempt history. */
 export interface WebhookDeliveryWithAttempts {
   delivery: WebhookDeliveryRecord
   attempts: WebhookAttemptRecord[]
@@ -117,38 +88,27 @@ 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>
+  abstract send<T extends SendWebhookInput>(
+    input: Safe<T>
+  ): 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 +119,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 +129,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',
@@ -857,17 +831,17 @@ export function defineServiceTests(config: ServiceTestConfig): void {
           token: string
           endpoint: string
         }>('api-key')
-        assert.deepEqual(result, {
+        assert.deepEqual(result.reveal(), {
           token: 'sk-123',
           endpoint: 'https://api.example.com',
         })
       })
 
-      test('getSecret returns raw string', async () => {
+      test('getSecret wraps the raw string rather than returning it', async () => {
         const service = await factory({ key: kek })
         await service.setSecret('string-secret', 'plain-value')
         const result = await service.getSecret('string-secret')
-        assert.strictEqual(result, 'plain-value')
+        assert.strictEqual(result.reveal(), 'plain-value')
       })
 
       test('hasSecret returns true/false', async () => {
@@ -888,7 +862,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         await service.setSecret('upsert-key', { v: 1 })
         await service.setSecret('upsert-key', { v: 2 })
         const result = await service.getSecret<{ v: number }>('upsert-key')
-        assert.deepEqual(result, { v: 2 })
+        assert.deepEqual(result.reveal(), { v: 2 })
       })
 
       test('deleteSecret removes the key', async () => {
@@ -913,7 +887,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         const before = await rotatedService.getSecret<{
           important: string
         }>('rotate-test')
-        assert.deepEqual(before, { important: 'data' })
+        assert.deepEqual(before.reveal(), { important: 'data' })
 
         assert.ok(rotatedService.rotateKEK)
         const count = await rotatedService.rotateKEK!()
@@ -926,7 +900,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         const after = await newOnlyService.getSecret<{
           important: string
         }>('rotate-test')
-        assert.deepEqual(after, { important: 'data' })
+        assert.deepEqual(after.reveal(), { important: 'data' })
       })
 
       test('rotateKEK throws without previousKey', async () => {

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' ||