@auto-engineer/dev-server 1.147.0 → 1.149.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @auto-engineer/dev-server
 
+## 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
+
+- [`d5ba3a0`](https://github.com/BeOnAuto/auto-engineer/commit/d5ba3a0e3fb0f6a9ad7a3a8b1815590ea77a5b42) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added state context instruction to generated decide handlers, preventing unnecessary narrowing when Given steps contain only state references
+
+- [`e0cdc4e`](https://github.com/BeOnAuto/auto-engineer/commit/e0cdc4e3363ad84d4bc49996a600ac75c97ccc38) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added context-aware classification of non-command fields in generated decide.ts scaffolds, distinguishing between date-derived, state-derived, and not-yet-tested fields
+
+- [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Extracted shared template helpers into a dedicated module for cleaner code generation
+
+- [`abb6540`](https://github.com/BeOnAuto/auto-engineer/commit/abb6540db7196ed7935c8a8610695828f9035fc3) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added status variant hints from Given state references to the state template, helping implementers create matching discriminated union variants
+
+- [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Extracted shared template helper functions into a dedicated module for better code reuse across generators
+  - Simplified template specs by removing inline duplicate definitions in favor of the shared helpers
+
+### Patch Changes
+
+- [`88fb1da`](https://github.com/BeOnAuto/auto-engineer/commit/88fb1da2b222de04dd4959d87657395ee960a6ce) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: skip empty file plans in scaffold output
+  - **server-generator-apollo-emmett**: filter state refs from given() in decide.specs.ts.ejs
+  - **server-generator-apollo-emmett**: move CS Given states from events to states array
+  - **global**: version packages
+  - **server-generator-apollo-emmett**: mark G1+G2 ketchup plan complete
+
+- [`4255f6d`](https://github.com/BeOnAuto/auto-engineer/commit/4255f6db0d128979e573244a615886482ce799b0) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Updated ketchup plan for state reference fix in decide template generator
+  - Marked generator bug fix milestones G1 and G2 as complete
+
+- [`62f1ea3`](https://github.com/BeOnAuto/auto-engineer/commit/62f1ea3dd1b4275211574e3df9d9a6571ae9b27a) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Fixed scaffold generation to correctly distinguish between event and state references in decision handlers
+  - Prevented contradictory instructions from appearing in generated code when Given clauses contain only state references
+
+- [`ba4f5c9`](https://github.com/BeOnAuto/auto-engineer/commit/ba4f5c9749fb1c15d444e78ca9a2689817f039cb) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added implementation plan for decide.ts code generation fixes in the Apollo Emmett server generator
+
+- Updated dependencies [[`88fb1da`](https://github.com/BeOnAuto/auto-engineer/commit/88fb1da2b222de04dd4959d87657395ee960a6ce), [`d5ba3a0`](https://github.com/BeOnAuto/auto-engineer/commit/d5ba3a0e3fb0f6a9ad7a3a8b1815590ea77a5b42), [`e0cdc4e`](https://github.com/BeOnAuto/auto-engineer/commit/e0cdc4e3363ad84d4bc49996a600ac75c97ccc38), [`4255f6d`](https://github.com/BeOnAuto/auto-engineer/commit/4255f6db0d128979e573244a615886482ce799b0), [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde), [`abb6540`](https://github.com/BeOnAuto/auto-engineer/commit/abb6540db7196ed7935c8a8610695828f9035fc3), [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde), [`62f1ea3`](https://github.com/BeOnAuto/auto-engineer/commit/62f1ea3dd1b4275211574e3df9d9a6571ae9b27a), [`ba4f5c9`](https://github.com/BeOnAuto/auto-engineer/commit/ba4f5c9749fb1c15d444e78ca9a2689817f039cb)]:
+  - @auto-engineer/cli@1.148.0
+  - @auto-engineer/message-bus@1.148.0
+
 ## 1.147.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.147.0",
-    "@auto-engineer/message-bus": "1.147.0"
+    "@auto-engineer/cli": "1.149.0",
+    "@auto-engineer/message-bus": "1.149.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@auto-engineer/cli": "1.147.0"
+    "@auto-engineer/cli": "1.149.0"
   },
-  "version": "1.147.0",
+  "version": "1.149.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "test": "vitest run --reporter=dot",