@pikku/core 0.12.71 → 0.12.74

package/src/services/in-memory-workflow-service.test.ts

@@ -91,7 +91,6 @@ describe('InMemoryWorkflowService', () => {
 
     test('should handle non-existent run gracefully', async () => {
       await service.updateRunStatus('non-existent', 'failed')
-      // Should not throw
     })
   })
 
@@ -258,18 +257,6 @@ describe('InMemoryWorkflowService', () => {
       assert.deepStrictEqual(state.failedNodeIds, [])
     })
 
-    test('should find nodes without steps', async () => {
-      const runId = await service.createRun('wf', {}, true, 'h', {} as any)
-      await service.insertStepState(runId, 'node1', null, {})
-
-      const missing = await service.getNodesWithoutSteps(runId, [
-        'node1',
-        'node2',
-        'node3',
-      ])
-      assert.deepStrictEqual(missing, ['node2', 'node3'])
-    })
-
     test('should get node results', async () => {
       const runId = await service.createRun('wf', {}, true, 'h', {} as any)
       const step1 = await service.insertStepState(runId, 'node1', null, {})

package/src/services/in-memory-workflow-service.ts

@@ -21,21 +21,7 @@ interface InternalStepData {
   stepName: string
 }
 
-/**
- * In-memory implementation of WorkflowService for inline-only execution
- *
- * This is a lightweight workflow service that stores all state in memory.
- * It only supports inline execution (no queue workers) and is ideal for:
- * - CLI tools that need workflow-like step orchestration
- * - Testing and development
- * - Single-process applications without persistence requirements
- *
- * @example
- * ```typescript
- * const workflowService = new InMemoryWorkflowService()
- * await workflowService.startWorkflow('myWorkflow', input, { type: 'cli' }, rpc, { inline: true })
- * ```
- */
+// knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
 export class InMemoryWorkflowService
   extends PikkuWorkflowService
   implements WorkflowRunService
@@ -169,7 +155,7 @@ export class InMemoryWorkflowService
     this.steps.set(key, step)
     this.stepData.set(stepId, { rpcName, data, stepName })
 
-    // Add to history (same reference so mutations are reflected)
+    // knowledge: decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md
     const history = this.stepHistory.get(runId) || []
     history.push(step)
     this.stepHistory.set(runId, history)
@@ -262,7 +248,6 @@ export class InMemoryWorkflowService
     failedStepId: string,
     status: 'pending' | 'running'
   ): Promise<StepState> {
-    // Find the failed step
     let failedStep: StepState | undefined
     let runId: string | undefined
     let stepName: string | undefined
@@ -304,12 +289,11 @@ export class InMemoryWorkflowService
     const key = `${runId}:${stepName}`
     this.steps.set(key, newStep)
 
-    // Copy step data to new step
     if (failedStepData) {
       this.stepData.set(newStepId, { ...failedStepData })
     }
 
-    // Add to history (same reference so mutations are reflected)
+    // knowledge: decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md
     const history = this.stepHistory.get(runId) || []
     history.push(newStep)
     this.stepHistory.set(runId, history)
@@ -380,7 +364,7 @@ export class InMemoryWorkflowService
   }
 
   async withRunLock<T>(_id: string, fn: () => Promise<T>): Promise<T> {
-    // In-memory service doesn't need locking for inline execution
+    // knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
     return fn()
   }
 
@@ -389,7 +373,6 @@ export class InMemoryWorkflowService
     _stepName: string,
     fn: () => Promise<T>
   ): Promise<T> {
-    // In-memory service doesn't need locking for inline execution
     return fn()
   }
 
@@ -398,7 +381,6 @@ export class InMemoryWorkflowService
       clearTimeout(timer)
     }
     this.sleepTimers.clear()
-    // Clear all in-memory state
     this.runs.clear()
     this.steps.clear()
     this.stepData.clear()
@@ -408,8 +390,6 @@ export class InMemoryWorkflowService
     this.workflowVersions.clear()
   }
 
-  // Graph workflow methods
-
   async getCompletedGraphState(runId: string): Promise<{
     completedNodeIds: string[]
     failedNodeIds: string[]
@@ -442,20 +422,6 @@ export class InMemoryWorkflowService
     return { completedNodeIds, failedNodeIds, branchKeys }
   }
 
-  async getNodesWithoutSteps(
-    runId: string,
-    nodeIds: string[]
-  ): Promise<string[]> {
-    const existingSteps = new Set<string>()
-    const prefix = `${runId}:`
-    for (const [key] of this.steps.entries()) {
-      if (key.startsWith(prefix)) {
-        existingSteps.add(key.substring(prefix.length))
-      }
-    }
-    return nodeIds.filter((id) => !existingSteps.has(id))
-  }
-
   protected override async listStepStates(
     runId: string
   ): Promise<Array<StepState & { stepName: string }>> {

package/src/services/index.ts

@@ -1,7 +1,3 @@
-/**
- * @module @pikku/core
- */
-
 export { LogLevel } from './logger.js'
 export { ScopedSecretService } from './scoped-secret-service.js'
 export {
@@ -41,20 +37,19 @@ export type {
   CopyFileArgs,
 } from './content-service.js'
 export type {
-  ScenarioActor,
-  ScenarioActorConfig,
-  ScenarioActorOf,
-  ScenarioActors,
+  ScenarioPersona,
+  ResolvedPersona,
+  ScenarioPersonaOf,
+  ScenarioPersonas,
   ScenarioInvokeOptions,
   ScenarioRpcMap,
   ScenarioHttpResponse,
-} from './scenario-actors-service.js'
-export { readScenarioHttpResponse } from './scenario-actors-service.js'
-export {
-  HttpScenarioActor,
-  createHttpScenarioActors,
-  type HttpScenarioActorsConfig,
-} from './http-scenario-actors.js'
+} from './personas-service.js'
+// The persona runtime — `HttpPersona`, `createHttpPersonas`,
+// `readScenarioHttpResponse`, `postScenarioJson` — is exported from
+// `@pikku/core/persona`, not from here. Types are free; those are values, and
+// they reach the actor-flow and agent runners, which no production server runs.
+export type { HttpPersonasConfig } from './http-personas.js'
 export type { JWTService } from './jwt-service.js'
 export type {
   EmailService,
@@ -137,6 +132,12 @@ export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
 export type { SessionStore } from './session-store.js'
 export type { ScopeService, Role } from './scope-service.js'
+export {
+  assertRoleIsMutable,
+  assertRoleNameAvailable,
+  roleLockReason,
+} from './system-role-guard.js'
+export type { IsSystemRole } from './system-role-guard.js'
 export {
   NoopAuditService,
   createInvocationAudit,
@@ -200,3 +201,7 @@ export {
   spy,
   type StubCall,
 } from './stub-tracker.js'
+export {
+  SecretHostNotAllowedError,
+  assertSecretAllowedForHost,
+} from './secret-host-binding.js'

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

@@ -22,11 +22,7 @@ type IstanbulCoverageGlobal = Record<string, IstanbulFileCoverage>
 const getCoverageGlobal = (): IstanbulCoverageGlobal | undefined =>
   (globalThis as { __coverage__?: IstanbulCoverageGlobal }).__coverage__
 
-/**
- * Reads istanbul-instrumented counters from the `__coverage__` global —
- * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
- * where source files are instrumented at load time by a Bun loader plugin).
- */
+/** The coverage backend for runtimes without V8 precise coverage, e.g. Bun. */
 export class IstanbulCoverageService implements CoverageService {
   async start(): Promise<void> {}
 
@@ -39,9 +35,7 @@ export class IstanbulCoverageService implements CoverageService {
         hits = new Map()
         lineHits.set(file.path, hits)
       }
-      // istanbul line semantics: a statement's count belongs to its start
-      // line only, so an enclosing multi-line statement never masks an
-      // unexecuted inner statement (e.g. a throw inside a taken if).
+      // knowledge: decisions/internals/istanbul-statement-counts-attach-to-the-start-line-only.md
       for (const [id, location] of Object.entries(file.statementMap)) {
         const count = file.s[id] ?? 0
         const line = location.start.line

package/src/services/jwt-service.ts

@@ -1,27 +1,12 @@
 import type { RelativeTimeInput } from '../time-utils.js'
 
-/**
- * Interface for handling JSON Web Tokens (JWT).
- */
 export interface JWTService {
-  /**
-   * Encodes a payload into a JWT.
-   * @param expiresIn - The expiration time of the token.
-   * @param payload - The payload to encode.
-   * @returns A promise that resolves to the encoded JWT.
-   */
   encode: <T extends any>(
     expiresIn: RelativeTimeInput,
     payload: T
   ) => Promise<string>
 
-  /**
-   * Decodes a JWT into its payload.
-   * @param hash - The JWT to decode.
-   * @param invalidHashError - An optional error to throw if the hash is invalid.
-   * @param debug - An optional flag for debugging.
-   * @returns A promise that resolves to the decoded payload.
-   */
+  /** `invalidHashError` replaces the implementation's own error when the hash does not verify. */
   decode: <T>(
     hash: string,
     invalidHashError?: Error,

package/src/services/local-content.test.ts

@@ -1,36 +1,54 @@
 import assert from 'node:assert/strict'
 import { describe, test } from 'node:test'
 
-import { LocalContent } from './local-content.js'
+import { LocalContent, signedContentPath } from './local-content.js'
+
+const createLogger = () =>
+  ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+    setLevel: () => {},
+  }) as any
+
+type CapturedPayload = {
+  signedAt: number
+  expiresAt: number
+  notBefore?: number
+  path?: string
+}
+
+const createContent = (
+  overrides: Partial<{ server?: string; assetUrlPrefix: string }> = {}
+) => {
+  let capturedPayload: CapturedPayload | undefined
+  const content = new LocalContent(
+    {
+      localFileUploadPath: '/tmp/uploads',
+      uploadUrlPrefix: '/reaper',
+      assetUrlPrefix: overrides.assetUrlPrefix ?? '/assets',
+      server:
+        'server' in overrides ? overrides.server : 'http://localhost:3000',
+    },
+    createLogger(),
+    {
+      encode: async (_expiresIn: any, payload: any) => {
+        capturedPayload = payload
+        return 'signed-token'
+      },
+      decode: async () => ({}) as any,
+    }
+  )
+  return {
+    content,
+    getPayload: () => capturedPayload,
+  }
+}
 
 describe('LocalContent signing', () => {
   test('binds notBefore into the signature payload', async () => {
-    let capturedPayload:
-      | { signedAt: number; expiresAt: number; notBefore?: number }
-      | undefined
-
-    const content = new LocalContent(
-      {
-        localFileUploadPath: '/tmp/uploads',
-        uploadUrlPrefix: '/reaper',
-        assetUrlPrefix: '/assets',
-        server: 'http://localhost:3000',
-      },
-      {
-        info: () => {},
-        warn: () => {},
-        error: () => {},
-        debug: () => {},
-        setLevel: () => {},
-      } as any,
-      {
-        encode: async (_expiresIn: any, payload: any) => {
-          capturedPayload = payload
-          return 'signed-token'
-        },
-        decode: async () => ({}),
-      }
-    )
+    const { content, getPayload } = createContent()
 
     const dateGreaterThan = new Date(Date.now() + 60_000)
     const dateLessThan = new Date(Date.now() + 120_000)
@@ -43,6 +61,7 @@ describe('LocalContent signing', () => {
 
     const url = new URL(signedUrl)
     assert.equal(url.searchParams.get('signature'), 'signed-token')
+    const capturedPayload = getPayload()
     assert.ok(capturedPayload)
     assert.equal(capturedPayload?.expiresAt, dateLessThan.getTime())
     assert.equal(capturedPayload?.notBefore, dateGreaterThan.getTime())
@@ -51,4 +70,117 @@ describe('LocalContent signing', () => {
       String(dateGreaterThan.getTime())
     )
   })
+
+  test('binds the asset path into the signature payload', async () => {
+    const { content, getPayload } = createContent()
+
+    const signedUrl = await content.signContentKey({
+      bucket: 'avatars',
+      contentKey: 'user-1.png',
+      dateLessThan: new Date(Date.now() + 60_000),
+    })
+
+    assert.equal(getPayload()?.path, '/assets/avatars/user-1.png')
+    assert.equal(
+      new URL(signedUrl).pathname,
+      '/assets/avatars/user-1.png',
+      'the bound path must be the path the server will receive'
+    )
+  })
+
+  test('two different content keys never share a bound path', async () => {
+    const { content, getPayload } = createContent()
+
+    await content.signContentKey({
+      bucket: 'avatars',
+      contentKey: 'user-1.png',
+      dateLessThan: new Date(Date.now() + 60_000),
+    })
+    const first = getPayload()?.path
+
+    await content.signContentKey({
+      bucket: 'private',
+      contentKey: 'passport-scan.png',
+      dateLessThan: new Date(Date.now() + 60_000),
+    })
+    const second = getPayload()?.path
+
+    assert.ok(first)
+    assert.notEqual(first, second)
+  })
+
+  test('binds nested and space-containing keys to their decoded path', async () => {
+    const { content, getPayload } = createContent()
+
+    const signedUrl = await content.signContentKey({
+      bucket: 'avatars',
+      contentKey: 'nested/deep/my file (1).png',
+      dateLessThan: new Date(Date.now() + 60_000),
+    })
+
+    const url = new URL(signedUrl)
+    assert.equal(
+      getPayload()?.path,
+      '/assets/avatars/nested/deep/my file (1).png'
+    )
+    assert.equal(
+      decodeURIComponent(url.pathname),
+      getPayload()?.path,
+      'the signed path must match the decoded pathname the server receives'
+    )
+  })
+
+  test('binds the path when no server origin is configured', async () => {
+    const { content, getPayload } = createContent({ server: undefined })
+
+    const signedUrl = await content.signContentKey({
+      bucket: 'avatars',
+      contentKey: 'user-1.png',
+      dateLessThan: new Date(Date.now() + 60_000),
+    })
+
+    assert.equal(getPayload()?.path, '/assets/avatars/user-1.png')
+    assert.ok(signedUrl.startsWith('/assets/avatars/user-1.png?'))
+  })
+
+  test('signURL binds the path of the url it signs', async () => {
+    const { content, getPayload } = createContent()
+
+    await content.signURL({
+      url: 'http://localhost:3000/assets/avatars/user-1.png',
+      dateLessThan: new Date(Date.now() + 60_000),
+    })
+
+    assert.equal(getPayload()?.path, '/assets/avatars/user-1.png')
+  })
+
+  test('refuses to construct without a JWT service', () => {
+    assert.throws(
+      () =>
+        new LocalContent(
+          {
+            localFileUploadPath: '/tmp/uploads',
+            uploadUrlPrefix: '/reaper',
+            assetUrlPrefix: '/assets',
+          },
+          createLogger(),
+          undefined as any
+        ),
+      /JWTService/
+    )
+  })
+})
+
+describe('signedContentPath', () => {
+  test('strips the origin and query, and decodes the path', () => {
+    assert.equal(
+      signedContentPath('http://localhost:3000/assets/a/b%20c.png?x=1'),
+      '/assets/a/b c.png'
+    )
+    assert.equal(signedContentPath('/assets/a/b%20c.png'), '/assets/a/b c.png')
+  })
+
+  test('is stable for a malformed percent escape', () => {
+    assert.equal(signedContentPath('/assets/100%.png'), '/assets/100%.png')
+  })
 })

package/src/services/local-content.ts

@@ -24,12 +24,42 @@ export interface LocalContentConfig {
   sizeLimit?: string
 }
 
+/**
+ * The representation of an asset that gets bound into a signed URL's
+ * signature, and that a server can reconstruct from an incoming request:
+ * the decoded path, without origin or query string.
+ *
+ * Both sides must derive it the same way, so signer and verifier share this
+ * function. Percent escapes are decoded so that a client re-encoding an
+ * optional character still matches; a malformed escape is left verbatim
+ * rather than throwing, which keeps both sides in agreement.
+ */
+export const signedContentPath = (urlOrPath: string): string => {
+  let pathname: string
+  try {
+    pathname = new URL(urlOrPath, 'http://pikku.local').pathname
+  } catch {
+    pathname = urlOrPath
+  }
+  try {
+    return decodeURIComponent(pathname)
+  } catch {
+    return pathname
+  }
+}
+
 export class LocalContent implements ContentService {
   constructor(
     private config: LocalContentConfig,
     private logger: Logger,
-    private jwt?: JWTService
-  ) {}
+    private jwt: JWTService
+  ) {
+    if (!jwt) {
+      throw new Error(
+        'LocalContent requires a JWTService: without one it cannot sign asset URLs, and unsigned URLs cannot be verified.'
+      )
+    }
+  }
 
   private safePath(bucket: string, key: string): string {
     const base = resolve(this.config.localFileUploadPath)
@@ -48,6 +78,7 @@ export class LocalContent implements ContentService {
   public async init() {}
 
   private async signParams(
+    url: string,
     dateLessThan: Date,
     dateGreaterThan?: Date
   ): Promise<string> {
@@ -60,33 +91,34 @@ export class LocalContent implements ContentService {
     if (dateGreaterThan) {
       params.set('notBefore', String(dateGreaterThan.getTime()))
     }
-    if (this.jwt) {
-      const expiresInSeconds = Math.max(
-        1,
-        Math.floor((expiresAt - signedAt) / 1000)
-      )
-      const payload: {
-        signedAt: number
-        expiresAt: number
-        notBefore?: number
-      } = {
-        signedAt,
-        expiresAt,
-      }
-      if (dateGreaterThan) {
-        payload.notBefore = dateGreaterThan.getTime()
-      }
-      const signature = await this.jwt.encode(
-        { value: expiresInSeconds, unit: 'second' },
-        payload
-      )
-      params.set('signature', signature)
+    const expiresInSeconds = Math.max(
+      1,
+      Math.floor((expiresAt - signedAt) / 1000)
+    )
+    const payload: {
+      signedAt: number
+      expiresAt: number
+      notBefore?: number
+      path: string
+    } = {
+      signedAt,
+      expiresAt,
+      path: signedContentPath(url),
     }
+    if (dateGreaterThan) {
+      payload.notBefore = dateGreaterThan.getTime()
+    }
+    const signature = await this.jwt.encode(
+      { value: expiresInSeconds, unit: 'second' },
+      payload
+    )
+    params.set('signature', signature)
     return params.toString()
   }
 
   public async signURL(args: SignURLArgs): Promise<string> {
     const params = await this.signParams(
+      args.url,
       args.dateLessThan,
       args.dateGreaterThan
     )

package/src/services/local-gateway-service.ts

@@ -6,22 +6,7 @@ import {
   resolveGatewayAdapter,
 } from '../wirings/gateway/gateway-runner.js'
 
-/**
- * Local GatewayService implementation.
- *
- * Starts all registered listener gateways unconditionally (single-process).
- * For distributed deployments, implement `GatewayService` with leader
- * election or similar coordination.
- *
- * @example
- * ```typescript
- * const gatewayService = new LocalGatewayService()
- * await gatewayService.start()
- *
- * // On shutdown
- * await gatewayService.stop()
- * ```
- */
+// knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
 export class LocalGatewayService implements GatewayService {
   private activeAdapters = new Map<string, GatewayAdapter>()
 
@@ -57,7 +42,7 @@ export class LocalGatewayService implements GatewayService {
             e
           )
         } catch {
-          // logger may not be available during shutdown
+          // The logger may already be gone during shutdown.
         }
       }
     }

package/src/services/local-secrets.ts

@@ -2,10 +2,6 @@ import { LocalVariablesService } from './local-variables.js'
 import type { SecretService } from './secret-service.js'
 import type { VariablesService } from './variables-service.js'
 
-/**
- * Service for retrieving secrets from environment variables.
- * Supports storing secrets locally in memory for CLI operations.
- */
 export class LocalSecretService implements SecretService {
   private localSecrets: Map<string, string> = new Map()
 

package/src/services/logger-console.test.ts

@@ -27,7 +27,6 @@ describe('ConsoleLogger', () => {
     console.log = (...args: any[]) => captured.push({ method: 'log', args })
   })
 
-  // Restore console after each test
   test('should log info at default level', () => {
     logger.info('test message')
     assert.strictEqual(captured.length, 1)

package/src/services/logger-console.ts

@@ -1,10 +1,7 @@
 import type { Logger } from './logger.js'
 import { LogLevel } from './logger.js'
 
-/**
- * Text-mode console logger.
- * Output: `INFO: message` or `[traceId] INFO: message`
- */
+/** Emits `INFO: message`, or `[traceId] INFO: message` when scoped. */
 export class ConsoleLogger implements Logger {
   private level: LogLevel = LogLevel.info
   private prefix: string
@@ -85,9 +82,8 @@ export class ConsoleLogger implements Logger {
 }
 
 /**
- * JSON-mode console logger.
- * Output: `{"level":"info","message":"...","traceId":"..."}`
- * CF Workers Logs auto-indexes JSON keys for filtering.
+ * Emits `{"level":"info","message":"...","traceId":"..."}` — one JSON object per
+ * line, because Cloudflare Workers Logs auto-indexes JSON keys for filtering.
  */
 export class JsonConsoleLogger implements Logger {
   private level: LogLevel = LogLevel.info