servherd 0.0.1 → 1.0.0

package/dist/services/process.service.js

@@ -0,0 +1,220 @@
+import pm2 from "pm2";
+import { logger } from "../utils/logger.js";
+const SERVHERD_PREFIX = "servherd-";
+/**
+ * Service for managing processes via PM2
+ */
+export class ProcessService {
+    connected = false;
+    /**
+     * Connect to PM2 daemon
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            pm2.connect((err) => {
+                if (err) {
+                    logger.error({ error: err }, "Failed to connect to PM2");
+                    reject(err);
+                    return;
+                }
+                this.connected = true;
+                logger.debug("Connected to PM2");
+                resolve();
+            });
+        });
+    }
+    /**
+     * Disconnect from PM2 daemon
+     */
+    disconnect() {
+        pm2.disconnect();
+        this.connected = false;
+        logger.debug("Disconnected from PM2");
+    }
+    /**
+     * Ensure connected to PM2
+     */
+    ensureConnected() {
+        if (!this.connected) {
+            throw new Error("Not connected to PM2. Call connect() first.");
+        }
+    }
+    /**
+     * Start a new process
+     */
+    async start(options) {
+        this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            pm2.start({
+                name: options.name,
+                script: options.script,
+                args: options.args,
+                cwd: options.cwd,
+                env: options.env,
+                instances: options.instances,
+                autorestart: options.autorestart ?? false,
+                watch: options.watch ?? false,
+                max_memory_restart: options.max_memory_restart,
+                output: options.output,
+                error: options.error,
+                // Enable ISO timestamps in logs by default
+                log_date_format: options.log_date_format ?? "YYYY-MM-DDTHH:mm:ss.SSSZ",
+            }, (err, proc) => {
+                if (err) {
+                    logger.error({ error: err, name: options.name }, "Failed to start process");
+                    reject(err);
+                    return;
+                }
+                logger.info({ name: options.name }, "Process started");
+                resolve(proc);
+            });
+        });
+    }
+    /**
+     * Stop a process by name
+     */
+    async stop(name) {
+        this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            pm2.stop(name, (err, proc) => {
+                if (err) {
+                    logger.error({ error: err, name }, "Failed to stop process");
+                    reject(err);
+                    return;
+                }
+                logger.info({ name }, "Process stopped");
+                resolve(proc);
+            });
+        });
+    }
+    /**
+     * Restart a process by name
+     */
+    async restart(name) {
+        this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            pm2.restart(name, (err, proc) => {
+                if (err) {
+                    logger.error({ error: err, name }, "Failed to restart process");
+                    reject(err);
+                    return;
+                }
+                logger.info({ name }, "Process restarted");
+                resolve(proc);
+            });
+        });
+    }
+    /**
+     * Delete a process by name
+     */
+    async delete(name) {
+        this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            pm2.delete(name, (err, proc) => {
+                if (err) {
+                    logger.error({ error: err, name }, "Failed to delete process");
+                    reject(err);
+                    return;
+                }
+                logger.info({ name }, "Process deleted");
+                resolve(proc);
+            });
+        });
+    }
+    /**
+     * Get process description
+     */
+    async describe(name) {
+        this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            pm2.describe(name, (err, procDesc) => {
+                if (err) {
+                    logger.error({ error: err, name }, "Failed to describe process");
+                    reject(err);
+                    return;
+                }
+                const desc = procDesc;
+                if (!desc || desc.length === 0) {
+                    resolve(undefined);
+                    return;
+                }
+                resolve(desc[0]);
+            });
+        });
+    }
+    /**
+     * List all PM2 processes
+     */
+    async list() {
+        this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            pm2.list((err, procList) => {
+                if (err) {
+                    logger.error({ error: err }, "Failed to list processes");
+                    reject(err);
+                    return;
+                }
+                resolve(procList || []);
+            });
+        });
+    }
+    /**
+     * List only servherd-managed processes
+     */
+    async listServherdProcesses() {
+        const allProcesses = await this.list();
+        return allProcesses.filter((p) => p.name.startsWith(SERVHERD_PREFIX));
+    }
+    /**
+     * Get the status of a process
+     */
+    async getStatus(name) {
+        try {
+            const proc = await this.describe(name);
+            if (!proc) {
+                return "unknown";
+            }
+            const status = proc.pm2_env.status;
+            // Map PM2 status to ServerStatus
+            switch (status) {
+                case "online":
+                    return "online";
+                case "stopped":
+                case "stopping":
+                    return "stopped";
+                case "errored":
+                    return "errored";
+                default:
+                    return "unknown";
+            }
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    /**
+     * Check if connected to PM2
+     */
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Flush (clear) logs for a process or all processes.
+     * @param name - Process name to flush logs for, or undefined/all for all processes
+     */
+    async flush(name) {
+        this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            const pm2Name = name ?? "all";
+            pm2.flush(pm2Name, (err) => {
+                if (err) {
+                    logger.error({ error: err, name: pm2Name }, "Failed to flush logs");
+                    reject(err);
+                    return;
+                }
+                logger.info({ name: pm2Name }, "Logs flushed");
+                resolve();
+            });
+        });
+    }
+}

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

@@ -0,0 +1,50 @@
+import { type Registry, type ServerEntry, type ServerFilter, type AddServerOptions } from "../types/registry.js";
+/**
+ * Service for managing the server registry
+ */
+export declare class RegistryService {
+    private registry;
+    private registryDir;
+    private registryPath;
+    constructor();
+    /**
+     * Load registry from file
+     */
+    load(): Promise<Registry>;
+    /**
+     * Save registry to file
+     */
+    save(): Promise<void>;
+    /**
+     * Add a new server to the registry
+     */
+    addServer(options: AddServerOptions): Promise<ServerEntry>;
+    /**
+     * Find server by name
+     */
+    findByName(name: string): ServerEntry | undefined;
+    /**
+     * Find server by ID
+     */
+    findById(id: string): ServerEntry | undefined;
+    /**
+     * Find server by cwd and command (for detecting duplicate registrations)
+     */
+    findByCommandHash(cwd: string, command: string): ServerEntry | undefined;
+    /**
+     * Update an existing server entry
+     */
+    updateServer(id: string, updates: Partial<ServerEntry>): Promise<void>;
+    /**
+     * Remove a server from the registry
+     */
+    removeServer(id: string): Promise<void>;
+    /**
+     * List servers with optional filtering
+     */
+    listServers(filter?: ServerFilter): ServerEntry[];
+    /**
+     * Get the registry file path
+     */
+    getRegistryPath(): string;
+}

package/dist/services/registry.service.js

@@ -0,0 +1,157 @@
+import { pathExists, readJson, ensureDir, writeJson } from "fs-extra/esm";
+import * as path from "path";
+import * as os from "os";
+import * as crypto from "crypto";
+import micromatch from "micromatch";
+import { RegistrySchema } from "../types/registry.js";
+import { generateName } from "../utils/names.js";
+import { logger } from "../utils/logger.js";
+const DEFAULT_REGISTRY = {
+    version: "1",
+    servers: [],
+};
+/**
+ * Service for managing the server registry
+ */
+export class RegistryService {
+    registry;
+    registryDir;
+    registryPath;
+    constructor() {
+        this.registry = { ...DEFAULT_REGISTRY, servers: [] };
+        this.registryDir = path.join(os.homedir(), ".servherd");
+        this.registryPath = path.join(this.registryDir, "registry.json");
+    }
+    /**
+     * Load registry from file
+     */
+    async load() {
+        try {
+            const exists = await pathExists(this.registryPath);
+            if (exists) {
+                const fileRegistry = await readJson(this.registryPath);
+                // Validate the loaded registry
+                const parsed = RegistrySchema.safeParse(fileRegistry);
+                if (parsed.success) {
+                    this.registry = parsed.data;
+                }
+                else {
+                    logger.warn({ error: parsed.error }, "Invalid registry file, using empty registry");
+                    this.registry = { ...DEFAULT_REGISTRY, servers: [] };
+                }
+            }
+            else {
+                this.registry = { ...DEFAULT_REGISTRY, servers: [] };
+            }
+        }
+        catch {
+            logger.warn("Failed to load registry file, using empty registry");
+            this.registry = { ...DEFAULT_REGISTRY, servers: [] };
+        }
+        return this.registry;
+    }
+    /**
+     * Save registry to file
+     */
+    async save() {
+        await ensureDir(this.registryDir);
+        await writeJson(this.registryPath, this.registry, { spaces: 2 });
+    }
+    /**
+     * Add a new server to the registry
+     */
+    async addServer(options) {
+        const existingNames = new Set(this.registry.servers.map((s) => s.name));
+        const name = options.name || generateName(existingNames);
+        const id = crypto.randomUUID();
+        const entry = {
+            id,
+            name,
+            command: options.command,
+            resolvedCommand: options.command, // Will be resolved with actual port later
+            cwd: options.cwd,
+            port: options.port,
+            protocol: options.protocol || "http",
+            hostname: options.hostname || "localhost",
+            env: options.env || {},
+            createdAt: new Date().toISOString(),
+            pm2Name: `servherd-${name}`,
+            tags: options.tags,
+            description: options.description,
+            usedConfigKeys: options.usedConfigKeys,
+            configSnapshot: options.configSnapshot,
+        };
+        this.registry.servers.push(entry);
+        await this.save();
+        return entry;
+    }
+    /**
+     * Find server by name
+     */
+    findByName(name) {
+        return this.registry.servers.find((s) => s.name === name);
+    }
+    /**
+     * Find server by ID
+     */
+    findById(id) {
+        return this.registry.servers.find((s) => s.id === id);
+    }
+    /**
+     * Find server by cwd and command (for detecting duplicate registrations)
+     */
+    findByCommandHash(cwd, command) {
+        return this.registry.servers.find((s) => s.cwd === cwd && s.command === command);
+    }
+    /**
+     * Update an existing server entry
+     */
+    async updateServer(id, updates) {
+        const index = this.registry.servers.findIndex((s) => s.id === id);
+        if (index === -1) {
+            throw new Error(`Server with id ${id} not found`);
+        }
+        this.registry.servers[index] = {
+            ...this.registry.servers[index],
+            ...updates,
+        };
+        await this.save();
+    }
+    /**
+     * Remove a server from the registry
+     */
+    async removeServer(id) {
+        const index = this.registry.servers.findIndex((s) => s.id === id);
+        if (index === -1) {
+            throw new Error(`Server with id ${id} not found`);
+        }
+        this.registry.servers.splice(index, 1);
+        await this.save();
+    }
+    /**
+     * List servers with optional filtering
+     */
+    listServers(filter) {
+        let servers = [...this.registry.servers];
+        if (filter?.name) {
+            servers = servers.filter((s) => s.name === filter.name);
+        }
+        if (filter?.tag) {
+            servers = servers.filter((s) => s.tags?.includes(filter.tag));
+        }
+        if (filter?.cwd) {
+            servers = servers.filter((s) => s.cwd === filter.cwd);
+        }
+        if (filter?.cmd) {
+            const pattern = filter.cmd;
+            servers = servers.filter((s) => micromatch.isMatch(s.command, pattern));
+        }
+        return servers;
+    }
+    /**
+     * Get the registry file path
+     */
+    getRegistryPath() {
+        return this.registryPath;
+    }
+}

package/dist/types/config.d.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+export declare const PortRangeSchema: z.ZodEffects<z.ZodObject<{
+    min: z.ZodNumber;
+    max: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    min: number;
+    max: number;
+}, {
+    min: number;
+    max: number;
+}>, {
+    min: number;
+    max: number;
+}, {
+    min: number;
+    max: number;
+}>;
+export declare const PM2ConfigSchema: z.ZodObject<{
+    logDir: z.ZodString;
+    pidDir: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    logDir: string;
+    pidDir: string;
+}, {
+    logDir: string;
+    pidDir: string;
+}>;
+/**
+ * Controls how servers are refreshed when config values change.
+ * - "manual": Requires explicit `servherd refresh` command
+ * - "prompt": Prompts user to restart affected servers when config changes via CLI
+ * - "auto": Automatically restarts affected servers when config changes via CLI
+ * - "on-start": Uses new config values on next start/restart (default, safest)
+ */
+export declare const RefreshOnChangeSchema: z.ZodEnum<["manual", "prompt", "auto", "on-start"]>;
+export type RefreshOnChange = z.infer<typeof RefreshOnChangeSchema>;
+export declare const GlobalConfigSchema: z.ZodObject<{
+    version: z.ZodString;
+    hostname: z.ZodString;
+    protocol: z.ZodEnum<["http", "https"]>;
+    portRange: z.ZodEffects<z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        min: number;
+        max: number;
+    }, {
+        min: number;
+        max: number;
+    }>, {
+        min: number;
+        max: number;
+    }, {
+        min: number;
+        max: number;
+    }>;
+    tempDir: z.ZodString;
+    pm2: z.ZodObject<{
+        logDir: z.ZodString;
+        pidDir: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        logDir: string;
+        pidDir: string;
+    }, {
+        logDir: string;
+        pidDir: string;
+    }>;
+    httpsCert: z.ZodOptional<z.ZodString>;
+    httpsKey: z.ZodOptional<z.ZodString>;
+    refreshOnChange: z.ZodOptional<z.ZodEnum<["manual", "prompt", "auto", "on-start"]>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    hostname: string;
+    protocol: "http" | "https";
+    portRange: {
+        min: number;
+        max: number;
+    };
+    tempDir: string;
+    pm2: {
+        logDir: string;
+        pidDir: string;
+    };
+    httpsCert?: string | undefined;
+    httpsKey?: string | undefined;
+    refreshOnChange?: "manual" | "prompt" | "auto" | "on-start" | undefined;
+}, {
+    version: string;
+    hostname: string;
+    protocol: "http" | "https";
+    portRange: {
+        min: number;
+        max: number;
+    };
+    tempDir: string;
+    pm2: {
+        logDir: string;
+        pidDir: string;
+    };
+    httpsCert?: string | undefined;
+    httpsKey?: string | undefined;
+    refreshOnChange?: "manual" | "prompt" | "auto" | "on-start" | undefined;
+}>;
+export type PortRange = z.infer<typeof PortRangeSchema>;
+export type PM2Config = z.infer<typeof PM2ConfigSchema>;
+export type GlobalConfig = z.infer<typeof GlobalConfigSchema>;
+export declare const DEFAULT_CONFIG: GlobalConfig;

package/dist/types/config.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export const PortRangeSchema = z.object({
+    min: z.number().int().min(1).max(65535),
+    max: z.number().int().min(1).max(65535),
+}).refine((data) => data.min <= data.max, {
+    message: "Port range min must be less than or equal to max",
+});
+export const PM2ConfigSchema = z.object({
+    logDir: z.string(),
+    pidDir: z.string(),
+});
+/**
+ * Controls how servers are refreshed when config values change.
+ * - "manual": Requires explicit `servherd refresh` command
+ * - "prompt": Prompts user to restart affected servers when config changes via CLI
+ * - "auto": Automatically restarts affected servers when config changes via CLI
+ * - "on-start": Uses new config values on next start/restart (default, safest)
+ */
+export const RefreshOnChangeSchema = z.enum(["manual", "prompt", "auto", "on-start"]);
+export const GlobalConfigSchema = z.object({
+    version: z.string(),
+    hostname: z.string(),
+    protocol: z.enum(["http", "https"]),
+    portRange: PortRangeSchema,
+    tempDir: z.string(),
+    pm2: PM2ConfigSchema,
+    httpsCert: z.string().optional(),
+    httpsKey: z.string().optional(),
+    refreshOnChange: RefreshOnChangeSchema.optional(),
+});
+export const DEFAULT_CONFIG = {
+    version: "1",
+    hostname: "localhost",
+    protocol: "http",
+    portRange: { min: 3000, max: 9999 },
+    tempDir: "/tmp/servherd",
+    pm2: {
+        logDir: "/tmp/servherd/logs",
+        pidDir: "/tmp/servherd/pids",
+    },
+    httpsCert: undefined,
+    httpsKey: undefined,
+    refreshOnChange: "on-start",
+};

package/dist/types/errors.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Error codes for servherd operations.
+ * Grouped by category:
+ * - 1xxx: Server-related errors
+ * - 2xxx: Port-related errors
+ * - 3xxx: PM2/Process-related errors
+ * - 4xxx: Configuration errors
+ * - 5xxx: Registry errors
+ * - 6xxx: Template errors
+ * - 7xxx: Command/CLI errors
+ * - 9xxx: Unknown/Other errors
+ */
+export declare enum ServherdErrorCode {
+    SERVER_NOT_FOUND = 1001,
+    SERVER_ALREADY_EXISTS = 1002,
+    SERVER_NOT_RUNNING = 1003,
+    SERVER_ALREADY_RUNNING = 1004,
+    PORT_UNAVAILABLE = 2001,
+    PORT_OUT_OF_RANGE = 2002,
+    PORT_ALLOCATION_FAILED = 2003,
+    PM2_CONNECTION_FAILED = 3001,
+    PM2_START_FAILED = 3002,
+    PM2_STOP_FAILED = 3003,
+    PM2_DELETE_FAILED = 3004,
+    PM2_RESTART_FAILED = 3005,
+    PM2_DESCRIBE_FAILED = 3006,
+    CONFIG_LOAD_FAILED = 4001,
+    CONFIG_SAVE_FAILED = 4002,
+    CONFIG_INVALID = 4003,
+    CONFIG_KEY_NOT_FOUND = 4004,
+    CONFIG_VALIDATION_FAILED = 4005,
+    REGISTRY_LOAD_FAILED = 5001,
+    REGISTRY_SAVE_FAILED = 5002,
+    REGISTRY_CORRUPT = 5003,
+    TEMPLATE_INVALID = 6001,
+    TEMPLATE_MISSING_VARIABLE = 6002,
+    COMMAND_INVALID = 7001,
+    COMMAND_MISSING_ARGUMENT = 7002,
+    COMMAND_CONFLICT = 7003,
+    INTERACTIVE_NOT_AVAILABLE = 7004,
+    UNKNOWN_ERROR = 9999
+}
+/**
+ * Details that can be attached to a ServherdError for additional context.
+ */
+export interface ServherdErrorDetails {
+    exitCode?: number;
+    stderr?: string;
+    stdout?: string;
+    cause?: Error;
+    serverName?: string;
+    port?: number;
+    command?: string;
+    path?: string;
+    [key: string]: unknown;
+}
+/**
+ * Custom error class for servherd operations.
+ * Includes error codes for programmatic handling and optional details.
+ */
+export declare class ServherdError extends Error {
+    readonly code: ServherdErrorCode;
+    readonly details?: ServherdErrorDetails;
+    constructor(code: ServherdErrorCode, message: string, details?: ServherdErrorDetails);
+    /**
+     * Serialize error to JSON for logging or API responses.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Get the string name of the error code.
+     */
+    getCodeName(): string;
+}
+/**
+ * Type guard to check if an error is a ServherdError.
+ */
+export declare function isServherdError(error: unknown): error is ServherdError;
+/**
+ * Format an error for CLI display.
+ * Includes color codes and proper formatting for terminal output.
+ */
+export declare function formatErrorForCLI(error: unknown): string;
+/**
+ * MCP tool response content item.
+ */
+interface MCPContentItem {
+    type: "text";
+    text: string;
+}
+/**
+ * MCP tool error response format.
+ */
+interface MCPErrorResponse {
+    isError: true;
+    content: MCPContentItem[];
+}
+/**
+ * Format an error for MCP tool response.
+ * Returns a structured error response compatible with MCP protocol.
+ */
+export declare function formatErrorForMCP(error: unknown): MCPErrorResponse;
+export {};