@pikku/core 0.12.71 → 0.12.74

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

@@ -2,46 +2,47 @@ import { pikkuState } from '../../../pikku-state.js';
 import { parseCLIArguments, generateCommandHelp } from '../command-parser.js';
 import { runCLICommand } from '../cli-runner.js';
 /**
- * Handles raw CLI input from a WebSocket channel.
- * Parses the args, resolves the command, and either returns help or executes it.
+ * The client sends argv untouched and this side owns parsing, so the command
+ * tree lives with the server and a client binary never needs to know it.
  */
-export async function handleRawCLI({ programName, args, singletonServices, createWireServices, }) {
+export async function handleRawCLI({ programName, args, singletonServices, createWireServices, onOutput, session, transport, }) {
     const allCLIMeta = pikkuState(null, 'cli', 'meta');
     if (!allCLIMeta) {
-        return { error: 'CLI metadata not found' };
+        return { error: 'CLI metadata not found', exitCode: 1 };
     }
     const programMeta = allCLIMeta.programs[programName];
     if (!programMeta) {
-        return { error: `Program "${programName}" not found` };
+        return { error: `Program "${programName}" not found`, exitCode: 1 };
     }
-    // Handle empty input or explicit help
     if (args.length === 0 ||
         args.includes('--help') ||
         args.includes('-h') ||
         args[0] === 'help') {
         const helpArgs = args.filter((a) => a !== 'help' && a !== '--help' && a !== '-h');
         const helpText = generateCommandHelp(programName, allCLIMeta, helpArgs);
-        return { help: helpText };
+        return { help: helpText, exitCode: 0 };
     }
-    // Parse the args
     const parsed = parseCLIArguments(args, programName, allCLIMeta);
-    // If there are errors or the command resolves to a group (no function), show help
     if (parsed.errors.length > 0 || parsed.commandPath.length === 0) {
         const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
-        return { help: helpText };
+        // Help says what is available, not what they got wrong — so the parser's
+        // reason rides alongside it.
+        return {
+            help: helpText,
+            error: parsed.errors.length > 0 ? parsed.errors.join('\n') : undefined,
+            exitCode: 1,
+        };
     }
-    // Check if the resolved command has a pikkuFuncId (is executable)
     let current = programMeta.commands[parsed.commandPath[0]];
     for (let i = 1; i < parsed.commandPath.length; i++) {
         current = current?.subcommands?.[parsed.commandPath[i]];
     }
     if (!current?.pikkuFuncId) {
-        // It's a group command — show help scoped to that group
         const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
-        return { help: helpText };
+        return { help: helpText, exitCode: 0 };
     }
-    // Execute the command
     const data = { ...parsed.positionals, ...parsed.options };
+    const commandId = parsed.commandPath.join('.');
     try {
         const result = await runCLICommand({
             program: programName,
@@ -49,10 +50,17 @@ export async function handleRawCLI({ programName, args, singletonServices, creat
             data,
             singletonServices,
             createWireServices,
+            session,
+            // Not known until parsing finishes here, so it is supplied per-frame.
+            onOutput: onOutput && ((data) => onOutput(data, commandId)),
+            transport,
         });
-        return { result };
+        return { result, exitCode: 0, commandId };
     }
     catch (e) {
-        return { error: e.message };
+        // A command can throw anything; `.message` off a string is undefined, and
+        // the run would then exit 1 saying nothing at all.
+        const message = e instanceof Error ? e.message : String(e);
+        return { error: message || 'Command failed', exitCode: 1, commandId };
     }
 }

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

@@ -0,0 +1,20 @@
+import type { ApprovalRequester, Capabilities } from '../../channel/channel-rpc.js';
+import type { CorePikkuCLIRender } from '../cli.types.js';
+/**
+ * Runs a CLI command entirely on the server. Unlike `executeCLIViaChannel`,
+ * argv is forwarded untouched and never parsed here, so the client carries no
+ * command metadata and its version may drift from the server's.
+ *
+ * `capabilities` are the functions this client agrees to run on the server's
+ * behalf: the map says what *can* run, and approval whether a call *should*.
+ * `approve` overrides the mode otherwise read from argv and from whether there
+ * is a terminal to ask at.
+ */
+export declare function executeRawCLIViaChannel({ pikkuWS, args, renderers, defaultRenderer, capabilities, approve, }: {
+    pikkuWS: any;
+    args?: string[];
+    renderers?: Record<string, CorePikkuCLIRender<any>>;
+    defaultRenderer?: CorePikkuCLIRender<any>;
+    capabilities?: Capabilities;
+    approve?: ApprovalRequester;
+}): Promise<number>;

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

@@ -0,0 +1,121 @@
+import { createChannelRPCResponder, isChannelRPCRequest, } from '../../channel/channel-rpc.js';
+import { approverForMode, takeApprovalFlags } from './cli-approval.js';
+/** The normal case once the server owns the command tree. */
+const defaultJSONRenderer = (_services, data) => {
+    console.log(JSON.stringify(data));
+};
+/**
+ * The command ran on the server, so there are no services here — but a renderer
+ * written for local execution can still reach for `services.logger`.
+ */
+const clientServices = { logger: console };
+/**
+ * Runs a CLI command entirely on the server. Unlike `executeCLIViaChannel`,
+ * argv is forwarded untouched and never parsed here, so the client carries no
+ * command metadata and its version may drift from the server's.
+ *
+ * `capabilities` are the functions this client agrees to run on the server's
+ * behalf: the map says what *can* run, and approval whether a call *should*.
+ * `approve` overrides the mode otherwise read from argv and from whether there
+ * is a terminal to ask at.
+ */
+export async function executeRawCLIViaChannel({ pikkuWS, args = process.argv.slice(2), renderers = {}, defaultRenderer, capabilities = {}, approve, }) {
+    // Stripped before argv goes to the server: a flag the server can see is one
+    // the server could act on.
+    const { mode, args: commandArgs } = takeApprovalFlags(args);
+    // Aborted when the run ends, so a prompt still on stdin stops holding the
+    // event loop open.
+    const runEnded = new AbortController();
+    const approver = approve ?? approverForMode(mode, { signal: runEnded.signal });
+    const render = (commandId, data) => {
+        const renderer = (commandId ? renderers[commandId] : undefined) ||
+            defaultRenderer ||
+            defaultJSONRenderer;
+        renderer(clientServices, data, undefined);
+    };
+    return new Promise((resolve) => {
+        const commandRoute = pikkuWS.getRoute('command');
+        let settled = false;
+        // Plain frames, not a command route: the server takes these off the socket
+        // before routing.
+        const respond = createChannelRPCResponder({
+            capabilities,
+            approve: approver,
+            send: (data) => {
+                // A capability can still be resolving when the run settles. `respond`
+                // is dispatched without a handler, so a throw here would surface as an
+                // unhandled rejection — and by then the answer is moot.
+                if (settled || pikkuWS.ws.readyState !== 1) {
+                    return;
+                }
+                pikkuWS.ws.send(JSON.stringify(data));
+            },
+        });
+        const finish = (code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            runEnded.abort();
+            pikkuWS.unsubscribe(handler);
+            try {
+                pikkuWS.ws.close();
+            }
+            catch {
+                // Already closing — the exit code is what matters.
+            }
+            resolve(code);
+        };
+        // Every frame, not a command id: the server owns the command tree, and
+        // progressive `channel.send` frames carry no routing key at all.
+        const handler = (message) => {
+            // Classified synchronously so a request never also reaches the renderer.
+            // Answering is deliberately not awaited, so a slow capability cannot
+            // stall the output stream behind it.
+            if (isChannelRPCRequest(message)) {
+                void respond(message);
+                return;
+            }
+            // Only declared shapes: the channel also carries the runtime's routing
+            // echo, and rendering that would print noise between real output.
+            switch (message?.action) {
+                case 'cli-output':
+                    render(message.commandId, message.data);
+                    break;
+                case 'cli-result':
+                    render(message.commandId, message.result);
+                    break;
+                case 'cli-help':
+                    console.log(message.help);
+                    break;
+                case 'cli-error':
+                    console.error(message.error);
+                    break;
+                case 'cli-control':
+                    if (message.event === 'complete') {
+                        finish(message.exitCode ?? 0);
+                    }
+                    break;
+            }
+        };
+        pikkuWS.subscribe(handler);
+        // Only the server's `complete` frame reports success: a socket that closes
+        // before one means the command did not finish.
+        pikkuWS.ws.addEventListener('close', () => finish(1));
+        // A transport failure exits like a failed command rather than rejecting —
+        // to a CLI user both are simply a run that did not work.
+        pikkuWS.ws.addEventListener('error', (error) => {
+            if (!settled) {
+                console.error(error?.message ?? String(error));
+                finish(1);
+            }
+        });
+        const sendCommand = () => commandRoute.send('__raw', { args: commandArgs });
+        if (pikkuWS.ws.readyState === 1) {
+            sendCommand();
+        }
+        else {
+            pikkuWS.ws.addEventListener('open', sendCommand);
+        }
+    });
+}

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

@@ -1,2 +1,6 @@
 export { executeCLIViaChannel } from './cli-channel-runner.js';
 export { handleRawCLI } from './cli-raw-channel-runner.js';
+export type { RawCLIFrame, RawCLIResult } from './cli-raw-channel-runner.js';
+export { executeRawCLIViaChannel } from './cli-raw-client-runner.js';
+export { APPROVAL_FLAGS, approverForMode, createTerminalApprover, takeApprovalFlags, } from './cli-approval.js';
+export type { ApprovalMode } from './cli-approval.js';

package/dist/wirings/cli/channel/index.js

@@ -1,2 +1,4 @@
 export { executeCLIViaChannel } from './cli-channel-runner.js';
 export { handleRawCLI } from './cli-raw-channel-runner.js';
+export { executeRawCLIViaChannel } from './cli-raw-client-runner.js';
+export { APPROVAL_FLAGS, approverForMode, createTerminalApprover, takeApprovalFlags, } from './cli-approval.js';

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

@@ -1,38 +1,38 @@
 import type { CorePikkuMiddleware, CoreUserSession } from '../../types/core.types.js';
 import type { CoreCLI, CorePikkuCLIRender, CoreCLICommandConfig } from './cli.types.js';
 import type { CoreSingletonServices, CoreServices, CreateWireServices, CreateConfig, CreateSingletonServices } from '../../types/core.types.js';
-/**
- * CLI command execution error - thrown when CLI execution fails
- * Should be caught by the wrapper to call process.exit()
- */
+import type { PikkuChannel } from '../channel/channel.types.js';
+/** The caller is expected to catch this and call `process.exit(exitCode)`. */
 export declare class CLIError extends Error {
     exitCode: number;
     constructor(message: string, exitCode?: number);
 }
-/**
- * Registers a CLI command tree and all its functions
- */
 export declare const wireCLI: <Commands extends Record<string, CoreCLICommandConfig<any, any, any>>, GlobalOptions, PikkuMiddleware extends CorePikkuMiddleware, GlobalOutput>(cli: CoreCLI<Commands, GlobalOptions, PikkuMiddleware, GlobalOutput>) => void;
-/**
- * Executes a CLI command for a specific program
- */
-export declare function runCLICommand({ program, commandPath, data, singletonServices, createWireServices, }: {
+export declare function runCLICommand({ program, commandPath, data, singletonServices, createWireServices, onOutput, session, transport, }: {
     program: string;
     commandPath: string[];
     data: Record<string, any>;
     singletonServices: CoreSingletonServices;
     createWireServices?: CreateWireServices;
+    /**
+     * A locally run CLI has none — the process is the user. Over a channel the
+     * command inherits what the connection authenticated as, or no authenticated
+     * command is reachable remotely.
+     */
+    session?: CoreUserSession;
+    /**
+     * Diverts everything the command emits to a sink instead of the local
+     * renderer: when running on behalf of a remote CLI, rendering here would
+     * print to the *server's* stdout.
+     */
+    onOutput?: (data: unknown) => Promise<void> | void;
+    /**
+     * The connection the command arrived on. The CLI wire's own channel is
+     * synthetic, so reaching the caller is delegated to the real one underneath.
+     */
+    transport?: PikkuChannel<unknown, any, any>;
 }): Promise<any>;
-/**
- * Factory function for CLI-specific renderers
- */
 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>;
-/**
- * Execute a CLI program with the given arguments
- * This is the main entry point for CLI programs
- *
- * @throws {CLIError} When CLI execution fails - should be caught by wrapper to call process.exit()
- */
 export declare function executeCLI({ programName, args, createConfig, createSingletonServices, createWireServices, }: {
     programName: string;
     args?: string[];

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

@@ -2,13 +2,11 @@ import { NotFoundError } from '../../errors/errors.js';
 import { isExpectedError } from '../../errors/error-handler.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { pikkuState } from '../../pikku-state.js';
+import { unsupportedChannelRemote } from '../channel/channel-rpc.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { LocalVariablesService } from '../../services/local-variables.js';
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js';
-/**
- * CLI command execution error - thrown when CLI execution fails
- * Should be caught by the wrapper to call process.exit()
- */
+/** The caller is expected to catch this and call `process.exit(exitCode)`. */
 export class CLIError extends Error {
     exitCode;
     constructor(message, exitCode = 1) {
@@ -17,25 +15,16 @@ export class CLIError extends Error {
         this.name = 'CLIError';
     }
 }
-/**
- * Default JSON renderer for CLI output. Emits single-line NDJSON so
- * the output stays machine-parseable when the CLI is run with
- * `--output json`; pretty-printing here would break NDJSON consumers.
- */
+// knowledge: decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md
 const defaultJSONRenderer = (_services, data) => {
     console.log(JSON.stringify(data));
 };
-/**
- * Registers a CLI command tree and all its functions
- */
 export const wireCLI = (cli) => {
-    // Get the existing metadata that was generated during inspection
     const cliMeta = pikkuState(null, 'cli', 'meta') || {};
     if (!cliMeta.programs?.[cli.program]) {
         console.warn(`[pikku] Skipping CLI program '${cli.program}' — metadata not found. Consider moving this wiring to its own file.`);
         return;
     }
-    // Get existing programs state and add this program
     const programs = pikkuState(null, 'cli', 'programs') || {};
     programs[cli.program] = {
         defaultRenderer: (cli.render ||
@@ -45,18 +34,12 @@ export const wireCLI = (cli) => {
         tags: cli.tags,
     };
     pikkuState(null, 'cli', 'programs', programs);
-    // Register all command functions recursively
     registerCLICommands(cli.commands, [], cli.options || {}, cli.program);
 };
-/**
- * Unwraps a function from pikku wrappers (pikkuFunc, pikkuSessionlessFunc, etc.)
- * These wrappers return { func, middleware, ... } but we need the actual function
- */
 function unwrapFunc(command) {
     if (typeof command === 'function') {
         return { func: command };
     }
-    // If command has a func property that's an object with func, unwrap it
     if (command.func &&
         typeof command.func === 'object' &&
         'func' in command.func) {
@@ -68,27 +51,20 @@ function unwrapFunc(command) {
             tags: command.func.tags,
         };
     }
-    // Otherwise return as-is
     return command;
 }
-/**
- * Registers CLI commands and their functions recursively
- */
 function registerCLICommands(commands, path = [], inheritedOptions = {}, program) {
-    // Get the CLI metadata to find actual function names
     const cliMeta = pikkuState(null, 'cli', 'meta').programs[program];
     for (const [name, command] of Object.entries(commands)) {
         const fullPath = [...path, name];
         const commandId = fullPath.join('.');
-        // Navigate metadata to find the actual function name
         let currentMeta = cliMeta?.commands[fullPath[0]];
         for (let i = 1; i < fullPath.length; i++) {
             currentMeta = currentMeta?.subcommands?.[fullPath[i]];
         }
         const funcName = currentMeta?.pikkuFuncId;
-        // Skip if no function name (could be a command group)
+        // A command group has no function of its own.
         if (!funcName) {
-            // Recursively register subcommands if they exist
             if (typeof command === 'object' && command.subcommands) {
                 const commandOptions = command.options || {};
                 const mergedOptions = { ...inheritedOptions, ...commandOptions };
@@ -96,17 +72,14 @@ function registerCLICommands(commands, path = [], inheritedOptions = {}, program
             }
             continue;
         }
-        // Merge options (inherited + local)
         const commandOptions = typeof command === 'object' ? command.options || {} : {};
         const mergedOptions = { ...inheritedOptions, ...commandOptions };
-        // Store the options and middleware in program state for use during execution
         const programs = pikkuState(null, 'cli', 'programs');
         if (programs[program]) {
             if (!programs[program].commandOptions) {
                 programs[program].commandOptions = {};
             }
             programs[program].commandOptions[commandId] = mergedOptions;
-            // Store command middleware from the wire config
             if (typeof command === 'object' && command.middleware) {
                 if (!programs[program].commandMiddleware) {
                     programs[program].commandMiddleware = {};
@@ -115,21 +88,16 @@ function registerCLICommands(commands, path = [], inheritedOptions = {}, program
             }
         }
         addFunction(funcName, unwrapFunc(command), currentMeta?.packageName);
-        // Register renderer if provided
         if (typeof command === 'object' && command.render) {
             if (programs[program]) {
                 programs[program].renderers[commandId] = command.render;
             }
         }
-        // Recursively register subcommands
         if (typeof command === 'object' && command.subcommands) {
             registerCLICommands(command.subcommands, fullPath, mergedOptions, program);
         }
     }
 }
-/**
- * Plucks only the data that the function expects based on its schema
- */
 function pluckCLIData(mergedData, funcName, availableOptions) {
     const funcMeta = pikkuState(null, 'function', 'meta')[funcName];
     const schemaName = funcMeta?.inputSchemaName;
@@ -137,12 +105,11 @@ function pluckCLIData(mergedData, funcName, availableOptions) {
         ? pikkuState(funcMeta?.packageName ?? null, 'misc', 'schemas').get(schemaName)
         : null;
     if (schema && schema.properties) {
-        // If we have a schema, only include fields that are in the schema
         const result = {};
         for (const key of Object.keys(schema.properties)) {
             if (key in mergedData) {
+                // CLI values always arrive as strings; split comma lists the schema wants as arrays.
                 let value = mergedData[key];
-                // CLI passes all values as strings — coerce to array when schema expects one
                 const propSchema = schema.properties[key];
                 if (propSchema?.type === 'array' && !Array.isArray(value)) {
                     value = typeof value === 'string' ? value.split(',') : [value];
@@ -150,28 +117,21 @@ function pluckCLIData(mergedData, funcName, availableOptions) {
                 result[key] = value;
             }
             else if (availableOptions[key]?.default !== undefined) {
-                // Apply default if not provided
                 result[key] = availableOptions[key].default;
             }
         }
         return result;
     }
     else {
-        // No schema, include all data
         return { ...mergedData };
     }
 }
-/**
- * Executes a CLI command for a specific program
- */
-export async function runCLICommand({ program, commandPath, data, singletonServices, createWireServices, }) {
-    // Get the command metadata to find the function name
+export async function runCLICommand({ program, commandPath, data, singletonServices, createWireServices, onOutput, session, transport, }) {
     const cliMeta = pikkuState(null, 'cli', 'meta');
     const programMeta = cliMeta.programs?.[program];
     if (!programMeta) {
         throw new NotFoundError(`Program not found: ${program}`);
     }
-    // Navigate command tree to find the function name
     let currentCommand = programMeta.commands[commandPath[0]];
     if (!currentCommand) {
         throw new NotFoundError(`Command not found: ${commandPath.join(' ')}`);
@@ -184,14 +144,11 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
         currentCommand = currentCommand.subcommands[commandPath[i]];
     }
     const funcName = currentCommand.pikkuFuncId;
-    // Get program-specific data
     const programs = pikkuState(null, 'cli', 'programs') || {};
     const programData = programs[program];
-    // Combine program middleware + command middleware from the hierarchy
     const allWireMiddleware = [
         ...(programData?.middleware || []),
     ];
-    // Walk through the command path and collect middleware from the runtime config
     const commandParts = [];
     for (const part of commandPath) {
         commandParts.push(part);
@@ -201,20 +158,19 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             allWireMiddleware.push(...middleware);
         }
     }
-    // Get command ID and options
     const commandId = commandPath.join('.');
     const availableOptions = programData?.commandOptions?.[commandId] || {};
-    // Pluck only the fields the function expects
     const pluckedData = () => pluckCLIData(data, funcName, availableOptions);
-    // Get the renderer
     const renderer = programData?.renderers[commandId] || programData?.defaultRenderer;
-    // Create a CLI channel for progressive output
     let cliState;
     const channel = {
         channelId: `cli:${program}:${commandId}`,
         openingData: pluckedData,
         send: async (data) => {
-            if (renderer) {
+            if (onOutput) {
+                await onOutput(data);
+            }
+            else if (renderer) {
                 await Promise.resolve(renderer(singletonServices, data, undefined));
             }
         },
@@ -234,8 +190,16 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
         clearState: () => {
             cliState = undefined;
         },
+        // A locally-run command is already on the machine it would call back to,
+        // so there is no peer to answer.
+        remote: transport
+            ? (funcName, data) => transport.remote(funcName, data)
+            : unsupportedChannelRemote,
     };
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
+    if (session) {
+        userSession.setInitial(session);
+    }
     const wire = {
         cli: {
             program,
@@ -259,12 +223,12 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             sessionService: userSession,
             packageName: currentCommand.packageName,
         });
-        // Render the final result. `--json` / `--output json` routes the result
-        // through the global JSON renderer, but only for commands that opted into
-        // result-rendering by declaring a `render` — inline-printing commands (no
-        // per-command renderer) keep emitting their own output untouched.
-        // Skip if result is undefined (void functions handle their own output).
-        if (result !== undefined) {
+        // knowledge: decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md
+        // A void function has already emitted its own output.
+        //
+        // `onOutput` is progressive output only — the result goes back to the
+        // caller, and emitting it here too would deliver it twice.
+        if (result !== undefined && !onOutput) {
             const commandRenderer = programData?.renderers[commandId];
             const jsonMode = data.json === true || data.output === 'json';
             const finalRenderer = jsonMode && commandRenderer !== undefined
@@ -277,28 +241,17 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
         return result;
     }
     finally {
-        // Close the channel
         channel.close();
     }
 }
-/**
- * Factory function for CLI-specific renderers
- */
 export const pikkuCLIRender = (renderer) => {
     return renderer;
 };
-/**
- * Execute a CLI program with the given arguments
- * This is the main entry point for CLI programs
- *
- * @throws {CLIError} When CLI execution fails - should be caught by wrapper to call process.exit()
- */
 export async function executeCLI({ programName, args, createConfig, createSingletonServices, createWireServices, }) {
     if (!args) {
         throw new Error('CLI arguments are required, this is to satisfy release diffs');
     }
     try {
-        // Get CLI metadata from state
         const allCLIMeta = pikkuState(null, 'cli', 'meta');
         if (!allCLIMeta) {
             throw new Error('[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/docs/pikku-cli/errors/pku342 for more information.');
@@ -307,10 +260,8 @@ export async function executeCLI({ programName, args, createConfig, createSingle
         if (!programMeta) {
             throw new CLIError(`CLI program "${programName}" not found`, 1);
         }
-        // Parse arguments for this specific program
         const parsed = parseCLIArguments(args, programName, allCLIMeta);
-        // Handle help (check after parsing to support subcommand help)
-        // Show help if --help/-h is present, or if no args AND no default command
+        // Parsed first so that `<command> --help` resolves to that command's help.
         const shouldShowHelp = args.includes('--help') ||
             args.includes('-h') ||
             (args.length === 0 && parsed.commandPath.length === 0);
@@ -319,37 +270,30 @@ export async function executeCLI({ programName, args, createConfig, createSingle
             console.log(helpText);
             return;
         }
-        // Non-fatal diagnostics (unknown options are still accepted) go to stderr
-        // so they never pollute a command's machine-readable stdout.
+        // knowledge: decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md
         parsed.warnings.forEach((warning) => console.error(`Warning: ${warning}`));
         if (parsed.errors.length > 0) {
-            // Check if any error is about an unknown command
+            // knowledge: decisions/internals/cli-parse-errors-are-routed-by-message-prefix.md
             const hasUnknownCommand = parsed.errors.some((error) => error.startsWith('Unknown command:') ||
                 error.startsWith('Command not found:') ||
                 error.startsWith('Missing subcommand:'));
             if (hasUnknownCommand) {
-                // Show help instead of error for unknown commands
                 const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
                 console.log(helpText);
                 throw new CLIError('Unknown command', 1);
             }
             else {
-                // Show errors for other types of errors
                 console.error('Errors:');
                 parsed.errors.forEach((error) => console.error(`  ${error}`));
                 throw new CLIError(parsed.errors.join('\n'), 1);
             }
         }
-        // Merge positionals and options into single data object
         const data = { ...parsed.positionals, ...parsed.options };
-        // Create config (pass data in case it needs to use any parsed options)
         const config = createConfig
             ? await createConfig(new LocalVariablesService(), data)
             : {};
-        // Create services with config and register in global state
         const singletonServices = await createSingletonServices(config);
         pikkuState(null, 'package', 'singletonServices', singletonServices);
-        // Execute the command
         await runCLICommand({
             program: programName,
             commandPath: parsed.commandPath,
@@ -359,21 +303,16 @@ export async function executeCLI({ programName, args, createConfig, createSingle
         });
     }
     catch (error) {
-        // Re-throw CLIError as-is
         if (error instanceof CLIError) {
             throw error;
         }
-        // An expected failure (a deliberate PikkuError, e.g. a build gate
-        // tripping) — its message says everything, so print that alone (no
-        // `Error:` prefix). Anything else is an uncaught error: log the object so
-        // its stack shows.
+        // An expected PikkuError's message is written to be the whole output.
         if (isExpectedError(error)) {
             console.error(error.message);
         }
         else {
             console.error('Error:', error);
         }
-        // Show stack trace in verbose mode (even for expected errors).
         if (args.includes('--verbose') || args.includes('-v')) {
             console.error('Stack trace:', error.stack);
         }