@cleocode/cleo 2026.4.31 → 2026.4.35

package/dist/cli/commands/web.js

@@ -0,0 +1,277 @@
+/**
+ * CLI web command - manage CLEO Web UI server lifecycle.
+ * Ported from scripts/web.sh
+ * @task T4551
+ * @epic T4545
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError, formatError, getCleoHome } from '@cleocode/core';
+import { cliOutput } from '../renderers/index.js';
+const DEFAULT_PORT = 3456;
+const DEFAULT_HOST = '127.0.0.1';
+/**
+ * Get web server file paths.
+ * @task T4551
+ */
+function getWebPaths() {
+    const cleoHome = getCleoHome();
+    return {
+        pidFile: join(cleoHome, 'web-server.pid'),
+        configFile: join(cleoHome, 'web-server.json'),
+        logFile: join(cleoHome, 'logs', 'web-server.log'),
+    };
+}
+/**
+ * Check if a process is running by PID.
+ * @task T4551
+ */
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get server status.
+ * @task T4551
+ */
+async function getStatus() {
+    const { pidFile, configFile } = getWebPaths();
+    try {
+        const pidStr = (await readFile(pidFile, 'utf-8')).trim();
+        const pid = parseInt(pidStr, 10);
+        if (Number.isNaN(pid) || !isProcessRunning(pid)) {
+            return { running: false, pid: null, port: null, host: null, url: null };
+        }
+        let port = DEFAULT_PORT;
+        let host = DEFAULT_HOST;
+        try {
+            const config = JSON.parse(await readFile(configFile, 'utf-8'));
+            port = config.port ?? DEFAULT_PORT;
+            host = config.host ?? DEFAULT_HOST;
+        }
+        catch {
+            // Use defaults
+        }
+        return { running: true, pid, port, host, url: `http://${host}:${port}` };
+    }
+    catch {
+        return { running: false, pid: null, port: null, host: null, url: null };
+    }
+}
+/**
+ * Register the web command.
+ * @task T4551
+ */
+export function registerWebCommand(program) {
+    const webCmd = program.command('web').description('Manage CLEO Web UI server');
+    webCmd
+        .command('start')
+        .description('Start the web server')
+        .option('--port <port>', 'Server port', String(DEFAULT_PORT))
+        .option('--host <host>', 'Server host', DEFAULT_HOST)
+        .action(async (opts) => {
+        try {
+            const port = parseInt(opts['port'], 10);
+            const host = opts['host'];
+            const { pidFile, configFile, logFile } = getWebPaths();
+            // Check if already running
+            const status = await getStatus();
+            if (status.running) {
+                throw new CleoError(ExitCode.GENERAL_ERROR, `Server already running (PID: ${status.pid})`);
+            }
+            // Resolve server location from the main @cleocode/cleo package
+            const projectRoot = process.env['CLEO_ROOT'] ?? process.cwd();
+            const distServerDir = join(projectRoot, 'dist', 'cli');
+            // Ensure log directory exists
+            await mkdir(join(getCleoHome(), 'logs'), { recursive: true });
+            // Save config
+            await writeFile(configFile, JSON.stringify({
+                port,
+                host,
+                startedAt: new Date().toISOString(),
+            }));
+            // Check if server is built (dist/cli/index.js from @cleocode/cleo)
+            const webIndexPath = join(distServerDir, 'index.js');
+            try {
+                await stat(webIndexPath);
+            }
+            catch {
+                // Need to build
+                try {
+                    execFileSync('npm', ['run', 'build'], { cwd: projectRoot, stdio: 'ignore' });
+                }
+                catch {
+                    throw new CleoError(ExitCode.GENERAL_ERROR, `Build failed. Check logs: ${logFile}`);
+                }
+            }
+            // Start server
+            const serverProcess = spawn('node', [webIndexPath], {
+                cwd: projectRoot,
+                env: {
+                    ...process.env,
+                    CLEO_WEB_PORT: String(port),
+                    CLEO_WEB_HOST: host,
+                },
+                detached: true,
+                stdio: 'ignore',
+            });
+            serverProcess.unref();
+            await writeFile(pidFile, String(serverProcess.pid));
+            // Wait for server to respond
+            const maxAttempts = 30;
+            let started = false;
+            for (let i = 0; i < maxAttempts; i++) {
+                try {
+                    const response = await fetch(`http://${host}:${port}/api/health`);
+                    if (response.ok) {
+                        started = true;
+                        break;
+                    }
+                }
+                catch {
+                    // Not ready yet
+                }
+                await new Promise((resolve) => setTimeout(resolve, 500));
+            }
+            if (!started) {
+                try {
+                    process.kill(serverProcess.pid);
+                }
+                catch {
+                    /* ignore */
+                }
+                await rm(pidFile, { force: true });
+                throw new CleoError(ExitCode.GENERAL_ERROR, 'Server failed to start within 15 seconds');
+            }
+            cliOutput({
+                pid: serverProcess.pid,
+                port,
+                host,
+                url: `http://${host}:${port}`,
+            }, { command: 'web', message: `CLEO Web UI running on port ${port}` });
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+    webCmd
+        .command('stop')
+        .description('Stop the web server')
+        .action(async () => {
+        try {
+            const { pidFile } = getWebPaths();
+            const status = await getStatus();
+            if (!status.running || !status.pid) {
+                // Clean up stale PID file
+                await rm(pidFile, { force: true });
+                cliOutput({ running: false }, { command: 'web', message: 'Server is not running' });
+                return;
+            }
+            // Graceful shutdown (cross-platform)
+            try {
+                if (process.platform === 'win32') {
+                    spawn('taskkill', ['/PID', String(status.pid), '/T'], { stdio: 'ignore' });
+                }
+                else {
+                    process.kill(status.pid, 'SIGTERM');
+                }
+            }
+            catch {
+                /* ignore */
+            }
+            // Wait for exit
+            for (let i = 0; i < 10; i++) {
+                if (!isProcessRunning(status.pid))
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, 500));
+            }
+            // Force kill if still running
+            if (isProcessRunning(status.pid)) {
+                try {
+                    if (process.platform === 'win32') {
+                        spawn('taskkill', ['/PID', String(status.pid), '/F', '/T'], { stdio: 'ignore' });
+                    }
+                    else {
+                        process.kill(status.pid, 'SIGKILL');
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            await rm(pidFile, { force: true });
+            cliOutput({ stopped: true }, { command: 'web', message: 'CLEO Web UI stopped' });
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+    webCmd
+        .command('status')
+        .description('Check server status')
+        .action(async () => {
+        try {
+            const status = await getStatus();
+            cliOutput(status, { command: 'web' });
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+    webCmd
+        .command('open')
+        .description('Open browser to the UI')
+        .action(async () => {
+        try {
+            const status = await getStatus();
+            if (!status.running || !status.url) {
+                throw new CleoError(ExitCode.GENERAL_ERROR, 'Web server is not running. Start with: cleo web start');
+            }
+            // Try to open browser
+            const url = status.url;
+            const platform = process.platform;
+            try {
+                if (platform === 'linux') {
+                    spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+                }
+                else if (platform === 'darwin') {
+                    spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+                }
+                else if (platform === 'win32') {
+                    spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+                }
+            }
+            catch {
+                // Can't open browser — user can open manually
+            }
+            cliOutput({ url }, { command: 'web', message: `Open browser to: ${url}` });
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=web.js.map

package/dist/cli/commands/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../../../src/cli/commands/web.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGrE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,MAAM,YAAY,GAAG,IAAI,CAAC;AAC1B,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC;;;GAGG;AACH,SAAS,WAAW;IAClB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC;QACzC,UAAU,EAAE,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QAC7C,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC;KAClD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,SAAS;IAOtB,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,WAAW,EAAE,CAAC;IAE9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAEjC,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;YAChD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;QAC1E,CAAC;QAED,IAAI,IAAI,GAAG,YAAY,CAAC;QACxB,IAAI,IAAI,GAAG,YAAY,CAAC;QAExB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;YAC/D,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,YAAY,CAAC;YACnC,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,YAAY,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IAC1E,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;IAE/E,MAAM;SACH,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,sBAAsB,CAAC;SACnC,MAAM,CAAC,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;SAC5D,MAAM,CAAC,eAAe,EAAE,aAAa,EAAE,YAAY,CAAC;SACpD,MAAM,CAAC,KAAK,EAAE,IAA6B,EAAE,EAAE;QAC9C,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAW,EAAE,EAAE,CAAC,CAAC;YAClD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAW,CAAC;YACpC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC;YAEvD,2BAA2B;YAC3B,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;YACjC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,aAAa,EACtB,gCAAgC,MAAM,CAAC,GAAG,GAAG,CAC9C,CAAC;YACJ,CAAC;YAED,+DAA+D;YAC/D,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAC9D,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;YAEvD,8BAA8B;YAC9B,MAAM,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAE9D,cAAc;YACd,MAAM,SAAS,CACb,UAAU,EACV,IAAI,CAAC,SAAS,CAAC;gBACb,IAAI;gBACJ,IAAI;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC,CACH,CAAC;YAEF,mEAAmE;YACnE,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;YACrD,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,YAAY,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,gBAAgB;gBAChB,IAAI,CAAC;oBACH,YAAY,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;gBAC/E,CAAC;gBAAC,MAAM,CAAC;oBACP,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,6BAA6B,OAAO,EAAE,CAAC,CAAC;gBACtF,CAAC;YACH,CAAC;YAED,eAAe;YACf,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,EAAE;gBAClD,GAAG,EAAE,WAAW;gBAChB,GAAG,EAAE;oBACH,GAAG,OAAO,CAAC,GAAG;oBACd,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC;oBAC3B,aAAa,EAAE,IAAI;iBACpB;gBACD,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,QAAQ;aAChB,CAAC,CAAC;YAEH,aAAa,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;YAEpD,6BAA6B;YAC7B,MAAM,WAAW,GAAG,EAAE,CAAC;YACvB,IAAI,OAAO,GAAG,KAAK,CAAC;YAEpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,IAAI,CAAC;oBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,UAAU,IAAI,IAAI,IAAI,aAAa,CAAC,CAAC;oBAClE,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;wBAChB,OAAO,GAAG,IAAI,CAAC;wBACf,MAAM;oBACR,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,gBAAgB;gBAClB,CAAC;gBACD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAC3D,CAAC;YAED,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,GAAI,CAAC,CAAC;gBACnC,CAAC;gBAAC,MAAM,CAAC;oBACP,YAAY;gBACd,CAAC;gBACD,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnC,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,0CAA0C,CAAC,CAAC;YAC1F,CAAC;YAED,SAAS,CACP;gBACE,GAAG,EAAE,aAAa,CAAC,GAAG;gBACtB,IAAI;gBACJ,IAAI;gBACJ,GAAG,EAAE,UAAU,IAAI,IAAI,IAAI,EAAE;aAC9B,EACD,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,+BAA+B,IAAI,EAAE,EAAE,CACnE,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;gBAC7B,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,MAAM;SACH,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,qBAAqB,CAAC;SAClC,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,IAAI,CAAC;YACH,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;YAEjC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;gBACnC,0BAA0B;gBAC1B,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;gBACpF,OAAO;YACT,CAAC;YAED,qCAAqC;YACrC,IAAI,CAAC;gBACH,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;oBACjC,KAAK,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;gBAC7E,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;gBACtC,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YAED,gBAAgB;YAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5B,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC;oBAAE,MAAM;gBACzC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAC3D,CAAC;YAED,8BAA8B;YAC9B,IAAI,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjC,IAAI,CAAC;oBACH,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;wBACjC,KAAK,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;oBACnF,CAAC;yBAAM,CAAC;wBACN,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;oBACtC,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,YAAY;gBACd,CAAC;YACH,CAAC;YAED,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAEnC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC,CAAC;QACnF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;gBAC7B,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,MAAM;SACH,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,qBAAqB,CAAC;SAClC,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;YACjC,SAAS,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;gBAC7B,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,MAAM;SACH,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,wBAAwB,CAAC;SACrC,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;gBACnC,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,aAAa,EACtB,uDAAuD,CACxD,CAAC;YACJ,CAAC;YAED,sBAAsB;YACtB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;YACvB,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;YAElC,IAAI,CAAC;gBACH,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;oBACzB,KAAK,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;gBACxE,CAAC;qBAAM,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBACjC,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;gBACpE,CAAC;qBAAM,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;oBAChC,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;gBACtF,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,8CAA8C;YAChD,CAAC;YAED,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,oBAAoB,GAAG,EAAE,EAAE,CAAC,CAAC;QAC7E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;gBAC7B,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/field-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI field extraction context.
+ *
+ * Singleton that holds the resolved field extraction options for the current
+ * CLI invocation. Set once in the Commander.js preAction hook; read by
+ * dispatchFromCli() to apply field filtering and MVI control universally
+ * across all commands.
+ *
+ * Delegates to @cleocode/lafs v1.5.0 resolveFieldExtraction()
+ * for canonical conflict detection, flag parsing, and type resolution.
+ * Mirrors the format-context.ts pattern for --json/--human/--quiet.
+ *
+ * @epic T4953
+ * @task T4979
+ */
+import { type FieldExtractionResolution } from '@cleocode/lafs';
+export type { FieldExtractionResolution as FieldContext };
+/**
+ * Set the field extraction context for this CLI invocation.
+ * Called once from the preAction hook in src/cli/index.ts.
+ */
+export declare function setFieldContext(ctx: FieldExtractionResolution): void;
+/**
+ * Get the current field extraction context.
+ */
+export declare function getFieldContext(): FieldExtractionResolution;
+/**
+ * Parse global field options from Commander.js parsed opts and resolve via
+ * the canonical LAFS SDK resolver (conflict detection, type narrowing).
+ */
+export declare function resolveFieldContext(opts: Record<string, unknown>): FieldExtractionResolution;
+//# sourceMappingURL=field-context.d.ts.map

package/dist/cli/field-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-context.d.ts","sourceRoot":"","sources":["../../src/cli/field-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAEL,KAAK,yBAAyB,EAE/B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,yBAAyB,IAAI,YAAY,EAAE,CAAC;AAQ1D;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,yBAAyB,GAAG,IAAI,CAEpE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,yBAAyB,CAE3D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,yBAAyB,CAO5F"}

package/dist/cli/field-context.js

@@ -0,0 +1,47 @@
+/**
+ * CLI field extraction context.
+ *
+ * Singleton that holds the resolved field extraction options for the current
+ * CLI invocation. Set once in the Commander.js preAction hook; read by
+ * dispatchFromCli() to apply field filtering and MVI control universally
+ * across all commands.
+ *
+ * Delegates to @cleocode/lafs v1.5.0 resolveFieldExtraction()
+ * for canonical conflict detection, flag parsing, and type resolution.
+ * Mirrors the format-context.ts pattern for --json/--human/--quiet.
+ *
+ * @epic T4953
+ * @task T4979
+ */
+import { resolveFieldExtraction, } from '@cleocode/lafs';
+let currentContext = {
+    mvi: 'minimal',
+    mviSource: 'default',
+    expectsCustomMvi: false,
+};
+/**
+ * Set the field extraction context for this CLI invocation.
+ * Called once from the preAction hook in src/cli/index.ts.
+ */
+export function setFieldContext(ctx) {
+    currentContext = ctx;
+}
+/**
+ * Get the current field extraction context.
+ */
+export function getFieldContext() {
+    return currentContext;
+}
+/**
+ * Parse global field options from Commander.js parsed opts and resolve via
+ * the canonical LAFS SDK resolver (conflict detection, type narrowing).
+ */
+export function resolveFieldContext(opts) {
+    const input = {
+        fieldFlag: typeof opts['field'] === 'string' ? opts['field'] : undefined,
+        fieldsFlag: typeof opts['fields'] === 'string' ? opts['fields'] : undefined,
+        mviFlag: typeof opts['mvi'] === 'string' ? opts['mvi'] : undefined,
+    };
+    return resolveFieldExtraction(input);
+}
+//# sourceMappingURL=field-context.js.map

package/dist/cli/field-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-context.js","sourceRoot":"","sources":["../../src/cli/field-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAIxB,IAAI,cAAc,GAA8B;IAC9C,GAAG,EAAE,SAAS;IACd,SAAS,EAAE,SAAS;IACpB,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAA8B;IAC5D,cAAc,GAAG,GAAG,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC/D,MAAM,KAAK,GAAyB;QAClC,SAAS,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;QACxE,UAAU,EAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;QAC3E,OAAO,EAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;KACnE,CAAC;IACF,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/cli/format-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI output format resolution context.
+ *
+ * Singleton that holds the resolved output format for the current CLI invocation.
+ * Set once in the Commander.js preAction hook; read by cliOutput() and renderers.
+ *
+ * @task T4665
+ * @epic T4663
+ */
+import type { FlagResolution } from '@cleocode/lafs';
+/**
+ * Set the resolved format for this CLI invocation.
+ * Called once from the preAction hook in src/cli/index.ts.
+ */
+export declare function setFormatContext(resolution: FlagResolution): void;
+/**
+ * Get the current resolved format.
+ */
+export declare function getFormatContext(): FlagResolution;
+/**
+ * Check if output should be JSON format.
+ */
+export declare function isJsonFormat(): boolean;
+/**
+ * Check if output should be human-readable format.
+ */
+export declare function isHumanFormat(): boolean;
+/**
+ * Check if quiet mode is enabled (suppress non-essential output).
+ */
+export declare function isQuiet(): boolean;
+//# sourceMappingURL=format-context.d.ts.map

package/dist/cli/format-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-context.d.ts","sourceRoot":"","sources":["../../src/cli/format-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAYrD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAEjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAEjD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAEjC"}

package/dist/cli/format-context.js

@@ -0,0 +1,50 @@
+/**
+ * CLI output format resolution context.
+ *
+ * Singleton that holds the resolved output format for the current CLI invocation.
+ * Set once in the Commander.js preAction hook; read by cliOutput() and renderers.
+ *
+ * @task T4665
+ * @epic T4663
+ */
+/**
+ * Current resolved format for this CLI invocation.
+ * Defaults to JSON (agent-first) until resolved by preAction hook.
+ */
+let currentResolution = {
+    format: 'json',
+    source: 'default',
+    quiet: false,
+};
+/**
+ * Set the resolved format for this CLI invocation.
+ * Called once from the preAction hook in src/cli/index.ts.
+ */
+export function setFormatContext(resolution) {
+    currentResolution = resolution;
+}
+/**
+ * Get the current resolved format.
+ */
+export function getFormatContext() {
+    return currentResolution;
+}
+/**
+ * Check if output should be JSON format.
+ */
+export function isJsonFormat() {
+    return currentResolution.format === 'json';
+}
+/**
+ * Check if output should be human-readable format.
+ */
+export function isHumanFormat() {
+    return currentResolution.format === 'human';
+}
+/**
+ * Check if quiet mode is enabled (suppress non-essential output).
+ */
+export function isQuiet() {
+    return currentResolution.quiet;
+}
+//# sourceMappingURL=format-context.js.map

package/dist/cli/format-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-context.js","sourceRoot":"","sources":["../../src/cli/format-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;GAGG;AACH,IAAI,iBAAiB,GAAmB;IACtC,MAAM,EAAE,MAAM;IACd,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,KAAK;CACb,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA0B;IACzD,iBAAiB,GAAG,UAAU,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,iBAAiB,CAAC,MAAM,KAAK,MAAM,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,iBAAiB,CAAC,MAAM,KAAK,OAAO,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO;IACrB,OAAO,iBAAiB,CAAC,KAAK,CAAC;AACjC,CAAC"}

package/dist/cli/help-generator.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ParamDef-driven Commander help generator.
+ *
+ * Provides two functions:
+ *  - `buildOperationHelp()` — emits a multi-section help string (Description,
+ *    USAGE, ARGUMENTS, OPTIONS, PRECONDITIONS) from a ParamDef array and the
+ *    static LAFS gate table.
+ *  - `applyParamDefsToCommand()` — replaces hand-written `.option()` chains on
+ *    a ShimCommand with generated calls derived from the same ParamDef array.
+ *
+ * Both functions read exactly the same source of truth that the dispatch
+ * registry and `cleo schema` use, eliminating the duplication that caused
+ * missing enum values, absent required indicators, and hidden gate docs.
+ *
+ * Gate lookup uses `describeOperation()` from `@cleocode/lafs`, which is the
+ * public API over the static LAFS gate table in `operation-gates.ts`.
+ *
+ * @module
+ * @epic T335
+ * @task T339
+ */
+import type { ParamDef } from '../dispatch/types.js';
+import type { ShimCommand } from './commander-shim.js';
+/**
+ * Build a multi-section Commander-compatible help string from a ParamDef
+ * array and the static LAFS gate table.
+ *
+ * Sections emitted:
+ * - `Description:` — one-line operation summary
+ * - `USAGE:` — positional args listed in required/optional angle/square brackets
+ * - `ARGUMENTS:` — positional params with descriptions (omitted when none)
+ * - `OPTIONS:` — flag params with type, enum values, and required indicator
+ * - `PRECONDITIONS:` — gates sourced from `packages/lafs/src/operation-gates.ts`
+ *   via `describeOperation()` (omitted when the gate table has no entry for
+ *   this operation key)
+ * - `Examples:` — pre-canned examples for the five seeded operations
+ *
+ * @param operationKey - Fully-qualified operation key, e.g. `"tasks.add"`.
+ * @param description - One-line summary of the operation.
+ * @param params - ParamDef array for the operation.
+ * @returns Multi-line help string.
+ */
+export declare function buildOperationHelp(operationKey: string, description: string, params: readonly ParamDef[]): string;
+/**
+ * Register Commander options and positional arguments on a ShimCommand from
+ * a ParamDef array.
+ *
+ * Replaces hand-written `.option(...)` chains with a single call.
+ *
+ * Handles:
+ * - Positional args (`cli.positional === true`) → `.argument()`
+ * - Short aliases (`cli.short`) → `-s, --flag <type>`
+ * - Flag name overrides (`cli.flag`) → `--custom-flag`
+ * - Boolean flags (type === `'boolean'`) → no value placeholder
+ * - Custom parse functions (`cli.parse`) → forwarded to `.option()`
+ * - Enum constraints surfaced in the option description
+ * - Required vs optional indicators appended to the description
+ *
+ * **Note:** The caller is still responsible for the `.action(...)` callback
+ * because action bodies are command-specific and cannot be auto-generated.
+ *
+ * **Hybrid pattern:** Some commands keep hand-written `.option()` calls after
+ * this call for options that have no ParamDef entry (e.g. `--dry-run`,
+ * `--field`, `--format`, `--desc`). That is intentional — those options are
+ * CLI-surface-only and do not belong in the dispatch registry.
+ *
+ * @param command - The ShimCommand returned by `.command(nameAndArgs)`.
+ * @param params - The ParamDef array for this operation.
+ * @param operationKey - `"tasks.add"` etc. Reserved for future hook or tracing
+ *   use; currently not mutated on the shim since ShimCommand has no first-class
+ *   help-text override API.
+ */
+export declare function applyParamDefsToCommand(command: ShimCommand, params: readonly ParamDef[], operationKey: string): void;
+//# sourceMappingURL=help-generator.d.ts.map

package/dist/cli/help-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-generator.d.ts","sourceRoot":"","sources":["../../src/cli/help-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAsEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,QAAQ,EAAE,GAC1B,MAAM,CAwFR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,YAAY,EAAE,MAAM,GACnB,IAAI,CAmCN"}