@pikku/core 0.12.92 → 0.12.94

package/src/middleware/cors.ts

@@ -8,13 +8,21 @@ import {
  * matching origin and otherwise sends no `Access-Control-Allow-Origin` at all,
  * so the browser reports "origin not allowed" rather than an origin mismatch
  * against whichever entry happened to be first.
+ *
+ * @example snippet: corsMiddleware
  */
 export const cors = pikkuMiddlewareFactory<{
+  /** Which origins may call. Defaults to `*`, which the browser rejects alongside `credentials: true` — name the origins instead. */
   origin?: string | string[] | true
+  /** Methods a cross-origin caller may use. Defaults to the common six; a method missing here fails preflight rather than the request. */
   methods?: string[]
+  /** Request headers a caller may send. Defaults to content-type, authorization and x-api-key. */
   headers?: string[]
+  /** Response headers the browser will let the caller's JavaScript read. Everything else is hidden from it even on a 200. */
   exposeHeaders?: string[]
+  /** Whether cookies and auth headers ride along. Requires a named origin, never `*`. */
   credentials?: boolean
+  /** Seconds the browser may cache this preflight. Defaults to a day. */
   maxAge?: number
 }>(
   ({

package/src/middleware/middleware-factories.ts

@@ -39,6 +39,10 @@ export const pikkuMiddlewareFactory = <In = any>(
   return factory
 }
 
+/**
+ * Declares middleware for a channel — it runs around the connection and its
+ * messages rather than around a single request.
+ */
 export const pikkuChannelMiddleware = <
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   Event = unknown,
@@ -48,12 +52,22 @@ export const pikkuChannelMiddleware = <
   return middleware
 }
 
+/**
+ * Declares channel middleware that takes options, so one definition can be
+ * wired several times with different configuration.
+ *
+ * @example snippet: channelMiddlewareFactory
+ */
 export const pikkuChannelMiddlewareFactory = <In = any>(
   factory: CorePikkuChannelMiddlewareFactory<In>
 ): CorePikkuChannelMiddlewareFactory<In> => {
   return factory
 }
 
+/**
+ * Declares middleware for an agent run — hooks around the model call, its tool
+ * calls and the run's state.
+ */
 export const pikkuAgentMiddleware = <
   State extends Record<string, unknown> = Record<string, unknown>,
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,

package/src/public-surface.json

@@ -272,10 +272,13 @@
     "validateAndBuildSystemRoleDefinitionsMeta"
   ],
   "./persona": [
+    "APP_SCOPE_ROOT",
     "ActorSignIn",
     "HttpPersona",
     "IMPERSONATE_USER_ID_HEADER",
     "OperatorSignIn",
+    "appScopeId",
+    "buildAppScopeDefinition",
     "createHttpPersonas",
     "definePersonas",
     "establishOperatorSession",

package/src/services/local-secrets.test.ts

@@ -22,7 +22,7 @@ describe('LocalSecretService', () => {
     const vars = new LocalVariablesService({})
     const service = new LocalSecretService(vars)
     await assert.rejects(() => service.getSecret('MISSING'), {
-      message: 'Requested secret not found',
+      message: 'Requested secret not found: MISSING',
     })
   })
 
@@ -44,7 +44,7 @@ describe('LocalSecretService', () => {
     const vars = new LocalVariablesService({})
     const service = new LocalSecretService(vars)
     await assert.rejects(() => service.getSecret('MISSING'), {
-      message: 'Requested secret not found',
+      message: 'Requested secret not found: MISSING',
     })
   })
 

package/src/services/local-secrets.ts

@@ -32,7 +32,7 @@ export class LocalSecretService implements SecretService {
     if (value) {
       return createSecretValue(this.parseSecret<T>(value))
     }
-    throw new Error('Requested secret not found')
+    throw new Error(`Requested secret not found: ${key}`)
   }
 
   public async setSecret(key: string, value: unknown): Promise<void> {

package/src/services/personas-service.ts

@@ -38,6 +38,8 @@ export interface ScenarioHttpResponse<T = unknown> {
  * `invokeRaw` returns this, and a step that has to reach past a persona — a
  * route with no RPC, an identity no persona can hold — reaches for this rather
  * than writing the same record by hand.
+ *
+ * @example snippet: scenarioPolling
  */
 export const readScenarioHttpResponse = async <T = unknown>(
   res: Response
@@ -84,6 +86,8 @@ export interface ScenarioJsonRequest {
  * outright when the target answers an empty body or an HTML error page. A
  * refusal is the expected outcome of a permissions scenario, so it has to
  * survive as data.
+ *
+ * @example snippet: scenarioHttpStep
  */
 export const postScenarioJson = async <T = unknown>(
   url: string,

package/src/services/secret-service.ts

@@ -4,7 +4,6 @@ import type { SecretValue } from '../classification/secret-value.js'
 export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }
 
 export interface SecretService {
-  /** Throws if the secret is not found. Unwrap the result with `.reveal()`. */
   getSecret<T = string>(key: string): Promise<SecretValue<T>>
   /** Answers for any key, including a disallowed one — it must not throw. */
   hasSecret(key: string): Promise<boolean>

package/src/testing/service-tests/secret-service-tests.ts

@@ -44,7 +44,7 @@ export const defineSecretServiceTests = (
     test('getSecret throws for missing key', async () => {
       const service = await factory({ key: kek })
       await assert.rejects(() => service.getSecret('nonexistent'), {
-        message: 'Requested secret not found',
+        message: 'Requested secret not found: nonexistent',
       })
     })
 

package/src/types/core.types.ts

@@ -373,10 +373,15 @@ export type CommonWireMeta = {
   pikkuFuncId: string
   packageName?: string
 
+  /** A human name for this wiring, shown wherever it is listed rather than called. */
   title?: string
+  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** What this does, for whoever is reading the wiring rather than writing it. */
   description?: string
+  /** Names of error classes this may throw, so each one's registered status is used instead of a 500. */
   errors?: string[]
 
   middleware?: MiddlewareMetadata[]

package/src/wirings/addon/addon-auth-tags.test.ts

@@ -7,7 +7,7 @@ import {
   addTagMiddleware,
   clearMiddlewareCache,
 } from '../../middleware-runner.js'
-import { ForbiddenError } from '../../errors/errors.js'
+import { ForbiddenError, MissingSessionError } from '../../errors/errors.js'
 import { resolveAddonAuth, resolveAddonTags, wireAddon } from './wire-addon.js'
 
 const ADDON_PACKAGE = '@addon/console'
@@ -114,7 +114,7 @@ describe('wireAddon auth on direct wirings', () => {
 
     await assert.rejects(
       () => callOverDirectWiring('credentialGet'),
-      ForbiddenError
+      MissingSessionError
     )
   })
 
@@ -141,7 +141,7 @@ describe('wireAddon auth on direct wirings', () => {
 
     await assert.rejects(
       () => callOverDirectWiring('credentialGet', { auth: true }),
-      ForbiddenError
+      MissingSessionError
     )
   })
 
@@ -161,7 +161,7 @@ describe('wireAddon auth on direct wirings', () => {
     ]) {
       await assert.rejects(
         () => callOverDirectWiring('credentialGet', { wireType }),
-        ForbiddenError,
+        MissingSessionError,
         `${wireType} should have been gated`
       )
     }

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

@@ -2,35 +2,31 @@ import { pikkuState } from '../../pikku-state.js'
 import { getTagGroups } from '../../utils.js'
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js'
 export type WireAddonConfig = {
+  /** How this instance is addressed. One package may be wired more than once, and the name is what tells the instances apart. */
   name: string
+  /** The npm package the addon ships in. */
   package: string
+  /** Where to reach the addon when it runs as its own service rather than in-process. */
   rpcEndpoint?: string
+  /** Requires a session for every function in the addon, whatever each one declares. Gates an addon whose functions are individually open. */
   auth?: boolean
+  /** Offers the addon's functions to MCP clients as tools, without wiring each one. */
   mcp?: boolean
+  /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
   /** Required of every function in the addon, on top of the function's own. */
   scopes?: string[]
+  /** Points a secret the addon reads at a different key in this deployment, so two instances can hold different credentials. */
   secretOverrides?: Record<string, string>
+  /** Points a variable the addon reads at a different key in this deployment. */
   variableOverrides?: Record<string, string>
+  /** Points a credential the addon reads at a different key in this deployment. */
   credentialOverrides?: Record<string, string>
-  /**
-   * Secrets this instance may read on top of the ones it declared, named as the
-   * addon reads them — the scope check runs before `secretOverrides` renames
-   * them, so an overridden secret is named here by its addon-side key. Listing
-   * one in `secretOverrides` grants it too.
-   *
-   * For an addon whose secret names come off its input rather than its own
-   * source, this is how the host lends names the addon could not declare.
-   */
+  /** Extra secrets this instance may read, named as the addon reads them — the scope check runs before `secretOverrides` renames them. */
   secretGrants?: string[]
   /** Credentials this instance may read on top of the ones it declared. */
   credentialGrants?: string[]
-  /**
-   * Hands this instance the whole `SecretService` instead of one scoped to the
-   * secrets it declared. The value is the reason, recorded in the deploy
-   * manifest — an addon that names secrets at runtime cannot be scoped, and
-   * only the consuming app, never the addon, can grant it.
-   */
+  /** Hands over the whole `SecretService` unscoped. The value is the reason, recorded in the deploy manifest. */
   globalSecrets?: string
   /**
    * Hands this instance the whole `CredentialService` instead of one narrowed
@@ -40,6 +36,12 @@ export type WireAddonConfig = {
   globalCredentials?: string
 }
 
+/**
+ * Installs an addon into this project: its functions, wirings and scopes become
+ * part of the app, under the namespace and options given here.
+ *
+ * @example snippet: addonWiring
+ */
 export const wireAddon = (config: WireAddonConfig): void => {
   pikkuState(null, 'addons', 'packages').set(config.name, {
     package: config.package,

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

@@ -25,6 +25,10 @@ export type WireRemoteAddonConfig = {
   tags?: string[]
 }
 
+/**
+ * Installs an addon that runs as its own deployed service: the contract is
+ * local, the calls go over the wire to the addon's own host.
+ */
 export const wireRemoteAddon = (config: WireRemoteAddonConfig): void => {
   pikkuState(null, 'addons', 'packages').set(config.name, {
     package: config.package,

package/src/wirings/agent/agent-authorization.test.ts

@@ -8,7 +8,11 @@ import {
 } from '../../pikku-state.js'
 import { assertAgentAuthorized } from './agent-prepare.js'
 import { clearPermissionsCache } from '../../permissions.js'
-import { ForbiddenError, MissingScopeError } from '../../errors/errors.js'
+import {
+  ForbiddenError,
+  MissingScopeError,
+  MissingSessionError,
+} from '../../errors/errors.js'
 import type { CoreAgent } from './agent.types.js'
 import type { CoreUserSession } from '../../types/core.types.js'
 
@@ -73,7 +77,7 @@ describe('assertAgentAuthorized', () => {
     await assertAgentAuthorized(agent, {}, null)
   })
 
-  test('throws ForbiddenError when auth is explicitly true and no session exists', async () => {
+  test('throws MissingSessionError when auth is explicitly true and no session exists', async () => {
     const agent = addAgent('needs-session', { auth: true })
     await assert.rejects(
       () =>
@@ -82,7 +86,7 @@ describe('assertAgentAuthorized', () => {
           { sessionService: sessionService(undefined) },
           null
         ),
-      ForbiddenError
+      MissingSessionError
     )
   })
 

package/src/wirings/agent/agent-prepare.ts

@@ -22,7 +22,7 @@ import {
   type PermissionWire,
 } from '../../permissions.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
-import { ForbiddenError } from '../../errors/errors.js'
+import { ForbiddenError, MissingSessionError } from '../../errors/errors.js'
 import { verifyScopes } from '../../scopes.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
@@ -315,7 +315,7 @@ export async function assertAgentAuthorized(
     : undefined
 
   if (agent.auth === true && !session) {
-    throw new ForbiddenError('Authentication required')
+    throw new MissingSessionError('Authentication required')
   }
 
   verifyScopes(agent.scopes, session)

package/src/wirings/agent/agent.types.ts

@@ -183,6 +183,7 @@ export interface PikkuAgentMiddlewareHooks<
   State extends Record<string, unknown> = Record<string, unknown>,
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
 > {
+  /** Rewrites what the model is about to see — messages and instructions — before each turn. */
   modifyInput?: (
     services: SingletonServices,
     ctx: {
@@ -210,6 +211,7 @@ export interface PikkuAgentMiddlewareHooks<
     | Promise<{ messages: AgentMessage[]; instructions: string }>
     | { messages: AgentMessage[]; instructions: string }
 
+  /** Sees the model's output as it streams, for redaction or live inspection. Keeps its own `state` across chunks, unlike the shared run notes. */
   modifyOutputStream?: (
     services: SingletonServices,
     ctx: {
@@ -262,6 +264,7 @@ export interface PikkuAgentMiddlewareHooks<
    * and handed to anything that grades the run, and scrubbing the reply alone
    * leaves them untouched.
    */
+  /** Rewrites the finished output of a turn, after streaming has completed. */
   modifyOutput?: (
     services: SingletonServices,
     ctx: {
@@ -282,6 +285,7 @@ export interface PikkuAgentMiddlewareHooks<
         toolCalls?: NonNullable<AgentStep['toolCalls']>
       }
 
+  /** Runs before a tool executes, and may rewrite the arguments the model chose. Returning nothing leaves them as they are. */
   beforeToolCall?: (
     services: SingletonServices,
     ctx: {
@@ -294,6 +298,7 @@ export interface PikkuAgentMiddlewareHooks<
     | { args: Record<string, unknown> }
     | void
 
+  /** Runs once a tool has returned, and may replace its result before the model sees it. */
   afterToolCall?: (
     services: SingletonServices,
     ctx: {
@@ -305,6 +310,7 @@ export interface PikkuAgentMiddlewareHooks<
     }
   ) => Promise<{ result: unknown } | void> | { result: unknown } | void
 
+  /** Runs at the end of each model turn. For observation — it cannot change what happened. */
   afterStep?: (
     services: SingletonServices,
     ctx: {
@@ -323,6 +329,7 @@ export interface PikkuAgentMiddlewareHooks<
     }
   ) => Promise<void> | void
 
+  /** Runs when a turn throws, with the step it failed on. For logging and cleanup; it does not swallow the error. */
   onError?: (
     services: SingletonServices,
     ctx: {
@@ -347,58 +354,51 @@ export type CoreAgent<
   Scope extends string = string,
   Scorer extends string = string,
 > = {
+  /** Unique across the project. It is how the agent is invoked and how its runs are grouped. */
   name: string
+  /** What the agent is for. Another agent choosing whether to delegate to this one reads it, so write it for that reader. */
   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 each one's registered status is used instead of a 500. */
   errors?: string[]
-  /**
-   * The three fields below are the system prompt. `buildInstructions` joins
-   * whichever are set with a blank line, always in this order — role, then
-   * personality, then goal — and appends the tool-usage rules if the agent has
-   * tools. Nothing checks them against each other: the split is there to keep a
-   * prompt legible, and text put in the wrong one still reaches the model.
-   *
-   * Who the agent is. 'You are a support engineer triaging inbound bugs.'
-   */
+  /** Who the agent is. Joined with `personality` and `goal`, in that order, to form the system prompt. */
   role?: string
   /** How it should sound: tone, vocabulary, how much it says at a time. */
   personality?: string
   /** What it is for — the only one of the three that is required. */
   goal: string
+  /** Which model to run on, as the provider names it. */
   model: string
+  /** How much the model is allowed to vary its answer. Lower is more repeatable, which is what a tool-driving agent usually wants. */
   temperature?: number
   /** Ownership/partitioning of this agent's threads and runs. Defaults to `'user'`. */
   sessionScope?: SessionScope
+  /** Functions the model may call, given to it as tools. A `readonly` one may be called without asking first. */
   tools?: unknown[]
+  /** Other agents this one may hand work to. `agentMode` decides whether it delegates or supervises. */
   agents?: unknown[]
+  /** Workflows the model may start, for work too long to sit inside one agent run. */
   workflows?: unknown[]
-  /**
-   * Grades this agent's finished runs on live traffic, named by the generated
-   * `ScorerName` union rather than by `ref()` — a scorer is not a function, so
-   * there is nothing in the function map for a ref to resolve against.
-   *
-   * A reference-based judge listed here is never sampled: live traffic has no
-   * answer key. Scenarios name scorers directly and may grade with scorers an
-   * agent does not ship with.
-   */
+  /** Grades finished runs on live traffic. A reference-based judge is never sampled here — live traffic has no answer key. */
   scorers?: Scorer[]
+  /** `delegate` hands a sub-agent the task and takes its answer; `supervise` keeps this agent in the loop over each step. */
   agentMode?: 'delegate' | 'supervise'
+  /** What the agent carries between runs, and how much of it. */
   memory?: AgentMemoryConfig
+  /** How many model turns a single run may take before it is stopped. The guard against a tool loop that never converges. */
   maxSteps?: number
+  /** Whether the model may answer without calling a tool (`auto`), must call one (`required`), or may not (`none`). */
   toolChoice?: 'auto' | 'required' | 'none'
-  /**
-   * Per-provider model settings, keyed by provider id and passed through
-   * untouched — for anything only one vendor offers, which the fields above
-   * deliberately do not try to unify.
-   *
-   * `{ openai: { reasoningEffort: 'minimal' } }` is the one that matters for
-   * voice: on gpt-5-mini it measured 0.9s to first token against 2.5s at the
-   * default, and a spoken reply is waited through rather than skimmed.
-   */
+  /** Per-provider settings passed through untouched, for what only one vendor offers. */
   providerOptions?: AIProviderOptions
+  /** The schema of what starts a run, which is also its input type. */
   input?: unknown
+  /** The schema the final answer must match, which is also its return type. Without one the agent returns free text. */
   output?: unknown
+  /** Filters this agent in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Runs before each model turn, to change what that turn sees or to stop the run. This is where a step budget or a tool narrowing goes. */
   prepareStep?: (ctx: {
     stepNumber: number
     messages: AgentMessage[]
@@ -407,8 +407,11 @@ export type CoreAgent<
     model: string
     stop: () => void
   }) => void | Promise<void>
+  /** Wraps the whole run: auth, tracing, spend limits. */
   middleware?: PikkuMiddleware[]
+  /** Wraps each message when the agent is driven over a channel. */
   channelMiddleware?: CorePikkuChannelMiddleware<any, any>[]
+  /** Hooks around each step and each tool call — the place to inspect, rewrite or veto what the model is about to do. */
   agentMiddleware?: PikkuAgentMiddlewareHooks<any, any>[]
   /**
    * Whether a session is required to run this agent. Defaults to `false`, since
@@ -427,6 +430,7 @@ export type CoreAgent<
    * `#pikku/scopes`, so an undeclared scope is a compile error.
    */
   scopes?: Scope[]
+  /** Checks that run before the agent starts. Grouped names OR together, so any one passing admits the caller. */
   permissions?: CorePermissionGroup<PikkuPermission>
 }
 

package/src/wirings/agent-scorer/agent-scorer.ts

@@ -18,6 +18,8 @@ const assertSampleRate = (name: string, sampleRate: number | undefined) => {
 /**
  * A heuristic scorer: pure code over the finished run, no model call, so it
  * grades on the fast lane.
+ *
+ * @example snippet: agentScorer
  */
 export const pikkuAgentScorer = <Services = any>(config: {
   name: string
@@ -49,6 +51,8 @@ export const pikkuAgentScorer = <Services = any>(config: {
  * The rubric field is `goal`, matching `pikkuAgent`'s prompt vocabulary — a
  * judge is a degenerate agent, and should use the same word for the same thing.
  * `prompt` is the escape hatch for non-standard framing.
+ *
+ * @example snippet: agentJudge
  */
 export const pikkuAgentJudge = <Services = any>(config: {
   name: string

package/src/wirings/channel/channel.types.ts

@@ -98,8 +98,11 @@ export type CoreChannel<
   PikkuPermission = CorePikkuPermission<ChannelData>,
   PikkuMiddleware = CorePikkuMiddleware,
 > = {
+  /** Unique across the project. It is how the channel is addressed in `pikku meta` and by the generated client. */
   name: string
+  /** The path a client opens the socket on. */
   route: Channel
+  /** Runs once when a client connects, before any message. Its return value is sent as the first message. */
   onConnect?:
     | ChannelConnect
     | {
@@ -112,7 +115,9 @@ export type CoreChannel<
         func?: ChannelDisconnect
         middleware?: PikkuMiddleware[]
       }
+  /** Handles any message that no `onMessageWiring` entry claimed. Without one, an unrouted message is dropped. */
   onMessage?: ChannelFunctionMessage
+  /** Routes messages by a key in their payload: the outer key is the field to switch on, the inner key its value. This is how one socket carries many operations. */
   onMessageWiring?: Record<
     string,
     Record<
@@ -125,17 +130,23 @@ export type CoreChannel<
         }
     >
   >
+  /** Wraps the connection: it runs on connect, where the session is established, not on every message. */
   middleware?: PikkuMiddleware[]
+  /** Wraps every message, which is where per-message concerns like rate limiting belong. */
   channelMiddleware?: Array<
     CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory
   >
+  /** Whether opening the channel requires a session. Defaults to true — a channel is closed unless it says otherwise. */
   auth?: boolean
+  /** Whether this channel carries binary frames. Text frames are still parsed as JSON. */
   binary?: boolean | null
+  /** Handles binary frames, which never reach `onMessage` because they are not JSON. Return a value to reply in kind. */
   onBinaryMessage?: (
     services: any,
     data: BinaryData,
     channel: PikkuChannel<ChannelData, any>
   ) => Promise<BinaryData | void> | BinaryData | void
+  /** Filters this channel in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
 }
 

package/src/wirings/cli/cli.types.ts

@@ -174,6 +174,12 @@ type SplitBySpace<S extends string> = S extends `${infer First} ${infer Rest}`
     ? []
     : [S]
 
+/**
+ * Strip the `...` a variadic positional carries, so `[files...]` validates
+ * against the `files` key the runtime parser fills.
+ */
+type StripVariadic<S extends string> = S extends `${infer Name}...` ? Name : S
+
 /**
  * Recursively build a tuple by stripping brackets from each element
  */
@@ -182,7 +188,7 @@ type BuildParamsTuple<Parts extends readonly string[]> =
     infer First extends string,
     ...infer Rest extends string[],
   ]
-    ? [StripBrackets<First>, ...BuildParamsTuple<Rest>]
+    ? [StripVariadic<StripBrackets<First>>, ...BuildParamsTuple<Rest>]
     : []
 
 /**
@@ -227,16 +233,39 @@ export type CoreCLICommandConfig<
   >,
   Params extends string = string,
 > = {
+  /**
+   * Positional arguments, written the way `--help` prints them: `<env>` is
+   * required, `[region]` optional. Each name must be a key of the function's
+   * input schema, so a typo is a compile error rather than an argument that
+   * silently never arrives.
+   */
   parameters?: ValidateParameters<Params, ExtractFunctionInput<FuncConfig>>
+  /** The function to run. Omit it on a command that exists only to hold `subcommands`. */
   func?: FuncConfig
+  /** The heading shown above this command's own help. */
   title?: string
+  /** The one-line summary listed beside the command name. */
   description?: string
+  /**
+   * Prints the result. The function returns data and this is the only thing
+   * that writes to stdout, which is what lets one command serve both a human
+   * reading it and a script parsing it.
+   */
   render?: PikkuCLIRender
+  /**
+   * Flags, keyed by the input field each one fills. A field with no entry is
+   * still accepted as `--field`; an entry is how it gets a short form, a
+   * default, or help text.
+   */
   options?: {
     [K in keyof ExtractFunctionInput<FuncConfig>]?: {
+      /** What this flag is for, as `--help` prints it. */
       description?: string
+      /** A single-letter alias, so `--verbose` can also be `-v`. */
       short?: string
+      /** How the argument is parsed. Inferred from the input schema when omitted. */
       type?: CLIOptionType
+      /** Used when the flag is absent, and shown in `--help` so nobody has to guess it. */
       default?: ExtractFunctionInput<FuncConfig>[K]
       /**
        * The values this option accepts. Rejected by the parser and listed in
@@ -246,13 +275,18 @@ export type CoreCLICommandConfig<
       choices?: ReadonlyArray<ExtractFunctionInput<FuncConfig>[K]>
     }
   }
+  /** Wraps every run of this command. */
   middleware?: PikkuMiddleware[]
+  /** Nested commands, keyed by the word that selects them: `deploy plan` is `deploy` with a `plan` subcommand. */
   subcommands?: Record<
     string,
     CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender, any>
   >
+  /** Whether running this requires a logged-in session. Defaults to true — a command is closed unless it says otherwise. */
   auth?: boolean
+  /** Permission checks run before the function, for a command that not every logged-in user may run. */
   permissions?: any[]
+  /** Runs when the parent is invoked with no subcommand named. */
   isDefault?: boolean
 }
 
@@ -308,14 +342,23 @@ export interface CoreCLI<
   PikkuMiddleware,
   PikkuCLIRender,
 > {
+  /** The command name a user types. It is also what `--help` prints as the program. */
   program: string
+  /** What the program is for, shown at the top of `--help`. */
   description?: string
+  /** Top-level commands, keyed by the word that selects them. */
   commands: Commands
+  /** Flags accepted before any command, for things that apply to the whole program. */
   options?: CLIOptions<Options>
+  /** Wraps every command. */
   middleware?: PikkuMiddleware[]
+  /** The fallback printer for commands that declare none of their own. */
   render?: PikkuCLIRender
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** Names of error classes any command may throw, so each one's registered exit behaviour is used. */
   errors?: string[]
+  /** Filters this program in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
   /**
    * Requires a session on the websocket serving this program remotely. Has no

package/src/wirings/cli/define-cli-commands.ts

@@ -1,6 +1,11 @@
 import type { CoreCLICommandConfig } from './cli.types.js'
 
-/** Identity at runtime; exists so a commands record can be typed and composed before `wireCLI`. */
+/**
+ * Identity at runtime; exists so a commands record can be typed and composed
+ * before `wireCLI`.
+ *
+ * @example snippet: cliCommandContract
+ */
 export function defineCLICommands<
   T extends Record<string, CoreCLICommandConfig<any, any, any, any>>,
 >(commands: T): T {