@pikku/core 0.12.106 → 0.12.111

package/src/function/functions.types.ts

@@ -1,319 +0,0 @@
-import type {
-  CoreServices,
-  CoreSecretlessSingletonServices,
-  CoreUserSession,
-  PikkuWire,
-  SecretlessServices,
-} from '../types/core.types.js'
-import type { CorePikkuMiddleware } from '../middleware/middleware.types.js'
-import type { PickRequired } from '../utils.js'
-import type { PikkuRPC } from '../wirings/rpc/rpc-types.js'
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-import type { PikkuError } from '../errors/error-handler.js'
-import type { CoreNodeConfig } from '../wirings/node/node.types.js'
-import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js'
-import type { Safe } from '../classification/secret-value.js'
-
-export type CorePikkuFunction<
-  In,
-  Out,
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Session extends CoreUserSession = CoreUserSession,
-  Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> =
-    PikkuWire<In, Out, true, Session>,
-> = (
-  services: Services,
-  data: In,
-  wire: Wire
-) => Wire['channel'] extends null
-  ? Promise<Safe<Out>>
-  : Promise<Safe<Out>> | Promise<void>
-
-export type CorePikkuFunctionSessionless<
-  In,
-  Out,
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Session extends CoreUserSession = CoreUserSession,
-  Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> =
-    PikkuWire<In, Out, false, Session>,
-> = (
-  services: Services,
-  data: In,
-  wire: Wire
-) => Wire['channel'] extends null
-  ? Promise<Safe<Out>>
-  : Promise<Safe<Out>> | Promise<void>
-
-export type CorePikkuPermission<
-  In = any,
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
-    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
-> = (services: Services, data: In, wire: Wire) => Promise<boolean>
-
-export type CorePikkuPermissionConfig<
-  In = any,
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
-    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
-> = {
-  func: CorePikkuPermission<In, Services, Wire>
-  name?: string
-  description?: string
-}
-
-export const pikkuPermission = <
-  In = any,
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Wire extends PickRequired<
-    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
-    'session'
-  > = PickRequired<
-    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
-    'session'
-  >,
->(
-  permission:
-    | CorePikkuPermission<In, Services, Wire>
-    | CorePikkuPermissionConfig<In, Services, Wire>
-): CorePikkuPermission<In, Services, Wire> => {
-  return typeof permission === 'function' ? permission : permission.func
-}
-
-export type CorePikkuPermissionFactory<
-  In = any,
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
-    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
-> = (input: In) => CorePikkuPermission<any, Services, Wire>
-
-export const pikkuPermissionFactory = <In = any>(
-  factory: CorePikkuPermissionFactory<In>
-): CorePikkuPermissionFactory<In> => {
-  return factory
-}
-
-/**
- * Renders a human-readable approval prompt for an AI agent, in place of the
- * raw tool arguments.
- */
-export type CorePikkuApprovalDescription<
-  In = any,
-  Services extends CoreSecretlessSingletonServices =
-    CoreSecretlessSingletonServices,
-> = (services: Services, data: In) => Promise<string>
-
-export const pikkuApprovalDescription = <
-  In = any,
-  Services extends CoreSecretlessSingletonServices =
-    CoreSecretlessSingletonServices,
->(
-  fn: CorePikkuApprovalDescription<In, Services>
-): CorePikkuApprovalDescription<In, Services> => {
-  return fn
-}
-
-export type CorePikkuAuth<
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Session extends CoreUserSession = CoreUserSession,
-> = (services: Services, session: Session) => Promise<boolean> | boolean
-
-export type CorePikkuAuthConfig<
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Session extends CoreUserSession = CoreUserSession,
-> = {
-  func: CorePikkuAuth<Services, Session>
-  name?: string
-  description?: string
-}
-
-/**
- * Marks a permission produced by `pikkuAuth`, so agent tool filtering can tell a
- * session check apart from an ordinary permission.
- *
- * knowledge: decisions/security/permission-auth-filtering-requires-live-permission-functions.md
- */
-export type AuthBranded = { __pikkuAuth?: true }
-
-export const pikkuAuth = <
-  Services extends CoreSecretlessSingletonServices =
-    SecretlessServices<CoreServices>,
-  Session extends CoreUserSession = CoreUserSession,
->(
-  auth:
-    CorePikkuAuth<Services, Session> | CorePikkuAuthConfig<Services, Session>
-): CorePikkuPermission<any, Services, any> => {
-  const fn = typeof auth === 'function' ? auth : auth.func
-  const wrapper: CorePikkuPermission<any, Services, any> & AuthBranded = async (
-    services: Services,
-    _data: any,
-    wire: any
-  ) => {
-    const session = wire.session
-    if (!session) return false
-    return fn(services, session as Session)
-  }
-  wrapper.__pikkuAuth = true
-  return wrapper
-}
-
-export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
-  Record<string, PikkuPermission | PikkuPermission[]> | undefined
-
-/**
- * A lifecycle hook: same call signature as the function it hangs off, return
- * value discarded. Setup/teardown, not a step — no id, no meta, no schema, so
- * it is never recorded and never replayed.
- */
-export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (
-  services: Services,
-  data: Data,
-  wire: Wire
-) => Promise<void> | void
-
-export type CorePikkuFunctionConfig<
-  PikkuFunction extends
-    | CorePikkuFunction<any, any, any, any, any>
-    | CorePikkuFunctionSessionless<any, any, any, any, any>,
-  PikkuPermission extends CorePikkuPermission<any, any, any> =
-    CorePikkuPermission<any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
-    any,
-    any
-  >,
-  InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined,
-  Scope extends string = string,
-> = {
-  /** A human name for this function, shown wherever it is listed rather than called. */
-  title?: string
-  /** What the function does. An agent choosing between tools reads this, so it is worth more care than a comment would be. */
-  description?: string
-  /** Explicit logical name override; lets multiple exports share a versioned base */
-  override?: string
-  /** Which version of this contract this export is. Two exports sharing an `override` and differing here are the same function at two versions. */
-  version?: number
-  /** Filters this function in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-  /** Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone. */
-  expose?: boolean
-  /**
-   * Declares that the body does its own permission check, so the function is
-   * not open despite naming no session, scope or permission. It grants
-   * nothing — asserting it falsely just disables the audit that would have
-   * caught the mistake. Requires `allow.permissionsInBody` in the config.
-   */
-  permissionsInBody?: boolean
-  /** Publishes the function in this package's remote surface, which is what a `wireRemoteAddon` consumer gets a typed client for. */
-  remote?: boolean
-  /** Offers the function to MCP clients as a tool, without a separate `wireMCPTool`. */
-  mcp?: boolean
-  /**
-   * Declares that the function only reads. It is enforced rather than
-   * decorative: a read-only session is refused any function without it, and an
-   * agent may call one without asking permission first.
-   */
-  readonly?: boolean
-  /** Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches. */
-  deploy?: 'serverless' | 'server' | 'auto'
-  /** Under an agent's `explicit` approval policy, calling this pauses for a human to approve it. */
-  approvalRequired?: boolean
-  /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. Defaults to false (inline). */
-  workflowQueued?: boolean
-  /** Number of retry attempts when this function is used as a workflow step. */
-  workflowRetries?: number
-  /** Timeout for this function when used as a workflow step (e.g. '30s', '5m'). */
-  workflowTimeout?: string
-  /**
-   * Scenario steps only: which surfaces this step declares a binding for. The
-   * runner uses it to pick a binding, decide whether to provision a browser,
-   * and report how much of the flow each surface actually covers.
-   */
-  surfaces?: ScenarioSurface[]
-  /** Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`. */
-  requiresActor?: boolean
-  /**
-   * Records every call in the audit log. `transactional` durability writes the
-   * entry in the same transaction as the work, so the two cannot disagree;
-   * `best-effort` does not hold the request up for it.
-   */
-  audit?:
-    | boolean
-    | {
-        durability?: 'best-effort' | 'transactional'
-      }
-  /** Builds the sentence a human is shown when asked to approve a call, from that call's own input. */
-  approvalDescription?: any
-  /** The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away. */
-  func: PikkuFunction
-  /**
-   * Scenarios only: runs before the scenario body, with the scenario's own
-   * signature. Throwing skips the body and fails the run, but `after` still
-   * runs.
-   */
-  before?: CorePikkuFunctionHook
-  /**
-   * Scenarios only: always runs after the body, in a `finally`. Throwing fails
-   * an otherwise-passing run; on an already-failed run it attaches as `cause`
-   * and never replaces the original error.
-   */
-  after?: CorePikkuFunctionHook
-  /**
-   * Scenarios only: why this scenario is held out of a default run. Reported
-   * as skipped rather than quietly omitted; naming it in `--flows` runs it.
-   */
-  skip?: string
-  /** Whether calling this requires a session, wherever it is wired. A wiring can be more permissive than the function, never less. */
-  auth?: boolean
-  /** Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access. */
-  scopes?: Scope[]
-  /** Checks that run before the body. Grouped names OR together, so any one passing admits the caller; use `scopes` to require rather than offer. */
-  permissions?: CorePermissionGroup<PikkuPermission>
-  /** Wraps this function wherever it is called from, unlike wiring middleware which only wraps one route into it. */
-  middleware?: PikkuMiddleware[]
-  /** The input schema, which is also the input type — there is no separate generic to keep in step with it. */
-  input?: InputSchema
-  /** The output schema, which is also the return type. Naming a type here instead is what produces PKU463. */
-  output?: OutputSchema
-  /** Presentation for this function as a node in a workflow graph. */
-  node?: CoreNodeConfig
-  /** Error classes this may throw, so each one's registered HTTP status is used instead of a 500. */
-  errors?: Array<typeof PikkuError>
-}
-
-/**
- * {@link CorePikkuFunctionConfig} for a function that runs without a session.
- *
- * Identical, minus `scopes`. Scopes are AND-ed and `verifyScopes` fails closed,
- * so an anonymous caller holds none and satisfies none — a sessionless function
- * with scopes rejects every caller it exists to serve. Gate it with
- * `permissions`, which receive the optional session and may pass anonymous.
- */
-export type CorePikkuSessionlessFunctionConfig<
-  PikkuFunction extends CorePikkuFunctionSessionless<any, any, any, any, any>,
-  PikkuPermission extends CorePikkuPermission<any, any, any> =
-    CorePikkuPermission<any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
-    any,
-    any
-  >,
-  InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined,
-> = Omit<
-  CorePikkuFunctionConfig<
-    PikkuFunction,
-    PikkuPermission,
-    PikkuMiddleware,
-    InputSchema,
-    OutputSchema
-  >,
-  'scopes'
->

package/src/function/index.ts

@@ -1,40 +0,0 @@
-export {
-  addFunction,
-  getAllFunctionNames,
-  runPikkuFunc,
-} from './function-runner.js'
-export {
-  pikkuAuth,
-  pikkuPermission,
-  pikkuPermissionFactory,
-  pikkuApprovalDescription,
-} from './functions.types.js'
-export type {
-  CorePikkuFunction,
-  CorePikkuFunctionSessionless,
-  CorePikkuFunctionConfig,
-  CorePikkuSessionlessFunctionConfig,
-  CorePikkuAuth,
-  CorePikkuAuthConfig,
-  CorePikkuPermission,
-} from './functions.types.js'
-export type { ListInput, ListOutput, Filter } from './list.types.js'
-export { AbandonedError } from './abort-scope.js'
-export type { AbortScope } from './abort-scope.js'
-export { checkAuthPermissions } from '../permissions.js'
-export type {
-  CorePermissionGroup,
-  CorePikkuApprovalDescription,
-  CorePikkuPermissionConfig,
-  CorePikkuPermissionFactory,
-} from './functions.types.js'
-export type {
-  FunctionMeta,
-  FunctionRuntimeMeta,
-  FunctionServicesMeta,
-  FunctionWiresMeta,
-  FunctionsMeta,
-  FunctionsRuntimeMeta,
-  PermissionMetadata,
-} from './function-meta.types.js'
-export { PikkuRequest } from './pikku-request.js'

package/src/function/list.types.test.ts

@@ -1,100 +0,0 @@
-/**
- * Type-level tests: no runtime assertions — valid shapes must compile and
- * invalid shapes must fail with `@ts-expect-error`. Excluded from `yarn build`
- * via tsconfig's test-file pattern.
- */
-
-import type { ListInput, ListOutput, Filter } from './list.types.js'
-
-type SessionFilter = {
-  status?: string[]
-  therapistId?: string
-  uploadedAt?: string
-}
-type SessionSort = 'user' | 'status' | 'uploaded_at'
-
-const _basic: ListInput<SessionFilter, SessionSort> = {
-  cursor: 'abc',
-  limit: 50,
-  sort: [
-    { column: 'uploaded_at', direction: 'desc' },
-    { column: 'status', direction: 'asc' },
-  ],
-  filter: { status: ['pending'] },
-  search: 'sarah',
-}
-void _basic
-
-const _empty: ListInput = {}
-void _empty
-
-// @ts-expect-error — 'created_at' is not in SessionSort
-const _badSort: ListInput<SessionFilter, SessionSort> = {
-  sort: [{ column: 'created_at', direction: 'asc' }],
-}
-void _badSort
-
-// @ts-expect-error — 'descending' is not a valid direction
-const _badDirection: ListInput<SessionFilter, SessionSort> = {
-  sort: [{ column: 'user', direction: 'descending' }],
-}
-void _badDirection
-
-interface Session {
-  id: string
-  user: string
-  status: string
-}
-
-const _output: ListOutput<Session> = {
-  rows: [{ id: '1', user: 'sarah', status: 'pending' }],
-  nextCursor: null,
-  totalCount: 42,
-}
-void _output
-
-// @ts-expect-error — missing nextCursor
-const _badOutput: ListOutput<Session> = {
-  rows: [],
-}
-void _badOutput
-
-const _leafEq: Filter<SessionFilter> = { therapistId: 'kim' }
-void _leafEq
-
-const _leafIn: Filter<SessionFilter> = { status: ['pending', 'processed'] }
-void _leafIn
-
-const _leafOp: Filter<SessionFilter> = {
-  uploadedAt: { gt: '2026-04-10', lte: '2026-04-17' },
-}
-void _leafOp
-
-const _leafNull: Filter<SessionFilter> = { therapistId: null }
-void _leafNull
-
-const _leafNot: Filter<SessionFilter> = { therapistId: { not: 'kim' } }
-void _leafNot
-
-const _and: Filter<SessionFilter> = [
-  { status: ['pending'] },
-  { therapistId: 'kim' },
-  { uploadedAt: { gt: '2026-04-10' } },
-]
-void _and
-
-const _or: Filter<SessionFilter> = {
-  viaKim: { therapistId: 'kim' },
-  viaPark: { therapistId: 'park' },
-}
-void _or
-
-const _nested: Filter<SessionFilter> = [
-  { status: ['pending'] },
-  {
-    kim: { therapistId: 'kim' },
-    park: { therapistId: 'park' },
-  },
-  { uploadedAt: { gt: '2026-04-10' } },
-]
-void _nested

package/src/function/list.types.ts

@@ -1,69 +0,0 @@
-/**
- * A list function is an ordinary `pikkuFunc` whose input and output adopt
- * these shapes. They are purely structural — no runtime behaviour attaches to
- * them — and exist so MCP tools, agents, RPC clients and widget libraries all
- * reason about cursor, filter, sort and search the same way.
- */
-
-export interface ListInput<
-  F extends Record<string, unknown> = Record<string, never>,
-  S extends string = never,
-> {
-  /** Opaque cursor from the previous page's `nextCursor`. */
-  cursor?: string
-  /** Page size. Server may cap. */
-  limit?: number
-  /** Ordered sort criteria — first entry is primary. */
-  sort?: Array<{ column: S; direction: 'asc' | 'desc' }>
-  filter?: Filter<F>
-  /** Unstructured text search across server-configured fields. */
-  search?: string
-}
-
-export interface ListOutput<Row> {
-  rows: Row[]
-  /** Null when no more pages. */
-  nextCursor: string | null
-  /** Optional — backend may skip when expensive. */
-  totalCount?: number
-}
-
-/**
- * Leaf predicate on a single field. The operator keywords mirror Prisma's
- * vocabulary; they are reserved and cannot be used as user field names in a
- * Filter's `F` type.
- */
-export type LeafValue<T> =
-  | T
-  | null
-  | T[]
-  | {
-      equals?: T | null
-      not?: T | null | LeafValue<T>
-      in?: T[]
-      notIn?: T[]
-      gt?: T
-      gte?: T
-      lt?: T
-      lte?: T
-      contains?: string
-      startsWith?: string
-      endsWith?: string
-      mode?: 'sensitive' | 'insensitive'
-    }
-
-/**
- * A single-key object keyed by a field of F. Single-key so the runtime
- * discriminator is unambiguous — multi-key objects are OR groups.
- */
-export type LeafFilter<F extends Record<string, unknown>> = {
-  [K in keyof F]: { [Key in K]: LeafValue<F[K]> }
-}[keyof F]
-
-/**
- * Recursive filter tree: an array is an AND of its children; an object is an
- * OR of its children, keyed by arbitrary unique labels that are ignored at
- * evaluation time; a single-key object is a leaf predicate.
- */
-export type Filter<F extends Record<string, unknown>> =
-  LeafFilter<F> | Filter<F>[] | { [label: string]: Filter<F> }

package/src/function/pikku-request.test.ts

@@ -1,35 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { PikkuRequest } from './pikku-request.js'
-
-class TestPikkuRequest<In> extends PikkuRequest<In> {}
-
-describe('PikkuRequest', () => {
-  test('returns stored data', async () => {
-    const request = new TestPikkuRequest({ hello: 'world' })
-
-    assert.deepEqual(await request.data(), { hello: 'world' })
-  })
-
-  test('preserves falsey payloads', async () => {
-    await assert.doesNotReject(async () => {
-      const zeroRequest = new TestPikkuRequest(0)
-      assert.equal(await zeroRequest.data(), 0)
-
-      const falseRequest = new TestPikkuRequest(false)
-      assert.equal(await falseRequest.data(), false)
-
-      const emptyStringRequest = new TestPikkuRequest('')
-      assert.equal(await emptyStringRequest.data(), '')
-    })
-  })
-
-  test('throws when data is undefined', async () => {
-    const request = new TestPikkuRequest(undefined as never)
-
-    await assert.rejects(() => request.data(), {
-      message: 'Data not found',
-    })
-  })
-})

package/src/function/pikku-request.ts

@@ -1,17 +0,0 @@
-/**
- * @group RequestResponse
- */
-export abstract class PikkuRequest<In = any> {
-  #data: In | undefined
-
-  constructor(data: In) {
-    this.#data = data
-  }
-
-  public async data(): Promise<In> {
-    if (this.#data === undefined) {
-      throw new Error('Data not found')
-    }
-    return this.#data
-  }
-}

package/src/gopass-secrets-removed.test.ts

@@ -1,51 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { join, dirname } from 'node:path'
-
-const srcRoot = dirname(fileURLToPath(import.meta.url))
-const packageRoot = join(srcRoot, '..')
-
-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 /\.(ts|js|mts|cts)$/.test(entry.name) ? [entryPath] : []
-  })
-
-describe('gopass secret service removal', () => {
-  test('the gopass-secrets module no longer exists', () => {
-    assert.equal(
-      existsSync(join(srcRoot, 'services/gopass-secrets.ts')),
-      false,
-      'services/gopass-secrets.ts was reintroduced'
-    )
-  })
-
-  test('package.json no longer exports ./services/gopass-secrets', () => {
-    const packageJson = JSON.parse(
-      readFileSync(join(packageRoot, 'package.json'), 'utf-8')
-    )
-    assert.equal(
-      packageJson.exports['./services/gopass-secrets'],
-      undefined,
-      './services/gopass-secrets export was reintroduced'
-    )
-  })
-
-  test('no source file references gopass', () => {
-    const offenders = collectSourceFiles(srcRoot).filter(
-      (file) =>
-        file !== fileURLToPath(import.meta.url) &&
-        /gopass/i.test(readFileSync(file, 'utf-8'))
-    )
-    assert.deepEqual(
-      offenders,
-      [],
-      `gopass references found in:\n${offenders.join('\n')}`
-    )
-  })
-})