@lotagate/cli 0.1.20 → 0.1.22

package/dist/application/commands/command-catalog.js

@@ -0,0 +1,159 @@
+const ALL = ['direct', 'tui'];
+const DIRECT = ['direct'];
+const TUI = ['tui'];
+const scopeOption = {
+    name: 'scope', valueName: '<user|project>', description: 'Extension scope', allowedValues: ['user', 'project'], requiredOn: DIRECT,
+};
+const goalLimitOptions = [
+    { name: 'token-budget', valueName: '<n>', description: 'Maximum token budget' },
+    { name: 'max-turns', valueName: '<n>', description: 'Maximum goal turns' },
+    { name: 'max-duration-ms', valueName: '<n>', description: 'Maximum goal duration' },
+];
+const modelOverrideOption = { name: 'model', valueName: '<model-id>', description: 'Use this model for this request only' };
+const outputOptions = [
+    { name: 'out', valueName: '<filename>', description: 'Output filename without extension' },
+    { name: 'out-dir', valueName: '<directory>', description: 'Local output directory, inside or outside the workspace' },
+    { name: 'force', description: 'Allow --out to replace an existing generated file' },
+];
+const imageOptions = [
+    modelOverrideOption,
+    { name: 'n', valueName: '<count>', description: 'Number of images' },
+    { name: 'size', valueName: '<size>', description: 'Requested image size' },
+    { name: 'quality', valueName: '<low|medium|high|auto>', description: 'Image quality', allowedValues: ['low', 'medium', 'high', 'auto'] },
+    { name: 'background', valueName: '<transparent|opaque|auto>', description: 'Image background', allowedValues: ['transparent', 'opaque', 'auto'] },
+    { name: 'output-format', valueName: '<png|jpeg|webp>', description: 'Image output format', allowedValues: ['png', 'jpeg', 'webp'] },
+    { name: 'output-compression', valueName: '<0-100>', description: 'Image output compression' },
+    { name: 'moderation', valueName: '<mode>', description: 'Image moderation mode' },
+    { name: 'user', valueName: '<id>', description: 'End-user identifier' },
+    ...outputOptions,
+];
+function action(spec) {
+    return spec;
+}
+/**
+ * Executable command contract for every public direct and slash command.
+ * Presentation layers consume this catalog; application handlers remain separate.
+ */
+export const COMMAND_ACTIONS = [
+    action({ id: 'help', path: ['help'], surfaces: ALL, summary: 'Show available commands', executor: 'help' }),
+    action({ id: 'version', path: ['version'], surfaces: ALL, summary: 'Show the CLI version', executor: 'version' }),
+    action({ id: 'config.get.default', path: ['config'], handlerPath: ['get'], surfaces: ALL, summary: 'Read effective configuration', arguments: [{ name: 'key', required: false }], executor: 'config', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'config.get', path: ['config', 'get'], handlerPath: ['get'], surfaces: ALL, summary: 'Read effective configuration', arguments: [{ name: 'key', required: false }], executor: 'config' }),
+    action({ id: 'config.set', path: ['config', 'set'], handlerPath: ['set'], surfaces: ALL, summary: 'Update global configuration', arguments: [{ name: 'key', required: true }, { name: 'value', required: true }], executor: 'config' }),
+    action({ id: 'config.path', path: ['config', 'path'], handlerPath: ['path'], surfaces: ALL, summary: 'Show configuration paths', executor: 'config' }),
+    action({ id: 'auth.status.default', path: ['auth'], handlerPath: ['status'], surfaces: ALL, summary: 'Show authentication status', executor: 'auth', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'auth.login.direct', path: ['auth', 'login'], handlerPath: ['login'], surfaces: DIRECT, summary: 'Save an API-key profile', options: [{ name: 'profile', valueName: '<name>', description: 'Profile name' }, { name: 'base-url', valueName: '<url>', description: 'Provider base URL' }], executor: 'auth', desktop: { exposed: false } }),
+    action({ id: 'auth.login.tui', path: ['auth', 'login'], handlerPath: ['login'], surfaces: TUI, summary: 'Save an API-key profile', options: [{ name: 'profile', valueName: '<name>', description: 'Profile name' }, { name: 'base-url', valueName: '<url>', description: 'Provider base URL' }], executor: 'tui-auth-login' }),
+    action({ id: 'auth.logout', path: ['auth', 'logout'], handlerPath: ['logout'], surfaces: ALL, summary: 'Remove an API-key profile', arguments: [{ name: 'profile', required: false }], executor: 'auth' }),
+    action({ id: 'auth.list', path: ['auth', 'list'], handlerPath: ['list'], surfaces: ALL, summary: 'List authentication profiles', executor: 'auth' }),
+    action({ id: 'auth.status', path: ['auth', 'status'], handlerPath: ['status'], surfaces: ALL, summary: 'Show authentication status', executor: 'auth' }),
+    action({ id: 'auth.use', path: ['auth', 'use'], handlerPath: ['use'], surfaces: ALL, summary: 'Select an authentication profile', arguments: [{ name: 'profile', required: true }], executor: 'auth' }),
+    action({ id: 'model.current.direct', path: ['model'], handlerPath: ['current'], surfaces: DIRECT, summary: 'Show the selected model', executor: 'model', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'model.select.tui', path: ['model'], surfaces: TUI, summary: 'Select a model', executor: 'tui-model-select', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'model.current', path: ['model', 'current'], handlerPath: ['current'], surfaces: ALL, summary: 'Show the selected model', executor: 'model' }),
+    action({ id: 'model.use', path: ['model', 'use'], handlerPath: ['use'], surfaces: ALL, summary: 'Select a model', arguments: [{ name: 'model', required: true }], executor: 'model' }),
+    action({ id: 'model.list', path: ['model', 'list'], handlerPath: ['list'], surfaces: ALL, summary: 'Fetch the model catalog', executor: 'model' }),
+    action({ id: 'model.refresh', path: ['model', 'refresh'], handlerPath: ['refresh'], surfaces: ALL, summary: 'Refresh the model catalog', executor: 'model' }),
+    action({ id: 'model.doctor', path: ['model', 'doctor'], handlerPath: ['doctor'], surfaces: ALL, summary: 'Inspect model configuration', executor: 'model' }),
+    action({ id: 'trust.status.default', path: ['trust'], handlerPath: ['status'], surfaces: ALL, summary: 'Show current project trust', executor: 'trust', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'trust.status', path: ['trust', 'status'], handlerPath: ['status'], surfaces: ALL, summary: 'Show current project trust', executor: 'trust' }),
+    action({ id: 'trust.list', path: ['trust', 'list'], handlerPath: ['list'], surfaces: ALL, summary: 'List trusted projects', executor: 'trust' }),
+    action({ id: 'trust.grant', path: ['trust', 'grant'], handlerPath: ['grant'], surfaces: ALL, summary: 'Trust the current project', executor: 'trust' }),
+    action({ id: 'trust.revoke', path: ['trust', 'revoke'], handlerPath: ['revoke'], surfaces: ALL, summary: 'Revoke current project trust', executor: 'trust' }),
+    action({ id: 'inspect', path: ['inspect'], surfaces: ALL, summary: 'Inspect current project identity', executor: 'inspect' }),
+    action({ id: 'hook.list.default', path: ['hook'], handlerPath: ['list'], surfaces: ALL, summary: 'List project and plugin hooks', executor: 'hook', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'hook.list', path: ['hook', 'list'], handlerPath: ['list'], surfaces: ALL, summary: 'List project and plugin hooks', executor: 'hook' }),
+    action({ id: 'mcp.list.default', path: ['mcp'], surfaces: ALL, summary: 'List configured MCP servers', executor: 'mcp', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'mcp.list', path: ['mcp', 'list'], handlerPath: ['list'], surfaces: ALL, summary: 'List configured MCP servers', executor: 'mcp' }),
+    action({ id: 'mcp.get', path: ['mcp', 'get'], handlerPath: ['get'], surfaces: ALL, summary: 'Inspect an MCP server', arguments: [{ name: 'name', required: true }], options: [scopeOption], executor: 'mcp' }),
+    action({ id: 'mcp.add', path: ['mcp', 'add'], handlerPath: ['add'], surfaces: ALL, summary: 'Add an MCP server', arguments: [{ name: 'name', required: true }], options: [
+            { name: 'type', valueName: '<stdio|http|sse>', description: 'MCP transport type (defaults to stdio)', allowedValues: ['stdio', 'http', 'sse'] },
+            { name: 'command', valueName: '<command>', description: 'stdio command', requiredWhen: { option: 'type', values: ['stdio'], absent: true } },
+            { name: 'url', valueName: '<url>', description: 'HTTP or SSE URL', requiredWhen: { option: 'type', values: ['http', 'sse'] } },
+            { name: 'args', valueName: '<a,b>', description: 'Comma-separated stdio arguments' }, scopeOption,
+        ], executor: 'mcp' }),
+    action({ id: 'mcp.reload', path: ['mcp', 'reload'], handlerPath: ['reload'], surfaces: ALL, summary: 'Reconnect configured MCP servers', executor: 'mcp' }),
+    action({ id: 'mcp.doctor', path: ['mcp', 'doctor'], handlerPath: ['doctor'], surfaces: ALL, summary: 'Validate MCP servers', executor: 'mcp' }),
+    ...['enable', 'disable', 'remove'].map((name) => action({ id: `mcp.${name}`, path: ['mcp', name], handlerPath: [name], surfaces: ALL, summary: `${name[0].toUpperCase()}${name.slice(1)} an MCP server`, arguments: [{ name: 'name', required: true }], options: [scopeOption], executor: 'mcp' })),
+    action({ id: 'plugin.list.default', path: ['plugin'], surfaces: ALL, summary: 'List installed plugins', executor: 'plugin', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'plugin.list', path: ['plugin', 'list'], handlerPath: ['list'], surfaces: ALL, summary: 'List installed plugins', executor: 'plugin' }),
+    action({ id: 'plugin.install', path: ['plugin', 'install'], handlerPath: ['install'], surfaces: ALL, summary: 'Install a plugin or standalone skill', arguments: [{ name: 'source', required: true }], options: [scopeOption, { name: 'sha256', valueName: '<hex>', description: 'Expected archive checksum' }, { name: 'signature', valueName: '<base64>', description: 'Archive signature' }, { name: 'public-key', valueName: '<pem>', description: 'Signature public key' }], executor: 'plugin' }),
+    ...['enable', 'disable', 'uninstall'].map((name) => action({ id: `plugin.${name}`, path: ['plugin', name], handlerPath: [name], surfaces: ALL, summary: `${name[0].toUpperCase()}${name.slice(1)} a plugin`, arguments: [{ name: 'name', required: true }], options: [scopeOption], executor: 'plugin' })),
+    action({ id: 'skill.list.default', path: ['skill'], surfaces: ALL, summary: 'List available skills', executor: 'skill', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'skill.list', path: ['skill', 'list'], handlerPath: ['list'], surfaces: ALL, summary: 'List available skills', executor: 'skill' }),
+    ...['info', 'enable', 'disable', 'remove'].map((name) => action({ id: `skill.${name}`, path: ['skill', name], handlerPath: [name], surfaces: ALL, summary: `${name[0].toUpperCase()}${name.slice(1)} a skill`, arguments: [{ name: 'name', required: true }], options: [scopeOption], executor: 'skill' })),
+    action({ id: 'skill.run.direct', path: ['skill', 'run'], handlerPath: ['run'], surfaces: DIRECT, summary: 'Print an enabled skill prompt', arguments: [{ name: 'name', required: true }], options: [scopeOption], executor: 'skill' }),
+    action({ id: 'skill.run.tui', path: ['skill', 'run'], surfaces: TUI, summary: 'Run an enabled skill', arguments: [{ name: 'name', required: true }, { name: 'arguments', required: false, variadic: true }], options: [scopeOption], executor: 'tui-skill-run' }),
+    action({ id: 'session.list.default', path: ['session'], surfaces: ALL, summary: 'List durable sessions', executor: 'session', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'session.list', path: ['session', 'list'], handlerPath: ['list'], surfaces: ALL, summary: 'List durable sessions', executor: 'session' }),
+    action({ id: 'session.show', path: ['session', 'show'], handlerPath: ['show'], surfaces: ALL, summary: 'Show a session transcript', arguments: [{ name: 'id', required: true }], executor: 'session' }),
+    action({ id: 'session.import', path: ['session', 'import'], handlerPath: ['import'], surfaces: ALL, summary: 'Import a session bundle', options: [{ name: 'file', valueName: '<path>', description: 'Session bundle path', required: true }], executor: 'session' }),
+    action({ id: 'session.resume.direct', path: ['session', 'resume'], handlerPath: ['resume'], surfaces: DIRECT, summary: 'Inspect or resume a session', arguments: [{ name: 'id', required: true }], options: [{ name: 'interactive', description: 'Open the session in the TUI' }], executor: 'session' }),
+    action({ id: 'session.resume.tui', path: ['session', 'resume'], surfaces: TUI, summary: 'Resume a session in this TUI', arguments: [{ name: 'id', required: true }], executor: 'tui-session-resume' }),
+    action({ id: 'session.fork', path: ['session', 'fork'], handlerPath: ['fork'], surfaces: ALL, summary: 'Fork a session', arguments: [{ name: 'id', required: true }], executor: 'session' }),
+    action({ id: 'session.compact.direct', path: ['session', 'compact'], handlerPath: ['compact'], surfaces: DIRECT, summary: 'Compact a session', arguments: [{ name: 'id', required: true }], executor: 'session' }),
+    action({ id: 'session.compact.tui', path: ['session', 'compact'], surfaces: TUI, summary: 'Compact the active session', executor: 'tui-session-compact' }),
+    action({ id: 'session.export', path: ['session', 'export'], handlerPath: ['export'], surfaces: ALL, summary: 'Export a session bundle', arguments: [{ name: 'id', required: true }], options: [{ name: 'out', valueName: '<path>', description: 'Output path' }], executor: 'session' }),
+    ...['recover', 'repair', 'delete'].map((name) => action({ id: `session.${name}`, path: ['session', name], handlerPath: [name], surfaces: ALL, summary: `${name[0].toUpperCase()}${name.slice(1)} a session`, arguments: [{ name: 'id', required: true }], executor: 'session' })),
+    action({ id: 'session.rename', path: ['session', 'rename'], surfaces: TUI, summary: 'Rename the active session', arguments: [{ name: 'name', required: true, variadic: true }], executor: 'tui-session-rename' }),
+    action({ id: 'goal.status.direct', path: ['goal', 'status'], handlerPath: ['status'], surfaces: DIRECT, summary: 'Show a session goal', arguments: [{ name: 'id', required: true }], options: [{ name: 'json', description: 'Use JSON output' }], executor: 'goal' }),
+    action({ id: 'goal.set', path: ['goal', 'set'], handlerPath: ['set'], surfaces: DIRECT, summary: 'Set a session goal', arguments: [{ name: 'id', required: true }, { name: 'objective', required: true, variadic: true }], options: [...goalLimitOptions, { name: 'json', description: 'Use JSON output' }], executor: 'goal' }),
+    action({ id: 'goal.pause.direct', path: ['goal', 'pause'], handlerPath: ['pause'], surfaces: DIRECT, summary: 'Pause a session goal', arguments: [{ name: 'id', required: true }], options: [{ name: 'json', description: 'Use JSON output' }], executor: 'goal' }),
+    action({ id: 'goal.resume.direct', path: ['goal', 'resume'], handlerPath: ['resume'], surfaces: DIRECT, summary: 'Resume a session goal', arguments: [{ name: 'id', required: true }], options: [...goalLimitOptions, { name: 'json', description: 'Use JSON output' }], executor: 'goal' }),
+    action({ id: 'goal.clear.direct', path: ['goal', 'clear'], handlerPath: ['clear'], surfaces: DIRECT, summary: 'Clear a session goal', arguments: [{ name: 'id', required: true }], executor: 'goal' }),
+    action({ id: 'goal.run', path: ['goal', 'run'], handlerPath: ['run'], surfaces: DIRECT, summary: 'Run a durable multi-turn goal', arguments: [{ name: 'objective', required: true, variadic: true }], options: goalLimitOptions, executor: 'goal' }),
+    ...['status', 'pause', 'resume', 'clear'].map((name) => action({ id: `goal.${name}.tui`, path: ['goal', name], surfaces: TUI, summary: `${name[0].toUpperCase()}${name.slice(1)} the active goal`, executor: 'tui-goal' })),
+    action({ id: 'goal.start.tui', path: ['goal'], surfaces: TUI, summary: 'Start a goal for the active session', arguments: [{ name: 'objective', required: true, variadic: true }], options: goalLimitOptions, executor: 'tui-goal', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'doctor', path: ['doctor'], surfaces: ALL, summary: 'Run local diagnostics', executor: 'doctor' }),
+    action({ id: 'chat.direct', path: ['chat'], surfaces: DIRECT, summary: 'Stream a chat completion', arguments: [{ name: 'prompt', required: false, variadic: true }], executor: 'chat' }),
+    action({ id: 'chat.tui', path: ['chat'], surfaces: TUI, summary: 'Send an interactive chat prompt', arguments: [{ name: 'prompt', required: true, variadic: true }], executor: 'tui-prompt' }),
+    action({ id: 'image.generate', path: ['image'], surfaces: ALL, summary: 'Generate image artifacts', arguments: [{ name: 'prompt', required: true, variadic: true }], options: imageOptions, executor: 'media' }),
+    action({ id: 'image.edit', path: ['image', 'edit'], handlerPath: ['edit'], surfaces: ALL, summary: 'Edit image artifacts', arguments: [{ name: 'prompt', required: true, variadic: true }], options: [
+            ...imageOptions,
+            { name: 'image', valueName: '<path[,path]>', description: 'Source local image files', required: true },
+            { name: 'mask', valueName: '<path>', description: 'Optional local mask image' },
+            { name: 'input-fidelity', valueName: '<low|high>', description: 'Input image fidelity', allowedValues: ['low', 'high'] },
+        ], executor: 'media' }),
+    action({ id: 'audio.speech', path: ['audio', 'speech'], handlerPath: ['speech'], surfaces: ALL, summary: 'Generate speech audio', arguments: [{ name: 'input', required: true, variadic: true }], options: [
+            modelOverrideOption, { name: 'voice', valueName: '<voice>', description: 'Voice identifier', required: true },
+            { name: 'instructions', valueName: '<text>', description: 'Voice instructions' },
+            { name: 'response-format', valueName: '<mp3|opus|aac|flac|wav|pcm>', description: 'Audio output format', allowedValues: ['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'] },
+            { name: 'speed', valueName: '<number>', description: 'Speech speed' }, ...outputOptions,
+        ], executor: 'media' }),
+    action({ id: 'audio.transcribe', path: ['audio', 'transcribe'], handlerPath: ['transcribe'], surfaces: ALL, summary: 'Transcribe an audio file', options: [
+            modelOverrideOption, { name: 'file', valueName: '<path>', description: 'Local audio file', required: true },
+            { name: 'language', valueName: '<code>', description: 'Input language code' }, { name: 'prompt', valueName: '<text>', description: 'Transcript prompt' },
+            { name: 'response-format', valueName: '<json|text|srt|verbose_json|vtt|diarized_json>', description: 'Transcript format', allowedValues: ['json', 'text', 'srt', 'verbose_json', 'vtt', 'diarized_json'] },
+            { name: 'temperature', valueName: '<number>', description: 'Sampling temperature' }, { name: 'timestamp-granularities', valueName: '<word,segment>', description: 'Timestamp granularities' },
+            { name: 'include', valueName: '<value[,value]>', description: 'Provider response fields' }, ...outputOptions,
+        ], executor: 'media' }),
+    action({ id: 'audio.translate', path: ['audio', 'translate'], handlerPath: ['translate'], surfaces: ALL, summary: 'Translate an audio file', options: [
+            modelOverrideOption, { name: 'file', valueName: '<path>', description: 'Local audio file', required: true },
+            { name: 'prompt', valueName: '<text>', description: 'Translation prompt' },
+            { name: 'response-format', valueName: '<json|text|srt|verbose_json|vtt>', description: 'Translation format', allowedValues: ['json', 'text', 'srt', 'verbose_json', 'vtt'] },
+            { name: 'temperature', valueName: '<number>', description: 'Sampling temperature' }, ...outputOptions,
+        ], executor: 'media' }),
+    action({ id: 'video.generate', path: ['video'], surfaces: ALL, summary: 'Create and retrieve a video artifact', arguments: [{ name: 'prompt', required: true, variadic: true }], options: [
+            modelOverrideOption, { name: 'parameters', valueName: '<json>', description: 'Provider video parameter object' }, { name: 'no-wait', description: 'Return the operation id without waiting' }, ...outputOptions,
+        ], executor: 'media' }),
+    action({ id: 'video.status', path: ['video', 'status'], handlerPath: ['status'], surfaces: ALL, summary: 'Show a video operation status', arguments: [{ name: 'operation-id', required: true }], executor: 'media' }),
+    action({ id: 'video.download', path: ['video', 'download'], handlerPath: ['download'], surfaces: ALL, summary: 'Download a completed video artifact', arguments: [{ name: 'operation-id', required: true }], options: outputOptions, executor: 'media' }),
+    action({ id: 'exec.direct', path: ['exec'], surfaces: DIRECT, summary: 'Run a headless agent prompt', arguments: [{ name: 'prompt', required: true, variadic: true }], options: [{ name: 'image', valueName: '<path[,path]>', description: 'Image attachments' }, { name: 'json', description: 'Use JSON events' }, { name: 'jsonl', description: 'Use JSONL events' }], executor: 'exec', desktop: { exposed: false } }),
+    action({ id: 'exec.tui', path: ['exec'], surfaces: TUI, summary: 'Run an interactive agent prompt', arguments: [{ name: 'prompt', required: true, variadic: true }], executor: 'tui-prompt' }),
+    action({ id: 'agent.stdio', path: ['agent', 'stdio'], handlerPath: ['stdio'], surfaces: DIRECT, summary: 'Run the JSONL agent protocol', executor: 'agent', desktop: { exposed: false } }),
+    action({ id: 'agent.desktop', path: ['agent', 'desktop'], handlerPath: ['desktop'], surfaces: DIRECT, summary: 'Run the desktop application protocol', executor: 'agent', desktop: { exposed: false } }),
+    action({ id: 'agent.info', path: ['agent'], surfaces: TUI, summary: 'Explain the direct JSONL agent protocol', executor: 'tui-agent-info' }),
+    ...['bash', 'zsh', 'powershell'].map((shell) => action({ id: `completions.${shell}`, path: ['completions', shell], handlerPath: [shell], surfaces: ALL, summary: `Print ${shell} completion definitions`, executor: 'completions', desktop: { exposed: false } })),
+    action({ id: 'completions.default', path: ['completions'], surfaces: ALL, summary: 'Print PowerShell completion definitions', executor: 'completions', defaultAction: true, hiddenFromHelp: true, desktop: { exposed: false } }),
+    action({ id: 'update.check.default', path: ['update'], handlerPath: ['check'], surfaces: ALL, summary: 'Check update policy', executor: 'update', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'update.check', path: ['update', 'check'], handlerPath: ['check'], surfaces: ALL, summary: 'Check update policy', executor: 'update' }),
+    action({ id: 'tui.clear', path: ['clear'], surfaces: TUI, summary: 'Clear the current transcript view', executor: 'tui-clear' }),
+    action({ id: 'tui.stop', path: ['stop'], surfaces: TUI, summary: 'Stop the active response', executor: 'tui-stop' }),
+    action({ id: 'tui.context', path: ['context'], surfaces: TUI, summary: 'Show context usage and session composition', executor: 'tui-context' }),
+    action({ id: 'tui.details', path: ['details'], surfaces: TUI, summary: 'Toggle tool execution details', executor: 'tui-details' }),
+    action({ id: 'tui.exit', path: ['exit'], surfaces: TUI, summary: 'Exit the interactive session', executor: 'tui-exit' }),
+    action({ id: 'attachments.list.default', path: ['attachments'], surfaces: TUI, summary: 'List pending attachments', executor: 'tui-attachments', defaultAction: true, hiddenFromHelp: true }),
+    action({ id: 'attachments.list', path: ['attachments', 'list'], surfaces: TUI, summary: 'List pending attachments', executor: 'tui-attachments' }),
+    action({ id: 'attachments.paste', path: ['attachments', 'paste'], surfaces: TUI, summary: 'Add an image from the clipboard', executor: 'tui-attachments' }),
+    action({ id: 'attachments.remove', path: ['attachments', 'remove'], surfaces: TUI, summary: 'Remove a pending attachment', arguments: [{ name: 'id', required: true }], executor: 'tui-attachments' }),
+];

package/dist/application/commands/command-contract.d.ts

@@ -0,0 +1,58 @@
+export type CommandSurface = 'direct' | 'tui';
+export type CommandExecutorId = 'help' | 'version' | 'config' | 'auth' | 'tui-auth-login' | 'trust' | 'inspect' | 'hook' | 'model' | 'tui-model-select' | 'mcp' | 'plugin' | 'skill' | 'tui-skill-run' | 'session' | 'tui-session-resume' | 'tui-session-compact' | 'tui-session-rename' | 'goal' | 'tui-goal' | 'doctor' | 'chat' | 'exec' | 'media' | 'tui-prompt' | 'agent' | 'tui-agent-info' | 'completions' | 'update' | 'tui-clear' | 'tui-stop' | 'tui-context' | 'tui-details' | 'tui-attachments' | 'tui-exit';
+export interface CommandArgumentSpec {
+    readonly name: string;
+    readonly required: boolean;
+    readonly variadic?: boolean;
+}
+export interface CommandOptionRequirement {
+    readonly option: string;
+    readonly values?: readonly string[];
+    readonly absent?: boolean;
+}
+export interface CommandOptionSpec {
+    readonly name: string;
+    readonly valueName?: string;
+    readonly description: string;
+    readonly required?: boolean;
+    readonly requiredOn?: readonly CommandSurface[];
+    readonly requiredWhen?: CommandOptionRequirement;
+    readonly allowedValues?: readonly string[];
+}
+export interface CommandActionSpec {
+    readonly id: string;
+    /** Tokens used to select this action on a supported surface. */
+    readonly path: readonly string[];
+    /** Tokens the existing application handler expects before parsed arguments. */
+    readonly handlerPath?: readonly string[];
+    readonly surfaces: readonly CommandSurface[];
+    readonly summary: string;
+    readonly arguments?: readonly CommandArgumentSpec[];
+    readonly options?: readonly CommandOptionSpec[];
+    readonly executor: CommandExecutorId;
+    /**
+     * Optional exposure policy for the Desktop JSONL protocol. Direct and TUI
+     * users continue to resolve commands from `surfaces`; this metadata only
+     * controls whether a command is safe and meaningful for a non-terminal
+     * Desktop client.
+     */
+    readonly desktop?: {
+        readonly exposed?: boolean;
+    };
+    /** Default action for a command group, such as `mcp` → `mcp list`. */
+    readonly defaultAction?: boolean;
+    /** Default routes are executable but excluded from command lists. */
+    readonly hiddenFromHelp?: boolean;
+}
+export interface CommandInvocation {
+    readonly surface: CommandSurface;
+    readonly action: CommandActionSpec;
+    readonly positionals: readonly string[];
+    readonly options: ReadonlyMap<string, string | boolean>;
+    readonly handlerPositionals: readonly string[];
+}
+export interface CommandSuggestion {
+    readonly value: string;
+    readonly label: string;
+    readonly description: string;
+}

package/dist/application/commands/command-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/application/commands/command-hints.d.ts

@@ -0,0 +1,9 @@
+import type { CliError } from '../../domain/errors/cli-error.js';
+import type { CliCommandHint } from '../../domain/errors/cli-command-hint.js';
+export type CommandSurface = 'tui' | 'direct';
+export declare function commandHint(actionId: string, tuiActionId?: string): CliCommandHint;
+export declare const AUTH_LOGIN_HINT: CliCommandHint;
+export declare const MODEL_SELECT_HINT: CliCommandHint;
+export declare const TRUST_GRANT_HINT: CliCommandHint;
+export declare function formatCommandHint(hint: CliCommandHint, surface: CommandSurface): string;
+export declare function formatCliErrorMessage(error: CliError, surface: CommandSurface): string;

package/dist/application/commands/command-hints.js

@@ -0,0 +1,17 @@
+import { formatCommandUsage } from './command-presentation.js';
+import { COMMAND_REGISTRY } from './command-runtime.js';
+export function commandHint(actionId, tuiActionId) {
+    return tuiActionId === undefined ? { actionId } : { actionId, tuiActionId };
+}
+export const AUTH_LOGIN_HINT = commandHint('auth.login.direct', 'auth.login.tui');
+export const MODEL_SELECT_HINT = commandHint('model.use');
+export const TRUST_GRANT_HINT = commandHint('trust.grant');
+export function formatCommandHint(hint, surface) {
+    const action = COMMAND_REGISTRY.get(surface === 'tui' ? hint.tuiActionId ?? hint.actionId : hint.actionId);
+    if (action === undefined)
+        return 'Try the relevant command from the command help.';
+    return `Try \`${formatCommandUsage(action, surface)}\`.`;
+}
+export function formatCliErrorMessage(error, surface) {
+    return error.hint === undefined ? error.userMessage : `${error.userMessage} ${formatCommandHint(error.hint, surface)}`;
+}

package/dist/application/commands/command-output.d.ts

@@ -0,0 +1,4 @@
+export interface CommandOutput {
+    write(value: string): unknown;
+    writeStructured?<T extends object>(value: T, fallbackText?: string): unknown;
+}

package/dist/application/commands/command-output.js

@@ -0,0 +1 @@
+export {};

package/dist/application/commands/command-parser.d.ts

@@ -0,0 +1,10 @@
+import type { CommandInvocation, CommandSurface } from './command-contract.js';
+import type { CommandRegistry } from './command-registry.js';
+export declare function tokenizeCommandInput(value: string): readonly string[];
+export declare function parseCommandInvocation(tokens: readonly string[], surface: CommandSurface, registry: CommandRegistry): CommandInvocation;
+/**
+ * Validates an already selected action. Protocol callers use this when the
+ * action id and parsed values are transported separately from the command
+ * text, while direct and TUI callers continue to use token parsing above.
+ */
+export declare function parseCommandInvocationForAction(actionId: string, positionals: readonly string[], options: ReadonlyMap<string, string | boolean>, surface: CommandSurface, registry: CommandRegistry): CommandInvocation;

package/dist/application/commands/command-parser.js

@@ -0,0 +1,155 @@
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+export function tokenizeCommandInput(value) {
+    const tokens = [];
+    let current = '';
+    let quote;
+    let escaping = false;
+    for (const character of value.trim()) {
+        if (escaping) {
+            current += character;
+            escaping = false;
+            continue;
+        }
+        if (character === '\\') {
+            if (quote !== undefined)
+                escaping = true;
+            else
+                current += character;
+            continue;
+        }
+        if (quote !== undefined) {
+            if (character === quote)
+                quote = undefined;
+            else
+                current += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (/\s/u.test(character)) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = '';
+            }
+            continue;
+        }
+        current += character;
+    }
+    if (escaping)
+        current += '\\';
+    if (current.length > 0)
+        tokens.push(current);
+    return tokens;
+}
+export function parseCommandInvocation(tokens, surface, registry) {
+    const action = registry.resolve(tokens, surface);
+    const remainder = tokens.slice(action.path.length);
+    const { positionals, options } = parseOptions(remainder, action);
+    return createInvocation(action, positionals, options, surface);
+}
+/**
+ * Validates an already selected action. Protocol callers use this when the
+ * action id and parsed values are transported separately from the command
+ * text, while direct and TUI callers continue to use token parsing above.
+ */
+export function parseCommandInvocationForAction(actionId, positionals, options, surface, registry) {
+    const action = registry.get(actionId);
+    if (action === undefined)
+        throw invalidArgument(`Unknown command action: ${actionId}.`);
+    if (!action.surfaces.includes(surface))
+        throw invalidArgument(`Command action ${actionId} is not available on the ${surface} surface.`);
+    return createInvocation(action, positionals, options, surface);
+}
+function createInvocation(action, positionals, options, surface) {
+    validateArguments(action, positionals);
+    validateOptions(action, options, surface);
+    return {
+        surface,
+        action,
+        positionals,
+        options,
+        handlerPositionals: [...(action.handlerPath ?? action.path.slice(1)), ...positionals],
+    };
+}
+function parseOptions(tokens, action) {
+    const positionals = [];
+    const options = new Map();
+    const definitions = new Map((action.options ?? []).map((option) => [option.name, option]));
+    let optionParsing = true;
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (optionParsing && token === '--') {
+            optionParsing = false;
+            continue;
+        }
+        if (!optionParsing || !token.startsWith('--') || token.length === 2) {
+            positionals.push(token);
+            continue;
+        }
+        const separator = token.indexOf('=');
+        const name = token.slice(2, separator < 0 ? undefined : separator);
+        const definition = definitions.get(name);
+        if (definition === undefined)
+            throw invalidArgument(`Unsupported option --${name} for ${action.path.join(' ')}.`);
+        if (options.has(name))
+            throw invalidArgument(`Option --${name} was provided more than once.`);
+        const inlineValue = separator < 0 ? undefined : token.slice(separator + 1);
+        if (definition.valueName === undefined) {
+            if (inlineValue !== undefined && inlineValue !== 'true')
+                throw invalidArgument(`Option --${name} does not accept a value.`);
+            options.set(name, inlineValue === undefined ? true : inlineValue);
+            continue;
+        }
+        const next = tokens[index + 1];
+        const value = inlineValue ?? (next === undefined || next === '--' || next.startsWith('--') ? undefined : next);
+        if (value === undefined || value.trim().length === 0)
+            throw missingArgument(`Missing value for --${name}.`);
+        if (inlineValue === undefined)
+            index += 1;
+        options.set(name, value);
+    }
+    return { positionals, options };
+}
+function validateArguments(action, positionals) {
+    const definitions = action.arguments ?? [];
+    const required = definitions.filter((argument) => argument.required).length;
+    if (positionals.length < required) {
+        const missing = definitions[positionals.length];
+        throw missingArgument(`Missing required argument: ${missing?.name ?? 'value'}.`);
+    }
+    const variadic = definitions.at(-1)?.variadic === true;
+    if (!variadic && positionals.length > definitions.length)
+        throw invalidArgument(`Too many arguments for ${action.path.join(' ')}.`);
+}
+function validateOptions(action, options, surface) {
+    const definitions = new Map((action.options ?? []).map((option) => [option.name, option]));
+    for (const name of options.keys()) {
+        if (!definitions.has(name))
+            throw invalidArgument(`Unsupported option --${name} for ${action.path.join(' ')}.`);
+    }
+    for (const definition of action.options ?? []) {
+        const requiredForSurface = definition.required === true || definition.requiredOn?.includes(surface) === true;
+        const conditionMatches = definition.requiredWhen === undefined ? false : matchesCondition(definition.requiredWhen, options);
+        if ((requiredForSurface || conditionMatches) && !options.has(definition.name))
+            throw missingArgument(`Missing required option --${definition.name}.`);
+        const value = options.get(definition.name);
+        if (definition.allowedValues !== undefined && typeof value === 'string' && !definition.allowedValues.includes(value)) {
+            throw invalidArgument(`Invalid value for --${definition.name}. Expected one of: ${definition.allowedValues.join(', ')}.`);
+        }
+    }
+}
+function matchesCondition(condition, options) {
+    const value = options.get(condition.option);
+    const absentMatches = condition.absent === true && value === undefined;
+    const valueMatches = condition.values === undefined ? value !== undefined : typeof value === 'string' && condition.values.includes(value);
+    return absentMatches || valueMatches;
+}
+function missingArgument(userMessage) {
+    return new CliError(CLI_ERROR_CODES.MISSING_ARGUMENT, userMessage, { category: 'arguments', userMessage });
+}
+function invalidArgument(userMessage) {
+    return new CliError(CLI_ERROR_CODES.INVALID_ARGUMENT, userMessage, { category: 'arguments', userMessage });
+}

package/dist/application/commands/command-presentation.d.ts

@@ -0,0 +1,7 @@
+import type { CommandActionSpec, CommandSuggestion, CommandSurface } from './command-contract.js';
+import type { CommandRegistry } from './command-registry.js';
+export declare function formatCommandReference(action: CommandActionSpec, surface: CommandSurface): string;
+export declare function formatCommandUsage(action: CommandActionSpec, surface: CommandSurface): string;
+export declare function formatCommandInvocation(action: CommandActionSpec, surface: CommandSurface, positionals?: readonly string[], options?: ReadonlyMap<string, string | boolean>): string;
+export declare function formatCommandHelp(registry: CommandRegistry, surface: CommandSurface): string;
+export declare function commandSuggestions(input: string, registry: CommandRegistry, surface: CommandSurface): readonly CommandSuggestion[];

package/dist/application/commands/command-presentation.js

@@ -0,0 +1,131 @@
+import { tokenizeCommandInput } from './command-parser.js';
+export function formatCommandReference(action, surface) {
+    return `${surface === 'direct' ? 'lotagate ' : '/'}${action.path.join(' ')}`;
+}
+export function formatCommandUsage(action, surface) {
+    const argumentTokens = formatArgumentTokens(action);
+    const optionTokens = (action.options ?? []).map((option) => {
+        const value = option.valueName === undefined ? `--${option.name}` : `--${option.name} ${option.valueName}`;
+        return isOptionRequired(option, surface) ? value : `[${value}]`;
+    });
+    return [formatCommandReference(action, surface), ...argumentTokens, ...optionTokens].join(' ');
+}
+export function formatCommandInvocation(action, surface, positionals = [], options = new Map()) {
+    const optionTokens = [...options.entries()].flatMap(([name, value]) => value === true ? [`--${name}`] : [`--${name}`, value]);
+    return [formatCommandReference(action, surface), ...positionals, ...optionTokens].join(' ');
+}
+export function formatCommandHelp(registry, surface) {
+    const rows = registry.list(surface)
+        .map((action) => ({ usage: formatCommandUsage(action, surface), summary: action.summary }));
+    const width = Math.max(...rows.map((row) => row.usage.length), 0);
+    const header = surface === 'direct' ? 'LotaGate CLI commands:' : 'Interactive commands:';
+    return `${header}\n${rows.map((row) => `  ${row.usage.padEnd(width)}  ${row.summary}`).join('\n')}`;
+}
+export function commandSuggestions(input, registry, surface) {
+    const prefix = surface === 'tui' ? '/' : '';
+    const source = surface === 'tui' ? input.trimStart().slice(1) : input.trimStart();
+    const trailingSpace = /\s$/u.test(source);
+    const tokens = tokenizeCommandInput(source);
+    if (tokens.length === 0)
+        return rootSuggestions(prefix, registry, surface, '');
+    if (tokens.length === 1 && !trailingSpace)
+        return rootSuggestions(prefix, registry, surface, tokens[0]);
+    const root = tokens[0].toLowerCase();
+    const allRootActions = registry.actionsForRoot(root, surface);
+    const rootActions = allRootActions.filter((action) => !action.hiddenFromHelp);
+    if (allRootActions.length === 0)
+        return [];
+    const currentSubcommand = trailingSpace ? '' : tokens[1] ?? '';
+    if (tokens.length <= 2) {
+        const defaultAction = findDefaultRootAction(allRootActions);
+        const exactSubcommand = tokens.length === 2 && rootActions.some((action) => action.path.length === 2 && action.path[1] === tokens[1]?.toLowerCase());
+        const partialSubcommand = !trailingSpace && tokens.length === 2 && rootActions.some((action) => action.path.length === 2 && action.path[1].startsWith(currentSubcommand.toLowerCase()));
+        if (tokens.length === 1 || (trailingSpace && tokens.length === 1) || exactSubcommand || partialSubcommand) {
+            if (!exactSubcommand)
+                return subcommandSuggestions(prefix, root, currentSubcommand, registry, surface);
+        }
+        else if (defaultAction !== undefined)
+            return optionSuggestions(input, defaultAction, surface, tokens);
+        else
+            return subcommandSuggestions(prefix, root, currentSubcommand, registry, surface);
+    }
+    const action = resolveSuggestionAction(tokens, registry, surface);
+    if (action === undefined)
+        return subcommandSuggestions(prefix, root, currentSubcommand, registry, surface);
+    if (!trailingSpace && tokens.length === action.path.length)
+        return [toCommandSuggestion(action, surface)];
+    return optionSuggestions(input, action, surface, tokens);
+}
+function rootSuggestions(prefix, registry, surface, query) {
+    const roots = new Map();
+    for (const action of registry.list(surface))
+        if (!roots.has(action.path[0]))
+            roots.set(action.path[0], action);
+    return [...roots.entries()]
+        .filter(([name]) => name.startsWith(query.toLowerCase()))
+        .map(([name, action]) => ({ value: `${prefix}${name}`, label: `${prefix}${name}`, description: action.summary }));
+}
+function subcommandSuggestions(prefix, root, query, registry, surface) {
+    const choices = new Map();
+    const actions = registry.actionsForRoot(root, surface);
+    for (const action of actions) {
+        if (action.hiddenFromHelp || action.path.length < 2)
+            continue;
+        const subcommand = action.path[1];
+        if (!subcommand.startsWith(query.toLowerCase()) || choices.has(subcommand))
+            continue;
+        choices.set(subcommand, action);
+    }
+    const defaultAction = findDefaultRootAction(actions);
+    return [
+        ...(defaultAction === undefined || !(defaultAction.arguments?.some((argument) => argument.required) ?? false) ? [] : [toCommandSuggestion(defaultAction, surface, prefix)]),
+        ...[...choices.values()].map((action) => toCommandSuggestion(action, surface, prefix)),
+    ];
+}
+function findDefaultRootAction(actions) {
+    return actions.find((action) => action.defaultAction === true && action.path.length === 1)
+        ?? actions.find((action) => action.path.length === 1 && !action.hiddenFromHelp);
+}
+function optionSuggestions(input, action, surface, tokens) {
+    const prefix = surface === 'tui' ? '/' : '';
+    const used = new Set(tokens.filter((token) => token.startsWith('--')).map((token) => token.slice(2).split('=')[0]));
+    const source = surface === 'tui' ? input.trimStart().slice(1) : input.trimStart();
+    const trailingSpace = /\s$/u.test(source);
+    const current = trailingSpace ? '' : tokens.at(-1) ?? '';
+    if (!current.startsWith('--'))
+        return [];
+    const replacementBase = trailingSpace ? source.trimEnd() : source.slice(0, Math.max(0, source.lastIndexOf(' '))).trimEnd();
+    return (action.options ?? [])
+        .filter((option) => !used.has(option.name) && `--${option.name}`.startsWith(current))
+        .map((option) => {
+        const token = `--${option.name}`;
+        const value = `${prefix}${replacementBase}${replacementBase.length === 0 ? '' : ' '}${token}`;
+        const label = option.valueName === undefined ? token : `${token} ${option.valueName}`;
+        return { value, label: isOptionRequired(option, surface) ? label : `[${label}]`, description: option.description };
+    });
+}
+function resolveSuggestionAction(tokens, registry, surface) {
+    try {
+        return registry.resolve(tokens, surface);
+    }
+    catch {
+        return undefined;
+    }
+}
+function toCommandSuggestion(action, surface, prefix) {
+    const value = prefix === undefined ? formatCommandReference(action, surface) : `${prefix}${action.path.join(' ')}`;
+    const label = formatCommandSuggestion(action, surface);
+    return { value, label, description: action.summary };
+}
+function formatCommandSuggestion(action, surface) {
+    return [formatCommandReference(action, surface), ...formatArgumentTokens(action)].join(' ');
+}
+function formatArgumentTokens(action) {
+    return (action.arguments ?? []).map((argument) => {
+        const value = argument.variadic ? `${argument.name}...` : argument.name;
+        return argument.required ? `<${value}>` : `[${value}]`;
+    });
+}
+function isOptionRequired(option, surface) {
+    return option.required === true || option.requiredOn?.includes(surface) === true;
+}

package/dist/application/commands/command-registry.d.ts

@@ -0,0 +1,11 @@
+import type { CommandActionSpec, CommandSurface } from './command-contract.js';
+export declare class CommandRegistry {
+    private readonly actions;
+    private readonly byId;
+    constructor(actions: readonly CommandActionSpec[]);
+    get(id: string): CommandActionSpec | undefined;
+    list(surface: CommandSurface, includeHidden?: boolean): readonly CommandActionSpec[];
+    actionsForRoot(root: string, surface: CommandSurface): readonly CommandActionSpec[];
+    resolve(tokens: readonly string[], surface: CommandSurface): CommandActionSpec;
+    private assertNoSurfaceCollisions;
+}