servherd 0.0.1 → 1.0.0

package/dist/services/config.service.d.ts

@@ -0,0 +1,80 @@
+import { type GlobalConfig } from "../types/config.js";
+/**
+ * Configuration search locations (in order of precedence):
+ * 1. Project-local configs (searched from cwd upward):
+ *    - package.json "servherd" key
+ *    - .servherdrc (JSON or YAML)
+ *    - .servherdrc.json
+ *    - .servherdrc.yaml / .servherdrc.yml
+ *    - .servherdrc.js / .servherdrc.cjs
+ *    - servherd.config.js / servherd.config.cjs
+ * 2. Global config: ~/.servherd/config.json
+ * 3. Environment variables (highest priority)
+ */
+/**
+ * Service for managing global configuration using cosmiconfig
+ */
+export declare class ConfigService {
+    private config;
+    private globalConfigDir;
+    private globalConfigPath;
+    private loadedFilepath;
+    private explorer;
+    constructor();
+    /**
+     * Load configuration from multiple sources with the following priority:
+     * 1. Environment variables (highest)
+     * 2. Project-local config file (if found)
+     * 3. Global config file (~/.servherd/config.json)
+     * 4. Default values (lowest)
+     */
+    load(searchFrom?: string): Promise<GlobalConfig>;
+    /**
+     * Load the global config file from ~/.servherd/config.json
+     */
+    private loadGlobalConfig;
+    /**
+     * Search for project-local config starting from the given directory
+     */
+    private searchProjectConfig;
+    /**
+     * Merge partial config into base config (supports deeply partial configs)
+     */
+    private mergeConfigs;
+    /**
+     * Save configuration to the global config file
+     */
+    save(config: GlobalConfig): Promise<void>;
+    /**
+     * Get a configuration value
+     */
+    get<K extends keyof GlobalConfig>(key: K): GlobalConfig[K];
+    /**
+     * Set a configuration value and persist to the global config file
+     */
+    set<K extends keyof GlobalConfig>(key: K, value: GlobalConfig[K]): Promise<void>;
+    /**
+     * Get default configuration
+     */
+    getDefaults(): GlobalConfig;
+    /**
+     * Get the global config file path
+     */
+    getConfigPath(): string;
+    /**
+     * Get the path of the currently loaded config file (if any)
+     */
+    getLoadedConfigPath(): string | null;
+    /**
+     * Get all supported config file names for documentation
+     */
+    getSupportedConfigFiles(): string[];
+    /**
+     * Apply environment variable overrides to configuration
+     */
+    applyEnvironmentOverrides(config: GlobalConfig): GlobalConfig;
+    /**
+     * Clear the cosmiconfig cache (useful for testing or after config changes)
+     */
+    clearCache(): void;
+}

package/dist/services/config.service.js

@@ -0,0 +1,227 @@
+import { cosmiconfig } from "cosmiconfig";
+import { ensureDir, writeJson } from "fs-extra/esm";
+import * as path from "path";
+import * as os from "os";
+import { DEFAULT_CONFIG, GlobalConfigSchema } from "../types/config.js";
+import { logger } from "../utils/logger.js";
+const MODULE_NAME = "servherd";
+/**
+ * Configuration search locations (in order of precedence):
+ * 1. Project-local configs (searched from cwd upward):
+ *    - package.json "servherd" key
+ *    - .servherdrc (JSON or YAML)
+ *    - .servherdrc.json
+ *    - .servherdrc.yaml / .servherdrc.yml
+ *    - .servherdrc.js / .servherdrc.cjs
+ *    - servherd.config.js / servherd.config.cjs
+ * 2. Global config: ~/.servherd/config.json
+ * 3. Environment variables (highest priority)
+ */
+/**
+ * Service for managing global configuration using cosmiconfig
+ */
+export class ConfigService {
+    config;
+    globalConfigDir;
+    globalConfigPath;
+    loadedFilepath = null;
+    explorer = cosmiconfig(MODULE_NAME, {
+        searchPlaces: [
+            "package.json",
+            `.${MODULE_NAME}rc`,
+            `.${MODULE_NAME}rc.json`,
+            `.${MODULE_NAME}rc.yaml`,
+            `.${MODULE_NAME}rc.yml`,
+            `.${MODULE_NAME}rc.js`,
+            `.${MODULE_NAME}rc.cjs`,
+            `${MODULE_NAME}.config.js`,
+            `${MODULE_NAME}.config.cjs`,
+        ],
+    });
+    constructor() {
+        this.config = { ...DEFAULT_CONFIG };
+        this.globalConfigDir = path.join(os.homedir(), ".servherd");
+        this.globalConfigPath = path.join(this.globalConfigDir, "config.json");
+    }
+    /**
+     * Load configuration from multiple sources with the following priority:
+     * 1. Environment variables (highest)
+     * 2. Project-local config file (if found)
+     * 3. Global config file (~/.servherd/config.json)
+     * 4. Default values (lowest)
+     */
+    async load(searchFrom) {
+        let baseConfig = { ...DEFAULT_CONFIG };
+        // First, try to load global config
+        const globalResult = await this.loadGlobalConfig();
+        if (globalResult) {
+            baseConfig = this.mergeConfigs(baseConfig, globalResult);
+        }
+        // Then, search for project-local config (overrides global)
+        const projectResult = await this.searchProjectConfig(searchFrom);
+        if (projectResult?.config && typeof projectResult.config === "object") {
+            // Accept partial configs without strict validation - merge will handle defaults
+            baseConfig = this.mergeConfigs(baseConfig, projectResult.config);
+            this.loadedFilepath = projectResult.filepath;
+            logger.debug({ filepath: projectResult.filepath }, "Loaded project config");
+        }
+        // Finally, apply environment variable overrides (highest priority)
+        this.config = this.applyEnvironmentOverrides(baseConfig);
+        return this.config;
+    }
+    /**
+     * Load the global config file from ~/.servherd/config.json
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async loadGlobalConfig() {
+        try {
+            const result = await this.explorer.load(this.globalConfigPath);
+            if (result?.config) {
+                const parsed = GlobalConfigSchema.deepPartial().safeParse(result.config);
+                if (parsed.success) {
+                    logger.debug({ filepath: this.globalConfigPath }, "Loaded global config");
+                    return parsed.data;
+                }
+                logger.warn({ error: parsed.error }, "Invalid global config file, ignoring");
+            }
+        }
+        catch {
+            // Global config doesn't exist or is unreadable, that's fine
+            logger.debug("No global config found");
+        }
+        return null;
+    }
+    /**
+     * Search for project-local config starting from the given directory
+     */
+    async searchProjectConfig(searchFrom) {
+        try {
+            const result = await this.explorer.search(searchFrom);
+            // Don't return if it's the global config (we handle that separately)
+            if (result?.filepath === this.globalConfigPath) {
+                return null;
+            }
+            return result;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Merge partial config into base config (supports deeply partial configs)
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mergeConfigs(base, partial) {
+        return {
+            ...base,
+            ...partial,
+            portRange: {
+                ...base.portRange,
+                ...(partial.portRange || {}),
+            },
+            pm2: {
+                ...base.pm2,
+                ...(partial.pm2 || {}),
+            },
+        };
+    }
+    /**
+     * Save configuration to the global config file
+     */
+    async save(config) {
+        await ensureDir(this.globalConfigDir);
+        await writeJson(this.globalConfigPath, config, { spaces: 2 });
+        this.config = config;
+    }
+    /**
+     * Get a configuration value
+     */
+    get(key) {
+        return this.config[key];
+    }
+    /**
+     * Set a configuration value and persist to the global config file
+     */
+    async set(key, value) {
+        this.config[key] = value;
+        await this.save(this.config);
+    }
+    /**
+     * Get default configuration
+     */
+    getDefaults() {
+        return { ...DEFAULT_CONFIG };
+    }
+    /**
+     * Get the global config file path
+     */
+    getConfigPath() {
+        return this.globalConfigPath;
+    }
+    /**
+     * Get the path of the currently loaded config file (if any)
+     */
+    getLoadedConfigPath() {
+        return this.loadedFilepath;
+    }
+    /**
+     * Get all supported config file names for documentation
+     */
+    getSupportedConfigFiles() {
+        return [
+            "package.json (\"servherd\" key)",
+            ".servherdrc",
+            ".servherdrc.json",
+            ".servherdrc.yaml",
+            ".servherdrc.yml",
+            ".servherdrc.js",
+            ".servherdrc.cjs",
+            "servherd.config.js",
+            "servherd.config.cjs",
+            "~/.servherd/config.json (global)",
+        ];
+    }
+    /**
+     * Apply environment variable overrides to configuration
+     */
+    applyEnvironmentOverrides(config) {
+        const result = { ...config };
+        if (process.env.SERVHERD_HOSTNAME) {
+            result.hostname = process.env.SERVHERD_HOSTNAME;
+        }
+        if (process.env.SERVHERD_PROTOCOL) {
+            const protocol = process.env.SERVHERD_PROTOCOL;
+            if (protocol === "http" || protocol === "https") {
+                result.protocol = protocol;
+            }
+        }
+        if (process.env.SERVHERD_PORT_MIN) {
+            const min = parseInt(process.env.SERVHERD_PORT_MIN, 10);
+            if (!isNaN(min)) {
+                result.portRange = { ...result.portRange, min };
+            }
+        }
+        if (process.env.SERVHERD_PORT_MAX) {
+            const max = parseInt(process.env.SERVHERD_PORT_MAX, 10);
+            if (!isNaN(max)) {
+                result.portRange = { ...result.portRange, max };
+            }
+        }
+        if (process.env.SERVHERD_TEMP_DIR) {
+            result.tempDir = process.env.SERVHERD_TEMP_DIR;
+        }
+        if (process.env.SERVHERD_HTTPS_CERT) {
+            result.httpsCert = process.env.SERVHERD_HTTPS_CERT;
+        }
+        if (process.env.SERVHERD_HTTPS_KEY) {
+            result.httpsKey = process.env.SERVHERD_HTTPS_KEY;
+        }
+        return result;
+    }
+    /**
+     * Clear the cosmiconfig cache (useful for testing or after config changes)
+     */
+    clearCache() {
+        this.explorer.clearCaches();
+    }
+}

package/dist/services/port.service.d.ts

@@ -0,0 +1,82 @@
+import type { GlobalConfig } from "../types/config.js";
+/**
+ * Result of port assignment, including whether a different port was assigned
+ */
+export interface PortAssignmentResult {
+    port: number;
+    reassigned: boolean;
+}
+/**
+ * Service for deterministic port generation and port availability checking
+ * using FNV-1a hashing and detect-port library
+ */
+export declare class PortService {
+    private portRange;
+    private usedPorts;
+    constructor(config: GlobalConfig);
+    /**
+     * Track a port as used (for CI mode sequential allocation)
+     * @param port - Port number to mark as used
+     */
+    trackUsedPort(port: number): void;
+    /**
+     * Clear all tracked used ports
+     */
+    clearUsedPorts(): void;
+    /**
+     * Generate a deterministic port number based on cwd and command
+     * Uses FNV-1a hash to ensure consistent port assignment for the same inputs
+     * @param cwd - Working directory of the server
+     * @param command - Command used to start the server
+     * @returns A port number within the configured range
+     */
+    generatePort(cwd: string, command: string): number;
+    /**
+     * Compute FNV-1a hash of the combined input string
+     * FNV-1a is a fast, non-cryptographic hash with good distribution
+     * @param cwd - Working directory
+     * @param command - Command string
+     * @returns A positive 32-bit integer hash
+     */
+    computeHash(cwd: string, command: string): number;
+    /**
+     * Check if a port is available for use
+     * @param port - Port number to check
+     * @returns true if port is available, false otherwise
+     */
+    isPortAvailable(port: number): Promise<boolean>;
+    /**
+     * Get an available port, starting from the preferred port
+     * If preferred is not available, searches for next available in range
+     * @param preferred - Preferred port number to try first
+     * @returns Object with assigned port and whether it was reassigned
+     */
+    getAvailablePort(preferred: number): Promise<PortAssignmentResult>;
+    /**
+     * Assign a port for a server, checking availability
+     * @param cwd - Working directory of the server
+     * @param command - Command used to start the server
+     * @param explicitPort - Optional explicit port to use (takes precedence)
+     * @param ciMode - If true, use sequential port allocation instead of deterministic
+     * @returns Object with assigned port and whether it was reassigned
+     */
+    assignPort(cwd: string, command: string, explicitPort?: number, ciMode?: boolean): Promise<PortAssignmentResult>;
+    /**
+     * Get next available port sequentially from the configured range
+     * Used in CI mode to avoid hash collisions and ensure predictable behavior
+     * @returns Object with assigned port and whether it was reassigned
+     */
+    private getNextAvailableSequential;
+    /**
+     * Validate that a port is within the configured range
+     * @param port - Port number to validate
+     * @throws ServherdError if port is outside range
+     */
+    validatePortInRange(port: number): void;
+    /**
+     * FNV-1a hash implementation
+     * @param str - String to hash
+     * @returns A positive 32-bit integer
+     */
+    private fnv1aHash;
+}

package/dist/services/port.service.js

@@ -0,0 +1,151 @@
+import detectPort from "detect-port";
+import { ServherdError, ServherdErrorCode } from "../types/errors.js";
+/**
+ * Service for deterministic port generation and port availability checking
+ * using FNV-1a hashing and detect-port library
+ */
+export class PortService {
+    portRange;
+    usedPorts = new Set();
+    constructor(config) {
+        this.portRange = config.portRange;
+    }
+    /**
+     * Track a port as used (for CI mode sequential allocation)
+     * @param port - Port number to mark as used
+     */
+    trackUsedPort(port) {
+        this.usedPorts.add(port);
+    }
+    /**
+     * Clear all tracked used ports
+     */
+    clearUsedPorts() {
+        this.usedPorts.clear();
+    }
+    /**
+     * Generate a deterministic port number based on cwd and command
+     * Uses FNV-1a hash to ensure consistent port assignment for the same inputs
+     * @param cwd - Working directory of the server
+     * @param command - Command used to start the server
+     * @returns A port number within the configured range
+     */
+    generatePort(cwd, command) {
+        const hash = this.computeHash(cwd, command);
+        const range = this.portRange.max - this.portRange.min + 1;
+        return this.portRange.min + (hash % range);
+    }
+    /**
+     * Compute FNV-1a hash of the combined input string
+     * FNV-1a is a fast, non-cryptographic hash with good distribution
+     * @param cwd - Working directory
+     * @param command - Command string
+     * @returns A positive 32-bit integer hash
+     */
+    computeHash(cwd, command) {
+        const input = `${cwd}:${command}`;
+        return this.fnv1aHash(input);
+    }
+    /**
+     * Check if a port is available for use
+     * @param port - Port number to check
+     * @returns true if port is available, false otherwise
+     */
+    async isPortAvailable(port) {
+        const availablePort = await detectPort(port);
+        return availablePort === port;
+    }
+    /**
+     * Get an available port, starting from the preferred port
+     * If preferred is not available, searches for next available in range
+     * @param preferred - Preferred port number to try first
+     * @returns Object with assigned port and whether it was reassigned
+     */
+    async getAvailablePort(preferred) {
+        // Try preferred port first
+        if (await this.isPortAvailable(preferred)) {
+            return { port: preferred, reassigned: false };
+        }
+        // Find next available port in range (from preferred+1 to max)
+        for (let port = preferred + 1; port <= this.portRange.max; port++) {
+            if (await this.isPortAvailable(port)) {
+                return { port, reassigned: true };
+            }
+        }
+        // Wrap around and check from min to preferred-1
+        for (let port = this.portRange.min; port < preferred; port++) {
+            if (await this.isPortAvailable(port)) {
+                return { port, reassigned: true };
+            }
+        }
+        throw new ServherdError(ServherdErrorCode.PORT_ALLOCATION_FAILED, `No available ports in range ${this.portRange.min}-${this.portRange.max}`);
+    }
+    /**
+     * Assign a port for a server, checking availability
+     * @param cwd - Working directory of the server
+     * @param command - Command used to start the server
+     * @param explicitPort - Optional explicit port to use (takes precedence)
+     * @param ciMode - If true, use sequential port allocation instead of deterministic
+     * @returns Object with assigned port and whether it was reassigned
+     */
+    async assignPort(cwd, command, explicitPort, ciMode = false) {
+        if (explicitPort !== undefined) {
+            this.validatePortInRange(explicitPort);
+            return this.getAvailablePort(explicitPort);
+        }
+        if (ciMode) {
+            return this.getNextAvailableSequential();
+        }
+        const preferred = this.generatePort(cwd, command);
+        return this.getAvailablePort(preferred);
+    }
+    /**
+     * Get next available port sequentially from the configured range
+     * Used in CI mode to avoid hash collisions and ensure predictable behavior
+     * @returns Object with assigned port and whether it was reassigned
+     */
+    async getNextAvailableSequential() {
+        let skippedPorts = false;
+        for (let port = this.portRange.min; port <= this.portRange.max; port++) {
+            // Skip ports we've already allocated in this session
+            if (this.usedPorts.has(port)) {
+                skippedPorts = true;
+                continue;
+            }
+            if (await this.isPortAvailable(port)) {
+                // If we skipped any ports (either tracked or unavailable), mark as reassigned
+                return { port, reassigned: skippedPorts };
+            }
+            skippedPorts = true;
+        }
+        throw new ServherdError(ServherdErrorCode.PORT_ALLOCATION_FAILED, `No available ports in range ${this.portRange.min}-${this.portRange.max}`);
+    }
+    /**
+     * Validate that a port is within the configured range
+     * @param port - Port number to validate
+     * @throws ServherdError if port is outside range
+     */
+    validatePortInRange(port) {
+        if (port < this.portRange.min || port > this.portRange.max) {
+            throw new ServherdError(ServherdErrorCode.PORT_OUT_OF_RANGE, `Port ${port} is outside configured range ${this.portRange.min}-${this.portRange.max}`);
+        }
+    }
+    /**
+     * FNV-1a hash implementation
+     * @param str - String to hash
+     * @returns A positive 32-bit integer
+     */
+    fnv1aHash(str) {
+        // FNV-1a parameters for 32-bit hash
+        const FNV_PRIME = 0x01000193;
+        const FNV_OFFSET_BASIS = 0x811c9dc5;
+        let hash = FNV_OFFSET_BASIS;
+        for (let i = 0; i < str.length; i++) {
+            hash ^= str.charCodeAt(i);
+            // Multiply by FNV prime and keep 32-bit
+            hash = Math.imul(hash, FNV_PRIME) >>> 0;
+        }
+        // Ensure positive integer
+        return hash >>> 0;
+    }
+}

package/dist/services/process.service.d.ts

@@ -0,0 +1,61 @@
+import type { PM2ProcessDescription, PM2StartOptions, PM2Process } from "../types/pm2.js";
+import type { ServerStatus } from "../types/registry.js";
+/**
+ * Service for managing processes via PM2
+ */
+export declare class ProcessService {
+    private connected;
+    /**
+     * Connect to PM2 daemon
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from PM2 daemon
+     */
+    disconnect(): void;
+    /**
+     * Ensure connected to PM2
+     */
+    private ensureConnected;
+    /**
+     * Start a new process
+     */
+    start(options: PM2StartOptions): Promise<PM2Process[]>;
+    /**
+     * Stop a process by name
+     */
+    stop(name: string): Promise<PM2Process[]>;
+    /**
+     * Restart a process by name
+     */
+    restart(name: string): Promise<PM2Process[]>;
+    /**
+     * Delete a process by name
+     */
+    delete(name: string): Promise<PM2Process[]>;
+    /**
+     * Get process description
+     */
+    describe(name: string): Promise<PM2ProcessDescription | undefined>;
+    /**
+     * List all PM2 processes
+     */
+    list(): Promise<PM2ProcessDescription[]>;
+    /**
+     * List only servherd-managed processes
+     */
+    listServherdProcesses(): Promise<PM2ProcessDescription[]>;
+    /**
+     * Get the status of a process
+     */
+    getStatus(name: string): Promise<ServerStatus>;
+    /**
+     * Check if connected to PM2
+     */
+    isConnected(): boolean;
+    /**
+     * Flush (clear) logs for a process or all processes.
+     * @param name - Process name to flush logs for, or undefined/all for all processes
+     */
+    flush(name?: string): Promise<void>;
+}