@pikku/cli 0.12.115 → 0.12.116

package/dist/src/functions/surface/render-surface-doc.js

@@ -0,0 +1,209 @@
+export class UnknownSurfaceTargetError extends Error {
+    target;
+    suggestions;
+    constructor(target, suggestions) {
+        super(suggestions.length > 0
+            ? `No door or export called '${target}'. Did you mean: ${suggestions.join(', ')}?`
+            : `No door or export called '${target}'. Run 'pikku doc' for the index.`);
+        this.target = target;
+        this.suggestions = suggestions;
+    }
+}
+const STEPS = [
+    'create a function',
+    'enhance it',
+    'wire it up',
+    'guard it',
+    'orchestrate it',
+    'test it',
+];
+const wrap = (text, width, indent) => text
+    .replace(/\s+/g, ' ')
+    .trim()
+    .split(' ')
+    .reduce((lines, word) => {
+    const last = lines[lines.length - 1];
+    if (last !== undefined && `${last} ${word}`.length <= width) {
+        lines[lines.length - 1] = `${last} ${word}`;
+    }
+    else {
+        lines.push(word);
+    }
+    return lines;
+}, [])
+    .map((line) => indent + line)
+    .join('\n');
+const columns = (values, perRow, width) => {
+    const rows = [];
+    for (let i = 0; i < values.length; i += perRow) {
+        rows.push('    ' +
+            values
+                .slice(i, i + perRow)
+                .map((value) => value.length >= width ? `${value}  ` : value.padEnd(width))
+                .join('')
+                .trimEnd());
+    }
+    return rows;
+};
+const appEntryPoint = (doc, id) => {
+    const entryPoint = doc.entryPoints.find((candidate) => candidate.id === id);
+    if (!entryPoint) {
+        throw new Error(`The surface doc has no '${id}' entry point.`);
+    }
+    return entryPoint;
+};
+const renderIndex = (doc, leaves, ai) => {
+    const total = leaves.reduce((count, leaf) => count + leaf.symbols.length, 0);
+    const lines = [
+        `pikku ${doc.version} — application surface, ${leaves.length} doors / ${total} exports`,
+        '',
+    ];
+    for (const step of STEPS) {
+        const names = leaves
+            .filter((leaf) => leaf.step === step)
+            .map((leaf) => leaf.name);
+        if (names.length > 0) {
+            lines.push(`  ${step.padEnd(20)}${names.join('  ')}`);
+        }
+    }
+    const fn = leaves.find((leaf) => leaf.name === 'function');
+    if (fn) {
+        lines.push('', `  ${fn.specifier} — every wiring eventually points at one of these`);
+        lines.push(...columns(fn.symbols.map((symbol) => symbol.name), 4, 26));
+    }
+    if (ai) {
+        const taught = leaves.filter((leaf) => leaf.skill);
+        const bare = leaves.filter((leaf) => !leaf.skill).map((leaf) => leaf.name);
+        lines.push('', '  what is above is what exists; these skills say how to use it');
+        lines.push(...columns(taught.map((leaf) => `${leaf.name} → ${[leaf.skill].flat().join(' + ')}`), 2, 38));
+        if (bare.length > 0) {
+            lines.push(wrap(`No skill teaches ${bare.join(', ')} — for those, this doc is the whole of it.`, 78, '  '));
+        }
+    }
+    lines.push('', '  pikku doc <door>      one door: what it exports and the keys you write', '  pikku doc <export>    one export: its signature, its keys, what it references', '  pikku doc a b c       several at once, in one call');
+    if (!ai) {
+        lines.push('  pikku doc --ai        the same, plus the skill to load for each door');
+    }
+    return lines.join('\n');
+};
+const renderSymbolRow = (symbol) => {
+    const lines = [
+        `  ${symbol.name}${symbol.deprecated ? '  [deprecated]' : ''}  (${symbol.kind})`,
+    ];
+    if (symbol.summary) {
+        lines.push(wrap(symbol.summary, 74, '      '));
+    }
+    const keys = symbol.members?.length ?? 0;
+    const more = keys > 0 || (symbol.examples?.length ?? 0) > 0;
+    const signature = symbol.signature?.replace(/\s+/g, ' ');
+    if (more) {
+        lines.push(`      ${keys > 0 ? `${keys} keys` : 'example'} — pikku doc ${symbol.name}`);
+    }
+    else if (signature && signature.length <= 96) {
+        lines.push(`      ${signature}`);
+    }
+    else if (signature) {
+        lines.push(`      pikku doc ${symbol.name}`);
+    }
+    lines.push('');
+    return lines;
+};
+const renderLeaf = (leaf, ai) => {
+    const lines = [`${leaf.specifier} — ${leaf.step}`, '', wrap(leaf.summary, 78, '  '), ''];
+    const statuses = leaf.symbols.filter((symbol) => symbol.status !== undefined);
+    for (const symbol of leaf.symbols.filter((symbol) => symbol.status === undefined)) {
+        lines.push(...renderSymbolRow(symbol));
+    }
+    if (statuses.length > 0) {
+        lines.push(`  ${statuses.length} error classes, each thrown to produce its HTTP status:`);
+        lines.push(...columns(statuses.map((symbol) => `${symbol.name} ${symbol.status}`), 3, 38));
+        lines.push('');
+    }
+    if (ai) {
+        lines.push(leaf.skill
+            ? `  Load the ${[leaf.skill].flat().join(' and ')} skill before writing this if you need how rather than what.`
+            : '  No skill teaches this door — what is above is the whole of it.');
+    }
+    return lines.join('\n');
+};
+const referencesOf = (symbol, home) => {
+    const blob = [
+        symbol.signature ?? '',
+        ...(symbol.members ?? []).map((member) => member.line),
+    ].join(' ');
+    return [...new Set(blob.match(/\b[A-Z][A-Za-z0-9]+\b/g) ?? [])].filter((name) => home.has(name) && name !== symbol.name);
+};
+const renderSymbol = (symbol, leaf, home, ai) => {
+    const lines = [`${symbol.name} — ${symbol.kind}, from ${leaf.specifier}`, ''];
+    if (symbol.deprecated) {
+        lines.push(`  DEPRECATED: ${symbol.deprecated}`, '');
+    }
+    if (symbol.docs) {
+        lines.push(wrap(symbol.docs, 78, '  '), '');
+    }
+    if (symbol.status !== undefined) {
+        lines.push(`  HTTP status ${symbol.status}`, '');
+    }
+    if (symbol.signature) {
+        lines.push('  ' + symbol.signature.replace(/\s+/g, ' '), '');
+    }
+    if (symbol.members?.length) {
+        lines.push('  keys you write');
+        for (const member of symbol.members) {
+            lines.push(`    ${member.line}`);
+            if (member.doc) {
+                lines.push(wrap(member.doc, 72, '        '));
+            }
+        }
+        lines.push('');
+    }
+    for (const example of symbol.examples ?? []) {
+        lines.push('  example');
+        lines.push(...example.split('\n').map((line) => '    ' + line));
+        lines.push('');
+    }
+    const references = referencesOf(symbol, home);
+    if (references.length > 0) {
+        lines.push('  references  ' +
+            references.map((name) => `${name} (${home.get(name)})`).join('  '));
+    }
+    if (ai && leaf.skill) {
+        lines.push('', `  Load the ${[leaf.skill].flat().join(' and ')} skill before writing this if you need how rather than what.`);
+    }
+    return lines.join('\n').trimEnd();
+};
+const near = (target, candidates) => {
+    const needle = target.toLowerCase();
+    return candidates
+        .filter((candidate) => candidate.toLowerCase().includes(needle))
+        .slice(0, 5);
+};
+export const renderSurfaceDoc = (doc, { target, ai = false, entryPoint = 'app' } = {}) => {
+    const leaves = appEntryPoint(doc, entryPoint).leaves;
+    if (!target) {
+        return renderIndex(doc, leaves, ai);
+    }
+    const leaf = leaves.find((candidate) => candidate.name === target || candidate.specifier === target);
+    if (leaf) {
+        return renderLeaf(leaf, ai);
+    }
+    const home = new Map();
+    for (const candidate of leaves) {
+        for (const symbol of candidate.symbols) {
+            if (!home.has(symbol.name)) {
+                home.set(symbol.name, candidate.specifier);
+            }
+        }
+    }
+    const owner = leaves.find((candidate) => candidate.symbols.some((symbol) => symbol.name === target));
+    const symbol = owner?.symbols.find((candidate) => candidate.name === target);
+    if (owner && symbol) {
+        return renderSymbol(symbol, owner, home, ai);
+    }
+    const elsewhere = doc.entryPoints.find((candidate) => candidate.id !== entryPoint &&
+        candidate.leaves.some((leaf2) => leaf2.symbols.some((symbol2) => symbol2.name === target)));
+    if (elsewhere) {
+        return renderSurfaceDoc(doc, { target, ai, entryPoint: elsewhere.id });
+    }
+    throw new UnknownSurfaceTargetError(target, near(target, [...leaves.map((candidate) => candidate.name), ...home.keys()]));
+};

package/dist/src/functions/surface/surface-doc.types.d.ts

@@ -1,5 +1,5 @@
-import type { SurfaceKind } from './collect-surface.js';
-export type { SurfaceKind };
+import type { SurfaceKind, SurfaceMember } from './collect-surface.js';
+export type { SurfaceKind, SurfaceMember };
 /**
  * The order in which you meet these doors while building a service. It is the
  * page's spine: the console groups by it and the reading order follows it.
@@ -23,6 +23,14 @@ export type SurfaceDocSymbol = {
     /** The full documentation, for the panel that reads one export. */
     docs?: string;
     deprecated?: string;
+    /** How it is called, printed from the compiler rather than from prose. */
+    signature?: string;
+    /** The keys of the options object it takes, one per line. */
+    members?: SurfaceMember[];
+    /** `@example` blocks, which the summary and docs both leave out. */
+    examples?: string[];
+    /** For an error class, the HTTP status it was registered with. */
+    status?: number;
 };
 export type SurfaceLeaf = {
     /** The specifier you import from, e.g. `#pikku/http`. */
@@ -30,6 +38,11 @@ export type SurfaceLeaf = {
     name: string;
     step: SurfaceStep;
     summary: string;
+    /**
+     * The skill to load for how rather than what, or `null` where this page is
+     * the whole story. Never absent: a leaf must answer the question.
+     */
+    skill: string | string[] | null;
     symbols: SurfaceDocSymbol[];
 };
 export type SurfaceEntryPointId = 'app' | 'addon';

package/dist/src/functions/surface/surface-editorial.d.ts

@@ -11,6 +11,12 @@ import type { SurfaceEntryPointId, SurfaceStep } from './surface-doc.types.js';
 export type LeafEditorial = {
     step: SurfaceStep;
     summary: string;
+    /**
+     * The skill that teaches this door, or `null` where the generated page says
+     * everything there is. Required so that adding a leaf forces the question
+     * rather than quietly shipping a door nothing teaches.
+     */
+    skill: string | string[] | null;
 };
 export type EntryPointEditorial = {
     job: string;

package/dist/src/functions/surface/surface-editorial.js

@@ -6,86 +6,107 @@
 export const LEAF_EDITORIAL = {
     setup: {
         step: 'create a function',
+        skill: 'pikku-services',
         summary: 'The three factories a project declares exactly once — its config, its singleton services and its per-wire services. An addon declares the same three in its own flavour, handed the logger, variables and secrets the host application already built. Everything else on this page is imported by features; these are imported by bootstrap and then left alone.',
     },
     function: {
         step: 'create a function',
-        summary: 'The function definers every wiring eventually points at, and the types they are written against.',
+        skill: 'pikku-concepts',
+        summary: 'The function definers every wiring eventually points at, and the types they are written against. A function is handed services, then its input, then the wire — and the wire is where the request lives: `session`, `setSession`, `clearSession`, `http`, `channel`, `rpc`. None of those are exports, so they are not listed here; destructure them from the third argument.',
     },
     middleware: {
         step: 'enhance it',
+        skill: 'pikku-middleware',
         summary: 'Middleware is one concept regardless of what it ends up attached to, so it is one import: define it here, then register it globally, against a tag, or against an HTTP route or channel.',
     },
     error: {
         step: 'enhance it',
+        skill: null,
         summary: 'The errors your functions throw and the HTTP status each one maps to, so a thrown error is part of the contract rather than a stack trace.',
     },
     variables: {
         step: 'enhance it',
+        skill: 'pikku-config',
         summary: 'Configuration a function reads through the variables service, declared once so a deployment can be checked for what it is missing.',
     },
     secrets: {
         step: 'enhance it',
+        skill: 'pikku-config',
         summary: 'Secrets a function can use without ever holding, declared here and resolved by the secrets service at runtime.',
     },
     credentials: {
         step: 'enhance it',
+        skill: null,
         summary: 'Third-party credentials — OAuth2 grants and API keys — declared so the runtime can acquire, refresh and inject them.',
     },
     addon: {
         step: 'enhance it',
+        skill: 'pikku-addon',
         summary: 'Installs an addon into this application, on its own or over rpc against a remote one.',
     },
     http: {
         step: 'wire it up',
+        skill: 'pikku-http',
         summary: 'Wires a function to an HTTP route, with the path parameters checked against the function input.',
     },
     channel: {
         step: 'wire it up',
+        skill: 'pikku-websocket',
         summary: 'Wires a function to a websocket channel, its message routes and its pub/sub topics.',
     },
     queue: {
         step: 'wire it up',
+        skill: 'pikku-queue',
         summary: 'Wires a function as a queue worker, so a job on the queue runs the same handler an HTTP route would.',
     },
     scheduler: {
         step: 'wire it up',
+        skill: 'pikku-schedule',
         summary: 'Wires a function to a cron expression to run it on a schedule.',
     },
     trigger: {
         step: 'wire it up',
+        skill: 'pikku-trigger',
         summary: 'Wires a function to an event a source emits, rather than to a caller that asks for it.',
     },
     gateway: {
         step: 'wire it up',
+        skill: 'pikku-gateway-slack',
         summary: 'Wires a function behind a gateway that receives requests on behalf of another system.',
     },
     mcp: {
         step: 'wire it up',
+        skill: 'pikku-mcp',
         summary: 'Wires a function as an MCP tool, resource or prompt for a model to call.',
     },
     cli: {
         step: 'wire it up',
+        skill: 'pikku-cli',
         summary: 'Wires a function as a command, with its flags and arguments derived from the function input.',
     },
     auth: {
         step: 'guard it',
+        skill: ['pikku-security', 'pikku-permissions'],
         summary: 'Who may call a function, and what the call is made with: permissions that see the request, auth gates that run before it, and the credentials a function borrows rather than holds.',
     },
     scopes: {
         step: 'guard it',
+        skill: 'pikku-permissions',
         summary: 'The scopes a caller can hold and the roles that grant them, gating a call outside the permission pool.',
     },
     workflow: {
         step: 'orchestrate it',
+        skill: 'pikku-workflow',
         summary: 'Composes functions into a durable workflow whose steps survive a restart and retry on their own.',
     },
     agent: {
         step: 'orchestrate it',
+        skill: 'pikku-agent',
         summary: 'Defines an AI agent, the tools it may call and the scorers that judge what it did.',
     },
     scenarios: {
         step: 'test it',
+        skill: 'pikku-scenario',
         summary: 'Drives features and scenarios against a real running server, in the vocabulary a user would use.',
     },
 };

package/dist/src/functions/wirings/agent/serialize-agent-types.js

@@ -31,6 +31,12 @@ type AgentConfig<
   workflows?: object[]
 }
 
+/**
+ * Declares an agent: the model, the prompt, the tools it may call and the shape
+ * of what it returns. Wire it like any other function.
+ *
+ * @example snippet: aiAgent
+ */
 export const pikkuAgent = <
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
@@ -40,16 +46,34 @@ export const pikkuAgent = <
   return agent
 }
 
+/**
+ * Declares a scorer that grades an agent run programmatically — a function over
+ * the run's input and output returning a score.
+ *
+ * @example snippet: agentScorer
+ */
 export const pikkuAgentScorer = (
   config: Parameters<typeof corePikkuAgentScorer<Services>>[0]
 ) => corePikkuAgentScorer<Services>(config)
 
+/**
+ * Declares a scorer that grades an agent run with another model, for the
+ * qualities a programmatic check cannot express.
+ *
+ * @example snippet: agentJudge
+ */
 export const pikkuAgentJudge = (
   config: Parameters<typeof corePikkuAgentJudge<Services>>[0]
 ) => corePikkuAgentJudge<Services>(config)
 
 
 
+/**
+ * A ready-made function that runs the named agent once and returns its result —
+ * wire it straight to a route when you need no logic around the run.
+ *
+ * @example snippet: aiAgentInvoke
+ */
 export const agent = <Name extends keyof AgentMap>(
   agentName: Name
 ) => {
@@ -60,6 +84,12 @@ export const agent = <Name extends keyof AgentMap>(
   >
 }
 
+/**
+ * The streaming counterpart of \`agent\`: wire it to a channel to send tokens and
+ * tool calls as they happen instead of waiting for the run to finish.
+ *
+ * @example snippet: aiAgentStream
+ */
 export const agentStream = <Name extends keyof AgentMap>(
   agentName?: Name
 ) => {
@@ -70,6 +100,12 @@ export const agentStream = <Name extends keyof AgentMap>(
   >
 }
 
+/**
+ * A ready-made function that answers one pending tool approval, letting a run
+ * that paused for a human carry on.
+ *
+ * @example snippet: agentApproval
+ */
 export const agentResume = () => {
   return coreAgentResume() as PikkuFunctionConfig<
     { runId: string; toolCallId: string; approved: boolean },
@@ -78,6 +114,11 @@ export const agentResume = () => {
   >
 }
 
+/**
+ * A ready-made function that answers every pending approval for a run at once.
+ *
+ * @example snippet: agentApproval
+ */
 export const agentApprove = <Name extends keyof AgentMap>(
   agentName: Name
 ) => {

package/dist/src/functions/wirings/agent/serialize-public-agent.js

@@ -144,7 +144,7 @@ export const getAgentThreads = pikkuSessionlessFunc({
   description:
     'Returns the caller\\'s AI agent threads from storage. Accepts optional filters: agentName, resourceId, limit, and offset for pagination.',
   expose: true,
-  auth: false,
+  auth: true,
   func: async ({ agentRunService }, input, { session }) => {
     // \`owners\` is an authorization constraint derived from the session, never
     // from input — \`resourceId\` remains a caller-supplied filter within it.

package/dist/src/functions/wirings/auth/serialize-auth-guards.js

@@ -69,24 +69,7 @@ type PikkuPermissionConfig<In = unknown, RequiredServices extends SecretlessServ
  * Factory function for creating permissions with tree-shaking support.
  * Supports both direct function and configuration object syntax.
  *
- * @example
- * \`\`\`typescript
- * // Direct function syntax
- * const permission = pikkuPermission(async ({ logger }, data, { session }) => {
- *   const session = await session?.get()
- *   return session?.role === 'admin'
- * })
- *
- * // Configuration object syntax with metadata
- * const adminPermission = pikkuPermission({
- *   name: 'Admin Permission',
- *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, data, { session }) => {
- *     const session = await session?.get()
- *     return session?.role === 'admin'
- *   }
- * })
- * \`\`\`
+ * @example snippet: permissionFunction
  */
 export const pikkuPermission = <In>(
   permission: PikkuPermission<In> | PikkuPermissionConfig<In>

package/dist/src/functions/wirings/auth/serialize-auth-types.js

@@ -60,6 +60,13 @@ export const serializeAuthTypes = (authTypesFile, functionTypesFile, secretsFile
         `  variables: TypedVariablesService`,
         `}`,
         '',
+        `/**`,
+        ` * Builds this project's Better Auth instance. The factory is handed the`,
+        ` * singleton services, with typed \`secrets\` and \`variables\`, and is called`,
+        ` * lazily so config and secrets are resolved before auth is constructed.`,
+        ` *`,
+        ` * @example snippet: betterAuthConfig`,
+        ` */`,
         `export const pikkuBetterAuth = <I extends BetterAuthInstance>(`,
         `  factory: (services: AuthSingletonServices) => I | Promise<I>`,
         `): PikkuBetterAuthFactory<I> =>`,

package/dist/src/functions/wirings/channels/serialize-channel-types.js

@@ -50,6 +50,8 @@ type ChannelWiring<ChannelData, Channel extends string> = CoreChannel<
  * @template Out - Output type for connection response
  * @param func - Function definition, either direct function or configuration object
  * @returns The normalized configuration object
+ *
+ * @example snippet: channelLifecycle
  */
 export const pikkuChannelConnectionFunc = <Out = unknown>(
   func:
@@ -65,6 +67,8 @@ export const pikkuChannelConnectionFunc = <Out = unknown>(
  *
  * @param func - Function definition, either direct function or configuration object
  * @returns The normalized configuration object
+ *
+ * @example snippet: channelLifecycle
  */
 export const pikkuChannelDisconnectionFunc = (
   func:
@@ -110,23 +114,7 @@ type PikkuChannelFuncConfigWithSchema<
  * @param func - Function definition, either direct function or configuration object
  * @returns The normalized configuration object
  *
- * @example
- * \`\`\`typescript
- * // Pattern 1: Using generic types
- * const handleMessage = pikkuChannelFunc<{text: string}, {received: boolean}>({
- *   func: async (_services, { text }) => ({ received: true })
- * })
- *
- * // Pattern 2: Using Zod schemas
- * const messageInput = z.object({ text: z.string() })
- * const messageOutput = z.object({ received: z.boolean() })
- *
- * const handleMessage = pikkuChannelFunc({
- *   input: messageInput,
- *   output: messageOutput,
- *   func: async (_services, { text }) => ({ received: true })
- * })
- * \`\`\`
+ * @example snippet: orderStatusChannel
  */
 export function pikkuChannelFunc<
   InputSchema extends StandardSchemaV1,
@@ -151,6 +139,8 @@ ${addon
  * @template ChannelData - Type of data associated with the channel
  * @template Channel - String literal type for the channel name
  * @param channel - Channel definition with connection, disconnection, and message handlers
+*
+* @example snippet: channelWiring
  */
 export const wireChannel = <ChannelData, Channel extends string>(
   channel: ChannelWiring<ChannelData, Channel> & AssertHTTPWiringParams<ChannelData, Channel>
@@ -165,6 +155,8 @@ export const wireChannel = <ChannelData, Channel extends string>(
  * @template T - Record of channel route handlers
  * @param routes - The channel routes record
  * @returns The same routes record (identity function for type safety)
+ *
+ * @example snippet: channelRoutes
  */
 export function defineChannelRoutes<T extends Record<string, any>>(routes: T): T {
   return defineChannelRoutesCore(routes)

package/dist/src/functions/wirings/cli/serialize-cli-types.js

@@ -39,12 +39,7 @@ type PikkuCLIRender<Data, RequiredServices extends SingletonServices = Singleton
  * @param render - Function that receives singleton services and data to render output
  * @returns A CLI renderer configuration
  *
- * @example
- * \`\`\`typescript
- * const myRenderer = pikkuCLIRender<MyData>(({ logger }, data) => {
- *   logger.info(data.message)
- * })
- * \`\`\`
+ * @example snippet: cliRenderer
  */
 export const pikkuCLIRender = <Data, RequiredServices extends SingletonServices = SingletonServices>(
   render: (services: SingletonServices, data: Data) => void | Promise<void>
@@ -73,6 +68,8 @@ type CLIWiring<Commands extends Record<string, CoreCLICommandConfig<any, PikkuMi
  * @template Commands - Type describing the command structure
  * @template GlobalOptions - Type for global CLI options
  * @param cli - CLI definition with program name, commands, and global options
+ *
+ * @example snippet: cliWiring
  */
 export const wireCLI = <Commands extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>, GlobalOptions>(
   cli: CLIWiring<Commands, GlobalOptions>
@@ -88,6 +85,8 @@ export const wireCLI = <Commands extends Record<string, CoreCLICommandConfig<any
  * @template Params - The parameters string literal type
  * @param config - CLI command configuration
  * @returns CLI command configuration with inferred types
+ *
+ * @example snippet: cliWiring
  */
 export const pikkuCLICommand = <
   FuncConfig extends PikkuFunctionConfig<any, any, 'cli' | 'rpc' | 'session'>,
@@ -104,6 +103,8 @@ export const pikkuCLICommand = <
  * @template T - Record of CLI command configurations
  * @param commands - The CLI commands record
  * @returns The same commands record (identity function for type safety)
+ *
+ * @example snippet: cliCommandContract
  */
 export const defineCLICommands = <T extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>>(
   commands: T

package/dist/src/functions/wirings/functions/pikku-command-function-types-split.js

@@ -35,7 +35,7 @@ export const pikkuFunctionTypesSplit = pikkuSessionlessFunc({
         await writeFileInDir(logger, middlewareTypesFile, serializeMiddlewareTypes(getFileImportRelativePath(middlewareTypesFile, functionTypesFile, packageMappings), `import type { RequiredSingletonServices } from '${getFileImportRelativePath(middlewareTypesFile, servicesFile, packageMappings)}'`, config.addonName));
         await writeFileInDir(logger, setupTypesFile, serializeSetupTypes(getFileImportRelativePath(setupTypesFile, functionTypesFile, packageMappings), pikkuConfigType
             ? `import type { ${pikkuConfigType.type} } from '${getFileImportRelativePath(setupTypesFile, pikkuConfigType.typePath, packageMappings)}'`
-            : '// Config type not found, will use fallback', pikkuConfigType?.type, `import type { RequiredSingletonServices, RequiredWireServices } from '${getFileImportRelativePath(setupTypesFile, servicesFile, packageMappings)}'`));
+            : '// Config type not found, will use fallback', pikkuConfigType?.type, `import type { RequiredSingletonServices, RequiredWireServices } from '${getFileImportRelativePath(setupTypesFile, servicesFile, packageMappings)}'`, config.allowShadowedServices));
         await writeFileInDir(logger, authGuardsFile, serializeAuthGuards(getFileImportRelativePath(authGuardsFile, functionTypesFile, packageMappings), `import type { RequiredSingletonServices } from '${getFileImportRelativePath(authGuardsFile, servicesFile, packageMappings)}'`, config.addonName));
         const addonRefs = serializeAddonRefs({
             addonHttp: visitState.exportedContracts.addonHttp,

package/dist/src/functions/wirings/functions/serialize-addon-refs.js

@@ -106,6 +106,10 @@ const __addonHttp = ${httpMap} as const
 const __addonChannel = ${channelMap} as const
 const __addonCli = ${cliMap} as const
 
+/**
+ * Names an HTTP route an installed addon wires, so you can link or redirect to
+ * it without hardcoding a path the addon may move.
+ */
 export const refHTTP = <Name extends keyof typeof __addonHttp>(
   name: Name,
   options?: { basePath?: string }
@@ -118,10 +122,18 @@ export const refHTTP = <Name extends keyof typeof __addonHttp>(
   ) as (typeof __addonHttp)[Name]
 }
 
+/**
+ * Names a channel an installed addon wires, for connecting to it without
+ * hardcoding its name.
+ */
 export const refChannel = <Name extends keyof typeof __addonChannel>(
   name: Name
 ): (typeof __addonChannel)[Name] => __addonChannel[name]
 
+/**
+ * Names a CLI command an installed addon wires, for invoking it without
+ * hardcoding its name.
+ */
 export const refCLI = <Name extends keyof typeof __addonCli>(
   name: Name
 ): (typeof __addonCli)[Name] => __addonCli[name]