@shepai/cli 1.54.0 → 1.55.1

package/dist/src/presentation/cli/commands/daemon/start-daemon.js

@@ -0,0 +1,135 @@
+/**
+ * startDaemon() — Shared daemon-spawn helper
+ *
+ * Contains the parent-side logic for starting the Shep web UI as a
+ * detached background daemon. Used by both:
+ *   - The default `shep` action (index.ts)
+ *   - The `shep start` command (start.command.ts)
+ *
+ * Flow:
+ *   1. Resolve available port (respects --port override)
+ *   2. Check if daemon is already running (idempotent — print URL and return)
+ *   3. Spawn the daemon with execArgv propagated (supports tsx in dev mode)
+ *      {detached: true, stdio: ['ignore','ignore','pipe']} + child.unref()
+ *   4. Wait briefly to confirm the child is alive; surface stderr on crash
+ *   5. Write daemon.json atomically via IDaemonService
+ *   6. Print formatted URL to stdout
+ *   7. Open browser via BrowserOpenerService
+ */
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import { container } from '../../../../../packages/core/src/infrastructure/di/container.js';
+import { findAvailablePort, DEFAULT_PORT } from '../../../../../packages/core/src/infrastructure/services/port.service.js';
+import { BrowserOpenerService } from '../../../../../packages/core/src/infrastructure/services/browser-opener.service.js';
+import { fmt, messages, spinner } from '../../ui/index.js';
+/** How long to wait (ms) after spawn to verify the child is still alive. */
+const SPAWN_SETTLE_MS = 500;
+/** Max time (ms) to wait for the server to become reachable before opening the browser. */
+const READY_TIMEOUT_MS = 30_000;
+/** Interval (ms) between readiness probes. */
+const READY_POLL_MS = 300;
+/**
+ * Start the Shep web UI as a detached background daemon.
+ * Idempotent: if a daemon is already running, prints the existing URL and returns.
+ */
+export async function startDaemon(opts = {}) {
+    const daemonService = container.resolve('IDaemonService');
+    // Check for an already-running daemon
+    const existing = await daemonService.read();
+    if (existing && daemonService.isAlive(existing.pid)) {
+        const url = `http://localhost:${existing.port}`;
+        messages.newline();
+        messages.info(`Shep is already running at ${fmt.code(url)}`);
+        messages.newline();
+        return;
+    }
+    // Resolve the port
+    const startPort = opts.port ?? DEFAULT_PORT;
+    const port = await findAvailablePort(startPort);
+    // Spawn the daemon as a detached child process.
+    // Propagate process.execArgv so tsx loader hooks (--require / --import) are
+    // available in dev mode. In production (compiled JS), execArgv is empty.
+    const child = spawn(process.execPath, [...process.execArgv, process.argv[1], '_serve', '--port', String(port)], {
+        detached: true,
+        // Keep stderr piped so we can surface startup errors; stdin/stdout detached.
+        stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    // Collect stderr in case the child crashes during startup.
+    let stderrChunks = [];
+    child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+    // Wait briefly for the child to either settle or crash.
+    const exitCode = await Promise.race([
+        new Promise((resolve) => child.on('exit', (code) => resolve(code))),
+        new Promise((resolve) => setTimeout(() => resolve(undefined), SPAWN_SETTLE_MS)),
+    ]);
+    if (exitCode !== undefined) {
+        // Child exited during the settle window — startup failed.
+        const stderr = Buffer.concat(stderrChunks).toString().trim();
+        messages.newline();
+        messages.error(`Daemon failed to start (exit code ${exitCode ?? 'unknown'}).`);
+        if (stderr) {
+            console.error(stderr);
+        }
+        messages.newline();
+        // Clean up stale daemon.json if it exists
+        await daemonService.delete();
+        return;
+    }
+    // Child is alive — detach fully.
+    // Unref stderr so the parent event loop is not held open, then unref the child.
+    child.stderr.destroy();
+    stderrChunks = [];
+    child.unref();
+    // Write daemon.json atomically
+    await daemonService.write({
+        pid: child.pid,
+        port,
+        startedAt: new Date().toISOString(),
+    });
+    const url = `http://localhost:${port}`;
+    messages.newline();
+    console.log(fmt.heading('Shep Web UI'));
+    messages.newline();
+    // Poll until the server responds, with a spinner on stderr.
+    // Skip readiness check in E2E / CI environments where the daemon child
+    // cannot actually start a Next.js server within the test's time window.
+    if (process.env.SHEP_SKIP_READINESS_CHECK) {
+        messages.success(`Daemon spawned at ${fmt.code(url)}`);
+    }
+    else {
+        const ready = await spinner('Starting server', () => waitForServer(url, READY_TIMEOUT_MS));
+        if (ready) {
+            messages.success(`Server ready at ${fmt.code(url)}`);
+        }
+        else {
+            messages.warning(`Server may still be starting at ${fmt.code(url)}`);
+        }
+    }
+    messages.newline();
+    const opener = new BrowserOpenerService({ warn: messages.warning });
+    opener.open(url);
+}
+/**
+ * Poll a URL until it returns any HTTP response (even 500).
+ * Resolves true when reachable, false on timeout.
+ */
+function waitForServer(url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    return new Promise((resolve) => {
+        const probe = () => {
+            if (Date.now() > deadline)
+                return resolve(false);
+            const req = http.get(url, () => {
+                resolve(true);
+            });
+            req.on('error', () => {
+                setTimeout(probe, READY_POLL_MS);
+            });
+            req.setTimeout(2000, () => {
+                req.destroy();
+                setTimeout(probe, READY_POLL_MS);
+            });
+        };
+        probe();
+    });
+}

package/dist/src/presentation/cli/commands/start.command.d.ts

@@ -0,0 +1,15 @@
+/**
+ * start Command
+ *
+ * Starts the Shep web UI as a detached background daemon.
+ * All spawn logic lives in the shared startDaemon() helper to avoid
+ * duplication between this command and the default `shep` action.
+ *
+ * Usage: shep start [--port <number>]
+ */
+import { Command } from 'commander';
+/**
+ * Create the start command.
+ */
+export declare function createStartCommand(): Command;
+//# sourceMappingURL=start.command.d.ts.map

package/dist/src/presentation/cli/commands/start.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.command.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/commands/start.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAW1D;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAc5C"}

package/dist/src/presentation/cli/commands/start.command.js

@@ -0,0 +1,33 @@
+/**
+ * start Command
+ *
+ * Starts the Shep web UI as a detached background daemon.
+ * All spawn logic lives in the shared startDaemon() helper to avoid
+ * duplication between this command and the default `shep` action.
+ *
+ * Usage: shep start [--port <number>]
+ */
+import { Command, InvalidArgumentError } from 'commander';
+import { startDaemon } from './daemon/start-daemon.js';
+function parsePort(value) {
+    const port = parseInt(value, 10);
+    if (isNaN(port) || port < 1024 || port > 65535) {
+        throw new InvalidArgumentError('Port must be an integer between 1024 and 65535');
+    }
+    return port;
+}
+/**
+ * Create the start command.
+ */
+export function createStartCommand() {
+    return new Command('start')
+        .description('Start the Shep web UI as a background daemon')
+        .option('-p, --port <number>', 'Port number (1024-65535)', parsePort)
+        .addHelpText('after', `
+Examples:
+  $ shep start               Start on default port (4050)
+  $ shep start --port 8080   Start on custom port`)
+        .action(async (options) => {
+        await startDaemon({ port: options.port });
+    });
+}

package/dist/src/presentation/cli/commands/status.command.d.ts

@@ -0,0 +1,20 @@
+/**
+ * status Command
+ *
+ * Displays live status and metrics for the running Shep web UI daemon.
+ *
+ * Metrics collected:
+ *   - PID, port, URL (from daemon.json)
+ *   - Uptime (computed from startedAt)
+ *   - CPU%, RSS memory (from ps shell-out via execFile — injection-safe)
+ *
+ * Gracefully degrades if ps is unavailable (timeout or error).
+ *
+ * Usage: shep status
+ */
+import { Command } from 'commander';
+/**
+ * Create the status command.
+ */
+export declare function createStatusCommand(): Command;
+//# sourceMappingURL=status.command.d.ts.map

package/dist/src/presentation/cli/commands/status.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.command.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/commands/status.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+EpC;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CA2C7C"}

package/dist/src/presentation/cli/commands/status.command.js

@@ -0,0 +1,119 @@
+/**
+ * status Command
+ *
+ * Displays live status and metrics for the running Shep web UI daemon.
+ *
+ * Metrics collected:
+ *   - PID, port, URL (from daemon.json)
+ *   - Uptime (computed from startedAt)
+ *   - CPU%, RSS memory (from ps shell-out via execFile — injection-safe)
+ *
+ * Gracefully degrades if ps is unavailable (timeout or error).
+ *
+ * Usage: shep status
+ */
+import { Command } from 'commander';
+import { execFile } from 'node:child_process';
+import { container } from '../../../../packages/core/src/infrastructure/di/container.js';
+import { renderDetailView, messages } from '../ui/index.js';
+const PS_TIMEOUT_MS = 2000;
+/**
+ * Parse ps output: "pid  cpu%  rss_kb\n"
+ * Returns formatted strings for display.
+ */
+function parsePs(output) {
+    const parts = output.trim().split(/\s+/);
+    const cpu = parts[1] ?? '?';
+    const rssKb = parseFloat(parts[2] ?? '0');
+    const rssMb = (rssKb / 1024).toFixed(1);
+    return { cpu, rssMb };
+}
+/**
+ * Human-readable uptime string, e.g. "2h 14m 3s".
+ */
+function humanizeUptime(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    const parts = [];
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    parts.push(`${seconds}s`);
+    return parts.join(' ');
+}
+/**
+ * Shell out to ps for CPU% and RSS, with a timeout guard.
+ * Uses execFile (not exec) — the PID is a separate array argument,
+ * preventing any possibility of shell injection.
+ */
+function fetchPsMetrics(pid) {
+    return new Promise((resolve) => {
+        const pidStr = String(pid);
+        let settled = false;
+        const fallback = () => ({ cpu: 'unavailable', rssMb: 'unavailable' });
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                child.kill();
+                resolve(fallback());
+            }
+        }, PS_TIMEOUT_MS);
+        const child = execFile('ps', ['-o', 'pid=,pcpu=,rss=', '-p', pidStr], { timeout: PS_TIMEOUT_MS }, (err, stdout) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err || !stdout.trim()) {
+                resolve(fallback());
+            }
+            else {
+                resolve(parsePs(stdout));
+            }
+        });
+    });
+}
+/**
+ * Create the status command.
+ */
+export function createStatusCommand() {
+    return new Command('status')
+        .description('Show the status of the Shep web UI daemon')
+        .action(async () => {
+        const daemonService = container.resolve('IDaemonService');
+        const state = await daemonService.read();
+        if (!state || !daemonService.isAlive(state.pid)) {
+            messages.newline();
+            messages.info('Shep daemon is not running.');
+            messages.info('Run `shep start` to launch it.');
+            messages.newline();
+            return;
+        }
+        const { pid, port, startedAt } = state;
+        const url = `http://localhost:${port}`;
+        const uptimeMs = Date.now() - Date.parse(startedAt);
+        const uptime = humanizeUptime(uptimeMs);
+        const { cpu, rssMb } = await fetchPsMetrics(pid);
+        renderDetailView({
+            title: 'Shep Daemon Status',
+            sections: [
+                {
+                    fields: [
+                        { label: 'PID', value: String(pid) },
+                        { label: 'Port', value: String(port) },
+                        { label: 'URL', value: url },
+                        { label: 'Started', value: new Date(startedAt).toLocaleString() },
+                        { label: 'Uptime', value: uptime },
+                        { label: 'CPU %', value: cpu === 'unavailable' ? 'unavailable' : `${cpu}%` },
+                        {
+                            label: 'Memory (RSS)',
+                            value: rssMb === 'unavailable' ? 'unavailable' : `${rssMb} MB`,
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+}

package/dist/src/presentation/cli/commands/stop.command.d.ts

@@ -0,0 +1,22 @@
+/**
+ * stop Command
+ *
+ * Stops the running Shep web UI daemon.
+ *
+ * Stop sequence:
+ *   1. Read daemon.json via IDaemonService
+ *   2. If no daemon / PID not alive: print clear message and exit 0
+ *   3. Validate PID is a positive finite integer
+ *   4. Send SIGTERM
+ *   5. Poll process liveness every 200ms for up to 5000ms
+ *   6. If still alive after 5s, send SIGKILL
+ *   7. Always delete daemon.json (in finally block)
+ *
+ * Usage: shep stop
+ */
+import { Command } from 'commander';
+/**
+ * Create the stop command.
+ */
+export declare function createStopCommand(): Command;
+//# sourceMappingURL=stop.command.d.ts.map

package/dist/src/presentation/cli/commands/stop.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop.command.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/commands/stop.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BpC;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CA+C3C"}

package/dist/src/presentation/cli/commands/stop.command.js

@@ -0,0 +1,79 @@
+/**
+ * stop Command
+ *
+ * Stops the running Shep web UI daemon.
+ *
+ * Stop sequence:
+ *   1. Read daemon.json via IDaemonService
+ *   2. If no daemon / PID not alive: print clear message and exit 0
+ *   3. Validate PID is a positive finite integer
+ *   4. Send SIGTERM
+ *   5. Poll process liveness every 200ms for up to 5000ms
+ *   6. If still alive after 5s, send SIGKILL
+ *   7. Always delete daemon.json (in finally block)
+ *
+ * Usage: shep stop
+ */
+import { Command } from 'commander';
+import { container } from '../../../../packages/core/src/infrastructure/di/container.js';
+import { messages } from '../ui/index.js';
+const POLL_INTERVAL_MS = 200;
+const MAX_WAIT_MS = 5000;
+/**
+ * Poll until the given PID is dead or the timeout expires.
+ * Returns true if the process is dead, false if it survived the timeout.
+ */
+async function pollUntilDead(daemonService, pid, maxMs, intervalMs) {
+    const deadline = Date.now() + maxMs;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        if (!daemonService.isAlive(pid)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Create the stop command.
+ */
+export function createStopCommand() {
+    return new Command('stop').description('Stop the running Shep web UI daemon').action(async () => {
+        const daemonService = container.resolve('IDaemonService');
+        const state = await daemonService.read();
+        // No daemon running or PID not alive
+        if (!state || !daemonService.isAlive(state.pid)) {
+            messages.info('No Shep daemon is running.');
+            await daemonService.delete();
+            return;
+        }
+        const { pid } = state;
+        // Validate PID is a positive finite integer before kill
+        if (!Number.isFinite(pid) || !Number.isInteger(pid) || pid <= 0) {
+            messages.info('No Shep daemon is running (invalid PID in state file).');
+            await daemonService.delete();
+            return;
+        }
+        try {
+            messages.info(`Stopping Shep daemon (PID ${pid})...`);
+            // Send SIGTERM — request graceful shutdown
+            process.kill(pid, 'SIGTERM');
+            // Poll for up to 5s waiting for the process to exit
+            const died = await pollUntilDead(daemonService, pid, MAX_WAIT_MS, POLL_INTERVAL_MS);
+            if (!died) {
+                // Graceful shutdown timed out — force kill
+                messages.info('Daemon did not stop gracefully, sending SIGKILL...');
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch {
+                    // Process may have exited between the check and the kill — ignore
+                }
+            }
+            messages.success('Shep daemon stopped.');
+        }
+        finally {
+            // Always clean up daemon.json regardless of termination path
+            await daemonService.delete();
+        }
+    });
+}

package/dist/src/presentation/cli/index.d.ts

@@ -8,9 +8,12 @@
  *   shep [command] [options]
  *
  * Commands:
- *   shep              Show help
+ *   shep              Start the web UI daemon (or run onboarding on first run)
+ *   shep start        Start the web UI as a background daemon
+ *   shep stop         Stop the running web UI daemon
+ *   shep status       Show status and metrics of the running daemon
  *   shep version      Display version information
- *   shep ui           Start the web UI
+ *   shep ui           Start the web UI (foreground, interactive)
  *   shep run          Run an AI agent workflow
  *   shep agent        Manage and view agent runs
  *   shep feat         Manage features through the SDLC lifecycle

package/dist/src/presentation/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/presentation/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/presentation/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,kBAAkB,CAAC"}

package/dist/src/presentation/cli/index.js

@@ -8,9 +8,12 @@
  *   shep [command] [options]
  *
  * Commands:
- *   shep              Show help
+ *   shep              Start the web UI daemon (or run onboarding on first run)
+ *   shep start        Start the web UI as a background daemon
+ *   shep stop         Stop the running web UI daemon
+ *   shep status       Show status and metrics of the running daemon
  *   shep version      Display version information
- *   shep ui           Start the web UI
+ *   shep ui           Start the web UI (foreground, interactive)
  *   shep run          Run an AI agent workflow
  *   shep agent        Manage and view agent runs
  *   shep feat         Manage features through the SDLC lifecycle
@@ -38,6 +41,12 @@ import { createIdeOpenCommand } from './commands/ide-open.command.js';
 import { createInstallCommand } from './commands/install.command.js';
 import { createUpgradeCommand } from './commands/upgrade.command.js';
 import { messages } from './ui/index.js';
+// Daemon lifecycle commands
+import { createStartCommand } from './commands/start.command.js';
+import { createStopCommand } from './commands/stop.command.js';
+import { createStatusCommand } from './commands/status.command.js';
+import { createServeCommand } from './commands/_serve.command.js';
+import { startDaemon } from './commands/daemon/start-daemon.js';
 // DI container and settings
 import { initializeContainer, container } from '../../../packages/core/src/infrastructure/di/container.js';
 import { InitializeSettingsUseCase } from '../../../packages/core/src/application/use-cases/settings/initialize-settings.use-case.js';
@@ -88,8 +97,13 @@ async function bootstrap() {
             .name('shep')
             .description(description)
             .version(version, '-v, --version', 'Display version number')
-            .action(() => {
-            program.outputHelp();
+            // task-10: Default action starts the daemon (or shows already-running URL).
+            // The onboarding gate above (lines 82-89) ensures the wizard runs on first launch;
+            // after the gate, startDaemon() is the correct next step in both cases.
+            // Commander only fires this action when no subcommand matches, so `shep start` etc.
+            // are unaffected.
+            .action(async () => {
+            await startDaemon();
         });
         // Register commands
         program.addCommand(createVersionCommand());
@@ -103,6 +117,11 @@ async function bootstrap() {
         program.addCommand(createIdeOpenCommand());
         program.addCommand(createInstallCommand());
         program.addCommand(createUpgradeCommand());
+        // Daemon lifecycle commands (task-9)
+        program.addCommand(createStartCommand());
+        program.addCommand(createStopCommand());
+        program.addCommand(createStatusCommand());
+        program.addCommand(createServeCommand()); // hidden from --help
         // Parse arguments (parseAsync needed for async command actions like init)
         await program.parseAsync();
     }