@karmaniverous/jeeves 0.5.3 → 0.5.5

package/dist/cli/jeeves/index.js

@@ -269,14 +269,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.2` placeholder is replaced by
+ * The `0.5.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.5.2';
+const CORE_VERSION = '0.5.4';
 
 /**
  * Runtime Node.js version floor check.

package/dist/cli/plugin/index.js

@@ -2,11 +2,14 @@
 import { writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync, readFileSync, readdirSync, copyFileSync, rmSync } from 'node:fs';
 import { dirname, basename, join, resolve } from 'node:path';
 import * as commander from 'commander';
-import { packageDirectorySync } from 'package-directory';
 import { randomUUID } from 'node:crypto';
 import { lock } from 'proper-lockfile';
 import 'semver';
+import 'node:child_process';
 import { homedir } from 'node:os';
+import { z } from 'zod';
+import { fileURLToPath } from 'node:url';
+import { packageDirectorySync } from 'package-directory';
 
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
@@ -127,14 +130,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.2` placeholder is replaced by
+ * The `0.5.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.5.2';
+const CORE_VERSION = '0.5.4';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -887,6 +890,153 @@ function seedSkill(workspacePath) {
     writeFileSync(skillPath, skillContent, 'utf-8');
 }
 
+/**
+ * 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({
+        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({
+        input: [z.record(z.string(), z.unknown())],
+        output: z.promise(z.void()),
+    })
+        .optional(),
+    /**
+     * 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
+        .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 `service install`.
+     */
+    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). */
+    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({ 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({ input: [z.custom()], output: z.void() })
+        .optional(),
+    /** Extension point: return additional plugin tool descriptors. */
+    customPluginTools: z
+        .function({ input: [z.custom()], output: z.array(z.unknown()) })
+        .optional(),
+});
+
+/**
+ * Resolve the package root directory from a module's `import.meta.url`.
+ *
+ * @module
+ */
+/**
+ * Get the nearest package root directory relative to the calling module URL.
+ *
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The absolute package root path, or `undefined` on any error.
+ */
+function getPackageRoot(importMetaUrl) {
+    try {
+        return packageDirectorySync({ cwd: fileURLToPath(importMetaUrl) });
+    }
+    catch {
+        return undefined;
+    }
+}
+
 /**
  * OpenClaw configuration helpers for plugin CLI installers.
  *
@@ -1090,8 +1240,13 @@ function readJsonFile(filePath) {
  * @returns A Commander program ready for `.parse()`.
  */
 function createPluginCli(options) {
-    const { pluginId, distDir, pluginPackage, configRoot = 'j:/config', } = options;
+    const { pluginId, importMetaUrl, pluginPackage, configRoot = 'j:/config', } = options;
     const componentName = options.componentName ?? deriveComponentName(pluginId);
+    const pkgRoot = getPackageRoot(importMetaUrl);
+    if (!pkgRoot) {
+        throw new Error(`Unable to resolve package root for plugin CLI: ${pluginPackage}`);
+    }
+    const distDir = join(pkgRoot, 'dist');
     const program = new Command()
         .name(pluginPackage)
         .description(`Jeeves ${componentName} plugin installer`);
@@ -1106,16 +1261,16 @@ function createPluginCli(options) {
         const configPath = resolveConfigPath(openClawHome);
         // 1. Copy dist to extensions
         const extensionsDir = join(openClawHome, 'extensions', pluginId);
+        if (!existsSync(distDir)) {
+            throw new Error(`Plugin dist directory not found: ${distDir}. Ensure the plugin is built before installing.`);
+        }
         console.log(`Copying dist to ${extensionsDir}...`);
-        copyDistFiles(distDir, extensionsDir);
+        copyDistFiles(distDir, join(extensionsDir, 'dist'));
         // Copy package.json and openclaw.plugin.json from package root
-        const pkgRoot = packageDirectorySync({ cwd: distDir });
-        if (pkgRoot) {
-            for (const file of ['package.json', 'openclaw.plugin.json']) {
-                const src = join(pkgRoot, file);
-                if (existsSync(src)) {
-                    copyFileSync(src, join(extensionsDir, file));
-                }
+        for (const file of ['package.json', 'openclaw.plugin.json']) {
+            const src = join(pkgRoot, file);
+            if (existsSync(src)) {
+                copyFileSync(src, join(extensionsDir, file));
             }
         }
         console.log('  ✓ Dist files copied');

package/dist/index.d.ts

@@ -427,8 +427,8 @@ declare function buildEffectiveConfig(opts: WorkspaceOptions): ResolvedCliConfig
 interface CreatePluginCliOptions {
     /** Plugin identifier (e.g., 'jeeves-watcher-openclaw'). */
     pluginId: string;
-    /** Absolute path to the dist directory to copy. */
-    distDir: string;
+    /** `import.meta.url` for the calling plugin CLI module. */
+    importMetaUrl: string;
     /** npm package name for the plugin. */
     pluginPackage: string;
     /** Component name (e.g., 'watcher'). Derived from pluginId if omitted. */
@@ -1497,6 +1497,19 @@ declare function seedSkill(workspacePath: string): void;
  */
 declare function createPluginToolset(descriptor: JeevesComponentDescriptor): ToolDescriptor[];
 
+/**
+ * Resolve the package root directory from a module's `import.meta.url`.
+ *
+ * @module
+ */
+/**
+ * Get the nearest package root directory relative to the calling module URL.
+ *
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The absolute package root path, or `undefined` on any error.
+ */
+declare function getPackageRoot(importMetaUrl: string): string | undefined;
+
 /**
  * Resolve the version of a package from its `import.meta.url`.
  *
@@ -1879,5 +1892,5 @@ interface ServiceManager {
  */
 declare function createServiceManager(descriptor: JeevesComponentDescriptor): ServiceManager;
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
 export type { AccountConfig, AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ComponentWriterOptions, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigProvenance, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreatePluginCliOptions, CreateStatusHandlerOptions, GoogleAuthOptions, HeartbeatEntry, InitOptions, JeevesComponentDescriptor, ManagedMarkers, ManagedSection, MemoryHygieneOptions, MemoryHygieneResult, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, PluginInstallRecord, RefreshPlatformContentOptions, RemoveManagedSectionOptions, ResolvedCliConfig, ResolvedValue, RetryOptions, RunOptions, SectionId, SeedContentOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WorkspaceConfig, WorkspaceOptions, WriteComponentVersionOptions };