unitup 0.2.0 → 0.3.0

package/.agents/AGENTS.md

@@ -0,0 +1,35 @@
+# Unitup Workspace Guidelines for AI Agents
+
+Welcome to **Unitup** — a lightweight, zero-dependency, cross-platform process manager and zero-downtime deployment orchestration engine.
+
+---
+
+## Core Invariants
+
+1. **Zero External Dependencies**:
+   - Production code in `src/` must NEVER import anything outside Node.js built-ins (`node:*`).
+   - `package.json` must keep `"dependencies": {}`.
+2. **Zero-Downtime Architectural Boundary**:
+   - Zero-downtime runtime primitives belong to `src/core/` (ProcessManager, Router, GenerationManager, ReadinessChecker, DrainManager, Supervisor, IPC).
+   - Deployment sequencing belongs to `src/deploy/` (DeploymentManager, RollbackManager).
+   - CLI (`src/cli.js`) is only a thin translation layer.
+3. **Multi-OS Native Daemon Support**:
+   - Linux: systemd user/system services & timers.
+   - macOS: launchd LaunchAgents / LaunchDaemons `.plist`.
+   - Windows: Windows Services via `sc.exe` and `WindowsServiceHost`.
+4. **Validation Triad**:
+   - Every code modification must pass:
+     ```bash
+     npm test && npx tsc --noEmit && npx biome check src/ test/
+     ```
+
+---
+
+## Workspace Skills Available
+
+For deep-dive runbooks and procedures, activate the specialized skills in `.agents/skills/`:
+
+- **[zero-downtime-deployment](file:///Users/ahmet/projects/unitup/.agents/skills/zero-downtime-deployment/SKILL.md)**: State machine, canary weighted routing, rollback, connection draining, and streaming protocol handling.
+- **[platform-service-adapters](file:///Users/ahmet/projects/unitup/.agents/skills/platform-service-adapters/SKILL.md)**: Systemd, launchd, and Windows service integration, escaping, user lingering, and command runner mocking.
+- **[multi-runtime-management](file:///Users/ahmet/projects/unitup/.agents/skills/multi-runtime-management/SKILL.md)**: Auto-detection and arguments for Node, Python, Bun, Deno, Go, Ruby, PHP, and generic binaries.
+- **[unitup-development-and-qa](file:///Users/ahmet/projects/unitup/.agents/skills/unitup-development-and-qa/SKILL.md)**: Testing standards with `node:test`, TypeScript declaration sync, and Biome linting.

package/.agents/skills/multi-runtime-management/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: multi-runtime-management
+description: >-
+  Manage, extend, and test multi-runtime support in Unitup: Node.js, Python, Bun, Deno, Go, Ruby,
+  PHP, Elixir, and generic executables. Use when modifying runtime detection, shebang parsing,
+  argument building, environment variable normalization, or memory limits.
+---
+
+# Multi-Runtime Management in Unitup
+
+This skill details how Unitup automatically detects, configures, and executes services across different programming runtimes without requiring external dependencies or containers.
+
+---
+
+## 1. Runtime Architecture
+
+Runtime logic resides in:
+```text
+src/runtimes/
+├── base.js         # BaseRuntime contract: detect(), getExecutable(), getArgs()
+├── node.js         # NodeRuntime (.js, .mjs, .cjs)
+├── python.js       # PythonRuntime (.py, python shebang, unbuffered -u flag)
+├── bun.js          # BunRuntime (.js, .ts with bun)
+├── deno.js         # DenoRuntime (.ts with deno, auto permission flags)
+├── go.js           # GoRuntime (.go -> go run, or compiled binaries)
+├── ruby.js         # RubyRuntime (.rb)
+├── php.js          # PHPRuntime (.php -> built-in web server or CLI)
+├── shell.js        # ShellRuntime (.sh, bash shebang)
+├── elixir.js       # ElixirRuntime (.ex, .exs)
+├── generic.js      # GenericExecutableRuntime (arbitrary command line)
+└── index.js        # detectRuntime(), resolveRuntimeConfig(), listSupportedRuntimes()
+```
+
+---
+
+## 2. Detection & Resolution Rules
+
+### 1. File Extension Detection
+- `.js`, `.mjs`, `.cjs` -> Node.js (or Bun/Deno if explicitly specified via `--runtime`)
+- `.py` -> Python (`python3` or `python` with `-u` for unbuffered logs)
+- `.rb` -> Ruby (`ruby`)
+- `.php` -> PHP (`php`)
+- `.sh` -> Shell (`bash` or `sh`)
+- `.go` -> Go (`go run`)
+- `.ex`, `.exs` -> Elixir (`elixir`)
+
+### 2. TypeScript Ambiguity Rule
+- `.ts` files **cannot** be auto-resolved to a single engine because both Bun and Deno execute TypeScript natively.
+- An error is thrown requiring the user to specify `--runtime bun` or `--runtime deno`.
+
+### 3. Shebang Header Detection
+If a file has no extension or is executable:
+- Reads the first 256 bytes of the file.
+- Inspects `#!/usr/bin/env ...` or `#!/bin/...` to detect runtime (e.g. `python3`, `ruby`, `node`, `bash`).
+
+### 4. Generic Command (`--command`)
+- When `--command "my-binary --flag"` is provided:
+  - Bypasses runtime detection.
+  - Resolves executable using `resolveExecutable()`.
+  - Splits and preserves argument tokens safely without shell injection vulnerabilities.
+
+---
+
+## 3. Normalization & App Metadata
+
+[normalizeServiceConfig](file:///Users/ahmet/projects/unitup/src/service/normalize.js) converts raw CLI/API flags into a canonical service descriptor:
+
+- Resolves absolute `cwd` (Working directory).
+- Resolves executable path or validates binary exists in `$PATH`.
+- Normalizes memory limits: parses `512M`, `1G`, `256MB` into bytes and native OS config strings.
+- Reads and saves metadata in `~/.config/unitup/apps/<name>.json`.
+
+---
+
+## 4. Testing Multi-Runtime Capabilities
+
+```bash
+# Run multi-runtime detection and argument builder tests
+node --test test/multi-runtime.test.js
+```

package/.agents/skills/platform-service-adapters/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: platform-service-adapters
+description: >-
+  Implement, test, and debug cross-platform OS service adapters in Unitup: systemd (Linux),
+  launchd (macOS), and Windows Services (Windows). Use when working with service definition generators,
+  system commands (systemctl, launchctl, sc.exe), user vs. system scopes, linger, or timer units.
+---
+
+# Cross-Platform Service Adapters in Unitup
+
+This skill covers the implementation patterns, escaping rules, permission boundaries, and testing practices for Unitup's native OS service adapters.
+
+---
+
+## 1. Adapter Architecture
+
+Unitup implements a unified interface across operating systems via [ServiceAdapter](file:///Users/ahmet/projects/unitup/src/platform/base.js):
+
+```text
+src/platform/
+├── base.js           # Base ServiceAdapter abstract class with standard contract
+├── linux.js          # LinuxAdapter: systemd user & system units via systemctl
+├── macos.js          # MacOSAdapter: launchd launchd.plist via launchctl
+├── windows.js        # WindowsAdapter: Windows Service via sc.exe
+├── windows-host.js   # WindowsServiceHost child process manager for Windows
+└── index.js          # getAdapter(platform), getPlatformCapabilities()
+```
+
+### Standard Adapter Methods:
+Each adapter implements:
+- `getCapabilities()`: `{ systemd, launchd, windowsService, userUnits, systemUnits, timers, memoryLimits }`
+- `generateService(config)`: Returns formatted service definition string
+- `install(config, opts)`: Writes service file and registers with OS daemon
+- `uninstall(name, opts)`: Unregisters service and deletes service file
+- `start(name, opts)`, `stop(name, opts)`, `restart(name, opts)`
+- `status(name, opts)`: Queries native service state (running, stopped, PID, uptime)
+- `enable(name, opts)`, `disable(name, opts)`
+
+---
+
+## 2. Platform Specifics & Service Formats
+
+### A. Linux (systemd)
+- **User scope (default)**: `~/.config/systemd/user/unitup-<name>.service`
+  - Requires user lingering for persistence across logout: `loginctl enable-linger <user>` (verified via `checkUserLinger()`).
+  - Controlled with `systemctl --user`.
+- **System scope**: `/etc/systemd/system/unitup-<name>.service`
+  - Requires root privileges; throws `PermissionRequiredError` if unprivileged.
+- **Unit Content Structure**:
+  ```ini
+  [Unit]
+  Description=Unitup Service - <name>
+  After=network.target
+
+  [Service]
+  Type=simple
+  WorkingDirectory=/path/to/app
+  ExecStart=/path/to/executable ...
+  Restart=always
+  RestartSec=3
+  MemoryMax=512M
+
+  [Install]
+  WantedBy=default.target
+  ```
+- **Escaping**: Always use `formatSystemdEnv()` and `escapeExecArg()` from [src/utils.js](file:///Users/ahmet/projects/unitup/src/utils.js).
+
+### B. macOS (launchd)
+- **User scope (default)**: `~/Library/LaunchAgents/com.unitup.<name>.plist`
+  - Domain target: `gui/<uid>` (for logged-in user) or `user/<uid>`.
+  - Bootstrapping: `launchctl bootstrap gui/<uid> <plistPath>`
+  - Kickstarting: `launchctl kickstart -k gui/<uid>/com.unitup.<name>`
+- **System scope**: `/Library/LaunchDaemons/com.unitup.<name>.plist`
+  - Domain target: `system` (requires root).
+- **XML Plist Generation**: Generated cleanly with standard XML elements (`ProgramArguments`, `WorkingDirectory`, `KeepAlive`, `EnvironmentVariables`, `StandardOutPath`, `StandardErrorPath`).
+
+### C. Windows (Windows Services)
+- **Tooling**: Uses `sc.exe create <name> binPath= ... start= auto`.
+- **WindowsServiceHost**: Because standard node scripts cannot run directly as Windows Services without a service wrapper, Unitup uses [WindowsServiceHost](file:///Users/ahmet/projects/unitup/src/platform/windows-host.js) to bridge process signals, log redirection, and Windows shutdown events.
+
+---
+
+## 3. Testing Platform Adapters Safely
+
+Native system commands (`systemctl`, `launchctl`, `sc.exe`) cannot and should not be executed directly in unit tests.
+
+Unitup provides runner injection via [src/utils.js](file:///Users/ahmet/projects/unitup/src/utils.js):
+
+```javascript
+import { setCommandRunner, resetCommandRunner } from '../src/utils.js';
+
+// Mock commands in tests:
+setCommandRunner(async (cmd, args) => {
+  if (cmd === 'systemctl' && args.includes('is-active')) {
+    return { stdout: 'active\n', stderr: '', code: 0 };
+  }
+  return { stdout: '', stderr: '', code: 0 };
+});
+
+// Always reset runner in afterEach / finally:
+resetCommandRunner();
+```
+
+### Verification Commands:
+```bash
+# Test all platform adapters
+node --test test/platform.test.js test/macos.test.js test/windows.test.js test/unit.test.js
+```

package/.agents/skills/unitup-development-and-qa/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: unitup-development-and-qa
+description: >-
+  Development standards, testing procedures, TypeScript type verification, Biome linting,
+  and zero-external-dependency constraints for the Unitup codebase. Use when adding new features,
+  running tests, updating index.d.ts, or validating pull requests.
+---
+
+# Unitup Development, QA & Quality Standards
+
+This skill outlines the core engineering invariants, code quality checks, and testing workflows required for any contribution to Unitup.
+
+---
+
+## 1. Golden Constraint: Zero External Dependencies
+
+**Unitup has strictly ZERO production external dependencies (`dependencies: {}` in package.json).**
+
+- Only Node.js built-in standard modules are allowed (`node:fs`, `node:path`, `node:os`, `node:child_process`, `node:http`, `node:net`, `node:events`, `node:assert`, `node:test`).
+- Never add npm packages to `dependencies`.
+- Development dependencies (`devDependencies`) are strictly limited to developer tooling: `biome` for linting/formatting and `typescript` for `.d.ts` type-checking.
+
+---
+
+## 2. Testing Principles & Node.js Test Runner
+
+Unitup uses the native Node.js test runner (`node:test` and `node:assert`). No Jest, Mocha, or Vitest.
+
+### Test Authoring Rules:
+1. **Never use hardcoded network ports**:
+   - Always use `port: 0` for ephemeral port allocation or `findFreePort()`.
+   - Hardcoding ports like `3000` or `8080` breaks developer machines running local web servers.
+2. **Deterministic Cleanup**:
+   - Every test that opens an HTTP server, router, socket, or temporary file must clean it up in an `afterEach` or `finally` block.
+3. **Mock Process & System Calls**:
+   - Do not call real `systemctl`, `launchctl`, or `sc.exe` in unit tests. Use `setCommandRunner()`.
+   - Use simulated process managers when testing deployment state machines to keep tests blazing fast (< 100ms per suite).
+
+### Common Test Commands:
+```bash
+# Run a specific test suite
+node --test test/canary.test.js
+node --test test/router.test.js
+node --test test/deployment-manager.test.js
+
+# Run the complete test suite across all platforms
+npm test
+```
+
+---
+
+## 3. TypeScript Type Synchronization (`index.d.ts`)
+
+Unitup is written in standard ES Modules (`"type": "module"`), but provides high-grade TypeScript declarations in [index.d.ts](file:///Users/ahmet/projects/unitup/index.d.ts).
+
+Whenever a public function, class, option, or result object is added or modified in `src/`:
+1. Update `index.d.ts` with matching types.
+2. Verify with the TypeScript compiler:
+   ```bash
+   npx tsc --noEmit
+   ```
+3. Ensure `npx tsc --noEmit` exits with **0 errors**.
+
+---
+
+## 4. Linting & Formatting with Biome
+
+Unitup uses Biome for sub-second formatting and static analysis:
+
+```bash
+# Check code style, formatting, and lint rules
+npx biome check src/ test/
+
+# Automatically apply safe fixes
+npx biome check --write src/ test/
+```
+
+Always ensure `npx biome check src/ test/` exits cleanly with zero errors before concluding tasks.
+
+---
+
+## 5. Pre-Commit / Pre-Push Checklist
+
+Before submitting any task, run the full validation chain:
+
+```bash
+npm test && npx tsc --noEmit && npx biome check src/ test/
+```

package/.agents/skills/zero-downtime-deployment/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: zero-downtime-deployment
+description: >-
+  Develop, test, and debug zero-downtime deployments, canary releases, rollback sequencing,
+  generation management, router reverse proxying, connection draining, and readiness probes in Unitup.
+  Use when modifying core routing, process lifecycle, readiness checks, drain manager, or deploy orchestration.
+---
+
+# Zero-Downtime Deployment & Traffic Routing in Unitup
+
+This skill provides architectural guidelines, lifecycle specifications, and testing procedures for Unitup's zero-downtime deployment subsystem.
+
+---
+
+## 1. Architectural Invariant: Core vs. Deploy Separation
+
+Unitup strictly decouples low-level process and routing primitives from deployment sequencing:
+
+```text
+unitup
+├── core/                         # Zero-downtime runtime primitives (No deployment sequencing)
+│   ├── process-manager.js        # Child process lifecycle (start, stop, isAlive, signal, waitForExit)
+│   ├── generation-manager.js     # Generation records, ephemeral internal ports, disk persistence
+│   ├── router.js                 # HTTP & WebSocket reverse proxy on stable public port, atomic switch, canary weights
+│   ├── readiness.js              # TCP connect & HTTP 2xx health probes, fast startup failure detection
+│   ├── drain-manager.js          # In-flight connection tracking, graceful drain, process retirement
+│   ├── lock.js                   # Cross-process deployment concurrency lock
+│   ├── supervisor.js             # Daemon supervisor (unitupd) managing generations and IPC
+│   └── ipc.js                    # Domain socket / Named Pipe IPC server and client
+│
+└── deploy/                       # Orchestration layer (Composes core primitives)
+    ├── deployment-manager.js     # State machine for full deployments and canary rollouts
+    └── rollback-manager.js       # Rollback sequencing and canary abortion
+```
+
+### Golden Rules:
+1. **Never put deployment sequencing into `core/`**: Router, ProcessManager, GenerationManager, and DrainManager must have no knowledge of "steps" or deployment decisions.
+2. **Never put networking or OS primitives into `deploy/`**: DeploymentManager and RollbackManager must only compose core primitives.
+3. **Never build zero-downtime inside CLI commands**: `src/cli.js` must remain a thin adapter that calls `deploy`, `promote`, or `rollback`.
+4. **Never create per-generation OS service units**: Only one supervisor service unit exists per application.
+
+---
+
+## 2. Deployment State Machine
+
+DeploymentManager executes a strict, observable state machine:
+
+```text
+IDLE
+  └── ACQUIRING_LOCK
+        └── CREATING_GENERATION
+              └── STARTING
+                    └── WAITING_READY
+                          ├── (If canary): SETTING_CANARY -> COMPLETE
+                          └── (If full deploy):
+                                SWITCHING
+                                  └── STABILIZING
+                                        └── DRAINING
+                                              └── STOPPING_PREVIOUS
+                                                    └── COMPLETE
+```
+
+### Critical Safety Invariants:
+- **Previous Generation Safety**: The previous generation is NEVER stopped or drained until the new generation has passed readiness and traffic has switched.
+- **Readiness Failure Preservation**: If the new generation fails readiness or crashes on startup, it is immediately stopped and removed. The router remains pointed at the previous generation, and the deployment fails cleanly.
+- **Stabilization Window**: During `stabilizationWindowMs` (default 500ms), if the new generation crashes, traffic is automatically reverted to the previous generation before an error is thrown.
+- **Port Mismatch & EADDRINUSE Diagnosis**: If user code hardcodes its listening port instead of reading `process.env.PORT`, `ReadinessChecker` diagnoses this immediately (raising `PortMismatchError` or diagnosing `EADDRINUSE` from captured process stderr) rather than hanging for 15 seconds.
+
+---
+
+## 3. Canary & Weighted Routing Mechanics
+
+### Router Primitives (`src/core/router.js`):
+- `setCanary(serviceName, generation, weight)`: Accepts decimal (`0.15`) or percentage (`"15%"` or `15`), normalized to `[0.0, 1.0]`.
+- `resolveBackend(serviceName, req)`:
+  1. **Header Override**:
+     - `x-canary: true`, `1`, `always` -> Routes to canary generation deterministically.
+     - `x-canary: false`, `0`, `never` -> Routes to primary active generation deterministically.
+  2. **Probabilistic Splitting**: If `Math.random() < canary.weight`, routes to canary.
+  3. **Fallback**: Routes to primary active generation.
+- `promoteCanary(serviceName)`: Atomically shifts primary backend to canary, clears canary map, returns promoted generation.
+- `clearCanary(serviceName)`: Removes canary backend without touching primary active generation.
+
+### Canary Deployment Flow:
+```bash
+# 1. Deploy canary with 10% traffic (keeps existing active generation intact)
+unitup deploy <app> --canary --weight 10%
+
+# 2. Inspect status (shows both active and canary generations with port & weight)
+unitup status <app>
+
+# 3A. Promote canary to 100% active (drains and stops old active generation)
+unitup promote <app>
+
+# 3B. OR abort canary (stops and drains canary, keeps old active generation intact)
+unitup rollback <app>
+```
+
+---
+
+## 4. Connection Draining & Streaming Protocols
+
+[DrainManager](file:///Users/ahmet/projects/unitup/src/core/drain-manager.js) ensures graceful retirement:
+1. `inFlightRequests` map tracks active HTTP requests and WebSocket connections per generation ID.
+2. In `_handleHttpRequest`: increments in-flight counter, decrements on response `'finish'` or `'close'`.
+3. In `_handleWebSocketUpgrade`: increments in-flight counter, decrements on socket `'close'`, `'end'`, or `'error'`.
+4. `DrainManager.drain(generation, { timeout, pollInterval, stopProcess })`:
+   - Polls `router.getInFlightCount(generation.id)`.
+   - Waits for active in-flight requests, long-lived WebSockets, Server-Sent Events (SSE), and chunked uploads to complete up to `timeout`.
+   - Stops the process gracefully (`SIGTERM` -> timeout -> `SIGKILL`).
+
+---
+
+## 5. Testing & Verification Runbook
+
+When modifying zero-downtime or routing code, run:
+
+```bash
+# 1. Core routing and architectural boundary tests
+node --test test/router.test.js test/deployment-manager.test.js test/rollback-manager.test.js test/canary.test.js
+
+# 2. Connection draining & streaming protocols test
+node --test test/live-connections.test.js test/drain-manager.test.js
+
+# 3. Continuous zero-downtime traffic integration test (v1 -> v2 -> v1 -> v2 under load)
+node --test test/zero-downtime-integration.test.js
+
+# 4. Full test suite and type check
+npm test
+npx tsc --noEmit
+```
+
+### Test Construction Rules:
+- **Never bind hardcoded ports** like `3000` or `8080`. Always use `port: 0` (ephemeral port allocation) or `findFreePort()` to avoid collisions with running user services.
+- **Always clean up servers and sockets** in `afterEach` or `finally` blocks.

package/index.d.ts

@@ -337,6 +337,20 @@ export class InvalidServiceConfigError extends UnitupError {
 export class ExecutableNotFoundError extends UnitupError {
   executable: string;
 }
+export class ReadinessTimeoutError extends Error {
+  generation: GenerationRecord;
+}
+export class ProcessStartupError extends Error {
+  generation: GenerationRecord;
+}
+export class PortMismatchError extends Error {
+  generation: GenerationRecord;
+  detectedPort: number;
+}
+export class DeploymentLockError extends Error {
+  service: string;
+  lockedPid?: number;
+}
 
 // Adapters
 export abstract class ServiceAdapter {
@@ -443,6 +457,7 @@ export function formatTable(
   columns: Array<{ key: string; label: string }>
 ): string;
 export function formatMemoryBytes(bytes: number | string): string;
+export function formatDuration(ms: number): string;
 export function validateMemorySize(val: string | number, paramName?: string): string;
 export function validateDuration(val: string | number, paramName?: string): string;
 
@@ -515,4 +530,125 @@ export function readScheduleMetadata(name: string): Record<string, unknown> | nu
 export function getScheduleMetadataPath(name: string): string;
 export function getSchedulesDir(): string;
 
+// Zero-Downtime Deployment Primitives & Orchestration
+export interface GenerationRecord {
+  id: number;
+  service: string;
+  pid: number;
+  internalPort: number;
+  status: 'starting' | 'active' | 'previous' | 'draining' | 'stopped' | 'canary' | string;
+  createdAt: string;
+  activatedAt?: string;
+  drainingAt?: string;
+  stoppedAt?: string;
+  canaryWeight?: number;
+}
+
+export interface DeploymentResult {
+  service: string;
+  previousGeneration: number | null;
+  currentGeneration: number;
+  downtimeMs: number;
+  status: string;
+  canaryWeight?: number;
+}
+
+export interface PromoteResult {
+  service: string;
+  promotedGeneration: number;
+  previousGeneration: number | null;
+  downtimeMs: number;
+  status: string;
+}
+
+export interface RollbackResult {
+  service: string;
+  rolledBackFrom: number | null;
+  activeGeneration: number;
+  status: string;
+}
+
+export function deploy(name: string, options?: Record<string, unknown>): Promise<DeploymentResult>;
+export function promote(name: string, options?: Record<string, unknown>): Promise<PromoteResult>;
+export function rollback(name: string, options?: Record<string, unknown>): Promise<RollbackResult>;
+export function generations(name: string, options?: Record<string, unknown>): GenerationRecord[];
+
+export class ProcessManager {
+  constructor(options?: Record<string, unknown>);
+  start(command: string, args?: string[], options?: Record<string, unknown>): { pid: number; child: any; exitPromise: Promise<any> };
+  stop(processOrPid: number | object, options?: { timeout?: number; signal?: string }): Promise<boolean>;
+  signal(processOrPid: number | object, signal?: string): boolean;
+  isAlive(processOrPid: number | object): boolean;
+  waitForExit(processOrPid: number | object, timeout?: number): Promise<{ exited: boolean; code?: number | null; signal?: string | null }>;
+}
+
+export class GenerationManager {
+  constructor(options?: Record<string, unknown>);
+  create(serviceName: string, config?: Record<string, unknown>, options?: Record<string, unknown>): Promise<GenerationRecord>;
+  getActive(serviceName: string): GenerationRecord | null;
+  getPrevious(serviceName: string): GenerationRecord | null;
+  getCanary(serviceName: string): GenerationRecord | null;
+  getGeneration(serviceName: string, id: number | string): GenerationRecord | null;
+  markActive(generation: GenerationRecord): void;
+  markCanary(generation: GenerationRecord, weight?: number | string): void;
+  markDraining(generation: GenerationRecord): void;
+  remove(generation: GenerationRecord, purge?: boolean): void;
+  cleanupStale(serviceName: string): number;
+  listGenerations(serviceName: string): GenerationRecord[];
+}
+
+export class Router {
+  constructor(options?: Record<string, unknown>);
+  listen(publicPort: number, host?: string): Promise<{ port: number; host: string }>;
+  switchBackend(serviceName: string, generation: { id: number; internalPort: number }): void;
+  getActiveBackend(serviceName: string): GenerationRecord | null;
+  setCanary(serviceName: string, generation: { id: number; internalPort: number }, weight?: number | string): void;
+  clearCanary(serviceName: string): void;
+  promoteCanary(serviceName: string): void;
+  getCanary(serviceName: string): { generation: { id: number; internalPort: number }; weight: number } | null;
+  resolveBackend(serviceName: string, req?: any): { id: number; internalPort: number } | null;
+  getInFlightCount(generationId: number | string): number;
+  close(): Promise<void>;
+}
+
+export class ReadinessChecker {
+  constructor(options?: Record<string, unknown>);
+  checkTcp(port: number, host?: string, timeout?: number): Promise<boolean>;
+  checkHttp(port: number, path?: string, timeout?: number): Promise<boolean>;
+  ensure(generation: GenerationRecord, options?: { path?: string }): Promise<boolean>;
+  wait(generation: GenerationRecord, options?: { timeout?: number; interval?: number; path?: string }): Promise<boolean>;
+}
+
+export class DrainManager {
+  constructor(options?: Record<string, unknown>);
+  drain(generation: GenerationRecord, options?: { timeout?: number; pollInterval?: number; stopProcess?: boolean }): Promise<{ drained: boolean; inFlightRemaining: number; timedOut: boolean }>;
+}
+
+export class DeploymentLock {
+  constructor(options?: Record<string, unknown>);
+  acquire(serviceName: string): Promise<boolean>;
+  release(serviceName: string): Promise<boolean>;
+}
+
+export class DeploymentManager {
+  constructor(options?: Record<string, unknown>);
+  deploy(serviceName: string, serviceConfig?: Record<string, unknown>, options?: Record<string, unknown>): Promise<DeploymentResult>;
+  promote(serviceName: string, serviceConfig?: Record<string, unknown>, options?: Record<string, unknown>): Promise<PromoteResult>;
+}
+
+export class RollbackManager {
+  constructor(options?: Record<string, unknown>);
+  rollback(serviceName: string, serviceConfig?: Record<string, unknown>, options?: Record<string, unknown>): Promise<RollbackResult>;
+}
+
+export class Supervisor {
+  constructor(serviceName: string, serviceConfig?: Record<string, unknown>, options?: Record<string, unknown>);
+  start(): Promise<Supervisor>;
+  stop(): Promise<void>;
+  static run(serviceName: string): Promise<void>;
+}
+
+export const defaultDeploymentManager: DeploymentManager;
+export const defaultRollbackManager: RollbackManager;
+
 export default defaultManager;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitup",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Minimal, zero-dependency cross-platform native service manager (systemd, launchd, Windows Services) for any runtime, script, or executable",
   "main": "src/index.js",
   "types": "./index.d.ts",