@pikku/core 0.12.84 → 0.12.86

package/src/services/file-scenario-run-store.test.ts

@@ -0,0 +1,349 @@
+import { describe, test, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  existsSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  FileScenarioRunStore,
+  scenarioRunSummary,
+} from './file-scenario-run-store.js'
+import type {
+  ScenarioResult,
+  ScenarioRunRecord,
+} from '../wirings/workflow/scenario-run.types.js'
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'pikku-scenario-runs-'))
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+const record = (
+  overrides: Partial<ScenarioRunRecord> = {}
+): ScenarioRunRecord => ({
+  runId: 'run-1',
+  environment: 'local',
+  surface: 'browser',
+  status: 'running',
+  startedAt: '2026-08-15T10:00:00.000Z',
+  results: [],
+  skipped: [],
+  hookFailures: [],
+  ...overrides,
+})
+
+const result = (overrides: Partial<ScenarioResult> = {}): ScenarioResult => ({
+  name: 'todos › a member adds one',
+  status: 'passed',
+  durationMs: 120,
+  ...overrides,
+})
+
+describe('FileScenarioRunStore', () => {
+  test('a run is readable from the moment it opens, before any scenario finishes', async () => {
+    const store = new FileScenarioRunStore({ dir })
+
+    await store.start(record())
+
+    const open = await store.get('run-1')
+    assert.equal(open?.status, 'running')
+    assert.deepEqual(open?.results, [])
+  })
+
+  test('scenarios accumulate as they finish, so a suite killed halfway keeps what ran', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+
+    await store.recordScenario('run-1', result({ name: 'one' }))
+    await store.recordScenario(
+      'run-1',
+      result({ name: 'two', status: 'failed' })
+    )
+
+    const partial = await store.get('run-1')
+    assert.deepEqual(
+      partial?.results.map((r) => r.name),
+      ['one', 'two']
+    )
+    assert.equal(
+      partial?.status,
+      'running',
+      'a run nobody finished is still running, not passed'
+    )
+  })
+
+  test('finishing settles the outcome and everything only known at the end', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    await store.recordScenario('run-1', result())
+
+    await store.finish('run-1', {
+      status: 'failed',
+      finishedAt: '2026-08-15T10:00:30.000Z',
+      skipped: [{ name: 'quarantined', reason: 'flaky' }],
+      hookFailures: ['feature after hook failed: boom'],
+    })
+
+    const done = await store.get('run-1')
+    assert.equal(done?.status, 'failed')
+    assert.equal(done?.finishedAt, '2026-08-15T10:00:30.000Z')
+    assert.deepEqual(done?.skipped, [{ name: 'quarantined', reason: 'flaky' }])
+    assert.equal(done?.results.length, 1, 'finishing does not lose the results')
+  })
+
+  test('concurrent scenario writes never lose one to a read-modify-write race', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+
+    await Promise.all(
+      Array.from({ length: 20 }, (_, i) =>
+        store.recordScenario('run-1', result({ name: `scenario-${i}` }))
+      )
+    )
+
+    const all = await store.get('run-1')
+    assert.equal(all?.results.length, 20)
+  })
+
+  test('runs list newest first, summarised without loading their stacks', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(
+      record({ runId: 'older', startedAt: '2026-08-14T10:00:00.000Z' })
+    )
+    await store.start(
+      record({ runId: 'newer', startedAt: '2026-08-15T10:00:00.000Z' })
+    )
+    await store.recordScenario(
+      'newer',
+      result({
+        artifacts: [{ scenario: 'x', kind: 'video', path: 'x/admin.mp4' }],
+      })
+    )
+    await store.recordScenario('newer', result({ status: 'failed' }))
+    await store.finish('newer', {
+      status: 'failed',
+      finishedAt: '2026-08-15T10:00:05.000Z',
+      skipped: [{ name: 'held', reason: 'no browser' }],
+      hookFailures: [],
+    })
+
+    const runs = await store.list()
+
+    assert.deepEqual(
+      runs.map((r) => r.runId),
+      ['newer', 'older']
+    )
+    assert.deepEqual(
+      { ...runs[0] },
+      {
+        runId: 'newer',
+        environment: 'local',
+        surface: 'browser',
+        status: 'failed',
+        startedAt: '2026-08-15T10:00:00.000Z',
+        finishedAt: '2026-08-15T10:00:05.000Z',
+        durationMs: 5000,
+        passed: 1,
+        failed: 1,
+        skipped: 1,
+        artifacts: 1,
+      }
+    )
+  })
+
+  test('a limit takes the newest runs, not whichever the filesystem returned first', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    for (const day of ['11', '12', '13']) {
+      await store.start(
+        record({
+          runId: `run-${day}`,
+          startedAt: `2026-08-${day}T10:00:00.000Z`,
+        })
+      )
+    }
+
+    const runs = await store.list({ limit: 2 })
+
+    assert.deepEqual(
+      runs.map((r) => r.runId),
+      ['run-13', 'run-12']
+    )
+  })
+
+  test('opening a run drops the oldest past the limit, with everything they filed', async () => {
+    const store = new FileScenarioRunStore({ dir, keep: 2 })
+    for (const day of ['11', '12', '13']) {
+      await store.start(
+        record({
+          runId: `run-${day}`,
+          startedAt: `2026-08-${day}T10:00:00.000Z`,
+        })
+      )
+      writeFileSync(join(dir, `run-${day}`, 'video.mp4'), 'x')
+    }
+
+    assert.deepEqual(
+      (await store.list()).map((r) => r.runId),
+      ['run-13', 'run-12']
+    )
+    assert.equal(
+      existsSync(join(dir, 'run-11')),
+      false,
+      'the pruned run takes its artifacts with it'
+    )
+  })
+
+  test('a keep of one still leaves the run being opened', async () => {
+    const store = new FileScenarioRunStore({ dir, keep: 1 })
+    await store.start(record({ runId: 'first' }))
+    await store.start(record({ runId: 'second' }))
+
+    assert.deepEqual(
+      (await store.list()).map((r) => r.runId),
+      ['second']
+    )
+  })
+
+  test('artifacts are filed against the scenario the run knows them by', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    await store.recordScenario('run-1', result({ name: 'checkout › breaks' }))
+    await store.recordScenario('run-1', result({ name: 'checkout › works' }))
+
+    await store.attachArtifacts('run-1', [
+      { scenario: 'checkout › breaks', kind: 'video', path: 'a/admin.mp4' },
+      {
+        scenario: 'checkout › breaks',
+        kind: 'failure',
+        path: 'a/failure-admin.png',
+      },
+      { scenario: 'a scenario that never ran', kind: 'video', path: 'b/x.mp4' },
+    ])
+
+    const [broke, worked] = (await store.get('run-1'))!.results
+    assert.deepEqual(
+      broke?.artifacts?.map((a) => a.path),
+      ['a/admin.mp4', 'a/failure-admin.png']
+    )
+    assert.equal(
+      worked?.artifacts,
+      undefined,
+      'a scenario that produced nothing gets no empty list to render'
+    )
+  })
+
+  test('a run id from outside cannot read its way out of the store', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    writeFileSync(join(dir, 'run.json'), JSON.stringify(record()))
+
+    assert.equal(await store.get('..'), undefined)
+    assert.equal(await store.get('../..'), undefined)
+    assert.equal(existsSync(join(dir, 'run.json')), true)
+
+    await store.remove('../..')
+    assert.equal(
+      existsSync(dir),
+      true,
+      'a traversing id must not delete the store itself'
+    )
+  })
+
+  test('an artifact is served with the type its extension implies', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    mkdirSync(join(dir, 'run-1', 'checkout'))
+    writeFileSync(join(dir, 'run-1', 'checkout', 'admin.mp4'), 'footage')
+    writeFileSync(join(dir, 'run-1', 'checkout', '01-shot.png'), 'image')
+
+    const video = await store.readArtifact('run-1', 'checkout/admin.mp4')
+    const shot = await store.readArtifact('run-1', 'checkout/01-shot.png')
+
+    assert.equal(video?.contentType, 'video/mp4')
+    assert.equal(Buffer.from(video!.body).toString(), 'footage')
+    assert.equal(shot?.contentType, 'image/png')
+  })
+
+  test('an artifact path cannot climb out of its run', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    writeFileSync(join(dir, 'secret.txt'), 'not yours')
+
+    assert.equal(await store.readArtifact('run-1', '../secret.txt'), undefined)
+    assert.equal(
+      await store.readArtifact('run-1', 'checkout/../../secret.txt'),
+      undefined
+    )
+    assert.equal(await store.readArtifact('run-1', '/etc/hosts'), undefined)
+    assert.equal(
+      await store.readArtifact('run-1', 'checkout/never-taken.png'),
+      undefined,
+      'and an artifact that was never filed is simply absent'
+    )
+  })
+
+  test('an artifact of a run that never existed is absent, not an error', async () => {
+    const store = new FileScenarioRunStore({ dir })
+
+    assert.equal(await store.readArtifact('run-1', 'a/b.png'), undefined)
+  })
+
+  test('a half-written run is skipped rather than failing the whole listing', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    mkdirSync(join(dir, 'killed-mid-write'))
+    writeFileSync(join(dir, 'killed-mid-write', 'run.json'), '{"runId":')
+
+    const runs = await store.list()
+
+    assert.deepEqual(
+      runs.map((r) => r.runId),
+      ['run-1']
+    )
+  })
+
+  test('a store with nothing in it lists nothing rather than throwing', async () => {
+    const store = new FileScenarioRunStore({ dir: join(dir, 'never-created') })
+
+    assert.deepEqual(await store.list(), [])
+    assert.equal(await store.get('run-1'), undefined)
+  })
+
+  test('recording against a run that does not exist is ignored, not invented', async () => {
+    const store = new FileScenarioRunStore({ dir })
+
+    await store.recordScenario('never-started', result())
+
+    assert.deepEqual(await store.list(), [])
+  })
+
+  test('removing a run takes its whole folder', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    writeFileSync(join(dir, 'run-1', 'video.mp4'), 'x')
+
+    await store.remove('run-1')
+
+    assert.equal(existsSync(join(dir, 'run-1')), false)
+  })
+})
+
+describe('scenarioRunSummary', () => {
+  test('a run still going has no duration to report', () => {
+    const summary = scenarioRunSummary(record({ results: [result()] }))
+
+    assert.equal(summary.durationMs, undefined)
+    assert.equal(summary.status, 'running')
+    assert.equal(summary.passed, 1)
+  })
+})

package/src/services/file-scenario-run-store.ts

@@ -0,0 +1,282 @@
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type {
+  ScenarioArtifact,
+  ScenarioResult,
+  ScenarioRunRecord,
+  ScenarioRunStore,
+  ScenarioRunSummary,
+} from '../wirings/workflow/scenario-run.types.js'
+
+/** The record, beside the images and footage the same run produced. */
+const RECORD_FILE = 'run.json'
+
+/**
+ * A run id is a path segment, and `get('../../etc')` is a file read.
+ *
+ * Ids are generated here, so anything failing this arrived from outside and is
+ * refused rather than sanitised — a request for a run that cannot exist is a
+ * request for a run that does not exist.
+ */
+const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/
+
+/** Counts and duration, derived rather than stored so they cannot disagree. */
+export const scenarioRunSummary = (
+  record: ScenarioRunRecord
+): ScenarioRunSummary => ({
+  runId: record.runId,
+  environment: record.environment,
+  surface: record.surface,
+  status: record.status,
+  startedAt: record.startedAt,
+  finishedAt: record.finishedAt,
+  durationMs: record.finishedAt
+    ? new Date(record.finishedAt).getTime() -
+      new Date(record.startedAt).getTime()
+    : undefined,
+  passed: record.results.filter((r) => r.status === 'passed').length,
+  failed: record.results.filter((r) => r.status === 'failed').length,
+  skipped: record.skipped.length,
+  artifacts: record.results.reduce(
+    (total, result) => total + (result.artifacts?.length ?? 0),
+    0
+  ),
+})
+
+/**
+ * What a scenario artifact is served as.
+ *
+ * A short, closed list rather than a MIME database: a run produces images and
+ * recordings and nothing else, and anything unrecognised is served as bytes the
+ * browser is told not to interpret.
+ */
+const CONTENT_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+}
+
+export const scenarioArtifactContentType = (path: string): string =>
+  CONTENT_TYPES[path.split('.').pop()?.toLowerCase() ?? ''] ??
+  'application/octet-stream'
+
+/**
+ * An artifact path is a content key from the record, but it arrives from a
+ * client and is joined onto a directory. Anything that could climb out of the
+ * run, or name something other than a file inside it, is refused.
+ */
+const SAFE_ARTIFACT_PATH =
+  /^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/
+
+export interface FileScenarioRunStoreOptions {
+  /** The directory runs live under — one folder per run, named by its id. */
+  dir: string
+  /**
+   * How many runs to keep. Older ones are deleted, with their artifacts, as a
+   * new run opens.
+   *
+   * Bounded on purpose: a run with video is megabytes, and an unbounded history
+   * beside a project is a directory nobody notices until it is enormous.
+   */
+  keep?: number
+}
+
+const DEFAULT_KEEP = 20
+
+/**
+ * Scenario run history as files on disk — the OSS store.
+ *
+ * One folder per run holding its record and everything it filed, which makes a
+ * run a thing you can open, copy, attach to an issue or delete with `rm -rf`.
+ * A hosted project swaps this for a table and an object store; the console
+ * reads the same shapes from either.
+ *
+ * Writes are serialised through one chain. Scenarios finish one at a time, but
+ * `recordScenario` is read-modify-write on a single file, and a store that
+ * corrupts its own history the first time two things overlap is worse than no
+ * history.
+ */
+export class FileScenarioRunStore implements ScenarioRunStore {
+  private writes: Promise<unknown> = Promise.resolve()
+
+  constructor(private readonly options: FileScenarioRunStoreOptions) {}
+
+  async start(record: ScenarioRunRecord): Promise<void> {
+    await this.serialise(async () => {
+      await this.write(record)
+      await this.prune(record.runId)
+    })
+  }
+
+  async recordScenario(runId: string, result: ScenarioResult): Promise<void> {
+    await this.serialise(async () => {
+      const record = await this.read(runId)
+      if (!record) {
+        return
+      }
+      record.results.push(result)
+      await this.write(record)
+    })
+  }
+
+  async attachArtifacts(
+    runId: string,
+    artifacts: ScenarioArtifact[]
+  ): Promise<void> {
+    if (artifacts.length === 0) {
+      return
+    }
+    await this.serialise(async () => {
+      const record = await this.read(runId)
+      if (!record) {
+        return
+      }
+      for (const artifact of artifacts) {
+        const result = record.results.find(
+          (candidate) => candidate.name === artifact.scenario
+        )
+        // An artifact whose scenario is not in the results belongs to a
+        // scenario that never produced one — it is dropped rather than filed
+        // under a run-level bucket nothing renders.
+        if (result) {
+          result.artifacts = [...(result.artifacts ?? []), artifact]
+        }
+      }
+      await this.write(record)
+    })
+  }
+
+  async finish(
+    runId: string,
+    outcome: Pick<
+      ScenarioRunRecord,
+      'status' | 'finishedAt' | 'skipped' | 'hookFailures'
+    >
+  ): Promise<void> {
+    await this.serialise(async () => {
+      const record = await this.read(runId)
+      if (!record) {
+        return
+      }
+      await this.write({ ...record, ...outcome })
+    })
+  }
+
+  async readArtifact(
+    runId: string,
+    path: string
+  ): Promise<
+    { body: Uint8Array<ArrayBuffer>; contentType: string } | undefined
+  > {
+    if (!SAFE_RUN_ID.test(runId) || !SAFE_ARTIFACT_PATH.test(path)) {
+      return undefined
+    }
+    try {
+      const file = await readFile(
+        join(this.options.dir, runId, ...path.split('/'))
+      )
+      return {
+        body: new Uint8Array(file),
+        contentType: scenarioArtifactContentType(path),
+      }
+    } catch {
+      return undefined
+    }
+  }
+
+  async list(options: { limit?: number } = {}): Promise<ScenarioRunSummary[]> {
+    const summaries: ScenarioRunSummary[] = []
+    for (const runId of await this.runIds()) {
+      const record = await this.read(runId)
+      if (record) {
+        summaries.push(scenarioRunSummary(record))
+      }
+    }
+    summaries.sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+    return options.limit ? summaries.slice(0, options.limit) : summaries
+  }
+
+  async get(runId: string): Promise<ScenarioRunRecord | undefined> {
+    return this.read(runId)
+  }
+
+  async remove(runId: string): Promise<void> {
+    if (!SAFE_RUN_ID.test(runId)) {
+      return
+    }
+    await rm(join(this.options.dir, runId), { recursive: true, force: true })
+  }
+
+  /** Where this run's artifacts live, for a driver writing into it. */
+  runDir(runId: string): string {
+    return join(this.options.dir, runId)
+  }
+
+  private serialise<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.writes.then(work, work)
+    // Swallowed on the CHAIN only, so one failed write does not reject every
+    // later one; the caller still sees its own rejection through `next`.
+    this.writes = next.catch(() => {})
+    return next
+  }
+
+  private async read(runId: string): Promise<ScenarioRunRecord | undefined> {
+    if (!SAFE_RUN_ID.test(runId)) {
+      return undefined
+    }
+    try {
+      const raw = await readFile(
+        join(this.options.dir, runId, RECORD_FILE),
+        'utf-8'
+      )
+      return JSON.parse(raw) as ScenarioRunRecord
+    } catch {
+      // A folder with artifacts but no readable record is a run that was killed
+      // mid-write. It is not listable, and it is not an error either.
+      return undefined
+    }
+  }
+
+  private async write(record: ScenarioRunRecord): Promise<void> {
+    const dir = join(this.options.dir, record.runId)
+    await mkdir(dir, { recursive: true })
+    await writeFile(
+      join(dir, RECORD_FILE),
+      JSON.stringify(record, null, 2) + '\n'
+    )
+  }
+
+  private async runIds(): Promise<string[]> {
+    try {
+      const entries = await readdir(this.options.dir, { withFileTypes: true })
+      return entries
+        .filter((entry) => entry.isDirectory() && SAFE_RUN_ID.test(entry.name))
+        .map((entry) => entry.name)
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Drop the oldest runs past the limit, never the one just opened — a `keep`
+   * of zero or one must still leave the run being started.
+   */
+  private async prune(keeping: string): Promise<void> {
+    const keep = this.options.keep ?? DEFAULT_KEEP
+    const dated: Array<{ runId: string; startedAt: string }> = []
+    for (const runId of await this.runIds()) {
+      if (runId === keeping) {
+        continue
+      }
+      const record = await this.read(runId)
+      dated.push({ runId, startedAt: record?.startedAt ?? '' })
+    }
+    dated.sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+    for (const { runId } of dated.slice(Math.max(keep - 1, 0))) {
+      await rm(join(this.options.dir, runId), { recursive: true, force: true })
+    }
+  }
+}

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

@@ -1,7 +1,7 @@
 import { randomUUID } from 'crypto'
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js'
 import { isExpectedError } from '../errors/error-handler.js'
-import type { SerializedError } from '../types/core.types.js'
+import type { SerializedError } from '../errors/serialized-error.js'
 import type {
   WorkflowPlannedStep,
   WorkflowQueueOptions,

package/src/services/index.ts

@@ -22,6 +22,12 @@ export { InMemoryQueueService } from './in-memory-queue-service.js'
 export { InMemoryTriggerService } from './in-memory-trigger-service.js'
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js'
 export { LocalGatewayService } from './local-gateway-service.js'
+export {
+  FileScenarioRunStore,
+  scenarioArtifactContentType,
+  scenarioRunSummary,
+  type FileScenarioRunStoreOptions,
+} from './file-scenario-run-store.js'
 export type {
   ContentService,
   SignContentKeyArgs,
@@ -67,8 +73,8 @@ export type { SessionService } from './user-session-service.js'
 export type {
   ScheduledTaskSummary,
   ScheduledTaskInfo,
-  SchedulerService,
 } from './scheduler-service.js'
+export { SchedulerService } from './scheduler-service.js'
 export type { TriggerService } from './trigger-service.js'
 export type { GatewayService } from './gateway-service.js'
 export type {
@@ -151,3 +157,9 @@ export {
   SecretHostNotAllowedError,
   assertSecretAllowedForHost,
 } from './secret-host-binding.js'
+export type {
+  AuditFacets,
+  AuditQuery,
+  AuditQueryResult,
+} from './audit-service.js'
+export { SecretAccessDeniedError, withoutSecrets } from './secretless.js'

package/src/services/local-content-request-handler.ts

@@ -78,8 +78,7 @@ const text = (status: number, body: string) =>
   })
 
 export type SignedContentVerification =
-  | { ok: true }
-  | { ok: false; status: number; body: string }
+  { ok: true } | { ok: false; status: number; body: string }
 
 /**
  * Verifies a signed content URL — the one function that decides whether a

package/src/services/local-secrets.ts

@@ -2,7 +2,7 @@ import {
   createSecretValue,
   isSecretValue,
   type SecretValue,
-} from '../secret-value.js'
+} from '../classification/secret-value.js'
 import { LocalVariablesService } from './local-variables.js'
 import type { SecretService, SecretValues } from './secret-service.js'
 import type { VariablesService } from './variables-service.js'