dev-server

@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

Loading

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]

Loading

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