servherd 0.0.1 → 1.0.0

package/dist/utils/config-drift.js

@@ -0,0 +1,128 @@
+/**
+ * Utilities for detecting configuration drift in servers.
+ * Drift occurs when config values have changed since a server was started.
+ */
+import { extractVariables, TEMPLATE_VAR_TO_CONFIG_KEY } from "./template.js";
+/**
+ * Extract the config keys used by a command template
+ * @param command - The command template string
+ * @returns Array of config keys used (e.g., ["hostname", "httpsCert"])
+ */
+export function extractUsedConfigKeys(command) {
+    const templateVars = extractVariables(command);
+    const configKeys = [];
+    for (const varName of templateVars) {
+        const configKey = TEMPLATE_VAR_TO_CONFIG_KEY[varName];
+        if (configKey) {
+            configKeys.push(configKey);
+        }
+    }
+    return [...new Set(configKeys)]; // Deduplicate
+}
+/**
+ * Create a config snapshot containing only the values used by a server
+ * @param config - Current global config
+ * @param usedConfigKeys - Config keys used by the server
+ * @returns Config snapshot with only relevant values
+ */
+export function createConfigSnapshot(config, usedConfigKeys) {
+    const snapshot = {};
+    for (const key of usedConfigKeys) {
+        if (key === "hostname") {
+            snapshot.hostname = config.hostname;
+        }
+        else if (key === "httpsCert") {
+            snapshot.httpsCert = config.httpsCert;
+        }
+        else if (key === "httpsKey") {
+            snapshot.httpsKey = config.httpsKey;
+        }
+    }
+    return snapshot;
+}
+/**
+ * Detect config drift for a server
+ * @param server - Server entry from registry
+ * @param currentConfig - Current global config
+ * @returns Drift detection result
+ */
+export function detectDrift(server, currentConfig) {
+    const driftedValues = [];
+    // If no snapshot exists, we can't detect drift
+    if (!server.configSnapshot || !server.usedConfigKeys) {
+        return { hasDrift: false, driftedValues: [] };
+    }
+    for (const configKey of server.usedConfigKeys) {
+        let startedWith;
+        let currentValue;
+        let templateVar;
+        if (configKey === "hostname") {
+            startedWith = server.configSnapshot.hostname;
+            currentValue = currentConfig.hostname;
+            templateVar = "hostname";
+        }
+        else if (configKey === "httpsCert") {
+            startedWith = server.configSnapshot.httpsCert;
+            currentValue = currentConfig.httpsCert;
+            templateVar = "https-cert";
+        }
+        else if (configKey === "httpsKey") {
+            startedWith = server.configSnapshot.httpsKey;
+            currentValue = currentConfig.httpsKey;
+            templateVar = "https-key";
+        }
+        if (templateVar && startedWith !== currentValue) {
+            driftedValues.push({
+                configKey,
+                templateVar,
+                startedWith,
+                currentValue,
+            });
+        }
+    }
+    return {
+        hasDrift: driftedValues.length > 0,
+        driftedValues,
+    };
+}
+/**
+ * Find all servers that use a specific config key
+ * @param servers - Array of server entries
+ * @param configKey - The config key to search for
+ * @returns Array of servers using that config key
+ */
+export function findServersUsingConfigKey(servers, configKey) {
+    return servers.filter(server => server.usedConfigKeys?.includes(configKey));
+}
+/**
+ * Find all servers with config drift
+ * @param servers - Array of server entries
+ * @param currentConfig - Current global config
+ * @returns Array of servers with drift and their drift details
+ */
+export function findServersWithDrift(servers, currentConfig) {
+    const results = [];
+    for (const server of servers) {
+        const drift = detectDrift(server, currentConfig);
+        if (drift.hasDrift) {
+            results.push({ server, drift });
+        }
+    }
+    return results;
+}
+/**
+ * Format drift information for display
+ * @param drift - Drift result to format
+ * @returns Formatted string describing the drift
+ */
+export function formatDrift(drift) {
+    if (!drift.hasDrift) {
+        return "No config drift";
+    }
+    const lines = drift.driftedValues.map(d => {
+        const started = d.startedWith ?? "(not set)";
+        const current = d.currentValue ?? "(not set)";
+        return `  ${d.configKey}: "${started}" → "${current}"`;
+    });
+    return `Config drift detected:\n${lines.join("\n")}`;
+}

package/dist/utils/error-handler.d.ts

@@ -0,0 +1,21 @@
+import { ServherdError, ServherdErrorCode } from "../types/errors.js";
+/**
+ * Create a ServherdError from an unknown error.
+ * Useful for wrapping errors from external libraries.
+ */
+export declare function wrapError(error: unknown, code: ServherdErrorCode, message?: string): ServherdError;
+/**
+ * Assert that a condition is true, throwing a ServherdError if not.
+ */
+export declare function assertServherd(condition: unknown, code: ServherdErrorCode, message: string): asserts condition;
+/**
+ * Try to execute a function, returning a result object.
+ * Useful for operations where you want to handle errors gracefully.
+ */
+export declare function tryAsync<T>(fn: () => Promise<T>): Promise<{
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: ServherdError;
+}>;

package/dist/utils/error-handler.js

@@ -0,0 +1,38 @@
+import { ServherdError, ServherdErrorCode, isServherdError } from "../types/errors.js";
+/**
+ * Create a ServherdError from an unknown error.
+ * Useful for wrapping errors from external libraries.
+ */
+export function wrapError(error, code, message) {
+    if (isServherdError(error)) {
+        return error;
+    }
+    const originalMessage = error instanceof Error ? error.message : String(error);
+    const finalMessage = message || originalMessage;
+    return new ServherdError(code, finalMessage, {
+        cause: error instanceof Error ? error : undefined,
+        stderr: error instanceof Error ? error.message : undefined,
+    });
+}
+/**
+ * Assert that a condition is true, throwing a ServherdError if not.
+ */
+export function assertServherd(condition, code, message) {
+    if (!condition) {
+        throw new ServherdError(code, message);
+    }
+}
+/**
+ * Try to execute a function, returning a result object.
+ * Useful for operations where you want to handle errors gracefully.
+ */
+export async function tryAsync(fn) {
+    try {
+        const value = await fn();
+        return { success: true, value };
+    }
+    catch (error) {
+        const wrappedError = wrapError(error, ServherdErrorCode.UNKNOWN_ERROR);
+        return { success: false, error: wrappedError };
+    }
+}

package/dist/utils/log-follower.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Follow a log file and emit new lines as they are written.
+ * Similar to `tail -f` behavior.
+ *
+ * @param logPath - Path to the log file to follow
+ * @param signal - AbortSignal to stop following
+ * @param onLine - Callback for each new line
+ * @returns Promise that resolves when following is stopped
+ */
+export declare function followLog(logPath: string, signal: AbortSignal, onLine: (line: string) => void): Promise<void>;

package/dist/utils/log-follower.js

@@ -0,0 +1,98 @@
+import { watch, createReadStream } from "fs";
+import { stat } from "fs/promises";
+import { createInterface } from "readline";
+/**
+ * Follow a log file and emit new lines as they are written.
+ * Similar to `tail -f` behavior.
+ *
+ * @param logPath - Path to the log file to follow
+ * @param signal - AbortSignal to stop following
+ * @param onLine - Callback for each new line
+ * @returns Promise that resolves when following is stopped
+ */
+export async function followLog(logPath, signal, onLine) {
+    // If already aborted, return immediately
+    if (signal.aborted) {
+        return;
+    }
+    // Get initial file size to start reading from the end
+    let position;
+    try {
+        const stats = await stat(logPath);
+        position = stats.size;
+    }
+    catch {
+        // If file doesn't exist yet, start from 0
+        position = 0;
+    }
+    /**
+     * Read new lines from the file starting at the current position.
+     */
+    const readNewLines = async () => {
+        if (signal.aborted) {
+            return;
+        }
+        try {
+            const currentStats = await stat(logPath);
+            const currentSize = currentStats.size;
+            // File was truncated or no new content
+            if (currentSize <= position) {
+                // If file was truncated, reset position
+                if (currentSize < position) {
+                    position = 0;
+                }
+                return;
+            }
+            // Read new content
+            const stream = createReadStream(logPath, {
+                start: position,
+                encoding: "utf-8",
+            });
+            const rl = createInterface({
+                input: stream,
+                crlfDelay: Infinity,
+            });
+            for await (const line of rl) {
+                if (signal.aborted) {
+                    stream.destroy();
+                    break;
+                }
+                // Only emit non-empty lines
+                if (line.trim()) {
+                    onLine(line);
+                }
+            }
+            // Update position to end of file
+            position = currentSize;
+        }
+        catch {
+            // Ignore errors reading the file (it may have been deleted/rotated)
+        }
+    };
+    return new Promise((resolve) => {
+        // Set up file watcher
+        const watcher = watch(logPath, async (eventType) => {
+            if (signal.aborted) {
+                return;
+            }
+            if (eventType === "change") {
+                await readNewLines();
+            }
+        });
+        // Handle watcher errors (e.g., file doesn't exist)
+        watcher.on("error", () => {
+            // Ignore errors - the file may be rotated or deleted
+        });
+        // Clean up on abort
+        const abortHandler = () => {
+            watcher.close();
+            resolve();
+        };
+        if (signal.aborted) {
+            abortHandler();
+        }
+        else {
+            signal.addEventListener("abort", abortHandler);
+        }
+    });
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,11 @@
+import pino, { type Logger } from "pino";
+export type LogLevel = "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent";
+export interface LoggerOptions {
+    level?: LogLevel;
+    pretty?: boolean;
+}
+/**
+ * Create a configured pino logger instance
+ */
+export declare function createLogger(options: LoggerOptions): Logger;
+export declare const logger: pino.Logger;

package/dist/utils/logger.js

@@ -0,0 +1,24 @@
+import pino from "pino";
+/**
+ * Create a configured pino logger instance
+ */
+export function createLogger(options) {
+    const level = options.level ?? "info";
+    const pretty = options.pretty ?? process.env.NODE_ENV !== "production";
+    if (pretty) {
+        return pino({
+            level,
+            transport: {
+                target: "pino-pretty",
+                options: {
+                    colorize: true,
+                    translateTime: "SYS:standard",
+                    ignore: "pid,hostname",
+                },
+            },
+        });
+    }
+    return pino({ level });
+}
+// Export a default logger instance
+export const logger = createLogger({ level: "info" });

package/dist/utils/names.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generate a human-readable name in adjective-noun format
+ * @param existing - Set of existing names to avoid duplicates
+ * @param maxAttempts - Maximum number of attempts to generate a unique name
+ * @returns A unique human-readable name
+ */
+export declare function generateName(existing?: Set<string>, maxAttempts?: number): string;

package/dist/utils/names.js

@@ -0,0 +1,20 @@
+import { FlexiHumanHash } from "flexi-human-hash";
+const fhh = new FlexiHumanHash("{{adjective}}-{{noun}}");
+/**
+ * Generate a human-readable name in adjective-noun format
+ * @param existing - Set of existing names to avoid duplicates
+ * @param maxAttempts - Maximum number of attempts to generate a unique name
+ * @returns A unique human-readable name
+ */
+export function generateName(existing, maxAttempts = 100) {
+    for (let i = 0; i < maxAttempts; i++) {
+        const name = fhh.hash();
+        if (!existing || !existing.has(name)) {
+            return name;
+        }
+    }
+    // Fallback: add a unique suffix if we can't find a unique name
+    const baseName = fhh.hash();
+    const timestamp = Date.now().toString(36).slice(-4);
+    return `${baseName}-${timestamp}`;
+}

package/dist/utils/template.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Template variable substitution engine for command templates
+ * Supports {{port}}, {{hostname}}, {{url}}, {{https-cert}}, {{https-key}} and other variables
+ */
+import type { GlobalConfig } from "../types/config.js";
+export interface TemplateVariables {
+    port?: number | string;
+    hostname?: string;
+    url?: string;
+    "https-cert"?: string;
+    "https-key"?: string;
+    [key: string]: string | number | undefined;
+}
+/**
+ * Render a template string by substituting variables
+ * @param template - The template string containing {{variable}} placeholders
+ * @param variables - Object containing variable values to substitute
+ * @returns The rendered string with variables replaced
+ */
+export declare function renderTemplate(template: string, variables: TemplateVariables): string;
+/**
+ * Extract all unique variable names from a template string
+ * @param template - The template string to analyze
+ * @returns Array of unique variable names found in the template
+ */
+export declare function extractVariables(template: string): string[];
+/**
+ * Parse an array of KEY=VALUE strings into a Record
+ * @param envStrings - Array of strings in KEY=VALUE format
+ * @returns Record with parsed key-value pairs
+ * @throws Error if a string is not in valid KEY=VALUE format
+ */
+export declare function parseEnvStrings(envStrings: string[]): Record<string, string>;
+/**
+ * Render template variables in all values of an env object
+ * @param env - Record of environment variables with potential template values
+ * @param variables - Template variables to substitute
+ * @returns New record with all values having templates substituted
+ */
+export declare function renderEnvTemplates(env: Record<string, string>, variables: TemplateVariables): Record<string, string>;
+/**
+ * Generate template variables from configuration
+ * @param config - Global configuration object
+ * @param port - The port number for this server
+ * @returns TemplateVariables object ready for template substitution
+ */
+export declare function getTemplateVariables(config: GlobalConfig, port: number): TemplateVariables;
+/**
+ * Mapping from template variable names to their corresponding config keys
+ * Variables not in this map are auto-generated (port, url) and can't be configured
+ */
+export declare const TEMPLATE_VAR_TO_CONFIG_KEY: Record<string, keyof GlobalConfig | null>;
+/**
+ * Human-readable prompts for each configurable template variable
+ */
+export declare const TEMPLATE_VAR_PROMPTS: Record<string, string>;
+/**
+ * Information about a missing template variable
+ */
+export interface MissingVariable {
+    /** The template variable name (e.g., "https-cert") */
+    templateVar: string;
+    /** The config key to set (e.g., "httpsCert"), or null if not configurable */
+    configKey: keyof GlobalConfig | null;
+    /** Human-readable prompt for the user */
+    prompt: string;
+    /** Whether this variable can be configured by the user */
+    configurable: boolean;
+}
+/**
+ * Find template variables that are used but have empty or missing values
+ * @param template - The template string to analyze
+ * @param variables - The current template variables
+ * @returns Array of MissingVariable objects for variables that need values
+ */
+export declare function findMissingVariables(template: string, variables: TemplateVariables): MissingVariable[];
+/**
+ * Format missing variables as a user-friendly error message
+ * @param missing - Array of missing variables
+ * @returns Formatted error message string
+ */
+export declare function formatMissingVariablesError(missing: MissingVariable[]): string;
+/**
+ * Format missing variables as an MCP-friendly error message
+ * @param missing - Array of missing variables
+ * @returns Formatted error message for MCP tool response
+ */
+export declare function formatMissingVariablesForMCP(missing: MissingVariable[]): string;

package/dist/utils/template.js

@@ -0,0 +1,180 @@
+/**
+ * Template variable substitution engine for command templates
+ * Supports {{port}}, {{hostname}}, {{url}}, {{https-cert}}, {{https-key}} and other variables
+ */
+// Regex to match template variables like {{port}}, {{ port }}, or {{https-cert}}
+const TEMPLATE_REGEX = /\{\{\s*([\w-]+)\s*\}\}/g;
+/**
+ * Render a template string by substituting variables
+ * @param template - The template string containing {{variable}} placeholders
+ * @param variables - Object containing variable values to substitute
+ * @returns The rendered string with variables replaced
+ */
+export function renderTemplate(template, variables) {
+    return template.replace(TEMPLATE_REGEX, (match, varName) => {
+        const value = variables[varName];
+        if (value !== undefined) {
+            return String(value);
+        }
+        // Leave unresolved variables unchanged
+        return match;
+    });
+}
+/**
+ * Extract all unique variable names from a template string
+ * @param template - The template string to analyze
+ * @returns Array of unique variable names found in the template
+ */
+export function extractVariables(template) {
+    const variables = new Set();
+    let match;
+    // Reset regex state
+    TEMPLATE_REGEX.lastIndex = 0;
+    while ((match = TEMPLATE_REGEX.exec(template)) !== null) {
+        variables.add(match[1]);
+    }
+    return Array.from(variables);
+}
+/**
+ * Parse an array of KEY=VALUE strings into a Record
+ * @param envStrings - Array of strings in KEY=VALUE format
+ * @returns Record with parsed key-value pairs
+ * @throws Error if a string is not in valid KEY=VALUE format
+ */
+export function parseEnvStrings(envStrings) {
+    const result = {};
+    for (const str of envStrings) {
+        const equalsIndex = str.indexOf("=");
+        if (equalsIndex === -1) {
+            throw new Error(`Invalid environment variable format: "${str}". Expected KEY=VALUE format.`);
+        }
+        const key = str.slice(0, equalsIndex);
+        const value = str.slice(equalsIndex + 1);
+        if (!key) {
+            throw new Error(`Invalid environment variable format: "${str}". Key cannot be empty.`);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Render template variables in all values of an env object
+ * @param env - Record of environment variables with potential template values
+ * @param variables - Template variables to substitute
+ * @returns New record with all values having templates substituted
+ */
+export function renderEnvTemplates(env, variables) {
+    const result = {};
+    for (const [key, value] of Object.entries(env)) {
+        result[key] = renderTemplate(value, variables);
+    }
+    return result;
+}
+/**
+ * Generate template variables from configuration
+ * @param config - Global configuration object
+ * @param port - The port number for this server
+ * @returns TemplateVariables object ready for template substitution
+ */
+export function getTemplateVariables(config, port) {
+    return {
+        port,
+        hostname: config.hostname,
+        url: `${config.protocol}://${config.hostname}:${port}`,
+        "https-cert": config.httpsCert ?? "",
+        "https-key": config.httpsKey ?? "",
+    };
+}
+/**
+ * Mapping from template variable names to their corresponding config keys
+ * Variables not in this map are auto-generated (port, url) and can't be configured
+ */
+export const TEMPLATE_VAR_TO_CONFIG_KEY = {
+    "port": null, // Auto-assigned, not configurable
+    "hostname": "hostname",
+    "url": null, // Auto-generated from protocol/hostname/port
+    "https-cert": "httpsCert",
+    "https-key": "httpsKey",
+};
+/**
+ * Human-readable prompts for each configurable template variable
+ */
+export const TEMPLATE_VAR_PROMPTS = {
+    "hostname": "Server hostname (e.g., localhost, 0.0.0.0):",
+    "https-cert": "Path to HTTPS certificate file:",
+    "https-key": "Path to HTTPS private key file:",
+};
+/**
+ * Find template variables that are used but have empty or missing values
+ * @param template - The template string to analyze
+ * @param variables - The current template variables
+ * @returns Array of MissingVariable objects for variables that need values
+ */
+export function findMissingVariables(template, variables) {
+    const usedVars = extractVariables(template);
+    const missing = [];
+    for (const varName of usedVars) {
+        const value = variables[varName];
+        // Check if the value is empty, undefined, or an empty string
+        if (value === undefined || value === "" || value === null) {
+            const configKey = TEMPLATE_VAR_TO_CONFIG_KEY[varName] ?? null;
+            const configurable = configKey !== null;
+            const prompt = TEMPLATE_VAR_PROMPTS[varName] ?? `Value for ${varName}:`;
+            missing.push({
+                templateVar: varName,
+                configKey,
+                prompt,
+                configurable,
+            });
+        }
+    }
+    return missing;
+}
+/**
+ * Format missing variables as a user-friendly error message
+ * @param missing - Array of missing variables
+ * @returns Formatted error message string
+ */
+export function formatMissingVariablesError(missing) {
+    if (missing.length === 0) {
+        return "";
+    }
+    const lines = [
+        "The following template variables are used but not configured:",
+        "",
+    ];
+    for (const v of missing) {
+        if (v.configurable) {
+            lines.push(`  {{${v.templateVar}}} - Set with: servherd config --set ${v.configKey} --value <value>`);
+        }
+        else {
+            lines.push(`  {{${v.templateVar}}} - This variable is auto-generated and cannot be configured directly`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Format missing variables as an MCP-friendly error message
+ * @param missing - Array of missing variables
+ * @returns Formatted error message for MCP tool response
+ */
+export function formatMissingVariablesForMCP(missing) {
+    if (missing.length === 0) {
+        return "";
+    }
+    const configurable = missing.filter(v => v.configurable);
+    if (configurable.length === 0) {
+        return "Template uses auto-generated variables that have no value. This may indicate an internal error.";
+    }
+    const lines = [
+        "Cannot start server: required configuration is missing.",
+        "",
+        "The command uses template variables that are not configured:",
+    ];
+    for (const v of configurable) {
+        lines.push(`  - {{${v.templateVar}}}: Use servherd_config tool with set="${v.configKey}" and value="<path or value>"`);
+    }
+    lines.push("");
+    lines.push("Please configure these values first, then retry the start command.");
+    return lines.join("\n");
+}

package/dist/utils/time-parser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parse a time filter string into a Date object.
+ * Supports duration format (1h, 30m, 2d, 1w, 30s) or ISO date strings.
+ *
+ * @param input - Time filter string to parse
+ * @returns Date object representing the cutoff time
+ * @throws ServherdError if the format is invalid
+ */
+export declare function parseTimeFilter(input: string): Date;
+/**
+ * Filter log lines by timestamp, keeping only those after the given date.
+ * Lines without timestamps (or where the parser returns null) are included.
+ *
+ * @param lines - Array of log lines to filter
+ * @param since - Only include logs from this date onward
+ * @param parseTimestamp - Function to extract a Date from a log line (returns null if no timestamp)
+ * @returns Filtered array of log lines
+ */
+export declare function filterLogsByTime(lines: string[], since: Date, parseTimestamp: (line: string) => Date | null): string[];