servherd 1.0.0 → 1.1.0

package/README.md

@@ -11,7 +11,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/servherd"><img src="https://img.shields.io/npm/v/servherd.svg" alt="npm version"></a>
   <a href="https://github.com/apowers313/servherd/actions/workflows/ci.yml"><img src="https://github.com/apowers313/servherd/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
-  <a href="https://codecov.io/gh/apowers313/servherd"><img src="https://codecov.io/gh/apowers313/servherd/branch/main/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://coveralls.io/github/apowers313/servherd?branch=master"><img src="https://coveralls.io/repos/github/apowers313/servherd/badge.svg?branch=master" alt="Coverage"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 </p>
 
@@ -200,6 +200,79 @@ servherd start --name my-flask -e FLASK_RUN_PORT={{port}} -- flask run
 servherd start --name my-fastapi -- uvicorn main:app --port {{port}}
 ```
 
+## Cross-Server Communication
+
+When running multiple servers (like a frontend and backend), you often need one server to know the port of another. The `{{$ ...}}` helper looks up properties from other running servers.
+
+### Basic Syntax
+
+```bash
+# Positional arguments: {{$ "server-name" "property"}}
+{{$ "backend" "port"}}
+
+# Named arguments (more explicit)
+{{$ service="backend" prop="port"}}
+
+# With aliases
+{{$ svc="backend" property="port"}}
+
+# Explicit working directory (for cross-project lookups)
+{{$ service="backend" prop="port" cwd="/path/to/project"}}
+```
+
+### Available Properties
+
+| Property | Description | Example |
+|----------|-------------|---------|
+| `port` | Server's assigned port | `9042` |
+| `url` | Full URL | `http://localhost:9042` |
+| `name` | Server name | `backend` |
+| `hostname` | Configured hostname | `localhost` |
+| `protocol` | Protocol (http/https) | `http` |
+
+### Frontend + Backend Example
+
+Start a backend API server, then a frontend that connects to it:
+
+```bash
+# Start backend first
+servherd start -n backend -e 'PORT={{port}}' -- node server.js
+
+# Start frontend with reference to backend's port
+servherd start -n frontend \
+  -e 'PORT={{port}}' \
+  -e 'API_URL=http://localhost:{{$ "backend" "port"}}' \
+  -- npm run dev
+```
+
+The frontend's `API_URL` will be set to the backend's actual port (e.g., `http://localhost:9042`).
+
+### npm Scripts Example
+
+In your `package.json`, use single quotes inside double quotes to avoid escaping issues:
+
+```json
+{
+  "scripts": {
+    "start:backend": "servherd start -n backend -e 'PORT={{port}}' -- node server.js",
+    "start:frontend": "servherd start -n frontend -e 'PORT={{port}}' -e 'API_URL=http://localhost:{{$ \"backend\" \"port\"}}' -- npm run dev",
+    "stop": "servherd stop --all"
+  }
+}
+```
+
+**Quoting tips for npm scripts:**
+- Wrap `-e` values in single quotes: `-e 'VAR={{value}}'`
+- Use escaped double quotes inside for `$` helper arguments: `{{$ \"name\" \"prop\"}}`
+- Both `{{$ "x" "y"}}` and `{{$ 'x' 'y'}}` work in Handlebars, but single quotes are easier in JSON
+
+### Important Notes
+
+1. **Start order matters** - The referenced server must be running before you start the dependent server
+2. **Same working directory** - By default, lookups are scoped to servers in the same working directory (same git worktree)
+3. **Error on missing** - If the referenced server doesn't exist, the start command will fail with a clear error message
+4. **Cross-project lookups** - Use the `cwd` parameter to reference servers in other directories
+
 ## CLI Reference
 
 ### Global Options
@@ -238,6 +311,7 @@ servherd start [options] -- <command>
 | `{{url}}` | Full URL | `http://localhost:8080` |
 | `{{https-cert}}` | HTTPS certificate path | `/path/to/cert.pem` |
 | `{{https-key}}` | HTTPS key path | `/path/to/key.pem` |
+| `{{$ "name" "prop"}}` | Look up property from another server | `{{$ "backend" "port"}}` |
 
 **Examples:**
 ```bash

package/dist/cli/commands/config.d.ts

@@ -10,6 +10,9 @@ export interface ConfigCommandOptions {
     refreshAll?: boolean;
     tag?: string;
     dryRun?: boolean;
+    add?: string;
+    remove?: string;
+    listVars?: boolean;
 }
 /**
  * Execute the config command
@@ -32,4 +35,11 @@ export declare function configAction(options: {
     reset?: boolean;
     force?: boolean;
     json?: boolean;
+    add?: string;
+    remove?: string;
+    listVars?: boolean;
+    refresh?: string;
+    refreshAll?: boolean;
+    tag?: string;
+    dryRun?: boolean;
 }): Promise<void>;

package/dist/cli/commands/config.js

@@ -1,4 +1,5 @@
 import { confirm, input, select } from "@inquirer/prompts";
+import { pathExists } from "fs-extra/esm";
 import { ConfigService } from "../../services/config.service.js";
 import { RegistryService } from "../../services/registry.service.js";
 import { formatConfigResult } from "../output/formatters.js";
@@ -9,10 +10,14 @@ import { ServherdError, ServherdErrorCode } from "../../types/errors.js";
 import { findServersUsingConfigKey } from "../../utils/config-drift.js";
 import { executeRefresh } from "./refresh.js";
 // Valid top-level config keys
-const VALID_TOP_LEVEL_KEYS = ["version", "hostname", "protocol", "portRange", "tempDir", "pm2", "httpsCert", "httpsKey", "refreshOnChange"];
+const VALID_TOP_LEVEL_KEYS = ["version", "hostname", "protocol", "portRange", "tempDir", "pm2", "httpsCert", "httpsKey", "refreshOnChange", "variables"];
 const VALID_NESTED_KEYS = ["portRange.min", "portRange.max", "pm2.logDir", "pm2.pidDir"];
 // Config keys that can affect server commands (used for drift detection)
 const SERVER_AFFECTING_KEYS = ["hostname", "httpsCert", "httpsKey"];
+// Reserved variable names that cannot be used for custom variables
+const RESERVED_VARIABLE_NAMES = ["port", "hostname", "url", "https-cert", "https-key"];
+// Regex pattern for valid variable names (must match template regex)
+const VARIABLE_NAME_PATTERN = /^[\w-]+$/;
 function isValidKey(key) {
     return VALID_TOP_LEVEL_KEYS.includes(key) || VALID_NESTED_KEYS.includes(key);
 }
@@ -126,6 +131,73 @@ export async function executeConfig(options) {
             dryRun: options.dryRun,
         };
     }
+    // Handle --list-vars
+    if (options.listVars) {
+        const config = await configService.load();
+        return {
+            variables: config.variables ?? {},
+        };
+    }
+    // Handle --add
+    if (options.add) {
+        const name = options.add;
+        if (options.value === undefined) {
+            return {
+                addedVar: false,
+                error: "--value is required when using --add",
+            };
+        }
+        // Validate variable name format
+        if (!VARIABLE_NAME_PATTERN.test(name)) {
+            return {
+                addedVar: false,
+                error: `Invalid variable name "${name}". Variable names can only contain letters, numbers, underscores, and hyphens.`,
+            };
+        }
+        // Check for reserved names
+        if (RESERVED_VARIABLE_NAMES.includes(name)) {
+            return {
+                addedVar: false,
+                error: `"${name}" is a reserved variable name. Reserved names: ${RESERVED_VARIABLE_NAMES.join(", ")}`,
+            };
+        }
+        const config = await configService.load();
+        const updatedConfig = {
+            ...config,
+            variables: {
+                ...(config.variables ?? {}),
+                [name]: options.value,
+            },
+        };
+        await configService.save(updatedConfig);
+        return {
+            addedVar: true,
+            varName: name,
+            varValue: options.value,
+        };
+    }
+    // Handle --remove
+    if (options.remove) {
+        const name = options.remove;
+        const config = await configService.load();
+        if (!config.variables || !(name in config.variables)) {
+            return {
+                removedVar: false,
+                error: `Variable "${name}" does not exist`,
+            };
+        }
+        const updatedVariables = { ...config.variables };
+        delete updatedVariables[name];
+        const updatedConfig = {
+            ...config,
+            variables: updatedVariables,
+        };
+        await configService.save(updatedConfig);
+        return {
+            removedVar: true,
+            varName: name,
+        };
+    }
     // Handle --get
     if (options.get) {
         const key = options.get;
@@ -191,6 +263,16 @@ export async function executeConfig(options) {
             }
             parsedValue = num;
         }
+        // Validate HTTPS certificate/key paths exist
+        if ((key === "httpsCert" || key === "httpsKey") && options.value && options.value.length > 0) {
+            const fileExists = await pathExists(options.value);
+            if (!fileExists) {
+                return {
+                    updated: false,
+                    error: `File not found: ${options.value}`,
+                };
+            }
+        }
         // Handle nested keys vs top-level keys
         let updatedConfig;
         if (key.includes(".")) {
@@ -311,6 +393,29 @@ export async function runConfigWizard() {
  */
 export async function configAction(options) {
     try {
+        // Check if any explicit option was provided
+        const hasOptions = options.show || options.get || options.set ||
+            options.reset || options.refresh || options.refreshAll ||
+            options.add || options.remove || options.listVars;
+        // If no options provided, run wizard in interactive mode, or show config in CI mode
+        if (!hasOptions) {
+            if (CIDetector.isCI()) {
+                // In CI, default to showing config (no interactive wizard)
+                const result = await executeConfig({ show: true });
+                if (options.json) {
+                    console.log(formatAsJson(result));
+                }
+                else {
+                    console.log(formatConfigResult(result));
+                }
+                return;
+            }
+            else {
+                // In interactive mode, run the wizard
+                await runConfigWizard();
+                return;
+            }
+        }
         const result = await executeConfig(options);
         if (options.json) {
             console.log(formatAsJson(result));

package/dist/cli/commands/info.js

@@ -3,6 +3,7 @@ import { ProcessService } from "../../services/process.service.js";
 import { formatServerInfo } from "../output/formatters.js";
 import { formatAsJson, formatErrorAsJson } from "../output/json-formatter.js";
 import { logger } from "../../utils/logger.js";
+import { ServherdError, ServherdErrorCode } from "../../types/errors.js";
 /**
  * Execute the info command
  */
@@ -15,7 +16,7 @@ export async function executeInfo(options) {
         // Find server by name
         const server = registryService.findByName(options.name);
         if (!server) {
-            throw new Error(`Server "${options.name}" not found`);
+            throw new ServherdError(ServherdErrorCode.SERVER_NOT_FOUND, `Server "${options.name}" not found`);
         }
         // Connect to PM2 to get process details
         await processService.connect();

package/dist/cli/commands/logs.js

@@ -37,11 +37,11 @@ export async function executeFlush(options) {
     try {
         await processService.connect();
         if (options.all) {
-            await processService.flush();
+            await processService.flushAll();
             return {
                 flushed: true,
                 all: true,
-                message: "Logs flushed for all servers",
+                message: "Logs flushed for all servherd-managed servers",
             };
         }
         if (!options.name) {

package/dist/cli/commands/refresh.d.ts

@@ -12,6 +12,12 @@ export interface RefreshResult {
     message?: string;
     driftDetails?: string;
     skipped?: boolean;
+    /** Whether port was reassigned due to being out of range */
+    portReassigned?: boolean;
+    /** Original port before reassignment */
+    originalPort?: number;
+    /** New port after reassignment */
+    newPort?: number;
 }
 /**
  * Execute the refresh command

package/dist/cli/commands/refresh.js

@@ -1,32 +1,50 @@
 import { RegistryService } from "../../services/registry.service.js";
 import { ProcessService } from "../../services/process.service.js";
 import { ConfigService } from "../../services/config.service.js";
+import { PortService } from "../../services/port.service.js";
 import { renderTemplate, renderEnvTemplates, getTemplateVariables } from "../../utils/template.js";
 import { extractUsedConfigKeys, createConfigSnapshot, findServersWithDrift, formatDrift, } from "../../utils/config-drift.js";
+/**
+ * Build template context for server lookups
+ */
+function buildTemplateContext(registryService, cwd) {
+    return {
+        cwd,
+        lookupServer: (name, lookupCwd) => {
+            return registryService.findByCwdAndName(lookupCwd ?? cwd, name);
+        },
+    };
+}
 /**
  * Re-resolve a server's command template with current config values
  * Updates the registry with new resolved command and config snapshot
+ * @param newPort - Optional new port if port was reassigned
  */
-async function refreshServerConfig(server, config, registryService) {
+async function refreshServerConfig(server, config, registryService, templateContext, newPort) {
+    const port = newPort ?? server.port;
     // Get template variables with current config
-    const templateVars = getTemplateVariables(config, server.port);
+    const templateVars = getTemplateVariables(config, port);
     // Re-resolve the command template
-    const resolvedCommand = renderTemplate(server.command, templateVars);
+    const resolvedCommand = renderTemplate(server.command, templateVars, templateContext);
     // Re-resolve environment variables if any
     const resolvedEnv = server.env
-        ? renderEnvTemplates(server.env, templateVars)
+        ? renderEnvTemplates(server.env, templateVars, templateContext)
         : {};
     // Extract new used config keys and create new snapshot
     const usedConfigKeys = extractUsedConfigKeys(server.command);
-    const configSnapshot = createConfigSnapshot(config, usedConfigKeys);
-    // Update the registry
-    await registryService.updateServer(server.id, {
+    const configSnapshot = createConfigSnapshot(config, usedConfigKeys, server.command);
+    // Update the registry (include port if it changed)
+    const updates = {
         resolvedCommand,
         env: resolvedEnv,
         usedConfigKeys,
         configSnapshot,
-    });
-    return { resolvedCommand };
+    };
+    if (newPort !== undefined) {
+        updates.port = newPort;
+    }
+    await registryService.updateServer(server.id, updates);
+    return { resolvedCommand, port };
 }
 /**
  * Execute the refresh command
@@ -73,22 +91,40 @@ export async function executeRefresh(options) {
                 }];
         }
         const results = [];
+        const portService = new PortService(config);
         for (const { server, drift } of serversWithDrift) {
             const driftDetails = formatDrift(drift);
+            // Build template context for this server's cwd
+            const templateContext = buildTemplateContext(registryService, server.cwd);
+            // Check if port needs reassignment
+            let newPort;
+            let portReassigned = false;
+            if (drift.portOutOfRange) {
+                const { port } = await portService.assignPort(server.cwd, server.command, undefined);
+                newPort = port;
+                portReassigned = true;
+            }
             // Dry run mode - just report what would happen
             if (options.dryRun) {
-                results.push({
+                const dryRunResult = {
                     name: server.name,
                     success: true,
                     skipped: true,
                     message: "Would refresh (dry-run mode)",
                     driftDetails,
-                });
+                };
+                if (portReassigned) {
+                    dryRunResult.portReassigned = true;
+                    dryRunResult.originalPort = server.port;
+                    dryRunResult.newPort = newPort;
+                    dryRunResult.message = `Would refresh and reassign port ${server.port} → ${newPort} (dry-run mode)`;
+                }
+                results.push(dryRunResult);
                 continue;
             }
             try {
-                // Re-resolve command with new config values
-                const { resolvedCommand } = await refreshServerConfig(server, config, registryService);
+                // Re-resolve command with new config values (and new port if reassigned)
+                const { resolvedCommand, port } = await refreshServerConfig(server, config, registryService, templateContext, newPort);
                 // Delete old process and start with new command
                 try {
                     await processService.delete(server.pm2Name);
@@ -110,16 +146,22 @@ export async function executeRefresh(options) {
                     cwd: server.cwd,
                     env: {
                         ...env,
-                        PORT: String(server.port),
+                        PORT: String(port),
                     },
                 });
                 const status = await processService.getStatus(server.pm2Name);
-                results.push({
+                const result = {
                     name: server.name,
                     success: true,
                     status,
                     driftDetails,
-                });
+                };
+                if (portReassigned) {
+                    result.portReassigned = true;
+                    result.originalPort = server.port;
+                    result.newPort = newPort;
+                }
+                results.push(result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);

package/dist/cli/commands/remove.js

@@ -4,6 +4,8 @@ import { ProcessService } from "../../services/process.service.js";
 import { formatRemoveResult } from "../output/formatters.js";
 import { formatAsJson, formatErrorAsJson } from "../output/json-formatter.js";
 import { logger } from "../../utils/logger.js";
+import { CIDetector } from "../../utils/ci-detector.js";
+import { ServherdError, ServherdErrorCode } from "../../types/errors.js";
 /**
  * Execute the remove command
  */
@@ -39,6 +41,10 @@ export async function executeRemove(options) {
         }
         // Ask for confirmation unless --force is specified
         if (!options.force) {
+            // In CI mode, require --force to prevent hanging on confirmation prompt
+            if (CIDetector.isCI()) {
+                throw new ServherdError(ServherdErrorCode.INTERACTIVE_NOT_AVAILABLE, "Remove requires --force flag in CI mode to prevent hanging on confirmation prompt");
+            }
             const serverNames = serversToRemove.map((s) => s.name).join(", ");
             const message = serversToRemove.length === 1
                 ? `Are you sure you want to remove server "${serversToRemove[0].name}"?`

package/dist/cli/commands/restart.js

@@ -6,22 +6,34 @@ import { formatAsJson, formatErrorAsJson } from "../output/json-formatter.js";
 import { logger } from "../../utils/logger.js";
 import { renderTemplate, renderEnvTemplates, getTemplateVariables } from "../../utils/template.js";
 import { extractUsedConfigKeys, createConfigSnapshot, detectDrift, } from "../../utils/config-drift.js";
+import { ServherdError, ServherdErrorCode } from "../../types/errors.js";
+/**
+ * Build template context for server lookups
+ */
+function buildTemplateContext(registryService, cwd) {
+    return {
+        cwd,
+        lookupServer: (name, lookupCwd) => {
+            return registryService.findByCwdAndName(lookupCwd ?? cwd, name);
+        },
+    };
+}
 /**
  * Re-resolve a server's command template with current config values
  * Updates the registry with new resolved command and config snapshot
  */
-async function refreshServerConfig(server, config, registryService) {
+async function refreshServerConfig(server, config, registryService, templateContext) {
     // Get template variables with current config
     const templateVars = getTemplateVariables(config, server.port);
     // Re-resolve the command template
-    const resolvedCommand = renderTemplate(server.command, templateVars);
+    const resolvedCommand = renderTemplate(server.command, templateVars, templateContext);
     // Re-resolve environment variables if any
     const resolvedEnv = server.env
-        ? renderEnvTemplates(server.env, templateVars)
+        ? renderEnvTemplates(server.env, templateVars, templateContext)
         : {};
     // Extract new used config keys and create new snapshot
     const usedConfigKeys = extractUsedConfigKeys(server.command);
-    const configSnapshot = createConfigSnapshot(config, usedConfigKeys);
+    const configSnapshot = createConfigSnapshot(config, usedConfigKeys, server.command);
     // Update the registry
     await registryService.updateServer(server.id, {
         resolvedCommand,
@@ -55,24 +67,26 @@ export async function executeRestart(options) {
         else if (options.name) {
             const server = registryService.findByName(options.name);
             if (!server) {
-                throw new Error(`Server "${options.name}" not found`);
+                throw new ServherdError(ServherdErrorCode.SERVER_NOT_FOUND, `Server "${options.name}" not found`);
             }
             servers = [server];
         }
         else {
-            throw new Error("Either --name, --all, or --tag must be specified");
+            throw new ServherdError(ServherdErrorCode.COMMAND_MISSING_ARGUMENT, "Either --name, --all, or --tag must be specified");
         }
         // Restart all matched servers
         const results = [];
         for (const server of servers) {
             try {
                 let configRefreshed = false;
+                // Build template context for this server's cwd
+                const templateContext = buildTemplateContext(registryService, server.cwd);
                 // Check if we should refresh config on restart (on-start mode)
                 if (config.refreshOnChange === "on-start") {
                     const drift = detectDrift(server, config);
                     if (drift.hasDrift) {
                         // Re-resolve command with new config values
-                        const { resolvedCommand } = await refreshServerConfig(server, config, registryService);
+                        const { resolvedCommand } = await refreshServerConfig(server, config, registryService, templateContext);
                         configRefreshed = true;
                         // Delete old process and start with new command
                         try {

package/dist/cli/commands/start.d.ts

@@ -10,12 +10,21 @@ export interface StartCommandOptions {
     env?: Record<string, string>;
 }
 export interface StartCommandResult {
-    action: "started" | "existing" | "restarted" | "renamed";
+    action: "started" | "existing" | "restarted" | "renamed" | "refreshed";
     server: ServerEntry;
     status: ServerStatus;
     portReassigned?: boolean;
     originalPort?: number;
     previousName?: string;
+    envChanged?: boolean;
+    /** Whether the command was changed (with explicit -n) */
+    commandChanged?: boolean;
+    /** Whether config drift was detected and applied */
+    configDrift?: boolean;
+    /** Details of config drift that was applied */
+    driftDetails?: string[];
+    /** User declined refresh when prompted */
+    userDeclinedRefresh?: boolean;
 }
 /**
  * Execute the start command