@pikku/core 0.12.92 → 0.12.93

package/src/wirings/http/http.types.ts

@@ -48,15 +48,19 @@ export type HTTPHeadersSchema = StandardSchemaV1<
 >
 
 export type HTTPRouteBaseConfig = {
+  /** How the body is serialised. Defaults to JSON; `xml` is for routes a caller you do not control insists on. */
   contentType?: 'xml' | 'json'
+  /** Seconds before the request is abandoned. Work that can outlast a request should be dispatched instead, not given a longer timeout. */
   timeout?: number
+  /** Filters this route in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** A schema the request headers are validated against, so a missing or malformed header fails before the function body runs. */
   headers?: HTTPHeadersSchema
 }
 
 export type CoreHTTPFunction = HTTPRouteBaseConfig & {
   route: string
-  eventChannel?: false
+  /** Sends the returned value as-is rather than JSON-encoding it, for a route whose body is binary or already serialised. */
   returnsJSON?: false
 }
 
@@ -70,100 +74,121 @@ export type PikkuQuery<T = Record<string, string | undefined>> = Record<
   string | T | null | Array<T | null>
 >
 
-export type CoreHTTPFunctionWiring<
+/**
+ * The keys every HTTP wiring takes, whatever it is wired to. The three that
+ * are not here — `method`, `auth` and `func` — are correlated rather than
+ * independent, and live in the unions below.
+ */
+type HTTPWiringShared<
+  R extends string,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any>,
+> = CoreHTTPFunction & {
+  /**
+   * The path this wiring answers on. `:name` marks a parameter, and every
+   * parameter in the path must be a key of the function's input schema —
+   * a mismatch is a compile error rather than a 404 at runtime.
+   */
+  route: R
+  /** Wraps every request to this route: auth, tracing, rate limiting. Runs before the permissions on `func`. */
+  middleware?: PikkuMiddleware[]
+}
+
+/**
+ * `auth` decides which kind of function this route can point at, so the two
+ * travel together: a route that requires a session gets a function that is
+ * handed one, and an open route gets a sessionless function that has none to
+ * read. Splitting them would let a function ask for a session the route never
+ * establishes.
+ */
+type HTTPWiringAuth<
   In,
   Out,
-  R extends string,
-  PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> =
-    CorePikkuFunction<In, Out>,
+  PikkuFunction extends CorePikkuFunction<In, Out, any, any, any>,
   PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
     In,
     Out,
     any,
     any,
     any
-  > = CorePikkuFunctionSessionless<In, Out>,
-  PikkuPermission extends CorePikkuPermission<In, any, any> =
-    CorePikkuPermission<In, any, any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
-    any,
-    any
   >,
+  PikkuPermission extends CorePikkuPermission<In, any, any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any>,
 > =
-  | (CoreHTTPFunction & {
-      route: R
-      method: HTTPMethod
+  | {
+      /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
+      auth?: true
+      /** The function to run. It is handed the session this route required. */
       func: CorePikkuFunctionConfig<
         PikkuFunction,
         PikkuPermission,
         PikkuMiddleware
       >
-      auth?: true
-      middleware?: PikkuMiddleware[]
-      sse?: undefined
-    })
-  | (CoreHTTPFunction & {
-      route: R
-      method: HTTPMethod
+    }
+  | {
+      /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
+      auth?: false
+      /** On an open route there is no session, so this must be a sessionless function. */
       func: CorePikkuFunctionConfig<
         PikkuFunctionSessionless,
         PikkuPermission,
         PikkuMiddleware
       >
-      auth?: false
-      middleware?: PikkuMiddleware[]
+    }
+
+/**
+ * `sse` and `query` are each valid on one method only, so the method carries
+ * them: streaming is a GET, and naming which input keys arrive in the query
+ * string is only a question on a POST, where the rest of the input is a body.
+ */
+type HTTPWiringMethod<In> =
+  | {
+      /** The HTTP method. A route and method together address one wiring. */
+      method: HTTPMethod
       sse?: undefined
-    })
-  | (CoreHTTPFunction & {
-      route: R
+    }
+  | {
+      /** The HTTP method. A route and method together address one wiring. */
       method: 'get'
-      func: CorePikkuFunctionConfig<
-        PikkuFunction,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-      auth?: true
-      middleware?: PikkuMiddleware[]
-      sse?: boolean
-    })
-  | (CoreHTTPFunction & {
-      route: R
-      method: 'get'
-      func: CorePikkuFunctionConfig<
-        PikkuFunctionSessionless,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-      auth?: false
-      middleware?: PikkuMiddleware[]
+      /** Streams the response as server-sent events instead of returning it once. GET only. */
       sse?: boolean
-    })
-  | (CoreHTTPFunction & {
-      route: R
+    }
+  | {
+      /** The HTTP method. A route and method together address one wiring. */
       method: 'post'
-      func: CorePikkuFunctionConfig<
-        PikkuFunction,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-      auth?: true
-      middleware?: PikkuMiddleware[]
+      /** Input keys that arrive in the query string rather than the body. POST only, where the body is the default home for input. */
       query?: Array<keyof In>
       sse?: undefined
-    })
-  | (CoreHTTPFunction & {
-      route: R
-      method: 'post'
-      func: CorePikkuFunctionConfig<
-        PikkuFunctionSessionless,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-      auth?: false
-      middleware?: PikkuMiddleware[]
-      query?: Array<keyof In>
-      sse?: undefined
-    })
+    }
+
+export type CoreHTTPFunctionWiring<
+  In,
+  Out,
+  R extends string,
+  PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> =
+    CorePikkuFunction<In, Out>,
+  PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
+    In,
+    Out,
+    any,
+    any,
+    any
+  > = CorePikkuFunctionSessionless<In, Out>,
+  PikkuPermission extends CorePikkuPermission<In, any, any> =
+    CorePikkuPermission<In, any, any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+> = HTTPWiringShared<R, PikkuMiddleware> &
+  HTTPWiringAuth<
+    In,
+    Out,
+    PikkuFunction,
+    PikkuFunctionSessionless,
+    PikkuPermission,
+    PikkuMiddleware
+  > &
+  HTTPWiringMethod<In>
 
 export type HTTPFunctionMetaInputTypes = {
   params?: string

package/src/wirings/mcp/mcp.types.ts

@@ -76,16 +76,27 @@ export type CoreMCPResource<
   PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
+  /** How the client addresses this resource. `{name}` marks a parameter, and every parameter must be a key of the function's input schema. */
   uri: string
+  /** The name a human sees in a client's resource list. */
   title: string
+  /** What the resource holds, written for the model deciding whether to read it. */
   description: string
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
   errors?: string[]
+  /** The media type of what the function returns, so the client knows whether it is text, JSON or an image. */
   mimeType?: string
+  /** Size in bytes, where it is known ahead of the read. A client uses it to decide whether to fetch at all. */
   size?: number
+  /** Whether the function returns the content in chunks rather than at once. */
   streaming?: boolean
+  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
   func: PikkuFunctionConfig
+  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
   middleware?: PikkuMiddleware[]
 }
 
@@ -96,14 +107,23 @@ export type CoreMCPTool<
   PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
+  /** How the model calls this tool. It is the tool's identity, so renaming it breaks any client that already knows it. */
   name: string
+  /** The name a human sees, where the calling `name` is not readable. */
   title?: string
+  /** What the tool does and when to reach for it. This is what the model decides on, so it earns more care than the rest of this object. */
   description?: string
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
   errors?: string[]
+  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
   func: PikkuFunctionConfig
+  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Whether the function returns its result in chunks rather than at once. */
   streaming?: boolean
+  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
   middleware?: PikkuMiddleware[]
 }
 
@@ -114,12 +134,19 @@ export type CoreMCPPrompt<
   PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
+  /** How the client asks for this prompt. */
   name: string
+  /** What the prompt is for, written for the human picking it out of a list. */
   description: string
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
   errors?: string[]
+  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
   func: PikkuFunctionConfig
+  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
   middleware?: PikkuMiddleware[]
 }
 

package/src/wirings/queue/queue.types.ts

@@ -135,11 +135,17 @@ export type CoreQueueWorker<
   PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> =
     CorePikkuFunctionConfig<any, any, any>,
 > = {
+  /** The queue this worker consumes. Whoever enqueues a job names the same string, so it is the contract between producer and consumer. */
   name: string
+  /** The function to run per job. Its `input` schema is the job payload's schema — a job that does not match is rejected before the body runs. */
   func: PikkuFunctionConfig
+  /** Concurrency, retry and backoff, passed through to the queue service backing this worker. Defaults come from the service, not from here. */
   config?: PikkuWorkerConfig
+  /** Names of error classes that mean the job is bad rather than the run — thrown, they fail the job permanently instead of being retried. */
   errors?: string[]
+  /** Filters this worker in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Wraps every job. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
   middleware?: PikkuFunctionConfig['middleware']
 }
 

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

@@ -21,10 +21,15 @@ export type CoreScheduledTask<
   >,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
+  /** Unique across the project. It is how the task is addressed in logs, in `pikku meta`, and by a scheduler service asked to run it now. */
   name: string
+  /** A five-field cron expression: minute, hour, day of month, month, day of week. `0 9 * * 1` is 09:00 every Monday. Interpreted in the deployment's timezone, not the author's. */
   schedule: string
+  /** The function to run. It receives no session and no input: a scheduled task has no caller, so it must be sessionless. */
   func: PikkuFunctionConfig
+  /** Filters this task in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Wraps every execution. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
   middleware?: PikkuMiddleware[]
 }
 

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

@@ -4,21 +4,9 @@ export type CoreSecret<T = unknown> = {
   description?: string
   secretId: string
   schema: T
-  /**
-   * A secret is REQUIRED by default because `getSecret` throws when the value is
-   * missing — a deploy without it is a runtime failure waiting to happen, so the
-   * deploy gate refuses it. Mark a secret `optional` when absence is a supported
-   * state the app handles (a feature that simply stays off): the generated map
-   * emits it as an optional property and `getSecret` resolves `undefined`
-   * instead of throwing.
-   */
+  /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
   optional?: boolean
-  /**
-   * 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.
-   */
+  /** Where a user goes to obtain this value, surfaced beside a missing one. */
   docsUrl?: string
   /** Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`. */
   rotationPeriod?: string
@@ -64,4 +52,11 @@ export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>
 
 export type SecretDefinitions = SecretDefinitionMeta[]
 
+/**
+ * Declares a secret this project needs, with the shape of its value. The CLI
+ * collects every declaration into `CredentialsMap`, which is what makes
+ * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: secrets
+ */
 export const defineSecret = <T>(_config: CoreSecret<T>): void => {}

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

@@ -72,11 +72,14 @@ export const pikkuTriggerFunc = <
 }
 
 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[]
-  graph?: true
 }
 
 export interface TriggerInstance {

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

@@ -1,23 +1,17 @@
 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
-  /**
-   * A variable is REQUIRED by default, and marking it `optional` is how a
-   * declaration says its absence is a supported state. Same flag, same
-   * polarity and same meaning as `CoreSecret.optional` — one word to learn
-   * rather than two with opposite senses.
-   *
-   * Defaulting to required rather than following `variables.get`'s
-   * `T | undefined` return is deliberate. That signature describes what a
-   * caller must HANDLE, not whether a deployment is correct without the value:
-   * an undefined feature flag is fine, an undefined API base URL is an outage
-   * that the type system cannot tell apart. Declaring the difference is the
-   * point of the flag, and the safe default for an undeclared one is to ask.
-   */
+  /** 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
 }
 
@@ -36,4 +30,11 @@ 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/workflow/graph/wire-workflow-graph.ts

@@ -2,12 +2,19 @@ export interface PikkuWorkflowGraphConfig<
   FuncMap extends Record<string, string>,
   T,
 > {
+  /** Keeps the graph in the codebase but out of the build. */
   disabled?: true
+  /** Unique across the project. It is how the graph is started and how its runs are grouped. */
   name?: string
+  /** What the graph does, for whoever is reading it rather than editing it. */
   description?: string
+  /** Filters this graph in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** The graph's steps, keyed by node id, each naming a function. `pikku meta` lists the names available here. */
   nodes: FuncMap
+  /** Per-node settings — retries, timeouts, the edges between them. */
   config?: T
+  /** Free text carried onto the rendered graph, for a reader who needs the reasoning the shape cannot show. */
   notes?: string[]
 }
 

package/src/wirings/workflow/scenario-cookie-jar.ts

@@ -4,6 +4,12 @@ export interface ScenarioCookieJar {
   readonly empty: boolean
 }
 
+/**
+ * A cookie store for a scenario run, so a step that signs in leaves the session
+ * cookie behind for the steps after it.
+ *
+ * @example snippet: scenarioCookieJar
+ */
 export const createCookieJar = (apiUrl: string): ScenarioCookieJar => {
   const jar = new Map<string, string>()
   const origin = new URL(apiUrl).origin

package/src/wirings/workflow/scenario-poll.ts

@@ -3,6 +3,12 @@ export interface PollOptions {
   intervalMs?: number
 }
 
+/**
+ * Retries an assertion until it passes or the timeout runs out — for the
+ * eventually-consistent parts of a scenario (a queued job, a projection).
+ *
+ * @example snippet: scenarioPolling
+ */
 export const pollUntil = async <T>(
   attempt: () => Promise<T | undefined> | T | undefined,
   { timeoutMs = 15_000, intervalMs = 250 }: PollOptions = {}

package/src/wirings/workflow/scenario-step-guards.ts

@@ -3,6 +3,12 @@ import type {
   ScenarioEnvironment,
 } from './scenario-step.types.js'
 
+/**
+ * The environment the current scenario run targets, or a throw explaining that
+ * the run carries none. Use it in a step that needs the target's URLs.
+ *
+ * @example snippet: scenarioHttpStep
+ */
 export const requireScenarioEnv = (
   scenarioStep: PikkuScenarioStepWire | undefined
 ): ScenarioEnvironment => {

package/src/wirings/workflow/workflow-errors.ts

@@ -15,6 +15,10 @@ export class WorkflowAsyncException extends Error {
   }
 }
 
+/**
+ * Thrown inside a workflow step when the run has been cancelled, so the step
+ * stops rather than finishing work nobody wants.
+ */
 export class WorkflowCancelledException extends Error {
   constructor(
     public readonly runId: string,