@pikku/core 0.12.71 → 0.12.74

package/src/wirings/rpc/wire-remote-addon.ts

@@ -1,50 +1,30 @@
 import { pikkuState } from '../../pikku-state.js'
 import type { CoreServices, PikkuWire } from '../../types/core.types.js'
 
-/**
- * How the consumer supplies the token the hosted addon's auth expects.
- *
- * This is a CLIENT authenticating to a hosted library — NOT pikku's trusted
- * machine-to-machine mesh (which uses `PIKKU_REMOTE_SECRET`). The consumer binds
- * the addon's declared auth requirement to a local source:
- *  - `credentialId` — per-user credential, resolved via `wire.getCredential(id)`
- *  - `secretId`     — platform key, resolved via the secrets service
- *  - `resolve`      — custom escape hatch
- * Omit entirely when the addon declares its remote surface is public.
- *
- * The value is sent `Authorization: Bearer <token>` by default; a non-default
- * header is declared once by the addon (its meta), never chosen here.
- */
+/** Sent as `Authorization: Bearer <token>`; a non-default header is declared by the addon. */
 export type RemoteAddonAuth =
   | { credentialId: string }
   | { secretId: string }
-  | { resolve: (services: CoreServices, wire: PikkuWire) => string | Promise<string> }
+  | {
+      resolve: (
+        services: CoreServices,
+        wire: PikkuWire
+      ) => string | Promise<string>
+    }
 
 export type WireRemoteAddonConfig = {
   /** Consumer-facing namespace, e.g. `registry` → `rpc('registry:getOpenApi')` */
   name: string
-  /**
-   * The addon package. Installed as a **devDependency** (types only — its
-   * handlers run on the host); `pikku verify` enforces this.
-   */
+  /** Must be installed as a devDependency — `pikku verify` enforces this. */
   package: string
-  /** Base URL of the host serving the addon's remote surface. */
   serverUrl: string | ((services: CoreServices) => string | Promise<string>)
-  /** Bind the addon's declared auth to a local source. Omit if the surface is public. */
+  /** Omit when the addon declares its remote surface public. */
   auth?: RemoteAddonAuth
   /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
   remoteName?: (fn: string) => string
   tags?: string[]
 }
 
-/**
- * Consume a hosted addon's `remote: true` RPCs transparently over HTTP.
- *
- * Unlike `wireAddon` (which bundles the addon's functions in-process, a
- * production dependency), `wireRemoteAddon` dispatches `rpc('name:fn')` to the
- * host at `serverUrl`, fully typed — the addon ships as a devDependency (types
- * only). See {@link RemoteAddonAuth} for how auth is bound.
- */
 export const wireRemoteAddon = (config: WireRemoteAddonConfig): void => {
   pikkuState(null, 'addons', 'packages').set(config.name, {
     package: config.package,

package/src/wirings/scheduler/log-schedulers.ts

@@ -1,10 +1,6 @@
 import { pikkuState } from '../../pikku-state.js'
 import type { Logger } from '../../services/index.js'
 
-/**
- * Logs all the loaded scheduled tasks.
- * @param logger - A logger for logging information.
- */
 export const logSchedulers = (logger: Logger) => {
   const scheduledTasks = pikkuState(null, 'scheduler', 'tasks')
   if (scheduledTasks.size === 0) {

package/src/wirings/scheduler/scheduler-runner.test.ts

@@ -36,7 +36,6 @@ describe('wireScheduler', () => {
       },
     }
 
-    // Set up metadata first
     pikkuState(null, 'scheduler', 'meta')['test-task'] = {
       pikkuFuncId: 'scheduler_test-task',
       name: 'test-task',
@@ -76,17 +75,14 @@ describe('wireScheduler', () => {
       },
     }
 
-    // Set up metadata
     pikkuState(null, 'scheduler', 'meta')['duplicate-task'] = {
       pikkuFuncId: 'scheduler_duplicate-task',
       name: 'duplicate-task',
       schedule: '0 0 * * *',
     }
 
-    // Wire first time
     wireScheduler(mockTask)
 
-    // Try to wire again
     assert.throws(
       () => wireScheduler(mockTask),
       (error: any) => {
@@ -147,7 +143,6 @@ describe('runScheduledTask', () => {
       },
     }
 
-    // Set up metadata and task
     pikkuState(null, 'scheduler', 'meta')['simple-task'] = {
       pikkuFuncId: 'scheduler_simple-task',
       name: 'simple-task',
@@ -247,7 +242,6 @@ describe('runScheduledTask', () => {
       },
     }
 
-    // Add task but not metadata
     pikkuState(null, 'scheduler', 'tasks').set('task-without-meta', mockTask)
 
     const mockLogger = createMockLogger()
@@ -581,10 +575,9 @@ describe('runScheduledTask', () => {
       })
     })
 
-    // Error should be re-thrown
     const logs = mockLogger.getLogs()
     const infoLogs = logs.filter((l) => l.level === 'info')
-    assert(infoLogs.length > 0) // Should have at least started logging
+    assert(infoLogs.length > 0)
   })
 
   test('should execute task with middleware', async () => {

package/src/wirings/scheduler/scheduler-runner.ts

@@ -19,7 +19,6 @@ import type {
 export type RunScheduledTasksParams = {
   name: string
   session?: CoreUserSession
-  /** Pre-resolved trace ID */
   traceId?: string
 }
 
@@ -96,7 +95,6 @@ export async function runScheduledTask({
     )
   }
 
-  // Create the scheduled task wire object
   const wire: PikkuRawWire = {
     traceId: resolvedTraceId,
     scheduledTask: {

package/src/wirings/scheduler/scheduler.types.ts

@@ -8,9 +8,6 @@ import type {
   CorePikkuFunctionSessionless,
 } from '../../function/functions.types.js'
 
-/**
- * Represents metadata for scheduled tasks, including title, schedule, and documentation.
- */
 export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
   Record<
     string,
@@ -21,9 +18,6 @@ export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
     }
   >
 
-/**
- * Represents a core scheduled task.
- */
 export type CoreScheduledTask<
   PikkuFunctionConfig = CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<void, void>
@@ -37,17 +31,10 @@ export type CoreScheduledTask<
   middleware?: PikkuMiddleware[]
 }
 
-/**
- * Represents a scheduled task wire object for middleware
- * Provides information about the current scheduled task execution
- */
 export interface PikkuScheduledTask {
-  /** The name of the scheduled task being executed */
   name: string
-  /** The cron schedule expression */
   schedule: string
-  /** Current execution timestamp */
   executionTime: Date
-  /** Skip the current task execution */
+  /** Never returns — throws to abort the run. */
   skip: (reason?: string) => void
 }

package/src/wirings/scope/{wire-scope.ts → define-scope.ts}

@@ -1,10 +1,9 @@
 import type { CoreScopes } from './scope.types.js'
 
 /**
- * No-op function for declaring scopes.
- * This exists purely for TypeScript type checking and will be tree-shaken.
- * The CLI extracts metadata via AST parsing and generates a `ScopeId` union,
- * so a function referencing an undeclared scope fails the build.
+ * Declares scopes. The body is a no-op that tree-shakes away — the CLI reads
+ * the call by AST and generates a `ScopeId` union, so a function referencing an
+ * undeclared scope fails the build.
  *
  * Scopes are keyed by segment at every level: a scope is named by its key, and
  * its value describes it. Every node is grantable — the declaration below
@@ -13,7 +12,7 @@ import type { CoreScopes } from './scope.types.js'
  *
  * @example
  * ```typescript
- * wireScope({
+ * defineScope({
  *   admin: {
  *     displayName: 'Administration',
  *     description: 'Administrative access',
@@ -31,4 +30,4 @@ import type { CoreScopes } from './scope.types.js'
  * })
  * ```
  */
-export const wireScope = (_config: CoreScopes): void => {}
+export const defineScope = (_config: CoreScopes): void => {}

package/src/wirings/scope/index.ts

@@ -1,4 +1,4 @@
-export { wireScope } from './wire-scope.js'
+export { defineScope } from './define-scope.js'
 export {
   flattenScopeDefinitions,
   validateAndBuildScopeDefinitionsMeta,

package/src/wirings/scope/scope.test.ts

@@ -63,8 +63,7 @@ describe('flattenScopeDefinitions', () => {
     )
   })
 
-  // An addon and its host app may both contribute the same root. Codegen writes
-  // these ids into an object literal, where a repeat is a TypeScript error.
+  // knowledge: decisions/internals/scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md
   test('a root declared twice is flattened once', () => {
     const tree = { users: { scopes: { ban: {} } } }
     const definitions: ScopeDefinitions = [

package/src/wirings/scope/scope.types.ts

@@ -1,21 +1,20 @@
 /**
- * A node within a scope tree. Every node is itself a grantable scope — given
- * `admin` containing `invoices` containing `create`, all three of `admin`,
- * `admin:invoices` and `admin:invoices:create` are valid scope ids.
+ * Every node is itself a grantable scope: `admin` containing `invoices`
+ * containing `create` yields all three of `admin`, `admin:invoices` and
+ * `admin:invoices:create`.
  */
 export type CoreScopeNode = {
-  /** Short human-readable name, e.g. "Administration". */
   displayName?: string
-  /** Longer-form description, surfaced in the console when granting. */
+  /** Surfaced in the console when granting. */
   description?: string
   /** Nested scopes, keyed by their segment. */
   scopes?: Record<string, CoreScopeNode>
 }
 
 /**
- * Scope trees to declare, keyed by their root segment. A root is just a node —
- * it is named by its key, exactly like every node beneath it. A key must not
- * contain `:` or be `*`.
+ * Scope trees keyed by their root segment — a root is named by its key exactly
+ * like every node beneath it. A key must not contain `:` or be `*`; nothing
+ * enforces that at runtime, only the build.
  */
 export type CoreScopes = Record<string, CoreScopeNode>
 
@@ -36,7 +35,6 @@ export type ScopeDefinitionMeta = {
 export type ScopeDefinitions = ScopeDefinitionMeta[]
 export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>
 
-/** A single scope, flattened out of the declared tree. */
 export type FlatScope = {
   /** Colon-delimited id, e.g. `admin:invoices:create`. */
   id: string

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

@@ -48,21 +48,8 @@ const flattenNodes = (
   }
 }
 
-/**
- * Flattens declared scope trees into the full list of grantable scope ids,
- * depth-first. Every node is emitted, including intermediate ones.
- *
- * Ids are unique. A root may legitimately be declared more than once — an addon
- * and its host app both contributing the same `admin` tree, say — and
- * {@link validateAndBuildScopeDefinitionsMeta} already guarantees those
- * declarations are identical, so the second one is redundant rather than
- * conflicting. Collapsing it here keeps every consumer honest: codegen emits an
- * object literal keyed by id (duplicates are a TypeScript error), and a
- * ScopeService syncs one row per scope instead of re-writing the same one.
- *
- * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
- * the declared set into its store.
- */
+/** Every node is emitted, intermediate ones included, depth-first. Ids are unique. */
+// knowledge: decisions/internals/scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md
 export const flattenScopeDefinitions = (
   definitions: ScopeDefinitions
 ): FlatScope[] => {
@@ -81,12 +68,7 @@ export const flattenScopeDefinitions = (
   })
 }
 
-/**
- * Validates declared scopes and keys them by name.
- *
- * Definitions sharing a name must be identical; a conflicting redeclaration is
- * a hard error naming both source files.
- */
+/** Definitions sharing a name must be identical; a conflicting one is a hard error. */
 export function validateAndBuildScopeDefinitionsMeta(
   definitions: ScopeDefinitions
 ): ScopeDefinitionsMeta {

package/src/wirings/secret/index.ts

@@ -1,4 +1,4 @@
-export { wireSecret } from './secret.types.js'
+export { defineSecret } from './secret.types.js'
 export type {
   CoreSecret,
   OAuth2CredentialConfig,

package/src/wirings/secret/secret.types.ts

@@ -5,26 +5,30 @@ export type CoreSecret<T = unknown> = {
   secretId: string
   schema: T
   /**
-   * Link to documentation explaining how to obtain this value — a provider's
-   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
-   * deploy UIs so a user facing a missing value has somewhere to go instead of
-   * an opaque identifier.
+   * Where a user goes to obtain this value — a provider's API-key page, a setup
+   * guide, an internal runbook. Consoles and deploy UIs surface it beside a
+   * missing value. The same field on every credential/variable definition means
+   * the same thing.
    */
   docsUrl?: string
+  /** Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`. */
+  rotationPeriod?: string
   /**
-   * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
-   * Stored in the generated secrets metadata so consumers can tell when a
-   * secret was last updated and whether it is due for rotation.
+   * Hosts this secret may be sent to, e.g. `['api.notion.com']` or
+   * `'*.notion.com'`. Omitted means unrestricted unless
+   * `config.secrets.requireAllowedHosts` is set.
    */
-  rotationPeriod?: string
+  allowedHosts?: string[]
 }
 
 export type OAuth2CredentialConfig = {
+  /** Where access/refresh tokens are stored */
   tokenSecretId: string
   authorizationUrl: string
   tokenUrl: string
   scopes: string[]
   pkce?: boolean
+  /** Appended to the authorization URL's query string. */
   additionalParams?: Record<string, string>
 }
 
@@ -34,15 +38,15 @@ export type SecretDefinitionMeta = {
   description?: string
   secretId: string
   schema?: Record<string, unknown> | string
-  /**
-   * Link to documentation explaining how to obtain this value — a provider's
-   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
-   * deploy UIs so a user facing a missing value has somewhere to go instead of
-   * an opaque identifier.
-   */
   docsUrl?: string
   oauth2?: OAuth2CredentialConfig
   rotationPeriod?: string
+  /**
+   * Hosts this secret may be sent to, e.g. `['api.notion.com']` or
+   * `'*.notion.com'`. Omitted means unrestricted unless
+   * `config.secrets.requireAllowedHosts` is set.
+   */
+  allowedHosts?: string[]
   sourceFile?: string
 }
 
@@ -50,4 +54,4 @@ export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>
 
 export type SecretDefinitions = SecretDefinitionMeta[]
 
-export const wireSecret = <T>(_config: CoreSecret<T>): void => {}
+export const defineSecret = <T>(_config: CoreSecret<T>): void => {}

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

@@ -2,11 +2,9 @@ import type {
   SecretDefinitions,
   SecretDefinitionsMeta,
 } from './secret.types.js'
+import type { SchemaRefLike } from '../../types/core.types.js'
 
-export interface SchemaRefLike {
-  variableName: string
-  sourceFile: string
-}
+export type { SchemaRefLike }
 
 export function validateAndBuildSecretDefinitionsMeta(
   definitions: SecretDefinitions,

package/src/wirings/trigger/trigger-runner.ts

@@ -12,11 +12,6 @@ import {
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { PikkuMissingMetaError } from '../../errors/errors.js'
 
-/**
- * Registers a trigger with the Pikku framework.
- * Declares a trigger name and its target pikku function.
- * Runs everywhere. Inspector extracts at build time.
- */
 export const wireTrigger = (trigger: CoreTrigger) => {
   const meta = pikkuState(null, 'trigger', 'meta')
   const triggerMeta = meta[trigger.name]
@@ -33,11 +28,7 @@ export const wireTrigger = (trigger: CoreTrigger) => {
   triggers.set(trigger.name, trigger as any)
 }
 
-/**
- * Registers a trigger source with the Pikku framework.
- * Provides the actual subscription function and input data.
- * Only imported in the trigger worker process.
- */
+// knowledge: decisions/internals/trigger-declaration-is-split-from-trigger-source.md
 export const wireTriggerSource = <TInput = unknown, TOutput = unknown>(
   source: CoreTriggerSource<TInput, TOutput>
 ) => {
@@ -63,23 +54,12 @@ export const wireTriggerSource = <TInput = unknown, TOutput = unknown>(
   )
 }
 
-/**
- * Parameters for setting up a trigger
- */
 export type SetupTriggerParams<TInput = unknown, TOutput = unknown> = {
   name: string
   input?: TInput
   onTrigger: (data: TOutput) => void | Promise<void>
 }
 
-/**
- * Sets up a registered trigger and starts listening for events.
- * Returns a TriggerInstance with a teardown function.
- *
- * @param name - The trigger name (must be registered via wireTrigger)
- * @param input - The input to pass to the trigger function
- * @param onTrigger - Callback invoked when the trigger fires
- */
 export async function setupTrigger<TInput = unknown, TOutput = unknown>({
   name,
   input,
@@ -122,16 +102,10 @@ export async function setupTrigger<TInput = unknown, TOutput = unknown>({
   return { name, teardown }
 }
 
-/**
- * Gets all registered triggers
- */
 export const getRegisteredTriggers = () => {
   return pikkuState(null, 'trigger', 'triggers')
 }
 
-/**
- * Gets trigger metadata
- */
 export const getTriggerMeta = () => {
   return pikkuState(null, 'trigger', 'meta')
 }

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

@@ -5,17 +5,10 @@ import type {
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { CoreNodeConfig } from '../node/node.types.js'
 
-/**
- * The trigger interaction object passed to trigger functions via the wire.
- * Call trigger() to fire the trigger and start a new workflow/execution.
- */
 export interface PikkuTrigger<TOutput = unknown> {
   invoke: (data: TOutput) => void
 }
 
-/**
- * Metadata for registered triggers stored in state.
- */
 export type TriggerMeta = Record<string, CommonWireMeta & { name: string }>
 
 export type TriggerSourceMeta = Record<
@@ -23,14 +16,6 @@ export type TriggerSourceMeta = Record<
   { name: string; pikkuFuncId: string; packageName?: string }
 >
 
-/**
- * A trigger function that sets up a subscription and returns a teardown function.
- * The trigger is fired via wire.trigger.invoke(data).
- *
- * @template TInput - Input type (configuration passed when wired)
- * @template TOutput - Output type produced when trigger fires
- * @template Services - Services available to the trigger
- */
 export type CorePikkuTriggerFunction<
   TInput = unknown,
   TOutput = unknown,
@@ -41,9 +26,6 @@ export type CorePikkuTriggerFunction<
   wire: { trigger: { invoke: (data: TOutput) => void } }
 ) => Promise<() => void | Promise<void>>
 
-/**
- * Configuration object for creating a trigger function with metadata
- */
 export type CorePikkuTriggerFunctionConfig<
   TInput = unknown,
   TOutput = unknown,
@@ -51,56 +33,15 @@ export type CorePikkuTriggerFunctionConfig<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
 > = {
-  /** Optional human-readable title for the trigger */
   title?: string
-  /** Optional description of what the trigger does */
   description?: string
-  /** Optional tags for categorization */
   tags?: string[]
-  /** The trigger function */
   func: CorePikkuTriggerFunction<TInput, TOutput, Services>
-  /** Optional Zod schema for input validation */
   input?: InputSchema
-  /** Optional Zod schema for output validation */
   output?: OutputSchema
-  /** Optional node configuration */
   node?: CoreNodeConfig
 }
 
-/**
- * Factory function for creating trigger functions
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const redisSubscribeTrigger = pikkuTriggerFunc<
- *   { channel: string },
- *   { message: string }
- * >(async ({ redis }, { channel }, { trigger }) => {
- *   const subscriber = redis.duplicate()
- *   await subscriber.subscribe(channel, (msg) => {
- *     trigger.invoke({ message: msg })
- *   })
- *   return () => subscriber.unsubscribe()
- * })
- *
- * // Configuration object syntax with metadata
- * export const redisSubscribeTrigger = pikkuTriggerFunc({
- *   title: 'Redis Subscribe Trigger',
- *   description: 'Listens to Redis pub/sub channel',
- *   input: z.object({ channel: z.string() }),
- *   output: z.object({ message: z.string() }),
- *   func: async ({ redis }, { channel }, { trigger }) => {
- *     const subscriber = redis.duplicate()
- *     await subscriber.subscribe(channel, (msg) => {
- *       trigger.invoke({ message: msg })
- *     })
- *     return () => subscriber.unsubscribe()
- *   }
- * })
- * ```
- */
 export const pikkuTriggerFunc = <
   TInput = unknown,
   TOutput = unknown,
@@ -130,44 +71,22 @@ export const pikkuTriggerFunc = <
   return triggerOrConfig
 }
 
-/**
- * Core trigger definition for registration.
- *
- * @template TInput - Input type (configuration passed when wired)
- * @template TOutput - Output type
- */
 export interface CoreTrigger<PikkuFunctionConfig = any> {
-  /** Unique name for this trigger */
   name: string
-  /** The target RPC function to invoke when the trigger fires */
   func: PikkuFunctionConfig
-  /** Optional description */
   description?: string
-  /** Optional tags for categorization */
   tags?: string[]
-  /** Whether this trigger is used by a graph workflow */
   graph?: true
 }
 
-/**
- * Represents a trigger instance with teardown capability
- */
 export interface TriggerInstance {
   name: string
   teardown: () => void | Promise<void>
 }
 
-/**
- * A trigger source that provides the subscription function.
- * Only imported in the trigger worker process.
- *
- * @template TInput - Input type passed to the trigger function
- * @template TOutput - Output type produced when trigger fires
- */
 export type CoreTriggerSource<TInput = unknown, TOutput = unknown> = {
-  /** Must match a wireTrigger name */
+  /** Must match the name of a `wireTrigger` registration. */
   name: string
-  /** The trigger function config that sets up the subscription */
   func: CorePikkuTriggerFunctionConfig<
     TInput,
     TOutput,

package/src/wirings/variable/index.ts

@@ -1,4 +1,4 @@
-export { wireVariable } from './variable.types.js'
+export { defineVariable } from './variable.types.js'
 export type {
   CoreVariable,
   VariableDefinitionMeta,

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

@@ -2,11 +2,9 @@ import type {
   VariableDefinitions,
   VariableDefinitionsMeta,
 } from './variable.types.js'
+import type { SchemaRefLike } from '../../types/core.types.js'
 
-export interface SchemaRefLike {
-  variableName: string
-  sourceFile: string
-}
+export type { SchemaRefLike }
 
 export function validateAndBuildVariableDefinitionsMeta(
   definitions: VariableDefinitions,

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

@@ -4,12 +4,6 @@ export type CoreVariable<T = unknown> = {
   description?: string
   variableId: string
   schema: T
-  /**
-   * Link to documentation explaining how to obtain this value — a provider's
-   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
-   * deploy UIs so a user facing a missing value has somewhere to go instead of
-   * an opaque identifier.
-   */
   docsUrl?: string
 }
 
@@ -19,12 +13,6 @@ export type VariableDefinitionMeta = {
   description?: string
   variableId: string
   schema?: Record<string, unknown> | string
-  /**
-   * Link to documentation explaining how to obtain this value — a provider's
-   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
-   * deploy UIs so a user facing a missing value has somewhere to go instead of
-   * an opaque identifier.
-   */
   docsUrl?: string
   sourceFile?: string
 }
@@ -33,4 +21,4 @@ export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>
 
 export type VariableDefinitions = VariableDefinitionMeta[]
 
-export const wireVariable = <T>(_config: CoreVariable<T>): void => {}
+export const defineVariable = <T>(_config: CoreVariable<T>): void => {}