@pikku/core 0.12.107 → 0.12.112

package/src/services/workflow-service.ts

@@ -1,120 +0,0 @@
-import type { CoreUserSession } from '../types/core.types.js'
-import type { SerializedError } from '../errors/serialized-error.js'
-import type {
-  WorkflowRun,
-  WorkflowPlannedStep,
-  WorkflowRunWire,
-  WorkflowRunStatus,
-  StepState,
-  WorkflowStatus,
-  WorkflowVersionStatus,
-} from '../wirings/workflow/workflow.types.js'
-import type {
-  RunTimeline,
-  ReconstructedRunState,
-} from '../wirings/workflow/run-timeline.js'
-
-export interface WorkflowService {
-  wireQueueWorkers?(): void
-  createRun(
-    workflowName: string,
-    input: any,
-    inline: boolean,
-    graphHash: string,
-    wire: WorkflowRunWire,
-    options?: {
-      deterministic?: boolean
-      plannedSteps?: WorkflowPlannedStep[]
-    }
-  ): Promise<string>
-  getRun(id: string): Promise<WorkflowRun | null>
-  getRunStatus(id: string): Promise<WorkflowRunStatus | null>
-  getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
-  getRunTimeline(id: string): Promise<RunTimeline | null>
-  reconstructRunStateAt(
-    id: string,
-    at?: number | Date
-  ): Promise<ReconstructedRunState | null>
-  updateRunStatus(
-    id: string,
-    status: WorkflowStatus,
-    output?: any,
-    error?: SerializedError
-  ): Promise<void>
-  withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>
-  close(): Promise<void>
-
-  resumeWorkflow(runId: string): Promise<void>
-  /**
-   * 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.
-   *
-   * The session must belong to the run's owner — see `assertWorkflowRunOwner`.
-   */
-  approveStep(
-    runId: string,
-    reason: string,
-    decision: unknown,
-    session?: CoreUserSession
-  ): Promise<void>
-  startWorkflow<I>(
-    name: string,
-    input: I,
-    wire: WorkflowRunWire,
-    rpcService: any,
-    options?: { inline?: boolean; startNode?: string }
-  ): Promise<{ runId: string }>
-  /** `pollIntervalMs` is a CEILING on the wait between reads, not a cadence. */
-  runToCompletion<I>(
-    name: string,
-    input: I,
-    rpcService: any,
-    options?: { pollIntervalMs?: number; wire?: WorkflowRunWire }
-  ): Promise<unknown>
-  runWorkflowJob(runId: string, rpcService: any): Promise<void>
-  orchestrateWorkflow(runId: string, rpcService: any): Promise<void>
-  executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>
-
-  insertStepState(
-    runId: string,
-    stepName: string,
-    rpcName: string,
-    data: any,
-    stepOptions?: { retries?: number; retryDelay?: string | number }
-  ): Promise<StepState>
-  getStepState(runId: string, stepName: string): Promise<StepState>
-  setStepRunning(stepId: string): Promise<void>
-  setStepScheduled(stepId: string): Promise<void>
-  setStepResult(stepId: string, result: any): Promise<void>
-  setStepChildRunId(stepId: string, childRunId: string): Promise<void>
-  setStepError(stepId: string, error: Error): Promise<void>
-  createRetryAttempt(
-    stepId: string,
-    status: 'pending' | 'running'
-  ): Promise<StepState>
-
-  executeWorkflowStep(
-    runId: string,
-    stepName: string,
-    rpcName: string | null,
-    data: any,
-    rpcService: any
-  ): Promise<void>
-
-  upsertWorkflowVersion(
-    name: string,
-    graphHash: string,
-    graph: any,
-    source: string,
-    status?: WorkflowVersionStatus
-  ): Promise<void>
-  updateWorkflowVersionStatus(
-    name: string,
-    graphHash: string,
-    status: WorkflowVersionStatus
-  ): Promise<void>
-  getWorkflowVersion(
-    name: string,
-    graphHash: string
-  ): Promise<{ graph: any; source: string } | null>
-}

package/src/side-effects-are-declared.test.ts

@@ -1,84 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync, readdirSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { join, dirname, relative } from 'node:path'
-
-const srcRoot = dirname(fileURLToPath(import.meta.url))
-const packageRoot = join(srcRoot, '..')
-
-/**
- * A statement that runs when the module is imported, rather than when
- * something in it is called. Today every one is an `addError(...)` registering
- * an error class in the runtime registry.
- */
-const TOP_LEVEL_CALL = /^[a-zA-Z_$][\w.$]*\(/
-
-const collectSourceFiles = (directory: string): string[] =>
-  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
-    const entryPath = join(directory, entry.name)
-    if (entry.isDirectory()) {
-      return entry.name === 'dist' ? [] : collectSourceFiles(entryPath)
-    }
-    return entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')
-      ? [entryPath]
-      : []
-  })
-
-/** Source modules that do something merely by being imported. */
-const modulesWithSideEffects = (): string[] =>
-  collectSourceFiles(srcRoot)
-    .filter((file) =>
-      readFileSync(file, 'utf-8')
-        .split('\n')
-        .some((line) => TOP_LEVEL_CALL.test(line))
-    )
-    .map((file) => `./dist/${relative(srcRoot, file).replace(/\.ts$/, '.js')}`)
-    .sort()
-
-const declared = (): string[] => {
-  const pkg = JSON.parse(
-    readFileSync(join(packageRoot, 'package.json'), 'utf-8')
-  )
-  return [...(pkg.sideEffects ?? [])].sort()
-}
-
-/**
- * `sideEffects` tells a bundler which modules it may not drop. Claiming
- * `false` outright would be untrue — the error registry is built by
- * `addError(...)` calls that run on import, and a bundler that dropped
- * `errors/errors.js` would leave `getErrorResponse` unable to find any of
- * them. Naming the modules exactly lets everything else be tree-shaken.
- *
- * knowledge: decisions/internals/side-effects-are-an-allowlist-not-a-boolean.md
- */
-describe('every module with import-time side effects is declared', () => {
-  test('the allowlist matches the modules that actually have them', () => {
-    const actual = modulesWithSideEffects()
-    const listed = declared()
-
-    assert.deepEqual(
-      { missing: actual.filter((m) => !listed.includes(m)) },
-      { missing: [] },
-      'a module runs code on import but is not in package.json sideEffects. ' +
-        'A bundler may drop it, and whatever it registered will be absent at ' +
-        'runtime.'
-    )
-
-    assert.deepEqual(
-      { stale: listed.filter((m) => !actual.includes(m)) },
-      { stale: [] },
-      'package.json sideEffects names a module that no longer has any — ' +
-        'remove it so bundlers can tree-shake it.'
-    )
-  })
-
-  test('the detector finds a known side effect', () => {
-    // Guards the test above: a detector matching nothing would pass whatever
-    // package.json claimed.
-    assert.ok(
-      modulesWithSideEffects().includes('./dist/errors/errors.js'),
-      'errors/errors.js registers every error class at import and must match'
-    )
-  })
-})

package/src/source-files-stay-composable.test.ts

@@ -1,41 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync, readdirSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { join, dirname, relative } from 'node:path'
-
-const srcRoot = dirname(fileURLToPath(import.meta.url))
-
-/**
- * The ceiling a single module may reach before it has to be composed out of
- * smaller ones.
- */
-const MAX_LINES = 2000
-
-const collectSourceFiles = (directory: string): string[] =>
-  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
-    const entryPath = join(directory, entry.name)
-    if (entry.isDirectory()) {
-      return entry.name === 'dist' ? [] : collectSourceFiles(entryPath)
-    }
-    return entry.name.endsWith('.ts') ? [entryPath] : []
-  })
-
-describe('source files stay composable', () => {
-  test(`no module in @pikku/core exceeds ${MAX_LINES} lines`, () => {
-    const offenders = collectSourceFiles(srcRoot)
-      .map((file) => ({
-        file: relative(srcRoot, file),
-        lines: readFileSync(file, 'utf-8').split('\n').length,
-      }))
-      .filter(({ lines }) => lines > MAX_LINES)
-      .sort((a, b) => b.lines - a.lines)
-
-    assert.deepEqual(
-      offenders,
-      [],
-      `modules over ${MAX_LINES} lines:\n` +
-        offenders.map(({ file, lines }) => `  ${lines}  ${file}`).join('\n')
-    )
-  })
-})

package/src/template-alias-surface.test.ts

@@ -1,240 +0,0 @@
-import { test, describe } from 'node:test'
-import * as assert from 'assert'
-import ts from 'typescript'
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-/**
- * Templates are the one tree that is copied verbatim into a user's project, so
- * whatever they import is what every new Pikku app starts life importing. The
- * app-developer surface is the generated `#pikku` alias; a relative path into
- * `.pikku` reaches the same file but teaches the wrong habit, and it breaks the
- * moment `create-pikku` moves the directory — which it does for StackBlitz,
- * where `.pikku` becomes `pikku-gen`.
- */
-const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
-const templatesDir = join(repoRoot, 'templates')
-const skipped = new Set(['node_modules', 'dist', '.pikku', '.next', 'build'])
-
-const walk = (dir: string, out: string[] = []): string[] => {
-  for (const entry of readdirSync(dir)) {
-    if (skipped.has(entry)) continue
-    const path = join(dir, entry)
-    if (statSync(path).isDirectory()) walk(path, out)
-    else if (path.endsWith('.ts') || path.endsWith('.tsx')) out.push(path)
-  }
-  return out
-}
-
-/**
- * `.gen.*` and `.d.ts` files are CLI output rather than template source: what
- * they import is decided by the codegen serializers, not by the template.
- */
-const isGenerated = (path: string) =>
-  path.includes('.gen.') || path.endsWith('.d.ts')
-
-const templateNames = () =>
-  readdirSync(templatesDir).filter((name) =>
-    existsSync(join(templatesDir, name, 'package.json'))
-  )
-
-const templateSourceFiles = (template: string) => {
-  const dir = join(templatesDir, template)
-  return walk(dir).filter((file) => !isGenerated(file))
-}
-
-/**
- * Parsed rather than grepped, so a `.pikku` path quoted inside a string
- * literal — a config default, a doc comment, a codegen fixture — is not
- * mistaken for an import the template actually makes.
- */
-const generatedImports = (file: string) => {
-  const source = ts.createSourceFile(
-    file,
-    readFileSync(file, 'utf8'),
-    ts.ScriptTarget.Latest,
-    true
-  )
-  const found: { specifier: string; line: number }[] = []
-  for (const statement of source.statements) {
-    if (
-      !ts.isImportDeclaration(statement) &&
-      !ts.isExportDeclaration(statement)
-    ) {
-      continue
-    }
-    const moduleSpecifier = statement.moduleSpecifier
-    if (!moduleSpecifier || !ts.isStringLiteral(moduleSpecifier)) continue
-    const specifier = moduleSpecifier.text
-    if (!specifier.startsWith('.')) continue
-    if (!/(^|\/)\.pikku\//.test(specifier)) continue
-    const { line } = source.getLineAndCharacterOfPosition(
-      statement.getStart(source)
-    )
-    found.push({ specifier, line: line + 1 })
-  }
-  return found
-}
-
-/**
- * Bun resolves a '#'-prefixed specifier as a Node subpath import and does not
- * apply tsconfig `paths` to it, so neither half of the alias reaches the
- * functions template next door: Node rejects the '../' imports target, and
- * `paths` is never consulted. Until the bun template takes a workspace
- * dependency on the functions template — which makes a bare specifier a legal
- * imports target — it has no alias mechanism and keeps the relative path.
- */
-const withoutAlias = new Set(['bun'])
-
-describe('templates ship the #pikku alias', () => {
-  test('no template reaches generated output through a relative path', () => {
-    const offenders: string[] = []
-
-    for (const template of templateNames()) {
-      if (withoutAlias.has(template)) continue
-      for (const file of templateSourceFiles(template)) {
-        for (const { specifier, line } of generatedImports(file)) {
-          offenders.push(`${relative(repoRoot, file)}:${line}  ${specifier}`)
-        }
-      }
-    }
-
-    assert.deepStrictEqual(
-      offenders,
-      [],
-      `Templates must reach generated output through the '#pikku' alias.\n` +
-        `A relative path into '.pikku' is the specifier every scaffolded app ` +
-        `would inherit, and it breaks when create-pikku relocates the ` +
-        `directory.\n\n` +
-        offenders.join('\n')
-    )
-  })
-
-  /**
-   * `paths` is what actually resolves the alias in a runtime template: it
-   * points at the functions template next door, and tsx, tsc and the
-   * inspector all consult it. The inspector in particular builds its own
-   * program and inherits only baseUrl, paths, rootDirs and pathsBasePath —
-   * it never sees an imports map.
-   */
-  test('every template using #pikku declares it in tsconfig paths', () => {
-    const offenders: string[] = []
-
-    for (const template of templateNames()) {
-      const usesAlias = templateSourceFiles(template).some((file) =>
-        /['"]#pikku\//.test(readFileSync(file, 'utf8'))
-      )
-      if (!usesAlias) continue
-
-      const tsconfigPath = join(templatesDir, template, 'tsconfig.json')
-      if (!existsSync(tsconfigPath)) {
-        offenders.push(`templates/${template}/tsconfig.json  missing`)
-        continue
-      }
-      const tsconfig = JSON.parse(readFileSync(tsconfigPath, 'utf8'))
-      if (!tsconfig.compilerOptions?.paths?.['#pikku/*']) {
-        offenders.push(`templates/${template}/tsconfig.json  missing paths`)
-      }
-    }
-
-    assert.deepStrictEqual(
-      offenders,
-      [],
-      `A template that imports '#pikku/…' has to declare it in tsconfig ` +
-        `'paths', which is what resolves it.\n\n` +
-        offenders.join('\n')
-    )
-  })
-
-  /**
-   * Every `#pikku/…` pattern shares the prefix `#pikku/`, and TypeScript picks
-   * the matching pattern with the longest prefix, ignoring the suffix and
-   * breaking the tie in favour of the first key. So a suffix-specific pattern
-   * such as `#pikku/*.json` only ever wins by being listed before the bare one
-   * — an ordering that does not survive `create-pikku` deep-merging the runtime
-   * template's tsconfig with the functions template's.
-   *
-   * The bare pattern therefore has to resolve a file as well as a directory
-   * index, which a target list does: `#pikku/mcp/mcp.gen.json` misses
-   * `.pikku/mcp/mcp.gen.json/index.ts` and lands on the file behind it.
-   */
-  test('the bare #pikku pattern resolves a file, not only a directory index', () => {
-    const offenders: string[] = []
-
-    for (const template of templateNames()) {
-      const declare = (
-        source: string,
-        targets: string | string[] | undefined
-      ) => {
-        if (targets === undefined) return
-        const list = Array.isArray(targets) ? targets : [targets]
-        // A directory-index target ends in the index file; anything else names
-        // whatever the alias was pointed at, which is what a file needs.
-        if (list.every((target) => /\/index\.[cm]?[jt]s$/.test(target))) {
-          offenders.push(`${source}  ${list.join(', ')}`)
-        }
-      }
-
-      const tsconfigPath = join(templatesDir, template, 'tsconfig.json')
-      if (existsSync(tsconfigPath)) {
-        const tsconfig = JSON.parse(readFileSync(tsconfigPath, 'utf8'))
-        declare(
-          `templates/${template}/tsconfig.json`,
-          tsconfig.compilerOptions?.paths?.['#pikku/*']
-        )
-      }
-
-      const pkg = JSON.parse(
-        readFileSync(join(templatesDir, template, 'package.json'), 'utf8')
-      )
-      declare(
-        `templates/${template}/package.json`,
-        pkg.imports?.['#pikku/*'] as string | string[] | undefined
-      )
-    }
-
-    assert.deepStrictEqual(
-      offenders,
-      [],
-      `The bare '#pikku/*' pattern must list a file target alongside the ` +
-        `directory index, because a suffix-specific pattern like ` +
-        `'#pikku/*.json' loses to it whenever it is not listed first — and ` +
-        `create-pikku's merge decides that order.\n\n` +
-        offenders.join('\n')
-    )
-  })
-
-  /**
-   * Node rejects an internal-imports target that is not './'-relative or a
-   * bare package specifier, so a '../' target throws ERR_INVALID_PACKAGE_TARGET
-   * rather than resolving. A runtime template reaching the functions template
-   * next door cannot express that as an imports map at all — it resolves
-   * through `paths`, and declaring the map anyway only looks like it works,
-   * because `paths` answers first.
-   */
-  test('no template declares an imports target Node will reject', () => {
-    const offenders: string[] = []
-
-    for (const template of templateNames()) {
-      const pkg = JSON.parse(
-        readFileSync(join(templatesDir, template, 'package.json'), 'utf8')
-      )
-      for (const [specifier, target] of Object.entries(pkg.imports ?? {})) {
-        if (typeof target === 'string' && target.startsWith('../')) {
-          offenders.push(
-            `templates/${template}/package.json  ${specifier} -> ${target}`
-          )
-        }
-      }
-    }
-
-    assert.deepStrictEqual(
-      offenders,
-      [],
-      `An 'imports' target must start with './' or be a bare package ` +
-        `specifier; '../' throws ERR_INVALID_PACKAGE_TARGET.\n\n` +
-        offenders.join('\n')
-    )
-  })
-})

package/src/test-utils.ts

@@ -1,38 +0,0 @@
-import { getAllPackageStates } from './pikku-state.js'
-import { clearMiddlewareCache } from './middleware-runner.js'
-import { clearPermissionsCache } from './permissions.js'
-import { clearChannelMiddlewareCache } from './wirings/channel/channel-middleware-runner.js'
-
-/**
- * Clears all runtime caches between test scenarios without touching registered
- * routes, functions, or middleware groups (which are set at module load time
- * and must persist for the whole test run).
- *
- * Call this alongside your DB snapshot restore in your Before hook:
- *
- * ```typescript
- * Before(async function() {
- *   await restoreSnapshot()
- *   clearPikkuRuntimeState()
- *   setSingletonServices(bundle.services)
- * })
- * ```
- *
- * Only works when NODE_ENV === 'test'. Logs an error and returns otherwise.
- */
-export const clearPikkuRuntimeState = (): void => {
-  if (process.env.NODE_ENV !== 'test') {
-    console.error(
-      '[pikku] clearPikkuRuntimeState() must only be called in test environments. Ignoring.'
-    )
-    return
-  }
-
-  clearMiddlewareCache()
-  clearPermissionsCache()
-  clearChannelMiddlewareCache()
-
-  for (const packageState of getAllPackageStates().values()) {
-    packageState.package.singletonServices = null
-  }
-}

package/src/testing/index.ts

@@ -1,3 +0,0 @@
-export { defineServiceTests } from './service-tests.js'
-export type { ServiceTestConfig } from './service-tests.js'
-export { clearPikkuRuntimeState } from '../test-utils.js'

package/src/testing/service-tests/agent-run-service-tests.ts

@@ -1,98 +0,0 @@
-import { describe, test, before } from 'node:test'
-import assert from 'node:assert/strict'
-
-import type { AgentRunService } from '../../wirings/agent/agent.types.js'
-import type { ServiceTestConfig } from '../service-tests.js'
-
-/** Conformance suite for `agentRunService`. Runs only when a backend supplies one. */
-export const defineAgentRunServiceTests = (
-  name: string,
-  agentRunService: NonNullable<
-    ServiceTestConfig['services']['agentRunService']
-  >,
-  /**
-   * Thread-ownership is a property of the two services together — the run
-   * service lists what the storage service owns — so that half of the suite
-   * only runs when a backend supplies both. Passed explicitly rather than
-   * closed over, so the dependency is visible in the signature.
-   */
-  agentStorageService?: ServiceTestConfig['services']['agentStorageService']
-): void => {
-  const factory = agentRunService
-  describe(`AgentRunService [${name}]`, () => {
-    let agentService: AgentRunService
-
-    before(async () => {
-      agentService = await factory()
-    })
-
-    test('listThreads', async () => {
-      const threads = await agentService.listThreads()
-      assert.ok(Array.isArray(threads))
-    })
-
-    if (agentStorageService) {
-      const storageFactory = agentStorageService
-
-      // The `owners` constraint is what keeps the generated thread-management
-      // functions from leaking across tenants: a caller may only list threads
-      // owned by one of their session principals, matching the
-      // `principal:sub-partition` composition resolveOwnerResourceId writes.
-      test('listThreads scopes to the given owners, including sub-partitions', async () => {
-        const storage = await storageFactory()
-        await storage.createThread('owner-alice')
-        await storage.createThread('owner-alice:project-1')
-        await storage.createThread('owner-bob:secret')
-
-        const threads = await agentService.listThreads({
-          owners: ['owner-alice'],
-        })
-        const ids = threads.map((t) => t.resourceId)
-
-        assert.ok(ids.includes('owner-alice'))
-        assert.ok(ids.includes('owner-alice:project-1'))
-        assert.ok(
-          !ids.some((id) => id.startsWith('owner-bob')),
-          "another owner's threads must not be listed"
-        )
-      })
-
-      test('listThreads with an owner does not match a lookalike prefix', async () => {
-        const storage = await storageFactory()
-        await storage.createThread('owner-al')
-        await storage.createThread('owner-alice-evil:p')
-
-        const threads = await agentService.listThreads({
-          owners: ['owner-al'],
-        })
-        const ids = threads.map((t) => t.resourceId)
-
-        assert.ok(ids.includes('owner-al'))
-        assert.ok(!ids.includes('owner-alice-evil:p'))
-      })
-
-      test('listThreads with an empty owners list returns nothing', async () => {
-        const storage = await storageFactory()
-        await storage.createThread('owner-empty-check')
-
-        const threads = await agentService.listThreads({ owners: [] })
-        assert.deepEqual(threads, [])
-      })
-    }
-
-    test('getThread returns null for missing', async () => {
-      const thread = await agentService.getThread('missing-thread')
-      assert.equal(thread, null)
-    })
-
-    test('getDistinctAgentNames', async () => {
-      const names = await agentService.getDistinctAgentNames()
-      assert.ok(Array.isArray(names))
-    })
-
-    test('deleteThread returns false for missing', async () => {
-      const result = await agentService.deleteThread('missing-thread')
-      assert.equal(result, false)
-    })
-  })
-}