@auto-engineer/dev-server 1.148.0 → 1.150.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @auto-engineer/dev-server
 
+## 1.150.0
+
+### Minor Changes
+
+- [`a502d47`](https://github.com/BeOnAuto/auto-engineer/commit/a502d472df528a1c5d53905898220c2a3a49d8a5) Thanks [@osamanar](https://github.com/osamanar)! -
+
+- [`c96a70e`](https://github.com/BeOnAuto/auto-engineer/commit/c96a70e49f9f64213450d0b9840bc9a8b2b1d77d) Thanks [@osamanar](https://github.com/osamanar)! -
+
+- [`4343bca`](https://github.com/BeOnAuto/auto-engineer/commit/4343bcaa2576703ae578fd9b7f5ec5b9776702a9) Thanks [@osamanar](https://github.com/osamanar)! -
+
+- [`28ffce9`](https://github.com/BeOnAuto/auto-engineer/commit/28ffce9c8b95f0c3ca61728bd1f667fa9416d461) Thanks [@osamanar](https://github.com/osamanar)! -
+
+- [`3fd5dbf`](https://github.com/BeOnAuto/auto-engineer/commit/3fd5dbfbfb4f7a5fe71ae53105b31a1b0f30f911) Thanks [@osamanar](https://github.com/osamanar)! -
+
+### Patch Changes
+
+- [`41f3df3`](https://github.com/BeOnAuto/auto-engineer/commit/41f3df3025445ba92208c2b007b8e29a40489309) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **global**: version packages
+  - **global**: major refresh to all the docs
+- Updated dependencies [[`a502d47`](https://github.com/BeOnAuto/auto-engineer/commit/a502d472df528a1c5d53905898220c2a3a49d8a5), [`c96a70e`](https://github.com/BeOnAuto/auto-engineer/commit/c96a70e49f9f64213450d0b9840bc9a8b2b1d77d), [`4343bca`](https://github.com/BeOnAuto/auto-engineer/commit/4343bcaa2576703ae578fd9b7f5ec5b9776702a9), [`28ffce9`](https://github.com/BeOnAuto/auto-engineer/commit/28ffce9c8b95f0c3ca61728bd1f667fa9416d461), [`41f3df3`](https://github.com/BeOnAuto/auto-engineer/commit/41f3df3025445ba92208c2b007b8e29a40489309), [`3fd5dbf`](https://github.com/BeOnAuto/auto-engineer/commit/3fd5dbfbfb4f7a5fe71ae53105b31a1b0f30f911)]:
+  - @auto-engineer/cli@1.150.0
+  - @auto-engineer/message-bus@1.150.0
+
+## 1.149.0
+
+### Minor Changes
+
+- [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: add Given state ref hints to state.ts.ejs
+  - **server-generator-apollo-emmett**: context-aware nonCommandField instructions
+  - **server-generator-apollo-emmett**: add state context instruction
+  - **server-generator-apollo-emmett**: extract shared template helpers
+  - **server-generator-apollo-emmett**: filter state refs from hasGivenEvents in decide.ts.ejs
+
+### Patch Changes
+
+- [`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38) Thanks [@SamHatoum](https://github.com/SamHatoum)! -
+
+- Updated dependencies [[`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38), [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98)]:
+  - @auto-engineer/cli@1.149.0
+  - @auto-engineer/message-bus@1.149.0
+
 ## 1.148.0
 
 ### Minor Changes

package/README.md

@@ -1,14 +1,12 @@
 # @auto-engineer/dev-server
 
-Development server commands for starting and managing client/server processes with file watching.
+Command handlers for starting, restarting, and managing development processes (server, client, Storybook) with file watching, port cleanup, and dependency installation.
 
 ---
 
 ## Purpose
 
-Without `@auto-engineer/dev-server`, you would have to manually manage process spawning, file watching for auto-restart, and process cleanup when developing client/server applications.
-
-This package provides command handlers that integrate with the CLI pipeline system to start development processes with optional file watching for automatic restarts on code changes.
+Provides a set of message-bus command handlers that manage the lifecycle of development processes. Each handler spawns a child process, optionally waits for HTTP readiness, and emits structured events on success or failure. The server command includes file watching with debounced auto-restart on code changes.
 
 ---
 
@@ -20,9 +18,7 @@ pnpm add @auto-engineer/dev-server
 
 ## Quick Start
 
-Register the handlers and start a development server:
-
-### 1. Register the handlers
+### 1. Register all command handlers
 
 ```typescript
 import { COMMANDS } from '@auto-engineer/dev-server';
@@ -32,179 +28,267 @@ const bus = createMessageBus();
 COMMANDS.forEach(cmd => bus.registerCommand(cmd));
 ```
 
-### 2. Send a command
+### 2. Dispatch a command
 
 ```typescript
 const result = await bus.dispatch({
   type: 'StartServer',
   data: {
     serverDirectory: './server',
+    port: 4000,
     watch: true,
   },
-  requestId: 'req-123',
+  requestId: 'req-1',
 });
-
-console.log(result);
-// → { type: 'ServerStarted', data: { serverDirectory: './server', pid: 12345, watching: true } }
+// result.type === 'ServerStarted' | 'ServerStartFailed'
 ```
 
-The server starts with file watching enabled, automatically restarting on code changes.
-
 ---
 
 ## How-to Guides
 
-### Run via CLI
+### Start the server with watch mode
+
+```bash
+auto start:server --server-directory=./server --watch --watch-directories=./server/src,./shared
+```
+
+The server process restarts automatically when watched files change. Restarts are debounced (default 2000ms).
+
+### Start client and Storybook
 
 ```bash
-auto start:server --server-directory=./server
 auto start:client --client-directory=./client
+auto start:storybook --storybook-directory=./client --port=6006
 ```
 
-### Run with Watch Mode
+Both commands wait for HTTP readiness before emitting their success event.
+
+### Restart a running process
 
 ```bash
-auto start:server --server-directory=./server --watch --watch-directories=./server,./shared
+auto restart:server --server-directory=./server
+auto restart:client --client-directory=./client
+auto restart:storybook --storybook-directory=./client
 ```
 
-### Run with Custom Command
+Restart commands kill the existing port holder before spawning a new process.
+
+### Install dependencies
 
 ```bash
-auto start:server --server-directory=./server --command="pnpm dev"
-auto start:client --client-directory=./client --command="npm run dev"
+auto install:client --base-dir=./client
+auto install:server --base-dir=./server
 ```
 
-### Handle Errors
+### Execute an ad-hoc command
 
-```typescript
-if (result.type === 'ServerStartFailed') {
-  console.error(result.data.error);
-}
+```bash
+auto exec --base-dir=./client --command="pnpm build"
 ```
 
-### Enable Debug Logging
+### Rebuild the component database
+
+```bash
+auto rebuild:component-db --base-dir=./client
+```
+
+### Reset everything
+
+```bash
+auto reset
+```
+
+Kills processes on ports 4000, 6006, and 8080, clears pipeline messages, and dispatches a `Clean` command.
+
+### Enable debug logging
 
 ```bash
 DEBUG=auto:dev-server:* auto start:server --server-directory=./server
 ```
 
+Each command uses its own debug namespace (e.g., `auto:dev-server:start-server`, `auto:dev-server:restart-client`).
+
 ---
 
 ## API Reference
 
-### Exports
+### COMMANDS
 
 ```typescript
-import {
-  COMMANDS,
-  startServerCommandHandler,
-  startClientCommandHandler,
-} from '@auto-engineer/dev-server';
-
-import type {
-  StartServerCommand,
-  StartClientCommand,
-  ServerStartedEvent,
-  ServerStartFailedEvent,
-  ClientStartedEvent,
-  ClientStartFailedEvent,
-} from '@auto-engineer/dev-server';
+import { COMMANDS } from '@auto-engineer/dev-server';
 ```
 
+Array of all 13 command handlers, ready to register on a message bus.
+
 ### Commands
 
-| Command | CLI Alias | Description |
-|---------|-----------|-------------|
-| `StartServer` | `start:server` | Start development server with optional file watching |
-| `StartClient` | `start:client` | Start development client process |
+| Command | Alias | Description | Default Port |
+|---------|-------|-------------|-------------|
+| `StartServer` | `start:server` | Start server with optional file watching | 4000 |
+| `StartClient` | `start:client` | Start client process | 8080 |
+| `StartStorybook` | `start:storybook` | Start Storybook dev server | 6006 |
+| `RestartServer` | `restart:server` | Kill port holder and restart server | 4000 |
+| `RestartClient` | `restart:client` | Kill port holder and restart client | 8080 |
+| `RestartStorybook` | `restart:storybook` | Kill port holder and restart Storybook | 6006 |
+| `ExecuteCommand` | `exec` | Run an ad-hoc shell command | -- |
+| `RebuildComponentDB` | `rebuild:component-db` | Rebuild component DB from Storybook manifests | -- |
+| `InstallClientDependencies` | `install:client` | Install client dependencies | -- |
+| `InstallServerDependencies` | `install:server` | Install server dependencies | -- |
+| `ResetPipeline` | `reset:pipeline` | Clear all pipeline messages and state | -- |
+| `Clean` | `clean` | Remove generated directories, restore `.context` | -- |
+| `Reset` | `reset` | Kill servers, clear pipeline, dispatch Clean | -- |
 
 ### StartServerCommand
 
 ```typescript
+import type { StartServerCommand } from '@auto-engineer/dev-server';
+
 type StartServerCommand = Command<
   'StartServer',
   {
     serverDirectory: string;
     command?: string;        // default: 'pnpm start'
+    port?: number;           // default: 4000
     watch?: boolean;         // default: true
-    watchDirectories?: string[];
+    watchDirectories?: string[];  // default: [serverDirectory/src]
     debounceMs?: number;     // default: 2000
   }
 >;
 ```
 
+Events: `ServerStarted`, `ServerStartFailed`, `ServerRestarting`, `ServerRestarted`
+
 ### StartClientCommand
 
 ```typescript
+import type { StartClientCommand } from '@auto-engineer/dev-server';
+
 type StartClientCommand = Command<
   'StartClient',
   {
     clientDirectory: string;
     command?: string;        // default: 'pnpm start'
+    port?: number;           // default: 8080
   }
 >;
 ```
 
-### ServerStartedEvent
+Events: `ClientStarted`, `ClientStartFailed`
+
+### StartStorybookCommand
 
 ```typescript
-type ServerStartedEvent = Event<
-  'ServerStarted',
+import type { StartStorybookCommand } from '@auto-engineer/dev-server';
+
+type StartStorybookCommand = Command<
+  'StartStorybook',
   {
-    serverDirectory: string;
-    pid: number;
-    port?: number;
-    watching: boolean;
+    storybookDirectory: string;
+    command?: string;        // default: 'pnpm storybook'
+    port?: number;           // default: 6006
+    fast?: boolean;          // default: false (sets STORYBOOK_FAST=1)
   }
 >;
 ```
 
-### ClientStartedEvent
+Events: `StorybookStarted`, `StorybookStartFailed`
+
+### ExecuteCommandCommand
 
 ```typescript
-type ClientStartedEvent = Event<
-  'ClientStarted',
+import type { ExecuteCommandCommand } from '@auto-engineer/dev-server';
+
+type ExecuteCommandCommand = Command<
+  'ExecuteCommand',
   {
-    clientDirectory: string;
-    pid: number;
-    port?: number;
+    baseDir: string;
+    command: string;
   }
 >;
 ```
 
+Events: `CommandExecuted` (includes stdout/stderr/exitCode), `CommandFailed`
+
+### Named handler exports
+
+Each command handler is also exported individually:
+
+```typescript
+import {
+  startServerCommandHandler,
+  startClientCommandHandler,
+  startStorybookCommandHandler,
+  restartServerCommandHandler,
+  restartClientCommandHandler,
+  restartStorybookCommandHandler,
+  executeCommandHandler,
+  rebuildComponentDBCommandHandler,
+  installClientDependenciesCommandHandler,
+  installServerDependenciesCommandHandler,
+  resetPipelineCommandHandler,
+  cleanCommandHandler,
+  resetCommandHandler,
+} from '@auto-engineer/dev-server';
+```
+
 ---
 
 ## Architecture
 
 ```
 src/
-├── index.ts
+├── index.ts                    # COMMANDS array + re-exports
+├── ensure-installed.ts         # Auto-install node_modules if missing
+├── port-cleanup.ts             # Kill processes holding a port (SIGTERM → SIGKILL)
+├── wait-for-http.ts            # Poll localhost until HTTP responds (<500)
 └── commands/
-    ├── start-server.ts
-    └── start-client.ts
+    ├── start-server.ts         # Spawn server + chokidar file watcher
+    ├── start-client.ts         # Spawn client, wait for HTTP ready
+    ├── start-storybook.ts      # Spawn Storybook, write settings, wait for HTTP
+    ├── restart-server.ts       # Kill port → delegate to StartServer
+    ├── restart-client.ts       # Kill port → delegate to StartClient
+    ├── restart-storybook.ts    # Kill port → delegate to StartStorybook
+    ├── execute-command.ts      # Run arbitrary shell command
+    ├── build-component-db.ts   # Rebuild component DB, parse artifact URL
+    ├── install-client-dependencies.ts
+    ├── install-server-dependencies.ts
+    ├── reset-pipeline.ts       # Clear pipeline messages
+    ├── clean.ts                # Remove server/client dirs, restore .context
+    ├── reset.ts                # Kill ports 4000/6006/8080, clear, clean
+    └── storybook-settings.ts   # Default Storybook settings JSON
 ```
 
-The following diagram shows the server watch flow:
-
 ```mermaid
 flowchart TB
-    A[StartServer] --> B[Spawn Process]
-    B --> C{Watch Mode?}
-    C -->|Yes| D[Start Watcher]
-    C -->|No| E[ServerStartedEvent]
-    D --> E
-    D --> F[File Change]
-    F --> G[Kill Process]
-    G --> B
+    A[StartServer command] --> B[Kill port holder]
+    B --> C[Spawn process]
+    C --> D[Wait for HTTP ready]
+    D --> E{Watch mode?}
+    E -->|Yes| F[Start chokidar watcher]
+    E -->|No| G[ServerStarted event]
+    F --> G
+    F --> H[File change detected]
+    H --> I[Debounce]
+    I --> J[Kill process]
+    J --> C
 ```
 
-*Flow: Command spawns process, optionally starts file watcher which restarts on changes.*
+```mermaid
+flowchart TB
+    R[RestartServer command] --> K[Kill port holder]
+    K --> L[Delegate to StartServer handler]
+    L --> M{Result?}
+    M -->|ServerStarted| N[ServerRestarted event]
+    M -->|ServerStartFailed| O[ServerRestartFailed event]
+```
 
 ### Dependencies
 
 | Package | Usage |
 |---------|-------|
-| `@auto-engineer/message-bus` | Command/event infrastructure |
-| `chokidar` | File system watching |
-| `execa` | Process execution |
-| `debug` | Debug logging |
+| `@auto-engineer/cli` | TUI service registry integration |
+| `@auto-engineer/message-bus` | `defineCommandHandler`, `Command`/`Event` types |
+| `chokidar` | File system watching for server auto-restart |
+| `execa` | Process spawning |
+| `debug` | Namespaced debug logging (`auto:dev-server:*`) |

package/package.json

@@ -18,16 +18,16 @@
     "chokidar": "^3.6.0",
     "debug": "^4.4.1",
     "execa": "^9.5.2",
-    "@auto-engineer/cli": "1.148.0",
-    "@auto-engineer/message-bus": "1.148.0"
+    "@auto-engineer/cli": "1.150.0",
+    "@auto-engineer/message-bus": "1.150.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@auto-engineer/cli": "1.148.0"
+    "@auto-engineer/cli": "1.150.0"
   },
-  "version": "1.148.0",
+  "version": "1.150.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "test": "vitest run --reporter=dot",