@karmaniverous/jeeves 0.4.3 → 0.4.5

package/dist/cli/jeeves/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import * as commander from 'commander';
 import { execSync, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, cpSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync, cpSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { gte } from 'semver';
+import { valid, gte } from 'semver';
 import { z } from 'zod';
 import { lock } from 'proper-lockfile';
 import { fileURLToPath } from 'node:url';
@@ -261,14 +261,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.2` placeholder is replaced by
+ * The `0.4.4` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.4.2';
+const CORE_VERSION = '0.4.4';
 
 /**
  * Dynamic discovery of installed Jeeves component CLIs.
@@ -409,7 +409,7 @@ var init$1 = /*#__PURE__*/Object.freeze({
 /** Zod schema for a service entry in core config. */
 const serviceEntrySchema = z.object({
     /** Service URL (must be a valid URL). */
-    url: z.string().url().describe('Service URL'),
+    url: z.url().describe('Service URL'),
 });
 /** Default bind address for all Jeeves services. */
 const DEFAULT_BIND_ADDRESS = '0.0.0.0';
@@ -443,7 +443,7 @@ const coreConfigSchema = z.object({
             .default(3600)
             .describe('Cache TTL in seconds'),
     })
-        .default({})
+        .prefault({})
         .describe('Registry cache settings'),
 });
 /**
@@ -598,7 +598,18 @@ function atomicWrite(filePath, content) {
     const dir = dirname(filePath);
     const tempPath = join(dir, `.${String(Date.now())}.tmp`);
     writeFileSync(tempPath, content, 'utf-8');
-    renameSync(tempPath, filePath);
+    try {
+        renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
 }
 /**
  * Execute a callback while holding a file lock.
@@ -1460,8 +1471,9 @@ function formatEndMarker(markerText) {
  * @returns `true` if the writer should proceed with the write.
  */
 function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRESHOLD_MS) {
-    // No existing stamp — always write
-    if (!existing)
+    // Always write when version comparison is impossible: invalid/placeholder
+    // versions (dev/test mode) or no existing stamp to compare against.
+    if (!valid(myVersion) || !existing || !valid(existing.version))
         return true;
     // My version >= stamped version — always write (I'm current or newer)
     if (gte(myVersion, existing.version))

package/dist/cli/plugin/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { writeFileSync, renameSync, existsSync, readFileSync, rmSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
+import { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, rmSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import * as commander from 'commander';
 import { lock } from 'proper-lockfile';
@@ -119,14 +119,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.2` placeholder is replaced by
+ * The `0.4.4` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.4.2';
+const CORE_VERSION = '0.4.4';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -152,7 +152,18 @@ function atomicWrite(filePath, content) {
     const dir = dirname(filePath);
     const tempPath = join(dir, `.${String(Date.now())}.tmp`);
     writeFileSync(tempPath, content, 'utf-8');
-    renameSync(tempPath, filePath);
+    try {
+        renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
 }
 /**
  * Execute a callback while holding a file lock.

package/dist/cli/service/index.js

@@ -1,9 +1,9 @@
 #!/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 { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 
 function getDefaultExportFromCjs (x) {
@@ -151,16 +151,20 @@ z.object({
     /** 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())),
+    initTemplate: z.function({
+        input: [],
+        output: z.record(z.string(), 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()))
+        .function({
+        input: [z.record(z.string(), z.unknown())],
+        output: z.promise(z.void()),
+    })
         .optional(),
     /**
      * Custom merge function for config apply. Receives the existing config
@@ -171,15 +175,27 @@ z.object({
      * name-based array merging for inference rules.
      */
     customMerge: z
-        .function()
-        .args(z.record(z.unknown()), z.record(z.unknown()))
-        .returns(z.record(z.unknown()))
+        .function({
+        input: [
+            z.record(z.string(), z.unknown()),
+            z.record(z.string(), z.unknown()),
+        ],
+        output: z.record(z.string(), z.unknown()),
+    })
         .optional(),
     /**
      * Returns command + args for launching the service process.
-     * Consumed by `start` CLI command and `service install`.
+     * Consumed by `service install`.
      */
-    startCommand: z.function().args(z.string()).returns(z.array(z.string())),
+    startCommand: z.function({
+        input: [z.string()],
+        output: z.array(z.string()),
+    }),
+    /** In-process service entry point for the CLI `start` command. */
+    run: z.function({
+        input: [z.string()],
+        output: z.promise(z.void()),
+    }),
     /** 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). */
@@ -187,25 +203,23 @@ z.object({
         message: 'refreshIntervalSeconds must be a prime number',
     }),
     /** Produce the component's TOOLS.md section content. */
-    generateToolsContent: z.function().returns(z.string()),
+    generateToolsContent: z.function({ input: [], output: z.string() }),
     /** Component dependencies for HEARTBEAT alert suppression. */
     dependencies: z
         .object({
+        /** Components that must be healthy for this component to function. */
         hard: z.array(z.string()),
+        /** Components that improve behavior but are not strictly required. */
         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())
+        .function({ input: [z.custom()], output: z.void() })
         .optional(),
     /** Extension point: return additional plugin tool descriptors. */
     customPluginTools: z
-        .function()
-        .args(z.custom())
-        .returns(z.array(z.unknown()))
+        .function({ input: [z.custom()], output: z.array(z.unknown()) })
         .optional(),
 });
 /**
@@ -701,14 +715,8 @@ function createServiceCli(descriptor) {
         .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);
-        });
+        .action(async (opts) => {
+        await descriptor.run(opts.config);
     });
     // --- status ---
     program

package/dist/index.d.ts

@@ -106,110 +106,29 @@ declare function isPrime(n: number): boolean;
  * plugin tools, and HTTP handlers.
  */
 declare const jeevesComponentDescriptorSchema: z.ZodObject<{
-    /** Component name (e.g., 'watcher', 'runner', 'server', 'meta'). */
     name: z.ZodString;
-    /** Component version (from package.json). */
     version: z.ZodString;
-    /** npm package name for the service. */
     servicePackage: z.ZodString;
-    /** npm package name for the plugin. */
     pluginPackage: z.ZodString;
-    /** System service name. Defaults to `jeeves-${name}` when not provided. */
     serviceName: z.ZodOptional<z.ZodString>;
-    /** Default port for the service's HTTP API. */
     defaultPort: z.ZodNumber;
-    /** Zod schema for validating config files. */
-    configSchema: z.ZodType<z.ZodTypeAny, z.ZodTypeDef, z.ZodTypeAny>;
-    /** Config file name (e.g., 'jeeves-watcher.config.json'). */
+    configSchema: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     configFileName: z.ZodString;
-    /** Returns a default config object for `init`. */
-    initTemplate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    /**
-     * 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.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodUnknown>], z.ZodUnknown>, z.ZodPromise<z.ZodVoid>>>;
-    /**
-     * Custom merge function for config apply. Receives the existing config
-     * and the patch, returns the merged result. Optional — if omitted,
-     * the default deep-merge (object-recursive, array-replacing) is used.
-     *
-     * Use this to implement domain-specific merge strategies such as
-     * name-based array merging for inference rules.
-     */
-    customMerge: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>], z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-    /**
-     * Returns command + args for launching the service process.
-     * Consumed by `start` CLI command and `service install`.
-     */
-    startCommand: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodArray<z.ZodString, "many">>;
-    /** TOOLS.md section name (e.g., 'Watcher'). */
+    initTemplate: z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    onConfigApply: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>], null>, z.ZodPromise<z.ZodVoid>>>;
+    customMerge: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>], null>, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    startCommand: z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodArray<z.ZodString>>;
+    run: z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodPromise<z.ZodVoid>>;
     sectionId: z.ZodString;
-    /** Refresh interval in seconds (must be a prime number). */
-    refreshIntervalSeconds: z.ZodEffects<z.ZodNumber, number, number>;
-    /** Produce the component's TOOLS.md section content. */
-    generateToolsContent: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodString>;
-    /** Component dependencies for HEARTBEAT alert suppression. */
+    refreshIntervalSeconds: z.ZodNumber;
+    generateToolsContent: z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodString>;
     dependencies: z.ZodOptional<z.ZodObject<{
-        hard: z.ZodArray<z.ZodString, "many">;
-        soft: z.ZodArray<z.ZodString, "many">;
-    }, "strip", z.ZodTypeAny, {
-        hard: string[];
-        soft: string[];
-    }, {
-        hard: string[];
-        soft: string[];
-    }>>;
-    /** Extension point: add custom CLI commands to the service CLI. */
-    customCliCommands: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodType<Command<[], {}, {}>, z.ZodTypeDef, Command<[], {}, {}>>], z.ZodUnknown>, z.ZodVoid>>;
-    /** Extension point: return additional plugin tool descriptors. */
-    customPluginTools: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodType<PluginApi, z.ZodTypeDef, PluginApi>], z.ZodUnknown>, z.ZodArray<z.ZodUnknown, "many">>>;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-    version: string;
-    servicePackage: string;
-    pluginPackage: string;
-    defaultPort: number;
-    configSchema: z.ZodTypeAny;
-    configFileName: string;
-    initTemplate: (...args: unknown[]) => Record<string, unknown>;
-    startCommand: (args_0: string, ...args: unknown[]) => string[];
-    sectionId: string;
-    refreshIntervalSeconds: number;
-    generateToolsContent: (...args: unknown[]) => string;
-    serviceName?: string | undefined;
-    onConfigApply?: ((args_0: Record<string, unknown>, ...args: unknown[]) => Promise<void>) | undefined;
-    customMerge?: ((args_0: Record<string, unknown>, args_1: Record<string, unknown>, ...args: unknown[]) => Record<string, unknown>) | undefined;
-    dependencies?: {
-        hard: string[];
-        soft: string[];
-    } | undefined;
-    customCliCommands?: ((args_0: Command<[], {}, {}>, ...args: unknown[]) => void) | undefined;
-    customPluginTools?: ((args_0: PluginApi, ...args: unknown[]) => unknown[]) | undefined;
-}, {
-    name: string;
-    version: string;
-    servicePackage: string;
-    pluginPackage: string;
-    defaultPort: number;
-    configSchema: z.ZodTypeAny;
-    configFileName: string;
-    initTemplate: (...args: unknown[]) => Record<string, unknown>;
-    startCommand: (args_0: string, ...args: unknown[]) => string[];
-    sectionId: string;
-    refreshIntervalSeconds: number;
-    generateToolsContent: (...args: unknown[]) => string;
-    serviceName?: string | undefined;
-    onConfigApply?: ((args_0: Record<string, unknown>, ...args: unknown[]) => Promise<void>) | undefined;
-    customMerge?: ((args_0: Record<string, unknown>, args_1: Record<string, unknown>, ...args: unknown[]) => Record<string, unknown>) | undefined;
-    dependencies?: {
-        hard: string[];
-        soft: string[];
-    } | undefined;
-    customCliCommands?: ((args_0: Command<[], {}, {}>, ...args: unknown[]) => void) | undefined;
-    customPluginTools?: ((args_0: PluginApi, ...args: unknown[]) => unknown[]) | undefined;
-}>;
+        hard: z.ZodArray<z.ZodString>;
+        soft: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    customCliCommands: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodCustom<Command<[], {}, {}>, Command<[], {}, {}>>], null>, z.ZodVoid>>;
+    customPluginTools: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodCustom<PluginApi, PluginApi>], null>, z.ZodArray<z.ZodUnknown>>>;
+}, z.core.$strip>;
 /** Inferred TypeScript type for the component descriptor. */
 type JeevesComponentDescriptor = z.infer<typeof jeevesComponentDescriptorSchema>;
 /**
@@ -871,54 +790,16 @@ declare const CORE_VERSION: string;
 declare const DEFAULT_BIND_ADDRESS = "0.0.0.0";
 /** Zod schema for the core config file. */
 declare const coreConfigSchema: z.ZodObject<{
-    /** JSON Schema pointer for IDE autocomplete. */
     $schema: z.ZodOptional<z.ZodString>;
-    /** Owner identity keys (canonical identityLinks references). */
-    owners: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    /**
-     * Bind address for all Jeeves services. Default: `0.0.0.0` (all interfaces).
-     * Individual components can override in their own config.
-     */
+    owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
     bindAddress: z.ZodDefault<z.ZodString>;
-    /** Service URL overrides keyed by service name. */
     services: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-        /** Service URL (must be a valid URL). */
-        url: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        url: string;
-    }, {
-        url: string;
-    }>>>;
-    /** Registry cache configuration. */
-    registryCache: z.ZodDefault<z.ZodObject<{
-        /** Cache TTL in seconds for npm registry queries. */
+        url: z.ZodURL;
+    }, z.core.$strip>>>;
+    registryCache: z.ZodPrefault<z.ZodObject<{
         ttlSeconds: z.ZodDefault<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        ttlSeconds: number;
-    }, {
-        ttlSeconds?: number | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    owners: string[];
-    bindAddress: string;
-    services: Record<string, {
-        url: string;
-    }>;
-    registryCache: {
-        ttlSeconds: number;
-    };
-    $schema?: string | undefined;
-}, {
-    $schema?: string | undefined;
-    owners?: string[] | undefined;
-    bindAddress?: string | undefined;
-    services?: Record<string, {
-        url: string;
-    }> | undefined;
-    registryCache?: {
-        ttlSeconds?: number | undefined;
-    } | undefined;
-}>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /** Core config type derived from the Zod schema. */
 type CoreConfig = z.infer<typeof coreConfigSchema>;
 /**

package/dist/index.js

@@ -1,12 +1,12 @@
-import { writeFileSync, renameSync, existsSync, readFileSync, mkdirSync, rmSync, readdirSync, copyFileSync, unlinkSync, cpSync } from 'node:fs';
+import { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, mkdirSync, rmSync, readdirSync, copyFileSync, cpSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { lock } from 'proper-lockfile';
 import { JSONPath } from 'jsonpath-plus';
 import * as commander from 'commander';
-import { gte, gt } from 'semver';
+import { valid, gte, gt } from 'semver';
 import { homedir } from 'node:os';
-import { execSync, spawn } from 'node:child_process';
 import { z } from 'zod';
+import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
 
@@ -176,14 +176,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.2` placeholder is replaced by
+ * The `0.4.4` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.4.2';
+const CORE_VERSION = '0.4.4';
 
 /**
  * Workspace and config root initialization.
@@ -291,7 +291,18 @@ function atomicWrite(filePath, content) {
     const dir = dirname(filePath);
     const tempPath = join(dir, `.${String(Date.now())}.tmp`);
     writeFileSync(tempPath, content, 'utf-8');
-    renameSync(tempPath, filePath);
+    try {
+        renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
 }
 /**
  * Execute a callback while holding a file lock.
@@ -1002,8 +1013,9 @@ function formatEndMarker(markerText) {
  * @returns `true` if the writer should proceed with the write.
  */
 function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRESHOLD_MS) {
-    // No existing stamp — always write
-    if (!existing)
+    // Always write when version comparison is impossible: invalid/placeholder
+    // versions (dev/test mode) or no existing stamp to compare against.
+    if (!valid(myVersion) || !existing || !valid(existing.version))
         return true;
     // My version >= stamped version — always write (I'm current or newer)
     if (gte(myVersion, existing.version))
@@ -1491,16 +1503,20 @@ const jeevesComponentDescriptorSchema = z.object({
     /** 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())),
+    initTemplate: z.function({
+        input: [],
+        output: z.record(z.string(), 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()))
+        .function({
+        input: [z.record(z.string(), z.unknown())],
+        output: z.promise(z.void()),
+    })
         .optional(),
     /**
      * Custom merge function for config apply. Receives the existing config
@@ -1511,15 +1527,27 @@ const jeevesComponentDescriptorSchema = z.object({
      * name-based array merging for inference rules.
      */
     customMerge: z
-        .function()
-        .args(z.record(z.unknown()), z.record(z.unknown()))
-        .returns(z.record(z.unknown()))
+        .function({
+        input: [
+            z.record(z.string(), z.unknown()),
+            z.record(z.string(), z.unknown()),
+        ],
+        output: z.record(z.string(), z.unknown()),
+    })
         .optional(),
     /**
      * Returns command + args for launching the service process.
-     * Consumed by `start` CLI command and `service install`.
+     * Consumed by `service install`.
      */
-    startCommand: z.function().args(z.string()).returns(z.array(z.string())),
+    startCommand: z.function({
+        input: [z.string()],
+        output: z.array(z.string()),
+    }),
+    /** In-process service entry point for the CLI `start` command. */
+    run: z.function({
+        input: [z.string()],
+        output: z.promise(z.void()),
+    }),
     /** 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). */
@@ -1527,25 +1555,23 @@ const jeevesComponentDescriptorSchema = z.object({
         message: 'refreshIntervalSeconds must be a prime number',
     }),
     /** Produce the component's TOOLS.md section content. */
-    generateToolsContent: z.function().returns(z.string()),
+    generateToolsContent: z.function({ input: [], output: z.string() }),
     /** Component dependencies for HEARTBEAT alert suppression. */
     dependencies: z
         .object({
+        /** Components that must be healthy for this component to function. */
         hard: z.array(z.string()),
+        /** Components that improve behavior but are not strictly required. */
         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())
+        .function({ input: [z.custom()], output: z.void() })
         .optional(),
     /** Extension point: return additional plugin tool descriptors. */
     customPluginTools: z
-        .function()
-        .args(z.custom())
-        .returns(z.array(z.unknown()))
+        .function({ input: [z.custom()], output: z.array(z.unknown()) })
         .optional(),
 });
 /**
@@ -2032,14 +2058,8 @@ function createServiceCli(descriptor) {
         .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);
-        });
+        .action(async (opts) => {
+        await descriptor.run(opts.config);
     });
     // --- status ---
     program
@@ -2972,7 +2992,7 @@ async function refreshPlatformContent(options) {
 /** Zod schema for a service entry in core config. */
 const serviceEntrySchema = z.object({
     /** Service URL (must be a valid URL). */
-    url: z.string().url().describe('Service URL'),
+    url: z.url().describe('Service URL'),
 });
 /** Default bind address for all Jeeves services. */
 const DEFAULT_BIND_ADDRESS = '0.0.0.0';
@@ -3006,7 +3026,7 @@ const coreConfigSchema = z.object({
             .default(3600)
             .describe('Cache TTL in seconds'),
     })
-        .default({})
+        .prefault({})
         .describe('Registry cache settings'),
 });
 /**

package/package.json

@@ -13,52 +13,52 @@
     "url": "https://github.com/karmaniverous/jeeves/issues"
   },
   "dependencies": {
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "jsonpath-plus": "^10.4.0",
     "package-directory": "^8.2.0",
     "proper-lockfile": "^4.1.2",
-    "semver": "^7.7.2",
-    "zod": "^3.25.67"
+    "semver": "^7.7.4",
+    "zod": "^4.3.6"
   },
   "description": "Shared library and CLI for the Jeeves AI assistant platform.",
   "devDependencies": {
     "@commander-js/extra-typings": "^14.0.0",
-    "@dotenvx/dotenvx": "^1.51.4",
-    "@eslint/js": "^9.39.2",
+    "@dotenvx/dotenvx": "^1.59.1",
+    "@eslint/js": "^10.0.1",
     "@rollup/plugin-alias": "^6.0.0",
-    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^25.0.3",
+    "@types/node": "^25.5.0",
     "@types/proper-lockfile": "^4.1.4",
-    "@types/semver": "^7.7.0",
-    "@vitest/coverage-v8": "^4.0.16",
-    "@vitest/eslint-plugin": "^1.6.4",
+    "@types/semver": "^7.7.1",
+    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/eslint-plugin": "^1.6.13",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
-    "eslint": "^9.39.2",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-tsdoc": "^0.5.0",
-    "fs-extra": "^11.3.3",
-    "knip": "^5.79.0",
-    "lefthook": "^2.0.13",
-    "prettier": "^3.7.4",
-    "release-it": "^19.2.2",
-    "rimraf": "^6.1.2",
-    "rollup": "^4.54.0",
-    "rollup-plugin-dts": "^6.3.0",
+    "eslint-plugin-tsdoc": "^0.5.2",
+    "fs-extra": "^11.3.4",
+    "knip": "^6.1.0",
+    "lefthook": "^2.1.4",
+    "prettier": "^3.8.1",
+    "release-it": "^19.2.4",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.60.1",
+    "rollup-plugin-dts": "^6.4.1",
     "tslib": "^2.8.1",
-    "typedoc": "^0.28.15",
-    "typedoc-plugin-mdn-links": "^5.0.10",
+    "typedoc": "^0.28.18",
+    "typedoc-plugin-mdn-links": "^5.1.1",
     "typedoc-plugin-replace-text": "^4.2.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.51.0",
-    "vitest": "^4.0.16"
+    "typescript-eslint": "^8.57.2",
+    "vitest": "^4.1.2"
   },
   "engines": {
     "node": ">=20"
@@ -139,5 +139,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.4.3"
+  "version": "0.4.5"
 }