@pikku/cli 0.12.115 → 0.12.117

package/dist/.pikku/channel/pikku-channel-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Channel-specific type definitions for tree-shaking optimization
@@ -31,6 +31,8 @@ type ChannelWiring<ChannelData, Channel extends string> = CoreChannel<ChannelDat
  * @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 declare const pikkuChannelConnectionFunc: <Out = unknown>(func: PikkuFunctionSessionless<void, Out, "channel" | "session" | "rpc"> | PikkuFunctionConfig<void, Out, "channel" | "session" | "rpc">) => PikkuFunctionConfig<void, Out, "channel" | "rpc" | "session">;
 /**
@@ -39,6 +41,8 @@ export declare const pikkuChannelConnectionFunc: <Out = unknown>(func: PikkuFunc
  *
  * @param func - Function definition, either direct function or configuration object
  * @returns The normalized configuration object
+ *
+ * @example snippet: channelLifecycle
  */
 export declare const pikkuChannelDisconnectionFunc: (func: PikkuFunctionSessionless<void, void, "channel"> | PikkuFunctionConfig<void, void, "channel" | "session" | "rpc">) => PikkuFunctionConfig<void, void, "channel" | "rpc" | "session">;
 /**
@@ -69,23 +73,7 @@ type PikkuChannelFuncConfigWithSchema<InputSchema extends StandardSchemaV1, Outp
  * @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 declare function pikkuChannelFunc<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuChannelFuncConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InferSchemaOutput<InputSchema>, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'channel' | 'session' | 'rpc'>;
 export declare function pikkuChannelFunc<In, Out = unknown>(func: PikkuFunctionSessionless<In, Out, 'channel' | 'session' | 'rpc'> | PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>): PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>;
@@ -95,6 +83,8 @@ export declare function pikkuChannelFunc<In, Out = unknown>(func: PikkuFunctionS
  * @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 declare const wireChannel: <ChannelData, Channel extends string>(channel: ChannelWiring<ChannelData, Channel> & AssertHTTPWiringParams<ChannelData, Channel>) => void;
 /**
@@ -104,6 +94,8 @@ export declare const wireChannel: <ChannelData, Channel extends string>(channel:
  * @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 declare function defineChannelRoutes<T extends Record<string, any>>(routes: T): T;
 export {};

package/dist/.pikku/channel/pikku-channel-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Channel-specific type definitions for tree-shaking optimization
@@ -12,6 +12,8 @@ import { wireChannel as wireChannelCore, defineChannelRoutes as defineChannelRou
  * @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 = (func) => {
     return typeof func === 'function' ? { func } : func;
@@ -22,6 +24,8 @@ export const pikkuChannelConnectionFunc = (func) => {
  *
  * @param func - Function definition, either direct function or configuration object
  * @returns The normalized configuration object
+ *
+ * @example snippet: channelLifecycle
  */
 export const pikkuChannelDisconnectionFunc = (func) => {
     return typeof func === 'function' ? { func } : func;
@@ -35,6 +39,8 @@ export function pikkuChannelFunc(func) {
  * @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 = (channel) => {
     wireChannelCore(channel);
@@ -46,6 +52,8 @@ export const wireChannel = (channel) => {
  * @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(routes) {
     return defineChannelRoutesCore(routes);

package/dist/.pikku/cli/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Subpath entry — `#pikku/cli` resolves here.

package/dist/.pikku/cli/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Subpath entry — `#pikku/cli` resolves here.

package/dist/.pikku/cli/pikku-cli-channel.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * WebSocket channel backend for 'pikku' CLI commands
@@ -10,6 +10,7 @@ import { pikkuMiddleware } from '../middleware/pikku-middleware-types.gen.js';
 import { generateCommandHelp } from '@pikku/core/cli';
 import { handleRawCLI } from '@pikku/core/cli/channel';
 import { pikkuState, getSingletonServices, getCreateWireServices, } from '@pikku/core/state';
+import { doc } from '../../src/functions/commands/doc.js';
 import { all } from '../../src/functions/commands/all.js';
 import { bootstrap } from '../../src/functions/commands/bootstrap.js';
 import { pikkuAudit } from '../../src/functions/commands/audit.js';
@@ -52,7 +53,6 @@ import { FabricLink } from '../../src/fabric/functions/link.function.js';
 import { FabricAddonVerify } from '../../src/fabric/functions/addon-verify.function.js';
 import { FabricPublish } from '../../src/fabric/functions/publish.function.js';
 import { FabricAdd } from '../../src/fabric/functions/add.function.js';
-import { FabricDeployPlan } from '../../src/fabric/functions/deploy.function.js';
 import { FabricDeployApply } from '../../src/fabric/functions/deploy.function.js';
 import { FabricDeployList } from '../../src/fabric/functions/deploy-list.function.js';
 import { FabricDeployUnits } from '../../src/fabric/functions/deploy-units.function.js';
@@ -240,6 +240,10 @@ wireChannel({
                 func: cliRaw,
                 middleware: [cliCloseOnComplete],
             },
+            'doc': {
+                func: doc,
+                middleware: [cliCloseOnComplete],
+            },
             'all': {
                 func: all,
                 middleware: [cliCloseOnComplete],
@@ -408,10 +412,6 @@ wireChannel({
                 func: FabricAdd,
                 middleware: [cliCloseOnComplete],
             },
-            'fabric.deploy.plan': {
-                func: FabricDeployPlan,
-                middleware: [cliCloseOnComplete],
-            },
             'fabric.deploy.apply': {
                 func: FabricDeployApply,
                 middleware: [cliCloseOnComplete],

package/dist/.pikku/cli/pikku-cli-client.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 import type { Capabilities } from '@pikku/core/channel';
 /**

package/dist/.pikku/cli/pikku-cli-client.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 import { executeRawCLIViaChannel } from '@pikku/core/cli/channel';
 import { CorePikkuWebsocket } from '@pikku/websocket';

package/dist/.pikku/cli/pikku-cli-contracts-meta.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 import contractsMeta from './pikku-cli-contracts-meta.gen.json';
 export default contractsMeta;

package/dist/.pikku/cli/pikku-cli-contracts-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 import contractsMeta from './pikku-cli-contracts-meta.gen.json' with { type: 'json' };
 export default contractsMeta;

package/dist/.pikku/cli/pikku-cli-contracts-meta.gen.json

@@ -153,24 +153,8 @@
             "pikkuFuncId": "",
             "positionals": [],
             "options": {},
-            "description": "Plan and apply deploys for a named branch or production",
+            "description": "Apply and inspect deploys for a named branch or production",
             "subcommands": {
-                "plan": {
-                    "pikkuFuncId": "FabricDeployPlan",
-                    "positionals": [],
-                    "options": {
-                        "branch": {
-                            "description": "Target branch to deploy",
-                            "short": "b"
-                        },
-                        "production": {
-                            "description": "Plan production (always main)",
-                            "default": false
-                        }
-                    },
-                    "renderName": "renderDeployPlan",
-                    "description": "Resolve the target ref and report what a deploy would do"
-                },
                 "apply": {
                     "pikkuFuncId": "FabricDeployApply",
                     "positionals": [],
@@ -183,17 +167,34 @@
                             "description": "Deploy production (always main)",
                             "default": false
                         },
-                        "message": {
-                            "description": "Annotation stored on the deployment",
-                            "short": "m"
+                        "ref": {
+                            "description": "Deploy a specific ref instead of the branch head"
+                        },
+                        "deploymentId": {
+                            "description": "Attach to an existing deployment instead of creating one (not with --branch/--production)"
+                        },
+                        "sync": {
+                            "description": "Wait for the deployment to finish and exit non-zero unless it went live",
+                            "default": false
+                        },
+                        "autoApprove": {
+                            "description": "Answer the confirmation prompt and publish a plan parked at the approval gate",
+                            "default": false
+                        },
+                        "allowDestructive": {
+                            "description": "Approve a plan whose migrations drop or rewrite data (--auto-approve alone will not)",
+                            "default": false
                         },
-                        "autoApply": {
-                            "description": "Deploy without the confirmation prompt",
+                        "timeout": {
+                            "description": "Seconds to wait under --sync (default 900)"
+                        },
+                        "json": {
+                            "description": "Machine-readable output (NDJSON)",
                             "default": false
                         }
                     },
                     "renderName": "renderDeployApply",
-                    "description": "Build + deploy a named branch or production (main)"
+                    "description": "Build + deploy a named branch or production (main), or attach to an existing deployment"
                 },
                 "list": {
                     "pikkuFuncId": "FabricDeployList",

package/dist/.pikku/cli/pikku-cli-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
 
@@ -28,12 +28,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 declare const pikkuCLIRender: <Data, RequiredServices extends SingletonServices = SingletonServices>(render: (services: SingletonServices, data: Data) => void | Promise<void>) => PikkuCLIRender<Data, RequiredServices>;
 /**
@@ -55,6 +50,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 declare const wireCLI: <Commands extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>, GlobalOptions>(cli: CLIWiring<Commands, GlobalOptions>) => void;
 /**
@@ -65,6 +62,8 @@ export declare const wireCLI: <Commands extends Record<string, CoreCLICommandCon
  * @template Params - The parameters string literal type
  * @param config - CLI command configuration
  * @returns CLI command configuration with inferred types
+ *
+ * @example snippet: cliWiring
  */
 export declare const pikkuCLICommand: <FuncConfig extends PikkuFunctionConfig<any, any, "cli" | "rpc" | "session">, Params extends string>(config: CLICommandConfig<FuncConfig, any, any, Params>) => CoreCLICommandConfig<FuncConfig, PikkuMiddleware, PikkuCLIRender<any>, string>;
 /**
@@ -73,6 +72,8 @@ export declare const pikkuCLICommand: <FuncConfig extends PikkuFunctionConfig<an
  * @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 declare const defineCLICommands: <T extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>>(commands: T) => T;
 export {};

package/dist/.pikku/cli/pikku-cli-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
 
@@ -15,12 +15,7 @@ import { wireCLI as wireCLICore, defineCLICommands as defineCLICommandsCore } fr
  * @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 = (render) => {
     return render;
@@ -32,6 +27,8 @@ export const pikkuCLIRender = (render) => {
  * @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 = (cli) => {
     wireCLICore(cli);
@@ -44,6 +41,8 @@ export const wireCLI = (cli) => {
  * @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 = (config) => {
     return config;
@@ -54,6 +53,8 @@ export const pikkuCLICommand = (config) => {
  * @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 = (commands) => {
     return defineCLICommandsCore(commands);

package/dist/.pikku/cli/pikku-cli-wirings-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 import { pikkuState } from '@pikku/core/state';
 import metaData from './pikku-cli-wirings-meta.gen.json' with { type: 'json' };

package/dist/.pikku/cli/pikku-cli-wirings-meta.gen.json

@@ -3,6 +3,29 @@
         "pikku": {
             "program": "pikku",
             "commands": {
+                "doc": {
+                    "pikkuFuncId": "doc",
+                    "positionals": [
+                        {
+                            "name": "topics",
+                            "required": false,
+                            "variadic": true
+                        }
+                    ],
+                    "options": {
+                        "ai": {
+                            "description": "Name the skill that teaches each door, for an agent deciding whether it needs to load one",
+                            "default": false
+                        },
+                        "addon": {
+                            "description": "Describe the addon surface instead of the application one",
+                            "default": false
+                        }
+                    },
+                    "renderName": "renderDoc",
+                    "description": "Print the API surface of the pikku installed here — the doors, what they export, and how each export is called",
+                    "parameters": "[topics...]"
+                },
                 "all": {
                     "pikkuFuncId": "all",
                     "positionals": [],
@@ -764,24 +787,8 @@
                             "pikkuFuncId": "",
                             "positionals": [],
                             "options": {},
-                            "description": "Plan and apply deploys for a named branch or production",
+                            "description": "Apply and inspect deploys for a named branch or production",
                             "subcommands": {
-                                "plan": {
-                                    "pikkuFuncId": "FabricDeployPlan",
-                                    "positionals": [],
-                                    "options": {
-                                        "branch": {
-                                            "description": "Target branch to deploy",
-                                            "short": "b"
-                                        },
-                                        "production": {
-                                            "description": "Plan production (always main)",
-                                            "default": false
-                                        }
-                                    },
-                                    "renderName": "renderDeployPlan",
-                                    "description": "Resolve the target ref and report what a deploy would do"
-                                },
                                 "apply": {
                                     "pikkuFuncId": "FabricDeployApply",
                                     "positionals": [],
@@ -794,17 +801,34 @@
                                             "description": "Deploy production (always main)",
                                             "default": false
                                         },
-                                        "message": {
-                                            "description": "Annotation stored on the deployment",
-                                            "short": "m"
+                                        "ref": {
+                                            "description": "Deploy a specific ref instead of the branch head"
                                         },
-                                        "autoApply": {
-                                            "description": "Deploy without the confirmation prompt",
+                                        "deploymentId": {
+                                            "description": "Attach to an existing deployment instead of creating one (not with --branch/--production)"
+                                        },
+                                        "sync": {
+                                            "description": "Wait for the deployment to finish and exit non-zero unless it went live",
+                                            "default": false
+                                        },
+                                        "autoApprove": {
+                                            "description": "Answer the confirmation prompt and publish a plan parked at the approval gate",
+                                            "default": false
+                                        },
+                                        "allowDestructive": {
+                                            "description": "Approve a plan whose migrations drop or rewrite data (--auto-approve alone will not)",
+                                            "default": false
+                                        },
+                                        "timeout": {
+                                            "description": "Seconds to wait under --sync (default 900)"
+                                        },
+                                        "json": {
+                                            "description": "Machine-readable output (NDJSON)",
                                             "default": false
                                         }
                                     },
                                     "renderName": "renderDeployApply",
-                                    "description": "Build + deploy a named branch or production (main)"
+                                    "description": "Build + deploy a named branch or production (main), or attach to an existing deployment"
                                 },
                                 "list": {
                                     "pikkuFuncId": "FabricDeployList",
@@ -1529,6 +1553,10 @@
                                     "description": "Install skills whose frontmatter includes installGroups: [fabric]",
                                     "default": false
                                 },
+                                "client": {
+                                    "description": "Install skills whose frontmatter includes installGroups: [client]",
+                                    "default": false
+                                },
                                 "update": {
                                     "description": "Overwrite existing skills if already installed",
                                     "default": false

package/dist/.pikku/cli/pikku-cli-wirings.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 import '../../src/cli.wiring.js';
 import '../../src/services.js';

package/dist/.pikku/cli/pikku-cli-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /* The files with an wireCLI function call */
 import '../../src/cli.wiring.js';

package/dist/.pikku/cli/pikku-cli.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 import '../pikku-bootstrap.gen.js';
 export declare function PikkuCLI(args: string[]): Promise<void>;

package/dist/.pikku/cli/pikku-cli.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 import { executeCLI, CLIError } from '@pikku/core/cli';
 import { createConfig as createConfig } from '../../src/services.js';

package/dist/.pikku/error/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Subpath entry — `#pikku/error` resolves here.

package/dist/.pikku/error/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Subpath entry — `#pikku/error` resolves here.

package/dist/.pikku/error/pikku-error-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Error catalogue — `#pikku/error` resolves here.

package/dist/.pikku/error/pikku-error-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Error catalogue — `#pikku/error` resolves here.

package/dist/.pikku/function/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Subpath entry — `#pikku/function` resolves here.

package/dist/.pikku/function/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.115
+ * This file was generated by @pikku/cli@0.12.117
  */
 /**
  * Subpath entry — `#pikku/function` resolves here.