@auto-engineer/dev-server

Command handlers for starting, restarting, and managing development processes (server, client, Storybook) with file watching, port cleanup, and dependency installation.

Purpose

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.

Installation

pnpm add @auto-engineer/dev-server

Quick Start

1. Register all command handlers

import { COMMANDS } from '@auto-engineer/dev-server';
import { createMessageBus } from '@auto-engineer/message-bus';

const bus = createMessageBus();
COMMANDS.forEach(cmd => bus.registerCommand(cmd));

2. Dispatch a command

const result = await bus.dispatch({
  type: 'StartServer',
  data: {
    serverDirectory: './server',
    port: 4000,
    watch: true,
  },
  requestId: 'req-1',
});
// result.type === 'ServerStarted' | 'ServerStartFailed'

How-to Guides

Start the server with watch mode

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

auto start:client --client-directory=./client
auto start:storybook --storybook-directory=./client --port=6006

Both commands wait for HTTP readiness before emitting their success event.

Restart a running process

auto restart:server --server-directory=./server
auto restart:client --client-directory=./client
auto restart:storybook --storybook-directory=./client

Restart commands kill the existing port holder before spawning a new process.

Install dependencies

auto install:client --base-dir=./client
auto install:server --base-dir=./server

Execute an ad-hoc command

auto exec --base-dir=./client --command="pnpm build"

Rebuild the component database

auto rebuild:component-db --base-dir=./client

Reset everything

auto reset

Kills processes on ports 4000, 6006, and 8080, clears pipeline messages, and dispatches a Clean command.

Enable debug logging

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

COMMANDS

import { COMMANDS } from '@auto-engineer/dev-server';

Array of all 13 command handlers, ready to register on a message bus.

Commands

| 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

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[];  // default: [serverDirectory/src]
    debounceMs?: number;     // default: 2000
  }
>;

Events: ServerStarted, ServerStartFailed, ServerRestarting, ServerRestarted

StartClientCommand

import type { StartClientCommand } from '@auto-engineer/dev-server';

type StartClientCommand = Command<
  'StartClient',
  {
    clientDirectory: string;
    command?: string;        // default: 'pnpm start'
    port?: number;           // default: 8080
  }
>;

Events: ClientStarted, ClientStartFailed

StartStorybookCommand

import type { StartStorybookCommand } from '@auto-engineer/dev-server';

type StartStorybookCommand = Command<
  'StartStorybook',
  {
    storybookDirectory: string;
    command?: string;        // default: 'pnpm storybook'
    port?: number;           // default: 6006
    fast?: boolean;          // default: false (sets STORYBOOK_FAST=1)
  }
>;

Events: StorybookStarted, StorybookStartFailed

ExecuteCommandCommand

import type { ExecuteCommandCommand } from '@auto-engineer/dev-server';

type ExecuteCommandCommand = Command<
  'ExecuteCommand',
  {
    baseDir: string;
    command: string;
  }
>;

Events: CommandExecuted (includes stdout/stderr/exitCode), CommandFailed

Named handler exports

Each command handler is also exported individually:

import {
  startServerCommandHandler,
  startClientCommandHandler,
  startStorybookCommandHandler,
  restartServerCommandHandler,
  restartClientCommandHandler,
  restartStorybookCommandHandler,
  executeCommandHandler,
  rebuildComponentDBCommandHandler,
  installClientDependenciesCommandHandler,
  installServerDependenciesCommandHandler,
  resetPipelineCommandHandler,
  cleanCommandHandler,
  resetCommandHandler,
} from '@auto-engineer/dev-server';

Architecture

src/
├── 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         # 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

flowchart TB
    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

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/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:*) |