@pikku/core 0.12.107 → 0.12.112

package/src/wirings/trigger/trigger.types.ts

@@ -1,100 +0,0 @@
-import type {
-  CommonWireMeta,
-  CoreSingletonServices,
-} from '../../types/core.types.js'
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-import type { CoreNodeConfig } from '../node/node.types.js'
-
-export interface PikkuTrigger<TOutput = unknown> {
-  invoke: (data: TOutput) => void
-}
-
-export type TriggerMeta = Record<string, CommonWireMeta & { name: string }>
-
-export type TriggerSourceMeta = Record<
-  string,
-  { name: string; pikkuFuncId: string; packageName?: string }
->
-
-export type CorePikkuTriggerFunction<
-  TInput = unknown,
-  TOutput = unknown,
-  Services extends CoreSingletonServices = CoreSingletonServices,
-> = (
-  services: Services,
-  input: TInput,
-  wire: { trigger: { invoke: (data: TOutput) => void } }
-) => Promise<() => void | Promise<void>>
-
-export type CorePikkuTriggerFunctionConfig<
-  TInput = unknown,
-  TOutput = unknown,
-  Services extends CoreSingletonServices = CoreSingletonServices,
-  InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined,
-> = {
-  title?: string
-  description?: string
-  tags?: string[]
-  func: CorePikkuTriggerFunction<TInput, TOutput, Services>
-  input?: InputSchema
-  output?: OutputSchema
-  node?: CoreNodeConfig
-}
-
-export const pikkuTriggerFunc = <
-  TInput = unknown,
-  TOutput = unknown,
-  Services extends CoreSingletonServices = CoreSingletonServices,
-  InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined,
->(
-  triggerOrConfig:
-    | CorePikkuTriggerFunction<TInput, TOutput, Services>
-    | CorePikkuTriggerFunctionConfig<
-        TInput,
-        TOutput,
-        Services,
-        InputSchema,
-        OutputSchema
-      >
-): CorePikkuTriggerFunctionConfig<
-  TInput,
-  TOutput,
-  Services,
-  InputSchema,
-  OutputSchema
-> => {
-  if (typeof triggerOrConfig === 'function') {
-    return { func: triggerOrConfig }
-  }
-  return triggerOrConfig
-}
-
-export interface CoreTrigger<PikkuFunctionConfig = any> {
-  /** What a `wireTriggerSource` points at to fire this trigger. It is the contract between the two, so both must spell it the same. */
-  name: string
-  /** The function to run each time the trigger fires. */
-  func: PikkuFunctionConfig
-  /** What firing this trigger means, for whoever is reading the wiring rather than writing it. */
-  description?: string
-  /** Filters this trigger in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-}
-
-export interface TriggerInstance {
-  name: string
-  teardown: () => void | Promise<void>
-}
-
-export type CoreTriggerSource<TInput = unknown, TOutput = unknown> = {
-  /** Must match the name of a `wireTrigger` registration. */
-  name: string
-  func: CorePikkuTriggerFunctionConfig<
-    TInput,
-    TOutput,
-    CoreSingletonServices,
-    StandardSchemaV1 | undefined,
-    StandardSchemaV1 | undefined
-  >
-} & (unknown extends TInput ? { input?: TInput } : { input: TInput })

package/src/wirings/variable/index.ts

@@ -1,8 +0,0 @@
-export { defineVariable } from './variable.types.js'
-export type {
-  CoreVariable,
-  VariableDefinitionMeta,
-  VariableDefinitionsMeta,
-  VariableDefinitions,
-} from './variable.types.js'
-export { validateAndBuildVariableDefinitionsMeta } from './validate-variable-definitions.js'

package/src/wirings/variable/validate-variable-definitions.test.ts

@@ -1,115 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import { validateAndBuildVariableDefinitionsMeta } from './validate-variable-definitions.js'
-
-describe('validateAndBuildVariableDefinitionsMeta', () => {
-  test('should build meta from single definition', () => {
-    const definitions = [
-      {
-        name: 'dbUrl',
-        displayName: 'Database URL',
-        description: 'Connection string',
-        variableId: 'DB_URL',
-        sourceFile: 'a.ts',
-      },
-    ]
-    const result = validateAndBuildVariableDefinitionsMeta(
-      definitions as any,
-      new Map()
-    )
-    assert.ok(result['dbUrl'])
-    assert.strictEqual(result['dbUrl'].variableId, 'DB_URL')
-  })
-
-  test('should allow duplicate variableId with same schema', () => {
-    const schemaLookup = new Map([
-      ['schema1', { variableName: 'Schema', sourceFile: 'types.ts' }],
-    ])
-    const definitions = [
-      {
-        name: 'var1',
-        displayName: 'Var 1',
-        description: 'd',
-        variableId: 'SHARED',
-        schema: 'schema1',
-        sourceFile: 'a.ts',
-      },
-      {
-        name: 'var2',
-        displayName: 'Var 2',
-        description: 'd',
-        variableId: 'SHARED',
-        schema: 'schema1',
-        sourceFile: 'b.ts',
-      },
-    ]
-    const result = validateAndBuildVariableDefinitionsMeta(
-      definitions as any,
-      schemaLookup
-    )
-    assert.ok(result['var1'])
-    assert.ok(result['var2'])
-  })
-
-  test('should throw when duplicate variableId has different schemas', () => {
-    const schemaLookup = new Map([
-      ['schema1', { variableName: 'SchemaA', sourceFile: 'types.ts' }],
-      ['schema2', { variableName: 'SchemaB', sourceFile: 'types2.ts' }],
-    ])
-    const definitions = [
-      {
-        name: 'var1',
-        displayName: 'Var 1',
-        description: 'd',
-        variableId: 'SHARED',
-        schema: 'schema1',
-        sourceFile: 'a.ts',
-      },
-      {
-        name: 'var2',
-        displayName: 'Var 2',
-        description: 'd',
-        variableId: 'SHARED',
-        schema: 'schema2',
-        sourceFile: 'b.ts',
-      },
-    ]
-    assert.throws(
-      () =>
-        validateAndBuildVariableDefinitionsMeta(
-          definitions as any,
-          schemaLookup
-        ),
-      (err: any) => err.message.includes('different schemas')
-    )
-  })
-
-  test('should handle empty definitions', () => {
-    const result = validateAndBuildVariableDefinitionsMeta([], new Map())
-    assert.deepStrictEqual(result, {})
-  })
-
-  test('carries optional into the meta so only the opted-out ones skip the gate', () => {
-    const result = validateAndBuildVariableDefinitionsMeta(
-      [
-        {
-          name: 'corsOrigins',
-          displayName: 'Allowed Browser Origins',
-          variableId: 'CORS_ORIGINS',
-          optional: true,
-          sourceFile: 'a.ts',
-        },
-        {
-          name: 'consoleUrl',
-          displayName: 'Console URL',
-          variableId: 'CONSOLE_URL',
-          sourceFile: 'a.ts',
-        },
-      ] as any,
-      new Map()
-    )
-    assert.strictEqual(result['corsOrigins']!.optional, true)
-    // Undeclared means required, which is what makes the gate ask by default.
-    assert.strictEqual(result['consoleUrl']!.optional, undefined)
-  })
-})

package/src/wirings/variable/validate-variable-definitions.ts

@@ -1,71 +0,0 @@
-import type {
-  VariableDefinitions,
-  VariableDefinitionsMeta,
-} from './variable.types.js'
-import type { SchemaRefLike } from '../../types/core.types.js'
-
-export type { SchemaRefLike }
-
-export function validateAndBuildVariableDefinitionsMeta(
-  definitions: VariableDefinitions,
-  schemaLookup: Map<string, SchemaRefLike>
-): VariableDefinitionsMeta {
-  const meta: VariableDefinitionsMeta = {}
-  const variableIdToDefinition: Map<string, VariableDefinitions[0]> = new Map()
-
-  for (const def of definitions) {
-    const existingDef = variableIdToDefinition.get(def.variableId)
-
-    if (existingDef) {
-      if (def.schema && existingDef.schema) {
-        const defSchemaRef = schemaLookup.get(def.schema as string)
-        const existingSchemaRef = schemaLookup.get(existingDef.schema as string)
-
-        if (defSchemaRef && existingSchemaRef) {
-          if (
-            defSchemaRef.variableName !== existingSchemaRef.variableName ||
-            defSchemaRef.sourceFile !== existingSchemaRef.sourceFile
-          ) {
-            throw new Error(
-              `Variable '${def.variableId}' is defined with different schemas.\n` +
-                `  First definition: ${existingDef.sourceFile} (schema: ${existingSchemaRef.variableName})\n` +
-                `  Second definition: ${def.sourceFile} (schema: ${defSchemaRef.variableName})\n` +
-                `Variables sharing a variableId must use the same schema.`
-            )
-          }
-        }
-      }
-
-      if (!meta[def.name]) {
-        meta[def.name] = {
-          name: def.name,
-          displayName: def.displayName,
-          description: def.description,
-          variableId: def.variableId,
-          schema: def.schema,
-          optional: def.optional,
-          docsUrl: def.docsUrl,
-          sourceFile: def.sourceFile,
-        }
-      }
-      continue
-    }
-
-    variableIdToDefinition.set(def.variableId, def)
-
-    if (!meta[def.name]) {
-      meta[def.name] = {
-        name: def.name,
-        displayName: def.displayName,
-        description: def.description,
-        variableId: def.variableId,
-        schema: def.schema,
-        optional: def.optional,
-        docsUrl: def.docsUrl,
-        sourceFile: def.sourceFile,
-      }
-    }
-  }
-
-  return meta
-}

package/src/wirings/variable/variable.types.ts

@@ -1,40 +0,0 @@
-export type CoreVariable<T = unknown> = {
-  /** How the variable is asked for in code. Generated into `VariablesMap`, so it is what `variables.get` autocompletes. */
-  name: string
-  /** The name shown to whoever configures the deployment. */
-  displayName: string
-  /** What the value does, for the person setting it rather than the one reading it. */
-  description?: string
-  /** The environment variable this reads, which is the name that has to exist on the host. */
-  variableId: string
-  /** The shape of the value. It arrives as a string, so this is also what parses it. */
-  schema: T
-  /** Required by default: this says the deployment is still correct without it. */
-  optional?: boolean
-  /** Where to go to work out what to set this to. */
-  docsUrl?: string
-}
-
-export type VariableDefinitionMeta = {
-  name: string
-  displayName: string
-  description?: string
-  variableId: string
-  schema?: Record<string, unknown> | string
-  optional?: boolean
-  docsUrl?: string
-  sourceFile?: string
-}
-
-export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>
-
-export type VariableDefinitions = VariableDefinitionMeta[]
-
-/**
- * Declares an environment variable this project needs, with the shape of its
- * value. The CLI collects every declaration into `VariablesMap`, which is what
- * makes `variables.get('NAME')` return the right type instead of `unknown`.
- *
- * @example snippet: variables
- */
-export const defineVariable = <T>(_config: CoreVariable<T>): void => {}

package/src/wirings/virtual-user/index.ts

@@ -1,107 +0,0 @@
-/**
- * Virtual user module exports.
- *
- * A virtual user is an LLM playing a persona that signs into a *running* stage
- * and works its API in character — non-deterministically, with a budget, and
- * with oracles watching what comes back. It is not a test runner: nothing here
- * asserts an expected outcome, because the point is the outcomes nobody thought
- * to expect.
- *
- * Everything it needs is derived from what a pikku project already generates —
- * the function meta becomes the catalogue, the scenario meta becomes the
- * intents, the declared personas become the identities — so adopting it is
- * configuration rather than authoring.
- *
- * The engine is transport-agnostic: the virtual user drives an
- * {@link VirtualUserTarget}, which in production is an `HttpPersona`
- * signed in as a real user against staging or production.
- */
-export type {
-  ApiCatalogueEntry,
-  IntentRecord,
-  IntentSource,
-  StepRecord,
-  VirtualUserBudget,
-  VirtualUserDisposition,
-  VirtualUserFinding,
-  VirtualUserRunResult,
-  VirtualUserTarget,
-} from './virtual-user.types.js'
-export { PRODUCTION_DISPOSITION } from './virtual-user.types.js'
-export {
-  runVirtualUser,
-  type RunVirtualUserParams,
-} from './run-virtual-user.js'
-export {
-  personaScopes,
-  prepareVirtualUserRun,
-  type VirtualUserPreparation,
-} from './prepare-virtual-user-run.js'
-export type {
-  VirtualUserRunOutcome,
-  VirtualUserRunRecord,
-  VirtualUserRunStart,
-  VirtualUserRunStore,
-} from './virtual-user-run-store.js'
-export type {
-  VirtualUserScheduleInput,
-  VirtualUserScheduleRecord,
-  VirtualUserScheduleStore,
-} from './virtual-user-schedule-store.js'
-export {
-  DEFAULT_MAX_INTERVAL_MS,
-  DEFAULT_MIN_INTERVAL_MS,
-  isDue,
-  nextRunAt,
-  STALE_RUN_AFTER_MS,
-  tickVirtualUserSchedules,
-  type VirtualUserTickParams,
-  type VirtualUserTickResult,
-} from './virtual-user-schedule.js'
-export {
-  DISPOSITIONS,
-  dispositionProfile,
-  type DispositionProfile,
-  type VirtualUserTuning,
-} from './virtual-user-dispositions.js'
-export {
-  catalogueClassification,
-  catalogueLookup,
-  isReadOnly,
-  reachableCatalogue,
-  unreachableCatalogue,
-} from './virtual-user-catalogue.js'
-export {
-  type AgentReachability,
-  type ReachableAgent,
-} from './virtual-user-agents.js'
-export { IntentStack, intentsForPersona } from './virtual-user-intents.js'
-export {
-  deriveCatalogue,
-  deriveIntents,
-  type SchemaMap,
-} from './virtual-user-derive.js'
-export {
-  personaVirtualUserTarget,
-  type PersonaTargetOptions,
-} from './virtual-user-target.js'
-export {
-  executeVirtualUserRun,
-  logVirtualUserTick,
-  requireVirtualUserRunStore,
-  requireVirtualUserScheduleStore,
-  runnablePersona,
-  serializeVirtualUserRun,
-  serializeVirtualUserSchedule,
-  serializeVirtualUserSteps,
-  signInPathFor,
-  startVirtualUserRun,
-  VIRTUAL_USER_VARIABLES,
-  virtualUserScheduleRunInput,
-  writeVirtualUserSchedule,
-  type ExecuteVirtualUserRunParams,
-  type ScaffoldPersonas,
-  type StartedVirtualUserRun,
-  type StartVirtualUserRunParams,
-  type WriteVirtualUserScheduleParams,
-} from './virtual-user-scaffold.js'

package/src/wirings/virtual-user/prepare-virtual-user-run.test.ts

@@ -1,115 +0,0 @@
-import { test, describe } from 'node:test'
-import assert from 'node:assert/strict'
-import {
-  personaScopes,
-  prepareVirtualUserRun,
-} from './prepare-virtual-user-run.js'
-
-const ROLE_DEFINITIONS = [
-  { name: 'editor', scopes: ['docs:write', 'docs:read'] },
-  { name: 'viewer', scopes: ['docs:read'] },
-]
-
-const FUNCTIONS_META = {
-  listDocs: { pikkuFuncName: 'listDocs', services: [], expose: true },
-  deleteDoc: { pikkuFuncName: 'deleteDoc', services: [], expose: true },
-} as any
-
-describe('personaScopes', () => {
-  test('expands the roles a persona declares into the scopes functions check', () => {
-    const scopes = personaScopes(
-      { roles: ['editor'] },
-      {
-        editor: ['docs:write', 'docs:read'],
-      }
-    )
-    assert.deepEqual(scopes, ['docs:read', 'docs:write'])
-  })
-
-  test('a persona with no roles holds no scopes', () => {
-    assert.deepEqual(personaScopes({}, { editor: ['docs:write'] }), [])
-  })
-
-  // Two roles granting the same scope is ordinary, and the catalogue narrowing
-  // downstream compares scopes as a set.
-  test('de-duplicates overlapping roles', () => {
-    const scopes = personaScopes(
-      { roles: ['editor', 'viewer'] },
-      {
-        editor: ['docs:write', 'docs:read'],
-        viewer: ['docs:read'],
-      }
-    )
-    assert.deepEqual(scopes, ['docs:read', 'docs:write'])
-  })
-
-  // An undeclared role granting everything would be the worst possible default.
-  test('an unknown role grants nothing', () => {
-    assert.deepEqual(personaScopes({ roles: ['ghost'] }, {}), [])
-  })
-})
-
-describe('prepareVirtualUserRun', () => {
-  // The CLI reads the inspector state, which holds an array; the scaffolded RPC
-  // reads metaService, which hands the same definitions back keyed by name. Both
-  // callers must land on the same scopes or the same persona and seed explore a
-  // different API depending on how the run was started.
-  test('accepts role definitions as an array or keyed by name, identically', () => {
-    const asArray = prepareVirtualUserRun({
-      persona: { roles: ['editor'] },
-      functionsMeta: FUNCTIONS_META,
-      systemRoles: ROLE_DEFINITIONS as any,
-    })
-    const asRecord = prepareVirtualUserRun({
-      persona: { roles: ['editor'] },
-      functionsMeta: FUNCTIONS_META,
-      systemRoles: {
-        editor: ROLE_DEFINITIONS[0],
-        viewer: ROLE_DEFINITIONS[1],
-      } as any,
-    })
-    assert.deepEqual(asArray.scopes, asRecord.scopes)
-    assert.deepEqual(asArray.scopes, ['docs:read', 'docs:write'])
-  })
-
-  test('derives the catalogue from the function meta', () => {
-    const { catalogue } = prepareVirtualUserRun({
-      persona: {},
-      functionsMeta: FUNCTIONS_META,
-    })
-    assert.deepEqual(catalogue.map((entry) => entry.name).sort(), [
-      'deleteDoc',
-      'listDocs',
-    ])
-  })
-
-  // An agent is reached rather than declared: its scopes are checked against the
-  // session, so a persona must find the specialists its roles unlock and no
-  // others.
-  test('narrows agents to the ones the persona s scopes reach', () => {
-    const agentsMeta = {
-      helper: { scopes: [] },
-      auditor: { scopes: ['docs:audit'] },
-    } as any
-
-    const { agents } = prepareVirtualUserRun({
-      persona: { roles: ['viewer'] },
-      functionsMeta: FUNCTIONS_META,
-      systemRoles: ROLE_DEFINITIONS as any,
-      agentsMeta,
-    })
-
-    assert.deepEqual(
-      agents.map((agent) => agent.name),
-      ['helper']
-    )
-  })
-
-  test('a project with no scenarios simply has no intents', () => {
-    const { intents } = prepareVirtualUserRun({
-      persona: {},
-      functionsMeta: FUNCTIONS_META,
-    })
-    assert.deepEqual(intents, [])
-  })
-})

package/src/wirings/virtual-user/prepare-virtual-user-run.ts

@@ -1,95 +0,0 @@
-import type { FunctionsMeta } from '../../function/function-meta.types.js'
-import type { WorkflowsMeta } from '../workflow/workflow.types.js'
-import { flattenSystemRoleDefinitions } from '../role/validate-role-definitions.js'
-import type {
-  SystemRoleDefinitions,
-  SystemRoleDefinitionsMeta,
-} from '../role/role.types.js'
-import {
-  deriveCatalogue,
-  deriveIntents,
-  type SchemaMap,
-} from './virtual-user-derive.js'
-import {
-  reachableAgents,
-  type AgentReachability,
-  type ReachableAgent,
-} from './virtual-user-agents.js'
-import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js'
-
-/**
- * The scopes a persona holds, resolved through its roles.
- *
- * Roles are the only thing a persona declares; scopes are what a function
- * checks. Narrowing a virtual user's catalogue needs the second, so the
- * expansion happens once, here, against the same `defineSystemRole` definitions
- * the seed grants from.
- */
-export const personaScopes = (
-  persona: { roles?: readonly string[] },
-  roleScopes: Record<string, readonly string[]>
-): string[] => {
-  const scopes = new Set<string>()
-  for (const role of persona.roles ?? []) {
-    for (const scope of roleScopes[role] ?? []) {
-      scopes.add(scope)
-    }
-  }
-  return [...scopes].sort()
-}
-
-/** Everything a run needs that is derived rather than decided. */
-export interface VirtualUserPreparation {
-  /** Every RPC the app exposes, narrowed to what this persona can reach. */
-  catalogue: ApiCatalogueEntry[]
-  intents: IntentSource[]
-  scopes: string[]
-  agents: ReachableAgent[]
-}
-
-/**
- * Derive what a virtual user needs from what the project already generates.
- *
- * Shared because there are two callers with the same problem and different
- * sources for it: `pikku persona run` reads the inspector state at build time,
- * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
- * must agree — a persona whose catalogue is narrower over RPC than on the CLI
- * finds different things from the same seed, which is exactly the property a
- * seed exists to give.
- *
- * Nothing here is authored for the virtual user's benefit: the function meta is
- * the catalogue, the scenario meta is the intents, and the role definitions are
- * what turn a persona's declared roles into the scopes a function checks.
- */
-export const prepareVirtualUserRun = (input: {
-  persona: { roles?: readonly string[] }
-  functionsMeta: FunctionsMeta
-  schemas?: SchemaMap
-  workflowsMeta?: WorkflowsMeta
-  /**
-   * Either shape: the inspector holds an array, `metaService` hands back the
-   * same definitions keyed by name. Accepting both is what lets the CLI and the
-   * scaffolded RPC share this.
-   */
-  systemRoles?: SystemRoleDefinitions | SystemRoleDefinitionsMeta
-  agentsMeta?: Readonly<Record<string, AgentReachability>>
-}): VirtualUserPreparation => {
-  const catalogue = deriveCatalogue(input.functionsMeta, input.schemas ?? {})
-  const intents = deriveIntents(input.workflowsMeta ?? {}, input.functionsMeta)
-
-  const declared = input.systemRoles ?? []
-  const roleScopes: Record<string, string[]> = {}
-  for (const role of flattenSystemRoleDefinitions(
-    Array.isArray(declared) ? declared : Object.values(declared)
-  )) {
-    roleScopes[role.name] = role.scopes
-  }
-  const scopes = personaScopes(input.persona, roleScopes)
-
-  // Gated by the same scopes as the RPCs, because an agent is reached rather
-  // than declared: `CoreAgent.scopes` is checked against the session, so a
-  // persona finds the specialists its roles unlock and no others.
-  const agents = reachableAgents(input.agentsMeta ?? {}, scopes)
-
-  return { catalogue, intents, scopes, agents }
-}