@pikku/core 0.12.143 → 0.12.145

package/dist/wirings/channel/channel.types.d.ts

@@ -1,9 +1,13 @@
 import type { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
 import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
+/** A binary channel frame. */
 export type BinaryData = ArrayBuffer | Uint8Array;
+/** Middleware that runs around each channel message. Call `next` with the event to pass it on, with several events to fan it out, or with `null` to drop it. */
 export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (services: Services, event: Event, next: (event: Event | Event[] | null) => Promise<void> | void) => Promise<void> | void;
+/** Builds a {@link CorePikkuChannelMiddleware} from configuration, so the same middleware can be reused with different settings. */
 export type CorePikkuChannelMiddlewareFactory<In = any, Services = any, Event = unknown> = (input: In) => CorePikkuChannelMiddleware<Services, Event>;
 import type { CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
+/** Options for running a channel connection. They mean the same as the matching {@link RunHTTPWiringOptions}. */
 export type RunChannelOptions = Partial<{
     skipUserSession: boolean;
     respondWith404: boolean;
@@ -11,11 +15,13 @@ export type RunChannelOptions = Partial<{
     logWarningsForStatusCodes: number[];
     bubbleErrors: boolean;
 }>;
+/** The connection a channel runner is handed: its id and, when it came over HTTP, the upgrade request and response. */
 export type RunChannelParams<ChannelData> = {
     channelId: string;
     request?: PikkuHTTPRequest<ChannelData>;
     response?: PikkuHTTPResponse;
 };
+/** Generated metadata for one channel handler: the function it runs and its resolved middleware. */
 export interface ChannelMessageMeta {
     pikkuFuncId: string;
     packageName?: string;
@@ -25,6 +31,7 @@ export interface ChannelMessageMeta {
     tags?: string[];
     middleware?: MiddlewareMetadata[];
 }
+/** Generated metadata for one wired channel: its route, input schema, handlers and message routing. */
 export interface ChannelMeta {
     name: string;
     route: string;
@@ -57,7 +64,9 @@ export interface ChannelMeta {
     middleware?: MiddlewareMetadata[];
     channelMiddleware?: MiddlewareMetadata[];
 }
+/** Generated metadata for every wired channel, keyed by name. */
 export type ChannelsMeta = Record<string, ChannelMeta>;
+/** The configuration {@link wireChannel} takes. An app's generated `wireChannel` narrows the function, permission and middleware types to its own. */
 export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = CorePikkuFunctionConfig<CorePikkuFunction<void, unknown> | CorePikkuFunctionSessionless<void, unknown>, CorePikkuPermission<void>, CorePikkuMiddleware>, ChannelDisconnect = CorePikkuFunctionConfig<CorePikkuFunction<void, void> | CorePikkuFunctionSessionless<void, void>, CorePikkuPermission<void>, CorePikkuMiddleware>, ChannelFunctionMessage = CorePikkuFunctionConfig<CorePikkuFunction<unknown, unknown> | CorePikkuFunctionSessionless<unknown, unknown>, CorePikkuPermission<unknown>, CorePikkuMiddleware>, 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;
@@ -99,6 +108,13 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
  * own functions. Loose on purpose: core cannot know the names.
  */
 export type ChannelRemote = (funcName: string, data?: any) => Promise<any>;
+/**
+ * The `channel` part of a function's wire when it runs on a channel: the connection's id and opening data, ways to send to and close it, per-connection state, and `remote` to call the peer.
+ *
+ * In serverless runtimes `setState`/`getState` go through the {@link ChannelStore},
+ * so state survives between invocations; elsewhere it lives in memory for the
+ * connection's lifetime.
+ */
 export interface PikkuChannel<OpeningData, out Out, Remote extends (...args: any[]) => any = ChannelRemote> {
     channelId: string;
     openingData: OpeningData;
@@ -116,9 +132,11 @@ export interface PikkuChannel<OpeningData, out Out, Remote extends (...args: any
      */
     remote: Remote;
 }
+/** The runtime side of one connection: how a channel's sends reach the actual socket. */
 export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
     send(message: Out, isBinary?: boolean): Promise<void> | void;
     sendBinary(data: BinaryData): Promise<void> | void;
     getChannel(): PikkuChannel<OpeningData, Out>;
 }
+/** Creates the {@link PikkuChannelHandler} for a connection. Serverless runtimes pass one so the channel can send back through the platform's API. */
 export type PikkuChannelHandlerFactory<OpeningData = unknown, Out = unknown> = (channelId: string, channelName: string, openingData: OpeningData) => PikkuChannelHandler<OpeningData, Out>;

package/dist/wirings/channel/define-channel-routes.d.ts

@@ -1 +1,6 @@
+/**
+ * Declares a set of message handlers for one `onMessageWiring` key, so they can be defined apart from the channel and keep their types. Returns the routes unchanged.
+ *
+ * @example snippet: channelRoutes
+ */
 export declare function defineChannelRoutes<T extends Record<string, any>>(routes: T): T;

package/dist/wirings/channel/define-channel-routes.js

@@ -1,3 +1,8 @@
+/**
+ * Declares a set of message handlers for one `onMessageWiring` key, so they can be defined apart from the channel and keep their types. Returns the routes unchanged.
+ *
+ * @example snippet: channelRoutes
+ */
 export function defineChannelRoutes(routes) {
     return routes;
 }

package/dist/wirings/channel/eventhub-service.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Pub/sub between channels, available as `eventHub` on singleton services.
+ *
+ * Channels `subscribe` to topics, and `publish` sends to every subscriber of a
+ * topic. Passing the publishing channel's id as `channelId` excludes it from
+ * delivery; `null` sends to all.
+ *
+ * @example snippet: channelPubSub
+ */
 export interface EventHubService<Topics extends Record<string, any>> {
     subscribe<T extends keyof Topics>(topic: T, channelId: string): Promise<void> | void;
     unsubscribe<T extends keyof Topics>(topic: T, channelId: string): Promise<void> | void;

package/dist/wirings/channel/eventhub-store.d.ts

@@ -1,3 +1,4 @@
+/** Persists topic subscriptions for serverless runtimes, where the subscribing and publishing invocations do not share memory. */
 export declare abstract class EventHubStore<EventTopics extends Record<string, any> = {}> {
     abstract getChannelIdsForTopic(topic: string): Promise<string[]>;
     abstract subscribe<T extends keyof EventTopics>(topic: T, channelId: string): Promise<boolean>;

package/dist/wirings/channel/eventhub-store.js

@@ -1,2 +1,3 @@
+/** Persists topic subscriptions for serverless runtimes, where the subscribing and publishing invocations do not share memory. */
 export class EventHubStore {
 }

package/dist/wirings/channel/index.d.ts

@@ -1,5 +1,5 @@
 export { wireChannel } from './channel-runner.js';
-export { addChannelMiddleware, combineChannelMiddleware, } from './channel-middleware-runner.js';
+export { addChannelMiddleware, combineChannelMiddleware, } from '../../channel-middleware-runner.js';
 export { logChannels } from './log-channels.js';
 export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js';
 export type { EventHubService } from './eventhub-service.js';

package/dist/wirings/channel/index.js

@@ -1,5 +1,5 @@
 export { wireChannel } from './channel-runner.js';
-export { addChannelMiddleware, combineChannelMiddleware, } from './channel-middleware-runner.js';
+export { addChannelMiddleware, combineChannelMiddleware, } from '../../channel-middleware-runner.js';
 export { logChannels } from './log-channels.js';
 export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js';
 export { ChannelStore } from './channel-store.js';

package/dist/wirings/channel/local/local-channel-handler.d.ts

@@ -1,6 +1,7 @@
 import type { Logger } from '../../../services/logger.js';
 import type { BinaryData } from '../channel.types.js';
 import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js';
+/** The {@link PikkuChannelHandler} for runtimes that hold the socket in-process (Node WebSocket servers, uWS, Bun). The runtime registers callbacks for sending, opening, messages and closing. */
 export declare class PikkuLocalChannelHandler<OpeningData = unknown, Out = unknown> extends PikkuAbstractChannelHandler<OpeningData, Out> {
     private onMessageCallback?;
     private onBinaryMessageCallback?;

package/dist/wirings/channel/local/local-channel-handler.js

@@ -1,4 +1,5 @@
 import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js';
+/** The {@link PikkuChannelHandler} for runtimes that hold the socket in-process (Node WebSocket servers, uWS, Bun). The runtime registers callbacks for sending, opening, messages and closing. */
 export class PikkuLocalChannelHandler extends PikkuAbstractChannelHandler {
     onMessageCallback;
     onBinaryMessageCallback;

package/dist/wirings/channel/local/local-channel-runner.d.ts

@@ -1,6 +1,19 @@
 import type { CoreChannel, RunChannelOptions } from '../channel.types.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
 import type { PikkuHTTPRequest, PikkuHTTPResponse } from '../../http/http.types.js';
+/**
+ * Opens a channel connection in-process and returns the handler the runtime drives the socket through.
+ *
+ * For an HTTP upgrade, the HTTP middleware registered for `'*'` and the
+ * channel's upgrade middleware run first, then the opening data is validated.
+ * Lookup and validation failures are written to `response` as an HTTP error
+ * rather than thrown, and resolve `undefined`.
+ *
+ * @param params.channelId - A unique id for the connection.
+ * @param params.request - The upgrade request; its path selects the channel.
+ * @param params.route - The path to match when there is no request.
+ * @returns The handler, or `undefined` when the channel could not be opened.
+ */
 export declare const runLocalChannel: ({ channelId, request, response, route, skipUserSession, respondWith404, coerceDataFromSchema, logWarningsForStatusCodes, bubbleErrors, }: Partial<Pick<CoreChannel<unknown, any>, 'route'>> & RunChannelOptions & {
     channelId: string;
     request?: PikkuHTTPRequest;

package/dist/wirings/channel/local/local-channel-runner.js

@@ -27,6 +27,19 @@ const runUpgradeMiddleware = async (singletonServices, request, response, userSe
     }
     return http;
 };
+/**
+ * Opens a channel connection in-process and returns the handler the runtime drives the socket through.
+ *
+ * For an HTTP upgrade, the HTTP middleware registered for `'*'` and the
+ * channel's upgrade middleware run first, then the opening data is validated.
+ * Lookup and validation failures are written to `response` as an HTTP error
+ * rather than thrown, and resolve `undefined`.
+ *
+ * @param params.channelId - A unique id for the connection.
+ * @param params.request - The upgrade request; its path selects the channel.
+ * @param params.route - The path to match when there is no request.
+ * @returns The handler, or `undefined` when the channel could not be opened.
+ */
 export const runLocalChannel = async ({ channelId, request, response, route, skipUserSession = false, respondWith404 = true, coerceDataFromSchema = true, logWarningsForStatusCodes = [], bubbleErrors = false, }) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();

package/dist/wirings/channel/local/local-eventhub-service.d.ts

@@ -1,5 +1,6 @@
 import type { PikkuChannelHandler } from '../channel.types.js';
 import type { EventHubService } from '../eventhub-service.js';
+/** An {@link EventHubService} that keeps subscriptions in memory, for a single process. A channel that fails to receive is dropped from all its topics. */
 export declare class LocalEventHubService<Data extends Record<string, any> = {}> implements EventHubService<Data> {
     private channels;
     private subscriptions;

package/dist/wirings/channel/local/local-eventhub-service.js

@@ -1,3 +1,4 @@
+/** An {@link EventHubService} that keeps subscriptions in memory, for a single process. A channel that fails to receive is dropped from all its topics. */
 export class LocalEventHubService {
     channels = new Map();
     subscriptions = new Map();

package/dist/wirings/channel/log-channels.d.ts

@@ -1,2 +1,3 @@
 import type { Logger } from '../../services/index.js';
+/** Logs every wired channel and its route at info level, typically once at startup. */
 export declare const logChannels: (logger: Logger) => void;

package/dist/wirings/channel/log-channels.js

@@ -1,4 +1,5 @@
 import { pikkuState } from '../../pikku-state.js';
+/** Logs every wired channel and its route at info level, typically once at startup. */
 export const logChannels = (logger) => {
     const channels = pikkuState(null, 'channel', 'channels');
     if (channels.size === 0) {

package/dist/wirings/channel/pikku-abstract-channel-handler.d.ts

@@ -1,4 +1,9 @@
 import type { BinaryData, PikkuChannel, PikkuChannelHandler } from './channel.types.js';
+/**
+ * Base class for a runtime's {@link PikkuChannelHandler}. A runtime implements `send` and `sendBinary`; this builds the {@link PikkuChannel} on top, with in-memory state and `remote`.
+ *
+ * Closing the channel fails any `remote` calls still waiting on the peer.
+ */
 export declare abstract class PikkuAbstractChannelHandler<OpeningData = unknown, Out = unknown> implements PikkuChannelHandler<OpeningData, Out> {
     channelId: string;
     channelName: string;

package/dist/wirings/channel/pikku-abstract-channel-handler.js

@@ -1,4 +1,9 @@
 import { channelRemote, releaseChannelHostRPC } from './channel-host-rpc.js';
+/**
+ * Base class for a runtime's {@link PikkuChannelHandler}. A runtime implements `send` and `sendBinary`; this builds the {@link PikkuChannel} on top, with in-memory state and `remote`.
+ *
+ * Closing the channel fails any `remote` calls still waiting on the peer.
+ */
 export class PikkuAbstractChannelHandler {
     channelId;
     channelName;

package/dist/wirings/channel/serverless/serverless-channel-runner.d.ts

@@ -1,10 +1,42 @@
 import type { CoreChannel, RunChannelOptions, RunChannelParams, PikkuChannelHandlerFactory } from '../channel.types.js';
 import type { ChannelStore } from '../channel-store.js';
+/** Parameters for the serverless channel runners: the connection, the {@link ChannelStore} that persists it, and the factory that builds a handler able to send through the platform. */
 export interface RunServerlessChannelParams<ChannelData> extends RunChannelParams<ChannelData> {
     channelStore: ChannelStore;
     channelHandlerFactory: PikkuChannelHandlerFactory;
     channelObject?: unknown;
 }
+/**
+ * Handles a serverless connect event: opens the channel, stores it, and runs `onConnect`.
+ *
+ * The opening data is validated against the channel's input schema. If
+ * `onConnect` (or its middleware) established a session, its `pikkuUserId` is
+ * stored with the channel, and later messages and the disconnect reload the
+ * session from `sessionStore` by that id. On success the response status is 101.
+ *
+ * Errors from `onConnect` are written to `response` as an HTTP error unless
+ * `bubbleErrors` is set.
+ *
+ * @throws {NotFoundError} When no channel is wired at `route`.
+ * @throws When the opening data fails validation.
+ */
 export declare const runChannelConnect: ({ channelId, channelObject, request, response, route, channelStore, channelHandlerFactory, coerceDataFromSchema, logWarningsForStatusCodes, respondWith404, bubbleErrors, }: Pick<CoreChannel<unknown, any>, 'route'> & RunChannelOptions & RunServerlessChannelParams<unknown>) => Promise<void>;
+/**
+ * Handles a serverless disconnect event: runs `onDisconnect` with the stored session, then removes the channel from the store.
+ *
+ * A channel already missing from the store is logged and ignored, and an error
+ * from `onDisconnect` is logged rather than thrown, so the channel is always
+ * removed.
+ */
 export declare const runChannelDisconnect: ({ channelId, channelStore, channelHandlerFactory, }: RunServerlessChannelParams<unknown>) => Promise<void>;
+/**
+ * Handles one message on a serverless channel, with the session reloaded from `sessionStore` by the `pikkuUserId` stored on connect.
+ *
+ * @param params - The connection and its store.
+ * @param data - The message as received.
+ * @returns The handler's reply. When the handler throws, the error is logged and
+ *   `{ error, errorName }` is returned with the error's message, so the runtime
+ *   can send it to the client. Throw errors whose messages are safe to show.
+ * @throws Whatever the store throws for a channel it does not hold.
+ */
 export declare const runChannelMessage: ({ channelId, channelStore, channelHandlerFactory, }: RunServerlessChannelParams<unknown>, data: unknown) => Promise<unknown>;

package/dist/wirings/channel/serverless/serverless-channel-runner.js

@@ -26,6 +26,20 @@ const getVariablesForChannel = ({ channelId, channelName, channelHandlerFactory,
         meta,
     };
 };
+/**
+ * Handles a serverless connect event: opens the channel, stores it, and runs `onConnect`.
+ *
+ * The opening data is validated against the channel's input schema. If
+ * `onConnect` (or its middleware) established a session, its `pikkuUserId` is
+ * stored with the channel, and later messages and the disconnect reload the
+ * session from `sessionStore` by that id. On success the response status is 101.
+ *
+ * Errors from `onConnect` are written to `response` as an HTTP error unless
+ * `bubbleErrors` is set.
+ *
+ * @throws {NotFoundError} When no channel is wired at `route`.
+ * @throws When the opening data fails validation.
+ */
 export const runChannelConnect = async ({ channelId, channelObject, request, response, route, channelStore, channelHandlerFactory, coerceDataFromSchema = true, logWarningsForStatusCodes = [], respondWith404 = true, bubbleErrors = false, }) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
@@ -98,6 +112,13 @@ export const runChannelConnect = async ({ channelId, channelObject, request, res
         }
     }
 };
+/**
+ * Handles a serverless disconnect event: runs `onDisconnect` with the stored session, then removes the channel from the store.
+ *
+ * A channel already missing from the store is logged and ignored, and an error
+ * from `onDisconnect` is logged rather than thrown, so the channel is always
+ * removed.
+ */
 export const runChannelDisconnect = async ({ channelId, channelStore, channelHandlerFactory, }) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
@@ -163,6 +184,16 @@ export const runChannelDisconnect = async ({ channelId, channelStore, channelHan
         await closeWireServices(singletonServices.logger, wireServices);
     }
 };
+/**
+ * Handles one message on a serverless channel, with the session reloaded from `sessionStore` by the `pikkuUserId` stored on connect.
+ *
+ * @param params - The connection and its store.
+ * @param data - The message as received.
+ * @returns The handler's reply. When the handler throws, the error is logged and
+ *   `{ error, errorName }` is returned with the error's message, so the runtime
+ *   can send it to the client. Throw errors whose messages are safe to show.
+ * @throws Whatever the store throws for a channel it does not hold.
+ */
 export const runChannelMessage = async ({ channelId, channelStore, channelHandlerFactory, }, data) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();

package/dist/wirings/cli/channel/cli-channel-runner.d.ts

@@ -1,4 +1,12 @@
 import type { CorePikkuCLIRender } from '../cli.types.js';
+/**
+ * Runs a CLI program whose commands execute on a server, sending each parsed command over a pikku WebSocket and rendering the result locally.
+ *
+ * Parsing and help happen on the client. Exits the process with status 1 when
+ * the program does not exist or the arguments do not parse; resolves when the
+ * server reports the command complete or the socket closes, and rejects on a
+ * socket or renderer error.
+ */
 export declare function executeCLIViaChannel({ programName, pikkuWS, args, renderers, defaultRenderer, }: {
     programName: string;
     pikkuWS: any;

package/dist/wirings/cli/channel/cli-channel-runner.js

@@ -4,6 +4,14 @@ import { generateCommandHelp, parseCLIArguments } from '../command-parser.js';
 const defaultJSONRenderer = (_services, data) => {
     console.log(JSON.stringify(data));
 };
+/**
+ * Runs a CLI program whose commands execute on a server, sending each parsed command over a pikku WebSocket and rendering the result locally.
+ *
+ * Parsing and help happen on the client. Exits the process with status 1 when
+ * the program does not exist or the arguments do not parse; resolves when the
+ * server reports the command complete or the socket closes, and rejects on a
+ * socket or renderer error.
+ */
 export async function executeCLIViaChannel({ programName, pikkuWS, args = process.argv.slice(2), renderers = {}, defaultRenderer, }) {
     const cliMeta = pikkuState(null, 'cli', 'meta');
     if (!cliMeta || !('programs' in cliMeta)) {

package/dist/wirings/cli/channel/cli-raw-channel-runner.d.ts

@@ -24,6 +24,7 @@ export type RawCLIFrame = {
     event: 'complete';
     exitCode: number;
 };
+/** What the server produces for one raw CLI invocation: help text, a result, or an error, plus the exit code the client should exit with. */
 export interface RawCLIResult {
     help?: string;
     result?: unknown;

package/dist/wirings/cli/cli-runner.d.ts

@@ -8,7 +8,32 @@ export declare class CLIError extends Error {
     exitCode: number;
     constructor(message: string, exitCode?: number);
 }
+/**
+ * Wires a command-line program: its commands, nested subcommands, options, renderers and middleware.
+ *
+ * Each command runs a pikku function with its positionals and options as input.
+ * The result is printed by the command's renderer, the program's `render`, or
+ * as JSON (also forced by `--json`). Run the program locally with
+ * {@link executeCLI}, or remotely over a channel.
+ *
+ * Registration needs the metadata `pikku` generates for the program. When none
+ * is found the wiring is skipped with a warning rather than throwing.
+ *
+ * @param cli - The program name, its commands, global options, renderer and middleware.
+ *
+ * @example snippet: wireCli
+ */
 export declare const wireCLI: <Commands extends Record<string, CoreCLICommandConfig<any, any, any>>, GlobalOptions, PikkuMiddleware extends CorePikkuMiddleware, GlobalOutput>(cli: CoreCLI<Commands, GlobalOptions, PikkuMiddleware, GlobalOutput>) => void;
+/**
+ * Runs one already-parsed CLI command. {@link executeCLI} calls this locally; the CLI channel runners call it for remote clients.
+ *
+ * Program middleware runs first, then the middleware of each command along the
+ * path. A local run has no session; over a channel, pass the session the
+ * connection authenticated as.
+ *
+ * @returns The command's result. It is also rendered, unless `onOutput` is set.
+ * @throws {NotFoundError} When the program or command path does not exist.
+ */
 export declare function runCLICommand({ program, commandPath, data, singletonServices, createWireServices, onOutput, session, transport, }: {
     program: string;
     commandPath: string[];
@@ -33,7 +58,25 @@ export declare function runCLICommand({ program, commandPath, data, singletonSer
      */
     transport?: PikkuChannel<unknown, any, any>;
 }): Promise<any>;
+/**
+ * Declares a renderer that prints a CLI command's result, typed against the command's output. Returns the renderer unchanged.
+ *
+ * Write to stdout only what the user should see; stdout is reserved for the
+ * command's output.
+ *
+ * @example snippet: cliRenderer
+ */
 export declare const pikkuCLIRender: <Data, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession>(renderer: (services: Services, data: Data, session?: Session) => void | Promise<void>) => CorePikkuCLIRender<Data, Services, Session>;
+/**
+ * Runs a wired CLI program in this process: parses `args`, prints help when asked, builds config and singleton services, and runs the command.
+ *
+ * Config and services are created only after parsing succeeds, so `--help` and
+ * argument errors never touch the project. Parse warnings go to stderr.
+ *
+ * @param params.programName - The program passed to {@link wireCLI}.
+ * @param params.args - The arguments after the program name, usually `process.argv.slice(2)`.
+ * @throws {CLIError} On an unknown program or command, invalid arguments, or a failed command. The caller should exit with its `exitCode`.
+ */
 export declare function executeCLI({ programName, args, createConfig, createSingletonServices, createWireServices, }: {
     programName: string;
     args?: string[];

package/dist/wirings/cli/cli-runner.js

@@ -19,6 +19,21 @@ export class CLIError extends Error {
 const defaultJSONRenderer = (_services, data) => {
     console.log(JSON.stringify(data));
 };
+/**
+ * Wires a command-line program: its commands, nested subcommands, options, renderers and middleware.
+ *
+ * Each command runs a pikku function with its positionals and options as input.
+ * The result is printed by the command's renderer, the program's `render`, or
+ * as JSON (also forced by `--json`). Run the program locally with
+ * {@link executeCLI}, or remotely over a channel.
+ *
+ * Registration needs the metadata `pikku` generates for the program. When none
+ * is found the wiring is skipped with a warning rather than throwing.
+ *
+ * @param cli - The program name, its commands, global options, renderer and middleware.
+ *
+ * @example snippet: wireCli
+ */
 export const wireCLI = (cli) => {
     const cliMeta = pikkuState(null, 'cli', 'meta') || {};
     if (!cliMeta.programs?.[cli.program]) {
@@ -153,6 +168,16 @@ function pluckCLIData(mergedData, funcName, availableOptions, packageName) {
         return { ...mergedData };
     }
 }
+/**
+ * Runs one already-parsed CLI command. {@link executeCLI} calls this locally; the CLI channel runners call it for remote clients.
+ *
+ * Program middleware runs first, then the middleware of each command along the
+ * path. A local run has no session; over a channel, pass the session the
+ * connection authenticated as.
+ *
+ * @returns The command's result. It is also rendered, unless `onOutput` is set.
+ * @throws {NotFoundError} When the program or command path does not exist.
+ */
 export async function runCLICommand({ program, commandPath, data, singletonServices, createWireServices, onOutput, session, transport, }) {
     const cliMeta = pikkuState(null, 'cli', 'meta');
     const programMeta = cliMeta.programs?.[program];
@@ -273,9 +298,27 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
         await channel.close();
     }
 }
+/**
+ * Declares a renderer that prints a CLI command's result, typed against the command's output. Returns the renderer unchanged.
+ *
+ * Write to stdout only what the user should see; stdout is reserved for the
+ * command's output.
+ *
+ * @example snippet: cliRenderer
+ */
 export const pikkuCLIRender = (renderer) => {
     return renderer;
 };
+/**
+ * Runs a wired CLI program in this process: parses `args`, prints help when asked, builds config and singleton services, and runs the command.
+ *
+ * Config and services are created only after parsing succeeds, so `--help` and
+ * argument errors never touch the project. Parse warnings go to stderr.
+ *
+ * @param params.programName - The program passed to {@link wireCLI}.
+ * @param params.args - The arguments after the program name, usually `process.argv.slice(2)`.
+ * @throws {CLIError} On an unknown program or command, invalid arguments, or a failed command. The caller should exit with its `exitCode`.
+ */
 export async function executeCLI({ programName, args, createConfig, createSingletonServices, createWireServices, }) {
     if (!args) {
         throw new Error('CLI arguments are required, this is to satisfy release diffs');

package/dist/wirings/cli/cli.types.d.ts

@@ -75,6 +75,7 @@ export interface CLICommandMeta {
     subcommands?: Record<string, CLICommandMeta>;
     middleware?: MiddlewareMetadata[];
     isDefault?: boolean;
+    hidden?: boolean;
 }
 /**
  * CLI metadata collection (per program)
@@ -209,6 +210,8 @@ export type CoreCLICommandConfig<FuncConfig, PikkuMiddleware extends CorePikkuMi
     permissions?: any[];
     /** Runs when the parent is invoked with no subcommand named. */
     isDefault?: boolean;
+    /** Still runs, but is left out of `--help`: for commands a program invokes, not a person. */
+    hidden?: boolean;
 };
 /**
  * CLI command definition
@@ -227,6 +230,7 @@ export interface CoreCLICommand<In, Out, PikkuFunctionConfig extends CorePikkuFu
     tags?: string[];
     subcommands?: Subcommands;
     isDefault?: boolean;
+    hidden?: boolean;
 }
 /**
  * Shorthand command definition (just a function)

package/dist/wirings/cli/command-parser.d.ts

@@ -1,4 +1,5 @@
 import type { CLIMeta } from './cli.types.js';
+/** The result of {@link parseCLIArguments}: which command was named, its positionals and options, and any errors that stop it running. */
 export interface ParsedCommand {
     program: string;
     commandPath: string[];
@@ -8,5 +9,17 @@ export interface ParsedCommand {
     /** Non-fatal: the command still runs. */
     warnings: string[];
 }
+/**
+ * Parses argv against a program's generated CLI metadata.
+ *
+ * Never throws on bad input: unknown commands and invalid values are returned in
+ * `errors`, unknown options in `warnings`. Safe to run on argv from a remote
+ * client, since the work done is bounded by the input's length.
+ *
+ * @param args - The arguments after the program name.
+ * @param programName - The program to parse for.
+ * @param allMeta - Generated CLI metadata.
+ */
 export declare function parseCLIArguments(args: string[], programName: string, allMeta: CLIMeta): ParsedCommand;
+/** Builds the help text for a program, or for the command at `commandPath`, from its generated metadata. */
 export declare function generateCommandHelp(programName: string, allMeta: CLIMeta, commandPath?: string[]): string;

package/dist/wirings/cli/command-parser.js

@@ -166,6 +166,17 @@ function assignOptionValue(optionArgs, key, value) {
         optionArgs[key] = value;
     }
 }
+/**
+ * Parses argv against a program's generated CLI metadata.
+ *
+ * Never throws on bad input: unknown commands and invalid values are returned in
+ * `errors`, unknown options in `warnings`. Safe to run on argv from a remote
+ * client, since the work done is bounded by the input's length.
+ *
+ * @param args - The arguments after the program name.
+ * @param programName - The program to parse for.
+ * @param allMeta - Generated CLI metadata.
+ */
 export function parseCLIArguments(args, programName, allMeta) {
     const result = {
         program: programName,
@@ -471,6 +482,7 @@ function applyOptionDefaults(optionDefs, options, result) {
         }
     }
 }
+/** Builds the help text for a program, or for the command at `commandPath`, from its generated metadata. */
 export function generateCommandHelp(programName, allMeta, commandPath = []) {
     const lines = [];
     const meta = allMeta.programs[programName];
@@ -482,6 +494,8 @@ export function generateCommandHelp(programName, allMeta, commandPath = []) {
         lines.push('');
         lines.push('Commands:');
         for (const [name, cmd] of Object.entries(meta.commands)) {
+            if (cmd.hidden)
+                continue;
             const desc = cmd.description || '';
             const defaultMarker = cmd.isDefault ? ' (default)' : '';
             lines.push(`  ${name.padEnd(20)} ${desc}${defaultMarker}`);
@@ -520,6 +534,8 @@ export function generateCommandHelp(programName, allMeta, commandPath = []) {
             lines.push('');
             lines.push('Subcommands:');
             for (const [name, sub] of Object.entries(commandMeta.subcommands)) {
+                if (sub.hidden)
+                    continue;
                 const desc = sub.description || '';
                 lines.push(`  ${name.padEnd(20)} ${desc}`);
             }

package/dist/wirings/credential/credential-overrides.d.ts

@@ -11,6 +11,7 @@ export type CredentialOverride = string | {
     /** `wire` is per user, `singleton` is one value for the deployment. */
     mode?: 'singleton' | 'wire';
 };
+/** Per-credential overrides for a wired package, keyed by the name the package declared. */
 export type CredentialOverrides = Record<string, CredentialOverride>;
 /** The rename half, in the `Record<string, string>` shape the alias path wants. */
 export declare const credentialOverrideAliases: (overrides: CredentialOverrides | undefined) => Record<string, string>;

package/dist/wirings/credential/credential.types.d.ts

@@ -1,4 +1,9 @@
 import type { OAuth2CredentialConfig } from '../secret/secret.types.js';
+/**
+ * The declaration {@link defineCredential} takes: a credential a user or the
+ * deployment has to supply, such as an API key or an OAuth connection. Values are
+ * stored by the `CredentialService`, never in code or generated meta.
+ */
 export type CoreCredential<T = unknown> = {
     /** How the credential is asked for in code. Generated into `CredentialsMap`, so it is what `credentials.get` autocompletes. */
     name: string;
@@ -29,5 +34,7 @@ export type CredentialDefinitionMeta = {
     };
     sourceFile?: string;
 };
+/** Credential declarations collected by the CLI, keyed by name. */
 export type CredentialDefinitionsMeta = Record<string, CredentialDefinitionMeta>;
+/** Credential declarations as the inspector found them, before de-duplication. */
 export type CredentialDefinitions = CredentialDefinitionMeta[];

package/dist/wirings/credential/validate-credential-definitions.d.ts

@@ -1,4 +1,11 @@
 import type { CredentialDefinitions, CredentialDefinitionsMeta } from './credential.types.js';
 import type { SchemaRefLike } from '../../types/core.types.js';
 export type { SchemaRefLike };
+/**
+ * Merges the credential declarations the inspector found into meta keyed by name.
+ * A name declared more than once must agree on type and schema.
+ *
+ * @throws Error when two declarations of one name disagree on `type` or schema.
+ * @internal Called by the CLI when generating meta.
+ */
 export declare function validateAndBuildCredentialDefinitionsMeta(definitions: CredentialDefinitions, schemaLookup: Map<string, SchemaRefLike>): CredentialDefinitionsMeta;