@shepai/cli 1.4.0 → 1.5.0

package/dist/src/infrastructure/services/port.service.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Port Service
+ *
+ * Port availability checking and auto-increment logic for the web server.
+ * Uses node:net try-bind pattern (same approach as Vite).
+ */
+/** Default port for the Shep web UI */
+export declare const DEFAULT_PORT = 4050;
+/** Maximum number of ports to try before giving up */
+export declare const MAX_PORT_ATTEMPTS = 20;
+/**
+ * Check if a port is available by attempting to bind to it.
+ */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/**
+ * Find an available port starting from `startPort`, incrementing up to `maxAttempts`.
+ * Throws if no available port is found or if the port is out of valid range.
+ */
+export declare function findAvailablePort(startPort: number, maxAttempts?: number): Promise<number>;
+//# sourceMappingURL=port.service.d.ts.map

package/dist/src/infrastructure/services/port.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.service.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/port.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,uCAAuC;AACvC,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAKpC;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBpE;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAA0B,GACtC,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/dist/src/infrastructure/services/port.service.js

@@ -0,0 +1,47 @@
+/**
+ * Port Service
+ *
+ * Port availability checking and auto-increment logic for the web server.
+ * Uses node:net try-bind pattern (same approach as Vite).
+ */
+import net from 'node:net';
+/** Default port for the Shep web UI */
+export const DEFAULT_PORT = 4050;
+/** Maximum number of ports to try before giving up */
+export const MAX_PORT_ATTEMPTS = 20;
+const MIN_PORT = 1024;
+const MAX_PORT = 65535;
+/**
+ * Check if a port is available by attempting to bind to it.
+ */
+export async function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => {
+            resolve(false);
+        });
+        server.once('listening', () => {
+            server.close(() => {
+                resolve(true);
+            });
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+/**
+ * Find an available port starting from `startPort`, incrementing up to `maxAttempts`.
+ * Throws if no available port is found or if the port is out of valid range.
+ */
+export async function findAvailablePort(startPort, maxAttempts = MAX_PORT_ATTEMPTS) {
+    if (startPort < MIN_PORT || startPort > MAX_PORT) {
+        throw new Error(`Port ${startPort} is out of valid range (${MIN_PORT}-${MAX_PORT})`);
+    }
+    for (let port = startPort; port < startPort + maxAttempts; port++) {
+        if (port > MAX_PORT)
+            break;
+        if (await isPortAvailable(port)) {
+            return port;
+        }
+    }
+    throw new Error(`No available port found between ${startPort}-${Math.min(startPort + maxAttempts - 1, MAX_PORT)}`);
+}

package/dist/src/infrastructure/services/web-server.service.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Web Server Service
+ *
+ * Manages the Next.js programmatic server lifecycle.
+ * Starts the web UI in the same Node.js process as the CLI,
+ * sharing the DI container and application layer.
+ *
+ * Supports both development (dev: true) and production (dev: false) modes.
+ * In production mode, Next.js serves the pre-built .next output.
+ */
+import next from 'next';
+import http from 'node:http';
+export interface WebServerDeps {
+    createNextApp: typeof next;
+    createHttpServer: typeof http.createServer;
+}
+/**
+ * Resolve the web UI directory path.
+ * Works in both development (src/) and production (dist/) contexts.
+ */
+export declare function resolveWebDir(): {
+    dir: string;
+    dev: boolean;
+};
+export declare class WebServerService {
+    private app;
+    private server;
+    private isShuttingDown;
+    private readonly deps;
+    constructor(deps?: Partial<WebServerDeps>);
+    /**
+     * Start the Next.js web server.
+     * @param port - Port to listen on
+     * @param dir - Path to the Next.js web package directory
+     * @param dev - Whether to run in development mode (default: auto-detect)
+     */
+    start(port: number, dir: string, dev?: boolean): Promise<void>;
+    /**
+     * Gracefully stop the server.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=web-server.service.d.ts.map

package/dist/src/infrastructure/services/web-server.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-server.service.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/web-server.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,IAAI,MAAM,WAAW,CAAC;AAM7B,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,OAAO,IAAI,CAAC;IAC3B,gBAAgB,EAAE,OAAO,IAAI,CAAC,YAAY,CAAC;CAC5C;AAOD;;;GAGG;AACH,wBAAgB,aAAa,IAAI;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAiB7D;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,GAAG,CAAwB;IACnC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;gBAEzB,IAAI,GAAE,OAAO,CAAC,aAAa,CAAM;IAI7C;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BjE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAoB5B"}

package/dist/src/infrastructure/services/web-server.service.js

@@ -0,0 +1,95 @@
+/**
+ * Web Server Service
+ *
+ * Manages the Next.js programmatic server lifecycle.
+ * Starts the web UI in the same Node.js process as the CLI,
+ * sharing the DI container and application layer.
+ *
+ * Supports both development (dev: true) and production (dev: false) modes.
+ * In production mode, Next.js serves the pre-built .next output.
+ */
+import next from 'next';
+import http from 'node:http';
+import path from 'node:path';
+import fs from 'node:fs';
+const defaultDeps = {
+    createNextApp: next,
+    createHttpServer: http.createServer,
+};
+/**
+ * Resolve the web UI directory path.
+ * Works in both development (src/) and production (dist/) contexts.
+ */
+export function resolveWebDir() {
+    // Check for development source directory first
+    const devDir = path.resolve(import.meta.dirname, '../../presentation/web');
+    if (fs.existsSync(path.join(devDir, 'next.config.ts'))) {
+        return { dir: devDir, dev: true };
+    }
+    // Production: web UI is shipped alongside dist/ in the package
+    const prodDir = path.resolve(import.meta.dirname, '../../../web');
+    if (fs.existsSync(path.join(prodDir, 'next.config.ts')) ||
+        fs.existsSync(path.join(prodDir, '.next'))) {
+        return { dir: prodDir, dev: false };
+    }
+    throw new Error('Web UI directory not found. Ensure the web UI is built (pnpm build:web).');
+}
+export class WebServerService {
+    app = null;
+    server = null;
+    isShuttingDown = false;
+    deps;
+    constructor(deps = {}) {
+        this.deps = { ...defaultDeps, ...deps };
+    }
+    /**
+     * Start the Next.js web server.
+     * @param port - Port to listen on
+     * @param dir - Path to the Next.js web package directory
+     * @param dev - Whether to run in development mode (default: auto-detect)
+     */
+    async start(port, dir, dev = true) {
+        const app = this.deps.createNextApp({
+            dev,
+            dir,
+            port,
+            hostname: 'localhost',
+        });
+        const handle = app.getRequestHandler();
+        await app.prepare();
+        this.app = app;
+        await new Promise((resolve, reject) => {
+            const server = this.deps.createHttpServer((req, res) => {
+                handle(req, res);
+            });
+            server.on('error', reject);
+            server.listen(port, 'localhost', () => {
+                this.server = server;
+                resolve();
+            });
+        });
+    }
+    /**
+     * Gracefully stop the server.
+     */
+    async stop() {
+        if (this.isShuttingDown)
+            return;
+        this.isShuttingDown = true;
+        try {
+            if (this.server) {
+                await new Promise((resolve) => {
+                    this.server.close(() => resolve());
+                });
+                this.server = null;
+            }
+            if (this.app) {
+                await this.app.close();
+                this.app = null;
+            }
+        }
+        finally {
+            this.isShuttingDown = false;
+        }
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * UI Command
+ *
+ * Starts the Shep web UI server.
+ * Runs Next.js in the same process as the CLI, sharing the DI container.
+ *
+ * Usage: shep ui [--port <number>]
+ *
+ * @example
+ * $ shep ui
+ * Shep Web UI
+ * Starting web server...
+ *
+ * ✓ Server ready at http://localhost:4050
+ * ℹ Press Ctrl+C to stop
+ */
+import { Command } from 'commander';
+/**
+ * Create the ui command
+ */
+export declare function createUiCommand(): Command;
+//# sourceMappingURL=ui.command.d.ts.map

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

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

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

@@ -0,0 +1,74 @@
+/**
+ * UI Command
+ *
+ * Starts the Shep web UI server.
+ * Runs Next.js in the same process as the CLI, sharing the DI container.
+ *
+ * Usage: shep ui [--port <number>]
+ *
+ * @example
+ * $ shep ui
+ * Shep Web UI
+ * Starting web server...
+ *
+ * ✓ Server ready at http://localhost:4050
+ * ℹ Press Ctrl+C to stop
+ */
+import { Command, InvalidArgumentError } from 'commander';
+import { findAvailablePort, DEFAULT_PORT } from '../../../infrastructure/services/port.service.js';
+import { WebServerService, resolveWebDir, } from '../../../infrastructure/services/web-server.service.js';
+import { colors, fmt, messages } from '../ui/index.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 ui command
+ */
+export function createUiCommand() {
+    return new Command('ui')
+        .description('Start the Shep web UI')
+        .option('-p, --port <number>', 'Port number (1024-65535)', parsePort)
+        .addHelpText('after', `
+Examples:
+  $ shep ui                 Start on default port (4050)
+  $ shep ui --port 8080     Start on custom port`)
+        .action(async (options) => {
+        try {
+            const startPort = options.port ?? DEFAULT_PORT;
+            const port = await findAvailablePort(startPort);
+            const { dir, dev } = resolveWebDir();
+            messages.newline();
+            console.log(fmt.heading('Shep Web UI'));
+            console.log(colors.muted(`Starting web server${dev ? ' (dev mode)' : ''}...`));
+            messages.newline();
+            const service = new WebServerService();
+            await service.start(port, dir, dev);
+            messages.success(`Server ready at ${fmt.code(`http://localhost:${port}`)}`);
+            messages.info('Press Ctrl+C to stop');
+            messages.newline();
+            // Handle graceful shutdown via SIGINT/SIGTERM
+            // The HTTP server keeps the event loop alive — no explicit wait needed
+            let isShuttingDown = false;
+            const shutdown = async () => {
+                if (isShuttingDown)
+                    return;
+                isShuttingDown = true;
+                messages.newline();
+                messages.info('Shutting down...');
+                await service.stop();
+                process.exit(0);
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            messages.error('Failed to start web UI', err);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -10,6 +10,7 @@
  * Commands:
  *   shep           Show help
  *   shep version   Display version information
+ *   shep ui        Start the web UI
  *   shep --version Display version number only
  *
  * Global Options:

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;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/presentation/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,kBAAkB,CAAC"}

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

@@ -10,6 +10,7 @@
  * Commands:
  *   shep           Show help
  *   shep version   Display version information
+ *   shep ui        Start the web UI
  *   shep --version Display version number only
  *
  * Global Options:
@@ -22,6 +23,7 @@ import { Command } from 'commander';
 import { VersionService } from '../../infrastructure/services/version.service.js';
 import { createVersionCommand } from './commands/version.command.js';
 import { createSettingsCommand } from './commands/settings/index.js';
+import { createUiCommand } from './commands/ui.command.js';
 import { messages } from './ui/index.js';
 // DI container and settings
 import { initializeContainer, container } from '../../infrastructure/di/container.js';
@@ -66,6 +68,7 @@ async function bootstrap() {
         // Register commands
         program.addCommand(createVersionCommand());
         program.addCommand(createSettingsCommand());
+        program.addCommand(createUiCommand());
         // Parse arguments (parseAsync needed for async command actions like init)
         await program.parseAsync();
     }