@shepai/cli 1.54.0 → 1.55.0

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();
     }