@pikku/core 0.12.107 → 0.12.112

package/src/factory-functions.test.ts

@@ -1,111 +0,0 @@
-import { test } from 'node:test'
-import assert from 'node:assert'
-import {
-  pikkuAuth,
-  pikkuPermission,
-  pikkuPermissionFactory,
-} from './function/functions.types.js'
-import {
-  pikkuMiddleware,
-  pikkuMiddlewareFactory,
-} from './middleware/middleware-factories.js'
-
-test('pikkuPermission returns the same function', async () => {
-  const originalFn = async () => true
-  const wrappedFn = pikkuPermission(originalFn)
-  assert.strictEqual(wrappedFn, originalFn)
-})
-
-test('pikkuMiddleware returns the same function', async () => {
-  const originalFn = async ({ logger }, wires, next) => next
-  const wrappedFn = pikkuMiddleware(originalFn)
-  assert.strictEqual(wrappedFn, originalFn)
-})
-
-test('pikkuPermissionFactory creates a factory function', async () => {
-  const factory = pikkuPermissionFactory<{ role: string }>(({ role }) => {
-    return pikkuPermission(async ({ logger }, data, { session }) => {
-      return (session as any)?.role === role
-    })
-  })
-
-  assert.strictEqual(typeof factory, 'function')
-  assert.strictEqual(factory.length, 1) // input parameter
-
-  // Call the factory to get a permission
-  const permission = factory({ role: 'admin' })
-  assert.strictEqual(typeof permission, 'function')
-  assert.strictEqual(permission.length, 3) // services, data, session
-})
-
-test('pikkuMiddlewareFactory creates a factory function', async () => {
-  const factory = pikkuMiddlewareFactory<{ message: string }>(({ message }) => {
-    return pikkuMiddleware(async ({ logger }, wires, next) => {
-      logger.info(message)
-      await next()
-    })
-  })
-
-  assert.strictEqual(typeof factory, 'function')
-  assert.strictEqual(factory.length, 1) // input parameter
-
-  // Call the factory to get middleware
-  const middleware = factory({ message: 'test' })
-  assert.strictEqual(typeof middleware, 'function')
-  assert.strictEqual(middleware.length, 3) // services, wires, next
-})
-
-test('pikkuPermissionFactory returns the same factory', async () => {
-  const originalFactory = () => pikkuPermission(async () => true)
-  const wrappedFactory = pikkuPermissionFactory(originalFactory as any)
-  assert.strictEqual(wrappedFactory, originalFactory)
-})
-
-test('pikkuMiddlewareFactory returns the same factory', async () => {
-  const originalFactory = ({ message }) =>
-    pikkuMiddleware(async ({ logger }, _wires, next) => {
-      logger.info(message)
-      await next()
-    })
-  const wrappedFactory = pikkuMiddlewareFactory(originalFactory)
-  assert.strictEqual(wrappedFactory, originalFactory)
-})
-
-test('pikkuAuth returns a 3-arg wrapper function', async () => {
-  const authFn = async (_services, session) => !!session
-  const wrapped = pikkuAuth(authFn)
-  assert.strictEqual(typeof wrapped, 'function')
-  assert.strictEqual(wrapped.length, 3)
-})
-
-test('pikkuAuth wrapper extracts session from wire and calls auth function', async () => {
-  let receivedSession = null
-  const authFn = async (_services, session) => {
-    receivedSession = session
-    return session.role === 'admin'
-  }
-  const wrapped = pikkuAuth(authFn)
-  const result = await wrapped({}, null, { session: { role: 'admin' } })
-  assert.strictEqual(result, true)
-  assert.deepStrictEqual(receivedSession, { role: 'admin' })
-})
-
-test('pikkuAuth wrapper returns false when no session', async () => {
-  const authFn = async (_services, session) => !!session
-  const wrapped = pikkuAuth(authFn)
-  const result = await wrapped({}, null, { session: null })
-  assert.strictEqual(result, false)
-})
-
-test('pikkuAuth config object syntax works', async () => {
-  const authFn = async (_services, session) => !!session
-  const wrapped = pikkuAuth({
-    func: authFn,
-    name: 'Is Authenticated',
-    description: 'Checks if user has a session',
-  })
-  assert.strictEqual(typeof wrapped, 'function')
-  assert.strictEqual(wrapped.length, 3)
-  const result = await wrapped({}, null, { session: { id: '1' } })
-  assert.strictEqual(result, true)
-})

package/src/function/abort-scope.test.ts

@@ -1,97 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import {
-  AbandonedError,
-  beginChanges,
-  getAbortScope,
-  runInAbortScope,
-  type AbortScope,
-} from './abort-scope.js'
-
-describe('beginChanges', () => {
-  test('is a no-op outside a scope, so a function need not know how it was called', async () => {
-    await beginChanges()
-    assert.equal(getAbortScope(), undefined)
-  })
-
-  test('lets the mutation proceed while the caller is still there', async () => {
-    let declared = false
-    const scope: AbortScope = {
-      abandoned: false,
-      onBeginChanges: () => {
-        declared = true
-      },
-    }
-
-    let mutated = false
-    await runInAbortScope(scope, async () => {
-      await beginChanges()
-      mutated = true
-    })
-
-    assert.equal(mutated, true)
-    assert.equal(declared, true)
-  })
-
-  test('stops the mutation when the caller has gone, and reports why', async () => {
-    let mutated = false
-    const scope: AbortScope = { abandoned: true, reason: 'speech' }
-
-    await assert.rejects(
-      () =>
-        runInAbortScope(scope, async () => {
-          await beginChanges()
-          mutated = true
-        }),
-      (error: unknown) => {
-        assert.ok(error instanceof AbandonedError)
-        assert.match(error.message, /speech/)
-        return true
-      }
-    )
-
-    // The whole point: the irreversible line never ran.
-    assert.equal(mutated, false)
-  })
-
-  test('survives the await boundaries a real function has', async () => {
-    // AsyncLocalStorage is the reason this works — the checkpoint is usually
-    // several awaits deep inside helpers that never took the scope as an
-    // argument.
-    const scope: AbortScope = { abandoned: true }
-    const nestedHelper = async () => {
-      await new Promise((resolve) => setImmediate(resolve))
-      await beginChanges()
-    }
-
-    await assert.rejects(
-      () =>
-        runInAbortScope(scope, async () => {
-          await new Promise((resolve) => setImmediate(resolve))
-          return nestedHelper()
-        }),
-      AbandonedError
-    )
-  })
-
-  test('reads the scope live, so an interrupt mid-function is still caught', async () => {
-    let aborted = false
-    const scope: AbortScope = {
-      get abandoned() {
-        return aborted
-      },
-    }
-
-    await assert.rejects(
-      () =>
-        runInAbortScope(scope, async () => {
-          // Plenty of interruptible work happens before the checkpoint.
-          await new Promise((resolve) => setImmediate(resolve))
-          aborted = true
-          await beginChanges()
-        }),
-      AbandonedError
-    )
-  })
-})

package/src/function/abort-scope.ts

@@ -1,80 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks'
-
-/**
- * Raised by {@link beginChanges} when the caller has gone away before anything
- * was changed. Distinct from a failure: nothing happened, so there is nothing
- * to report, retry or apologise for.
- */
-export class AbandonedError extends Error {
-  constructor(reason?: string) {
-    super(
-      reason
-        ? `Aborted before making changes: ${reason}`
-        : 'Aborted before making changes'
-    )
-    this.name = 'AbandonedError'
-  }
-}
-
-export interface AbortScope {
-  /** Whether whatever asked for this work has gone away. */
-  readonly abandoned: boolean
-  /** Why, when known — an interrupt reason, a disconnect, a cancellation. */
-  readonly reason?: string
-  /** Called by `beginChanges()` once a function commits to mutating. */
-  onBeginChanges?: () => void
-}
-
-/**
- * The ambient "is my caller still there?" signal.
- *
- * Ambient rather than a parameter because the question is the same one for
- * every wiring — an agent run that was interrupted, an HTTP request whose
- * client disconnected, a cancelled workflow — and threading it through every
- * signature would mean changing every function that merely sits between the
- * wiring and the mutation.
- */
-const scopeStorage = new AsyncLocalStorage<AbortScope>()
-
-/** Run `fn` with an abort scope that `beginChanges()` will observe. */
-export const runInAbortScope = <T>(scope: AbortScope, fn: () => T): T =>
-  scopeStorage.run(scope, fn)
-
-/** The current scope, if the caller is running inside one. */
-export const getAbortScope = (): AbortScope | undefined =>
-  scopeStorage.getStore()
-
-/**
- * Declare that everything after this line changes something.
- *
- * ```ts
- * const plan = await computePlan(input)   // interruptible, costs nothing to redo
- * await beginChanges()
- * await db.deleteProject(input.projectId) // past the point of no return
- * ```
- *
- * Two things happen here. If the caller has already gone away it throws, so the
- * mutation never runs and the interrupt is clean — nothing happened, and the
- * user is told nothing because there is nothing to tell. If the caller is still
- * there it marks this call as mutating, so an interrupt landing *after* this
- * point produces an `undelivered` note on the thread rather than silently
- * discarding work that did happen.
- *
- * It throws rather than returning a boolean on purpose: `if (await ...)` invites
- * ignoring the answer, and the failure mode of ignoring it is a mutation nobody
- * asked for.
- *
- * Entirely cooperative, and safe to call anywhere — outside a scope it is a
- * no-op, so a function does not need to know how it was invoked. A function
- * that never calls it keeps the conservative default: if it is not marked
- * `readonly`, an interrupt assumes it changed something and says so. The tool
- * that forgot to call this is exactly the one that cannot be assumed harmless.
- */
-export const beginChanges = async (): Promise<void> => {
-  const scope = scopeStorage.getStore()
-  if (!scope) return
-  if (scope.abandoned) {
-    throw new AbandonedError(scope.reason)
-  }
-  scope.onBeginChanges?.()
-}

package/src/function/function-meta.types.ts

@@ -1,151 +0,0 @@
-import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
-import type { AuditDurability } from '../services/audit-service.js'
-import type {
-  ScenarioStepKind,
-  ScenarioSurface,
-} from '../wirings/workflow/scenario-step.types.js'
-import type { CommonWireMeta } from '../types/core.types.js'
-
-export interface FunctionServicesMeta {
-  optimized: boolean
-  services: string[]
-}
-
-export interface FunctionWiresMeta {
-  optimized: boolean
-  wires: string[]
-}
-
-/**
- * A reference to a permission function, resolved by name. Function-scoped
- * only: there are no wire- or tag-level permission references.
- */
-export type PermissionMetadata = {
-  type: 'wire'
-  name: string
-  inline?: boolean
-}
-
-export type FunctionRuntimeMeta = {
-  pikkuFuncId: string
-  inputSchemaName: string | null
-  outputSchemaName: string | null
-  /** Scopes the session must hold to run this function. All are required (AND). */
-  scopes?: string[]
-  expose?: boolean
-  /**
-   * A sessionless function's own `auth: true`. `sessionless` carries the
-   * baseline — a `pikkuFunc` always requires a session — and this carries the
-   * tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to
-   * know whether a function is gated without running it.
-   */
-  auth?: boolean
-  /**
-   * The author's declaration that this function's permission check lives in its
-   * own body. Carries no runtime effect — it records a gate codegen cannot see,
-   * so an audit is not left to guess whether a sessionless function is open.
-   * Refused unless `allow.permissionsInBody` is set in `pikku.config.json`.
-   */
-  permissionsInBody?: boolean
-  remote?: boolean
-  /**
-   * A step RPC: invoked by name only from a scenario run and refused
-   * everywhere else, so it is never network-callable.
-   */
-  scenarioStep?: boolean
-  /**
-   * The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`,
-   * so it is held back from the app bootstrap and from every deployed unit.
-   */
-  scenario?: boolean
-  mcp?: boolean
-  readonly?: boolean
-  deploy?: 'serverless' | 'server' | 'auto'
-  sessionless?: boolean
-  /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. */
-  workflowQueued?: boolean
-  /** Retry count when this function is used as a workflow step. */
-  workflowRetries?: number
-  /** Timeout when this function is used as a workflow step (e.g. '30s', '5m'). */
-  workflowTimeout?: string
-  /**
-   * Scenario steps only: which surfaces this step declares a binding for.
-   *
-   * The reporter derives coverage from this — a `then` with no binding for the
-   * surface the run targeted was never actually witnessed there, which is a gap
-   * worth counting rather than excusing.
-   */
-  scenarioStepSurfaces?: ScenarioSurface[]
-  /**
-   * Scenario steps only: this step runs as a persona, so every call site must
-   * pass one and the runner injects it as `wire.actor`.
-   *
-   * Declared by `actor: true`, or implied by a `browser` binding — a window is
-   * opened as somebody. Absent on a step with nobody to be: an assertion over
-   * what an earlier step returned, or one posting credentials precisely because
-   * it must not reuse an actor's session.
-   */
-  scenarioStepRequiresActor?: boolean
-  /**
-   * Scenario steps only: who acts. Absent means `persona` — the ordinary step,
-   * and the only kind that existed before the other two.
-   *
-   * A `platform` or `addon` step is the app or a third-party system acting, and
-   * it must never reach a virtual user's catalogue. That is not tidiness: a
-   * virtual user that can invoke "Stripe's webhook arrives" can forge its own
-   * payment success, and every finding downstream of that is worthless.
-   */
-  scenarioStepKind?: ScenarioStepKind
-  /** Addon steps only: the addon whose system acts — `wireAddon`'s `name`. */
-  scenarioStepAddon?: string
-  /** Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input. */
-  scenarioStepTemplate?: string
-  /**
-   * The function's `audit` config, resolved — `audit: true` reads as
-   * `{ durability: 'best-effort' }`. Absent means the function records nothing:
-   * `auditLog.write()` from an unmarked function is dropped with a warning, so
-   * this is the only place a reader can see which functions have a trail at all
-   * without running them.
-   *
-   * Informational. The runner resolves audit from the live function config, not
-   * from here, so meta and runtime cannot disagree about whether audit is on.
-   */
-  audit?: {
-    durability: AuditDurability
-  }
-  version?: number
-  approvalRequired?: boolean
-  approvalDescription?: string
-  implementationHash?: string
-  contractHash?: string
-  inputHash?: string
-  outputHash?: string
-}
-
-export type FunctionMeta = FunctionRuntimeMeta &
-  Partial<
-    {
-      name: string
-      /** `remote`: a contract with no local body, answered by a connected client. */
-      functionType: 'user' | 'inline' | 'helper' | 'remote'
-      funcWrapper: string
-      services: FunctionServicesMeta
-      wires: FunctionWiresMeta
-      inputs: string[] | null
-      outputs: string[] | null
-      middleware: MiddlewareMetadata[]
-      permissions: PermissionMetadata[]
-      isDirectFunction: boolean
-      sourceFile: string
-      exportedName: string
-      /** File containing the handler body when it differs from sourceFile (imported handlers) */
-      bodySourceFile?: string
-      /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
-      bodyStart: number
-      /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
-      bodyEnd: number
-    } & CommonWireMeta
-  >
-
-export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
-export type FunctionsMeta = Record<string, FunctionMeta>