@karmaniverous/jeeves 0.4.0 → 0.4.1

package/dist/cli/service/index.js

@@ -0,0 +1,916 @@
+#!/usr/bin/env node
+import { execSync, spawn } from 'node:child_process';
+import { existsSync, unlinkSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as commander from 'commander';
+import { z } from 'zod';
+import { homedir } from 'node:os';
+
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+function getAugmentedNamespace(n) {
+  if (Object.prototype.hasOwnProperty.call(n, '__esModule')) return n;
+  var f = n.default;
+	if (typeof f == "function") {
+		var a = function a () {
+			var isInstance = false;
+      try {
+        isInstance = this instanceof a;
+      } catch {}
+			if (isInstance) {
+        return Reflect.construct(f, arguments, this.constructor);
+			}
+			return f.apply(this, arguments);
+		};
+		a.prototype = f.prototype;
+  } else a = {};
+  Object.defineProperty(a, '__esModule', {value: true});
+	Object.keys(n).forEach(function (k) {
+		var d = Object.getOwnPropertyDescriptor(n, k);
+		Object.defineProperty(a, k, d.get ? d : {
+			enumerable: true,
+			get: function () {
+				return n[k];
+			}
+		});
+	});
+	return a;
+}
+
+var extraTypings = {exports: {}};
+
+var require$$0 = /*@__PURE__*/getAugmentedNamespace(commander);
+
+var hasRequiredExtraTypings;
+
+function requireExtraTypings () {
+	if (hasRequiredExtraTypings) return extraTypings.exports;
+	hasRequiredExtraTypings = 1;
+	(function (module, exports$1) {
+		const commander = require$$0;
+
+		exports$1 = module.exports = {};
+
+		// Return a different global program than commander,
+		// and don't also return it as default export.
+		exports$1.program = new commander.Command();
+
+		/**
+		 * Expose classes. The FooT versions are just types, so return Commander original implementations!
+		 */
+
+		exports$1.Argument = commander.Argument;
+		exports$1.Command = commander.Command;
+		exports$1.CommanderError = commander.CommanderError;
+		exports$1.Help = commander.Help;
+		exports$1.InvalidArgumentError = commander.InvalidArgumentError;
+		exports$1.InvalidOptionArgumentError = commander.InvalidArgumentError; // Deprecated
+		exports$1.Option = commander.Option;
+
+		exports$1.createCommand = (name) => new commander.Command(name);
+		exports$1.createOption = (flags, description) =>
+		  new commander.Option(flags, description);
+		exports$1.createArgument = (name, description) =>
+		  new commander.Argument(name, description); 
+	} (extraTypings, extraTypings.exports));
+	return extraTypings.exports;
+}
+
+var extraTypingsExports = requireExtraTypings();
+var extraTypingsCommander = /*@__PURE__*/getDefaultExportFromCjs(extraTypingsExports);
+
+// wrapper to provide named exports for ESM.
+const {
+  program,
+  createCommand,
+  createArgument,
+  createOption,
+  CommanderError,
+  InvalidArgumentError,
+  InvalidOptionArgumentError, // deprecated old name
+  Command,
+  Argument,
+  Option,
+  Help,
+} = extraTypingsCommander;
+
+/**
+ * Zod schema for the Jeeves component descriptor.
+ *
+ * @remarks
+ * The descriptor replaces the v0.4.0 `JeevesComponent` interface with a
+ * Zod-first approach. The TypeScript type is inferred via `z.infer<>`.
+ * Validates at parse time: prime interval, callable functions.
+ */
+/**
+ * Check whether a number is prime.
+ *
+ * @param n - Number to check.
+ * @returns `true` if n is prime.
+ */
+function isPrime(n) {
+    if (n < 2)
+        return false;
+    if (n === 2)
+        return true;
+    if (n % 2 === 0)
+        return false;
+    for (let i = 3; i * i <= n; i += 2) {
+        if (n % i === 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Zod schema for the Jeeves component descriptor.
+ *
+ * @remarks
+ * Single source of truth for what a component must provide.
+ * Factories consume this descriptor to produce CLI commands,
+ * plugin tools, and HTTP handlers.
+ */
+z.object({
+    /** Component name (e.g., 'watcher', 'runner', 'server', 'meta'). */
+    name: z.string().min(1, 'name must be a non-empty string'),
+    /** Component version (from package.json). */
+    version: z.string().min(1, 'version must be a non-empty string'),
+    /** npm package name for the service. */
+    servicePackage: z.string().min(1),
+    /** npm package name for the plugin. */
+    pluginPackage: z.string().min(1),
+    /** System service name. Defaults to `jeeves-${name}` when not provided. */
+    serviceName: z.string().min(1).optional(),
+    /** Default port for the service's HTTP API. */
+    defaultPort: z.number().int().positive(),
+    /** Zod schema for validating config files. */
+    configSchema: z.custom((val) => val !== null &&
+        typeof val === 'object' &&
+        typeof val.parse === 'function', { message: 'configSchema must be a Zod schema' }),
+    /** Config file name (e.g., 'jeeves-watcher.config.json'). */
+    configFileName: z.string().min(1),
+    /** Returns a default config object for `init`. */
+    initTemplate: z.function().returns(z.record(z.unknown())),
+    /**
+     * Service-side callback after config apply. Receives the merged,
+     * validated config (not the raw patch). Optional — if omitted,
+     * write-only (service picks up changes on restart).
+     */
+    onConfigApply: z
+        .function()
+        .args(z.record(z.unknown()))
+        .returns(z.promise(z.void()))
+        .optional(),
+    /**
+     * Returns command + args for launching the service process.
+     * Consumed by `start` CLI command and `service install`.
+     */
+    startCommand: z.function().args(z.string()).returns(z.array(z.string())),
+    /** TOOLS.md section name (e.g., 'Watcher'). */
+    sectionId: z.string().min(1, 'sectionId must be a non-empty string'),
+    /** Refresh interval in seconds (must be a prime number). */
+    refreshIntervalSeconds: z.number().int().positive().refine(isPrime, {
+        message: 'refreshIntervalSeconds must be a prime number',
+    }),
+    /** Produce the component's TOOLS.md section content. */
+    generateToolsContent: z.function().returns(z.string()),
+    /** Component dependencies for HEARTBEAT alert suppression. */
+    dependencies: z
+        .object({
+        hard: z.array(z.string()),
+        soft: z.array(z.string()),
+    })
+        .optional(),
+    /** Extension point: add custom CLI commands to the service CLI. */
+    customCliCommands: z
+        .function()
+        .args(z.custom())
+        .returns(z.void())
+        .optional(),
+    /** Extension point: return additional plugin tool descriptors. */
+    customPluginTools: z
+        .function()
+        .args(z.custom())
+        .returns(z.array(z.unknown()))
+        .optional(),
+});
+/**
+ * Derive the effective service name from a descriptor.
+ *
+ * @param descriptor - The component descriptor.
+ * @returns The service name (explicit or derived from `jeeves-{name}`).
+ */
+function getEffectiveServiceName(descriptor) {
+    return descriptor.serviceName ?? `jeeves-${descriptor.name}`;
+}
+
+/**
+ * Workspace and config root initialization.
+ *
+ * @remarks
+ * `init()` must be called once before any other core library functions.
+ * It caches `workspacePath` and `configRoot` at module level.
+ * Core derives all namespaced paths from these values:
+ * - `{configRoot}/jeeves-core/` for core config
+ * - `{configRoot}/jeeves-{name}/` for each component
+ */
+/**
+ * Derive the component config directory from the component name.
+ *
+ * @param componentName - The component name (e.g., 'watcher', 'runner').
+ * @returns Absolute path to the component's config directory.
+ * @throws Error if `init()` has not been called.
+ */
+function getComponentConfigDir(componentName) {
+    throw new Error('jeeves-core: init() must be called first');
+}
+
+/**
+ * HTTP helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Thin wrappers around `fetch` that throw on non-OK responses
+ * and handle JSON serialisation/deserialisation.
+ */
+/**
+ * Fetch a URL with an automatic abort timeout.
+ *
+ * @param url - URL to fetch.
+ * @param timeoutMs - Timeout in milliseconds before aborting.
+ * @param init - Optional `fetch` init options.
+ * @returns The fetch Response object.
+ */
+/**
+ * Fetch JSON from a URL, throwing on non-OK responses.
+ *
+ * @param url - URL to fetch.
+ * @param init - Optional `fetch` init options.
+ * @returns Parsed JSON response body.
+ * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
+ */
+async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
+    }
+    return res.json();
+}
+/**
+ * POST JSON to a URL and return parsed response.
+ *
+ * @param url - URL to POST to.
+ * @param body - Request body (will be JSON-stringified).
+ * @returns Parsed JSON response body.
+ */
+async function postJson(url, body) {
+    return fetchJson(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+}
+
+/**
+ * Platform-aware service state detection.
+ *
+ * @remarks
+ * Detects whether a system service is installed and running.
+ * Delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ */
+/**
+ * Detect the state of a system service by name.
+ *
+ * @param serviceName - The service name (e.g., 'jeeves-runner').
+ * @returns The detected service state.
+ */
+function getServiceState(serviceName) {
+    switch (process.platform) {
+        case 'win32':
+            return getServiceStateWindows(serviceName);
+        case 'darwin':
+            return getServiceStateMacOS(serviceName);
+        default:
+            return getServiceStateLinux(serviceName);
+    }
+}
+/**
+ * Windows: detect via NSSM.
+ * - Exit code 3 = service does not exist
+ * - "SERVICE_RUNNING" in output = running
+ * - Other output = stopped/paused
+ */
+function getServiceStateWindows(serviceName) {
+    try {
+        const output = execSync(`nssm status ${serviceName}`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (output.includes('SERVICE_RUNNING'))
+            return 'running';
+        return 'stopped';
+    }
+    catch (err) {
+        // NSSM exits with code 3 when the service doesn't exist
+        if (isExecError(err) && err.status === 3)
+            return 'not_installed';
+        // Any other error (nssm not found, timeout, etc.) — treat as not installed
+        return 'not_installed';
+    }
+}
+/**
+ * Linux: detect via systemd user services.
+ * - `systemctl --user is-enabled {name}.service` exits non-zero = not installed
+ * - `systemctl --user is-active {name}.service` returns "active" = running
+ */
+function getServiceStateLinux(serviceName) {
+    try {
+        execSync(`systemctl --user is-enabled ${serviceName}.service`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        return 'not_installed';
+    }
+    try {
+        const output = execSync(`systemctl --user is-active ${serviceName}.service`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (output === 'active')
+            return 'running';
+        return 'stopped';
+    }
+    catch {
+        return 'stopped';
+    }
+}
+/**
+ * macOS: detect via launchctl.
+ * - `launchctl list {name}` exits non-zero = not installed
+ * - PID column is `-` or `0` = stopped
+ */
+function getServiceStateMacOS(serviceName) {
+    try {
+        const output = execSync(`launchctl list ${serviceName}`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        // launchctl list output formats:
+        // 1. Table row: "PID\tStatus\tLabel" (e.g., "1234\t0\tcom.jeeves.runner")
+        // 2. Plist-style: '"PID" = 1234;'
+        // 3. Single service: first token is the PID or "-"
+        // Try table format: first token is PID
+        const tableMatch = /^(\d+|-)\s/m.exec(output);
+        if (tableMatch) {
+            const pid = tableMatch[1];
+            return pid !== '-' && Number(pid) > 0 ? 'running' : 'stopped';
+        }
+        // Try plist-style: "PID" = <number>;
+        const plistMatch = /"PID"\s*=\s*(\d+)/m.exec(output);
+        if (plistMatch) {
+            return Number(plistMatch[1]) > 0 ? 'running' : 'stopped';
+        }
+        // If we got output but can't parse it, assume stopped (service exists but state unclear)
+        return 'stopped';
+    }
+    catch {
+        return 'not_installed';
+    }
+}
+/** Type guard for execSync errors with a status code. */
+function isExecError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'status' in err &&
+        typeof err.status === 'number');
+}
+
+/**
+ * Factory for platform-aware service lifecycle management.
+ *
+ * @remarks
+ * Produces a `ServiceManager` that handles install, uninstall, start,
+ * stop, restart, and status for system services. Delegates to NSSM
+ * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ */
+/** Exec helper that returns stdout. */
+function run(cmd) {
+    return execSync(cmd, {
+        encoding: 'utf-8',
+        timeout: 30_000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+}
+/** Exec helper that suppresses errors and returns success boolean. */
+function runQuiet(cmd) {
+    try {
+        execSync(cmd, {
+            encoding: 'utf-8',
+            timeout: 30_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the effective service name from options and descriptor.
+ *
+ * @param descriptor - Component descriptor.
+ * @param options - Optional overrides.
+ * @returns The service name to use.
+ */
+function resolveServiceName(descriptor, options) {
+    return options?.name ?? getEffectiveServiceName(descriptor);
+}
+/**
+ * Resolve the config path for install.
+ *
+ * @param descriptor - Component descriptor.
+ * @param options - Optional overrides.
+ * @returns Absolute config file path.
+ */
+function resolveConfigFilePath(descriptor, options) {
+    if (options?.configPath)
+        return options.configPath;
+    const configDir = getComponentConfigDir(descriptor.name);
+    return join(configDir, descriptor.configFileName);
+}
+/** Build a Windows NSSM service manager. */
+function createWindowsManager(descriptor) {
+    return {
+        install(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            const cfgPath = resolveConfigFilePath(descriptor, options);
+            const cmdArgs = descriptor.startCommand(cfgPath);
+            const appPath = cmdArgs[0];
+            const appArgs = cmdArgs.slice(1).join(' ');
+            run(`nssm install ${svcName} ${appPath}`);
+            if (appArgs) {
+                run(`nssm set ${svcName} AppParameters ${appArgs}`);
+            }
+            run(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
+            run(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
+            run(`nssm set ${svcName} AppRotateFiles 1`);
+            run(`nssm set ${svcName} AppRotateBytes 1048576`);
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`nssm stop ${svcName}`);
+            run(`nssm remove ${svcName} confirm`);
+        },
+        start(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`nssm start ${svcName}`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`nssm stop ${svcName}`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`nssm restart ${svcName}`);
+        },
+        status(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            return getServiceState(svcName);
+        },
+    };
+}
+/**
+ * Generate a systemd user unit file.
+ *
+ * @param svcName - Service name.
+ * @param cmdArgs - Command + args array.
+ * @returns Unit file content.
+ */
+function buildSystemdUnit(svcName, cmdArgs) {
+    const execStart = cmdArgs.join(' ');
+    return [
+        '[Unit]',
+        `Description=${svcName}`,
+        'After=network.target',
+        '',
+        '[Service]',
+        'Type=simple',
+        `ExecStart=${execStart}`,
+        'Restart=on-failure',
+        'RestartSec=5',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+    ].join('\n');
+}
+/** Build a Linux systemd service manager. */
+function createLinuxManager(descriptor) {
+    const unitDir = join(homedir(), '.config', 'systemd', 'user');
+    function unitPath(svcName) {
+        return join(unitDir, `${svcName}.service`);
+    }
+    return {
+        install(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            const cfgPath = resolveConfigFilePath(descriptor, options);
+            const cmdArgs = descriptor.startCommand(cfgPath);
+            mkdirSync(unitDir, { recursive: true });
+            writeFileSync(unitPath(svcName), buildSystemdUnit(svcName, cmdArgs));
+            run('systemctl --user daemon-reload');
+            run(`systemctl --user enable ${svcName}.service`);
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`systemctl --user stop ${svcName}.service`);
+            runQuiet(`systemctl --user disable ${svcName}.service`);
+            const path = unitPath(svcName);
+            if (existsSync(path))
+                unlinkSync(path);
+            runQuiet('systemctl --user daemon-reload');
+        },
+        start(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`systemctl --user start ${svcName}.service`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`systemctl --user stop ${svcName}.service`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`systemctl --user restart ${svcName}.service`);
+        },
+        status(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            return getServiceState(svcName);
+        },
+    };
+}
+/**
+ * Generate a macOS launchd plist.
+ *
+ * @param svcName - Service label.
+ * @param cmdArgs - Command + args array.
+ * @returns Plist XML content.
+ */
+function buildLaunchdPlist(svcName, cmdArgs) {
+    const argsXml = cmdArgs.map((a) => `    <string>${a}</string>`).join('\n');
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"',
+        '  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        '  <key>Label</key>',
+        `  <string>${svcName}</string>`,
+        '  <key>ProgramArguments</key>',
+        '  <array>',
+        argsXml,
+        '  </array>',
+        '  <key>RunAtLoad</key>',
+        '  <true/>',
+        '  <key>KeepAlive</key>',
+        '  <true/>',
+        '  <key>StandardOutPath</key>',
+        `  <string>${join(homedir(), 'Library', 'Logs', `${svcName}.log`)}</string>`,
+        '  <key>StandardErrorPath</key>',
+        `  <string>${join(homedir(), 'Library', 'Logs', `${svcName}.log`)}</string>`,
+        '</dict>',
+        '</plist>',
+    ].join('\n');
+}
+/** Build a macOS launchd service manager. */
+function createMacOSManager(descriptor) {
+    const agentsDir = join(homedir(), 'Library', 'LaunchAgents');
+    function plistPath(svcName) {
+        return join(agentsDir, `${svcName}.plist`);
+    }
+    return {
+        install(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            const cfgPath = resolveConfigFilePath(descriptor, options);
+            const cmdArgs = descriptor.startCommand(cfgPath);
+            mkdirSync(agentsDir, { recursive: true });
+            writeFileSync(plistPath(svcName), buildLaunchdPlist(svcName, cmdArgs));
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`launchctl unload ${plistPath(svcName)}`);
+            const path = plistPath(svcName);
+            if (existsSync(path))
+                unlinkSync(path);
+        },
+        start(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`launchctl load ${plistPath(svcName)}`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`launchctl unload ${plistPath(svcName)}`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`launchctl unload ${plistPath(svcName)}`);
+            run(`launchctl load ${plistPath(svcName)}`);
+        },
+        status(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            return getServiceState(svcName);
+        },
+    };
+}
+/**
+ * Create a platform-aware service manager from a component descriptor.
+ *
+ * @remarks
+ * Detects the current platform and returns a `ServiceManager` that
+ * delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ *
+ * @param descriptor - The component descriptor.
+ * @returns A `ServiceManager` for the current platform.
+ */
+function createServiceManager(descriptor) {
+    switch (process.platform) {
+        case 'win32':
+            return createWindowsManager(descriptor);
+        case 'darwin':
+            return createMacOSManager(descriptor);
+        default:
+            return createLinuxManager(descriptor);
+    }
+}
+
+/**
+ * Factory for the standard Jeeves service CLI.
+ *
+ * @remarks
+ * Produces a Commander program with all standard commands from
+ * a component descriptor. Components add domain-specific commands
+ * via `descriptor.customCliCommands`.
+ */
+/**
+ * Create a standard service CLI program from a component descriptor.
+ *
+ * @remarks
+ * Standard commands:
+ * - `start -c <path>` - Launch the service process (foreground)
+ * - `status [-p port]` - Probe service health
+ * - `config [jsonpath] [-p port]` - Query running config
+ * - `config validate -c <path>` - Validate a config file
+ * - `config apply [-p port] [--file path] [--replace]` - Apply config patch
+ * - `init [-o path]` - Generate default config
+ * - `service install` - Install system service
+ * - `service uninstall` - Uninstall system service
+ * - `service start` - Start system service
+ * - `service stop` - Stop system service
+ * - `service restart` - Restart system service
+ * - `service status` - Query system service state
+ *
+ * @param descriptor - The component descriptor.
+ * @returns A Commander program ready for custom commands and `.parse()`.
+ */
+function createServiceCli(descriptor) {
+    const defaultServiceName = getEffectiveServiceName(descriptor);
+    const program = new Command()
+        .name(`jeeves-${descriptor.name}`)
+        .description(`Jeeves ${descriptor.name} service CLI`)
+        .version(descriptor.version)
+        .enablePositionalOptions()
+        .passThroughOptions();
+    // --- start ---
+    program
+        .command('start')
+        .description('Launch the service process (foreground)')
+        .requiredOption('-c, --config <path>', 'Config file path')
+        .action((opts) => {
+        const cmdArgs = descriptor.startCommand(opts.config);
+        const proc = spawn(cmdArgs[0], cmdArgs.slice(1), {
+            stdio: 'inherit',
+        });
+        proc.on('exit', (code) => {
+            process.exit(code ?? 1);
+        });
+    });
+    // --- status ---
+    program
+        .command('status')
+        .description('Probe service health and version')
+        .option('-p, --port <port>', 'Service port', String(descriptor.defaultPort))
+        .action(async (opts) => {
+        const url = `http://127.0.0.1:${opts.port}`;
+        try {
+            const result = await fetchJson(`${url}/status`);
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Service unreachable: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    // --- config ---
+    const configCmd = program
+        .command('config')
+        .description('Query or manage service configuration');
+    configCmd
+        .command('query')
+        .description('Query running service config via JSONPath')
+        .argument('[jsonpath]', 'JSONPath expression')
+        .option('-p, --port <port>', 'Service port', String(descriptor.defaultPort))
+        .action(async (jsonpath, opts) => {
+        const url = `http://127.0.0.1:${opts.port}`;
+        const qs = jsonpath ? `?path=${encodeURIComponent(jsonpath)}` : '';
+        try {
+            const result = await fetchJson(`${url}/config${qs}`);
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Config query failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    configCmd
+        .command('validate')
+        .description('Validate a config file against the schema')
+        .requiredOption('-c, --config <path>', 'Config file path')
+        .action((opts) => {
+        try {
+            const raw = readFileSync(opts.config, 'utf-8');
+            const parsed = JSON.parse(raw);
+            descriptor.configSchema.parse(parsed);
+            console.log('Config is valid.');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Validation failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    configCmd
+        .command('apply')
+        .description('Apply a config patch to the running service')
+        .option('-p, --port <port>', 'Service port', String(descriptor.defaultPort))
+        .option('-f, --file <path>', 'Config patch file (JSON)')
+        .option('--replace', 'Replace entire config instead of merging')
+        .action(async (opts) => {
+        const url = `http://127.0.0.1:${opts.port}`;
+        let patch = {};
+        if (opts.file) {
+            const raw = readFileSync(opts.file, 'utf-8');
+            patch = JSON.parse(raw);
+        }
+        else {
+            // Read from stdin
+            const chunks = [];
+            for await (const chunk of process.stdin) {
+                chunks.push(chunk);
+            }
+            const input = Buffer.concat(chunks).toString('utf-8').trim();
+            if (input) {
+                patch = JSON.parse(input);
+            }
+        }
+        const qs = opts.replace ? '?replace=true' : '';
+        try {
+            const result = await postJson(`${url}/config/apply${qs}`, patch);
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Config apply failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    // --- init ---
+    program
+        .command('init')
+        .description('Generate default config file')
+        .option('-o, --output <path>', 'Output directory')
+        .action((opts) => {
+        const outputDir = opts.output ?? getComponentConfigDir(descriptor.name);
+        mkdirSync(outputDir, { recursive: true });
+        const configPath = join(outputDir, descriptor.configFileName);
+        if (existsSync(configPath)) {
+            console.log(`Config already exists at ${configPath}`);
+            return;
+        }
+        const template = descriptor.initTemplate();
+        writeFileSync(configPath, JSON.stringify(template, null, 2) + '\n');
+        console.log(`Config written to ${configPath}`);
+    });
+    // --- service ---
+    const serviceCmd = program
+        .command('service')
+        .description('System service management');
+    const svcManager = createServiceManager(descriptor);
+    serviceCmd
+        .command('install')
+        .description('Install as a system service')
+        .option('-c, --config <path>', 'Config file path')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.install({ name: opts.name, configPath: opts.config });
+            console.log(`Service "${opts.name}" installed.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Install failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('uninstall')
+        .description('Uninstall the system service')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.uninstall({ name: opts.name });
+            console.log(`Service "${opts.name}" uninstalled.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Uninstall failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('start')
+        .description('Start the system service')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.start({ name: opts.name });
+            console.log(`Service "${opts.name}" started.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Start failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('stop')
+        .description('Stop the system service')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.stop({ name: opts.name });
+            console.log(`Service "${opts.name}" stopped.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Stop failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('restart')
+        .description('Restart the system service')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.restart({ name: opts.name });
+            console.log(`Service "${opts.name}" restarted.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Restart failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('status')
+        .description('Query system service state')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            const state = svcManager.status({ name: opts.name });
+            console.log(`Service "${opts.name}": ${state}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Status failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    // Apply custom CLI commands if provided
+    if (descriptor.customCliCommands) {
+        // Cast required: @commander-js/extra-typings Command has generic type
+        // parameters that don't align with the descriptor's base Command type.
+        // The descriptor can't know the parent Command's exact generic parameters
+        // at definition time. The cast is safe — customCliCommands only adds
+        // subcommands and doesn't depend on the parent's generic state.
+        descriptor.customCliCommands(program);
+    }
+    return program;
+}
+
+export { createServiceCli };