unitup 0.3.0 → 0.4.0

package/src/deploy/deployment-manager.js

@@ -171,11 +171,7 @@ export class DeploymentManager extends EventEmitter {
       );
 
       // 4. WAITING_READY
-      this._setState(
-        DeploymentState.WAITING_READY,
-        { service: serviceName, generation: next.id },
-        options.onProgress
-      );
+      this._setState(DeploymentState.WAITING_READY, { service: serviceName, generation: next.id }, options.onProgress);
 
       try {
         const readyPath = options.readyPath || config.deploy?.ready;
@@ -201,18 +197,19 @@ export class DeploymentManager extends EventEmitter {
       const isCanary = Boolean(options.canary);
       const rawWeight =
         options.weight !== undefined ? options.weight : options.canaryWeight !== undefined ? options.canaryWeight : 0.1;
-      const parsedWeight = typeof rawWeight === 'string' ? Number.parseFloat(rawWeight.replace('%', '')) : Number(rawWeight);
+      const parsedWeight =
+        typeof rawWeight === 'string' ? Number.parseFloat(rawWeight.replace('%', '')) : Number(rawWeight);
       const numWeight = Number.isNaN(parsedWeight) ? 0.1 : parsedWeight;
       const canaryWeight = Math.max(0, Math.min(1, numWeight > 1 ? numWeight / 100 : numWeight));
 
       if (isCanary) {
         const publicPort = options.publicPort || config.port;
-        if (publicPort && (!this.router.server || this.router.listeningPort !== publicPort)) {
-          await this.router.listen(publicPort);
+        if (publicPort) {
+          await this.router.listen(publicPort, '0.0.0.0', serviceName);
         }
 
         if (!previous) {
-          this.router.switchBackend(serviceName, next);
+          this.router.switchBackend(serviceName, next, publicPort);
           this.generationManager.markActive(next);
         }
 
@@ -222,7 +219,7 @@ export class DeploymentManager extends EventEmitter {
           options.onProgress
         );
 
-        this.router.setCanary(serviceName, next, canaryWeight);
+        this.router.setCanary(serviceName, next, canaryWeight, publicPort);
         this.generationManager.markCanary(next, canaryWeight);
 
         const result = {
@@ -240,26 +237,18 @@ export class DeploymentManager extends EventEmitter {
       }
 
       // 5. SWITCHING
-      this._setState(
-        DeploymentState.SWITCHING,
-        { service: serviceName, generation: next.id },
-        options.onProgress
-      );
+      this._setState(DeploymentState.SWITCHING, { service: serviceName, generation: next.id }, options.onProgress);
 
       const publicPort = options.publicPort || config.port;
-      if (publicPort && (!this.router.server || this.router.listeningPort !== publicPort)) {
-        await this.router.listen(publicPort);
+      if (publicPort) {
+        await this.router.listen(publicPort, '0.0.0.0', serviceName);
       }
 
-      this.router.switchBackend(serviceName, next);
+      this.router.switchBackend(serviceName, next, publicPort);
       this.generationManager.markActive(next);
 
       // 6. STABILIZING
-      this._setState(
-        DeploymentState.STABILIZING,
-        { service: serviceName, generation: next.id },
-        options.onProgress
-      );
+      this._setState(DeploymentState.STABILIZING, { service: serviceName, generation: next.id }, options.onProgress);
 
       const stabilizationMs =
         options.stabilizationWindowMs !== undefined ? options.stabilizationWindowMs : this.defaultStabilizationMs;
@@ -271,7 +260,7 @@ export class DeploymentManager extends EventEmitter {
           if (!this.processManager.isAlive(next.pid)) {
             // New generation crashed during stabilization window! Revert to previous!
             if (previous && this.processManager.isAlive(previous.pid)) {
-              this.router.switchBackend(serviceName, previous);
+              this.router.switchBackend(serviceName, previous, publicPort);
               this.generationManager.markActive(previous);
             }
             this.generationManager.remove(next, true);
@@ -293,11 +282,7 @@ export class DeploymentManager extends EventEmitter {
 
       // 7. DRAINING
       if (previous && previous.id !== next.id) {
-        this._setState(
-          DeploymentState.DRAINING,
-          { service: serviceName, generation: previous.id },
-          options.onProgress
-        );
+        this._setState(DeploymentState.DRAINING, { service: serviceName, generation: previous.id }, options.onProgress);
 
         this.generationManager.markDraining(previous);
         const drainTimeout = options.drainTimeout || config.deploy?.drainTimeout || 10000;
@@ -370,11 +355,7 @@ export class DeploymentManager extends EventEmitter {
 
       // 2. Drain previous generation
       if (previous && previous.id !== canaryGen.id) {
-        this._setState(
-          DeploymentState.DRAINING,
-          { service: serviceName, generation: previous.id },
-          options.onProgress
-        );
+        this._setState(DeploymentState.DRAINING, { service: serviceName, generation: previous.id }, options.onProgress);
         this.generationManager.markDraining(previous);
         const drainTimeout = options.drainTimeout || config.deploy?.drainTimeout || 10000;
         await this.drainManager.drain(previous, { timeout: drainTimeout, stopProcess: false });

package/src/deploy/rollback-manager.js

@@ -151,7 +151,8 @@ export class RollbackManager {
       }
 
       // Switch router to previous generation
-      this.router.switchBackend(serviceName, previous);
+      const publicPort = options.publicPort || config.port;
+      this.router.switchBackend(serviceName, previous, publicPort);
       this.generationManager.markActive(previous);
 
       // Drain and stop the rolled-back current generation

package/src/index.js

@@ -1,3 +1,26 @@
+import {
+  DeploymentLock,
+  DeploymentLockError,
+  DrainManager,
+  GenerationManager,
+  IPCClient,
+  IPCServer,
+  PortMismatchError,
+  ProcessManager,
+  ProcessStartupError,
+  ReadinessChecker,
+  ReadinessTimeoutError,
+  Router,
+  Supervisor,
+  findFreePort
+} from './core/index.js';
+import {
+  DeploymentManager,
+  DeploymentState,
+  RollbackManager,
+  defaultDeploymentManager,
+  defaultRollbackManager
+} from './deploy/index.js';
 import { getDoctorInfo, runDoctor } from './doctor.js';
 import {
   ExecutableNotFoundError,
@@ -95,29 +118,6 @@ import {
   validateDuration,
   validateMemorySize
 } from './utils.js';
-import {
-  ProcessManager,
-  GenerationManager,
-  Router,
-  ReadinessChecker,
-  ReadinessTimeoutError,
-  ProcessStartupError,
-  PortMismatchError,
-  DrainManager,
-  DeploymentLock,
-  DeploymentLockError,
-  Supervisor,
-  IPCServer,
-  IPCClient,
-  findFreePort
-} from './core/index.js';
-import {
-  DeploymentManager,
-  DeploymentState,
-  defaultDeploymentManager,
-  RollbackManager,
-  defaultRollbackManager
-} from './deploy/index.js';
 
 // Aliases for unified cross-platform API
 const install = (opts) => defaultManager.install(opts);

package/src/platform/windows-host.js

@@ -1,4 +1,4 @@
-import { spawn, execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';

package/src/unit.js

@@ -99,6 +99,10 @@ export function generateUnitContent(opts) {
     .filter((p, i, self) => p && self.indexOf(p) === i)
     .join(':');
 
+  const logLevelMax = opts.logLevelMax || 'info';
+  const logRateLimitIntervalSec = opts.logRateLimitIntervalSec || '10s';
+  const logRateLimitBurst = opts.logRateLimitBurst !== undefined ? opts.logRateLimitBurst : 200;
+
   const serviceLines = [
     '[Unit]',
     `Description=unitup service: ${safeName}`,
@@ -112,7 +116,10 @@ export function generateUnitContent(opts) {
     `Restart=${restartPolicy}`,
     'RestartSec=3',
     'StandardOutput=journal',
-    'StandardError=journal'
+    'StandardError=journal',
+    `LogLevelMax=${logLevelMax}`,
+    `LogRateLimitIntervalSec=${logRateLimitIntervalSec}`,
+    `LogRateLimitBurst=${logRateLimitBurst}`
   ];
 
   const effectiveLimits = resolveEffectiveMemoryLimits(opts);
@@ -173,6 +180,8 @@ export function writeUnitFile(opts) {
     script: opts.script,
     cwd: opts.cwd,
     node: opts.nodePath,
+    port: opts.port,
+    deploy: opts.deploy,
     memoryHigh: opts.memoryHigh || opts.resources?.memoryHigh,
     memoryMax: opts.memoryMax || opts.resources?.memoryMax,
     memorySwapMax: opts.memorySwapMax || opts.resources?.memorySwapMax,
@@ -263,6 +272,12 @@ export function parseUnitContent(content) {
       result.memoryMax = trimmed.slice(10).trim();
     } else if (trimmed.startsWith('MemorySwapMax=')) {
       result.memorySwapMax = trimmed.slice(14).trim();
+    } else if (trimmed.startsWith('LogLevelMax=')) {
+      result.logLevelMax = trimmed.slice(12).trim();
+    } else if (trimmed.startsWith('LogRateLimitIntervalSec=')) {
+      result.logRateLimitIntervalSec = trimmed.slice(24).trim();
+    } else if (trimmed.startsWith('LogRateLimitBurst=')) {
+      result.logRateLimitBurst = Number.parseInt(trimmed.slice(18).trim(), 10);
     }
   }
 
@@ -320,6 +335,10 @@ export function generateScheduleServiceContent(opts) {
     .filter((p, i, self) => p && self.indexOf(p) === i)
     .join(':');
 
+  const logLevelMax = opts.logLevelMax || 'info';
+  const logRateLimitIntervalSec = opts.logRateLimitIntervalSec || '10s';
+  const logRateLimitBurst = opts.logRateLimitBurst !== undefined ? opts.logRateLimitBurst : 200;
+
   const serviceLines = [
     '[Unit]',
     `Description=unitup scheduled task: ${safeName}`,
@@ -331,7 +350,10 @@ export function generateScheduleServiceContent(opts) {
     `WorkingDirectory=${cwd}`,
     `ExecStart=${execStartLine}`,
     'StandardOutput=journal',
-    'StandardError=journal'
+    'StandardError=journal',
+    `LogLevelMax=${logLevelMax}`,
+    `LogRateLimitIntervalSec=${logRateLimitIntervalSec}`,
+    `LogRateLimitBurst=${logRateLimitBurst}`
   ];
 
   const effectiveLimits = resolveEffectiveMemoryLimits(opts);

package/.agents/AGENTS.md

@@ -1,35 +0,0 @@
-# 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

@@ -1,80 +0,0 @@
----
-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

@@ -1,108 +0,0 @@
----
-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

@@ -1,88 +0,0 @@
----
-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/
-```