@karmaniverous/jeeves 0.5.1 → 0.5.4

package/dist/cli/plugin/index.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 import { writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync, readFileSync, readdirSync, copyFileSync, rmSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+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;
@@ -126,14 +130,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.0` placeholder is replaced by
+ * The `0.5.3` 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.0';
+const CORE_VERSION = '0.5.3';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -149,27 +153,46 @@ const STALE_LOCK_MS = 120_000;
 const DEFAULT_CORE_VERSION = CORE_VERSION;
 /** Lock retry options. */
 const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+/** Maximum rename retry attempts on EPERM. */
+const ATOMIC_WRITE_MAX_RETRIES = 3;
+/** Delay between EPERM retries in milliseconds. */
+const ATOMIC_WRITE_RETRY_DELAY_MS = 100;
 /**
  * Write content to a file atomically via a temp file + rename.
  *
+ * @remarks
+ * Retries the rename up to three times on EPERM (Windows file-handle
+ * contention) with a 100 ms synchronous delay between attempts.
+ *
  * @param filePath - Absolute path to the target file.
  * @param content - Content to write.
  */
 function atomicWrite(filePath, content) {
     const dir = dirname(filePath);
-    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
+    const base = basename(filePath, '.md');
+    const tempPath = join(dir, `.${base}.${String(Date.now())}.${randomUUID().slice(0, 8)}.tmp`);
     writeFileSync(tempPath, content, 'utf-8');
-    try {
-        renameSync(tempPath, filePath);
-    }
-    catch (err) {
+    for (let attempt = 0; attempt < ATOMIC_WRITE_MAX_RETRIES; attempt++) {
         try {
-            unlinkSync(tempPath);
+            renameSync(tempPath, filePath);
+            return;
         }
-        catch {
-            /* best-effort cleanup */
+        catch (err) {
+            const isEperm = err instanceof Error &&
+                'code' in err &&
+                err.code === 'EPERM';
+            if (!isEperm || attempt === ATOMIC_WRITE_MAX_RETRIES - 1) {
+                try {
+                    unlinkSync(tempPath);
+                }
+                catch {
+                    /* best-effort cleanup */
+                }
+                throw err;
+            }
+            // Synchronous sleep before retry (acceptable in atomic write context)
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ATOMIC_WRITE_RETRY_DELAY_MS);
         }
-        throw err;
     }
 }
 /**
@@ -402,7 +425,7 @@ function parseHeartbeat(fileContent) {
     const userContent = fileContent.slice(0, headingIndex).trim();
     const sectionContent = fileContent.slice(headingIndex + HEARTBEAT_HEADING.length);
     const entries = [];
-    const h2Re = /^## (jeeves-\S+?|MEMORY\.md)(?:: declined)?$/gm;
+    const h2Re = /^## (jeeves-\S+?|\S+\.md)(?:: declined)?$/gm;
     let match;
     const h2Positions = [];
     while ((match = h2Re.exec(sectionContent)) !== null) {
@@ -483,6 +506,15 @@ function sortSectionsByOrder(sections) {
  * sections within the block, and returns the structured result plus
  * user content outside the markers.
  */
+/**
+ * Escape a string for safe use as a literal in a RegExp pattern.
+ *
+ * @param str - The string to escape.
+ * @returns The escaped string.
+ */
+function escapeForRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * Build regex patterns for the given markers.
  *
@@ -490,11 +522,9 @@ function sortSectionsByOrder(sections) {
  * @returns Object with begin and end regex patterns.
  */
 function buildMarkerPatterns(markers) {
-    const escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const escapedEnd = markers.end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return {
-        beginRe: new RegExp(`^<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$`, 'm'),
-        endRe: new RegExp(`^<!--\\s*${escapedEnd}\\s*-->\\s*$`, 'm'),
+        beginRe: new RegExp(`^<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$`, 'm'),
+        endRe: new RegExp(`^<!--\\s*${escapeForRegex(markers.end)}\\s*-->\\s*$`, 'm'),
     };
 }
 /**
@@ -819,6 +849,23 @@ Review is human/agent-mediated — core does not auto-delete.
 Memory hygiene is checked on every \`ComponentWriter\` cycle alongside component health. When budget or staleness thresholds are breached, a \`## MEMORY.md\` alert appears in HEARTBEAT.md under \`# Jeeves Platform Status\`. The alert includes character count, budget usage percentage, and any stale section names. When memory is healthy, the heading is absent — no alert content, no LLM cost on heartbeat polls.
 
 The \`## MEMORY.md\` heading follows the same declined/active lifecycle as component headings (\`## jeeves-{name}\`). Users can decline memory alerts by changing the heading to \`## MEMORY.md: declined\`.
+
+## Workspace File Size Monitoring
+
+OpenClaw applies a ~20,000-char injection limit to all workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, USER.md, MEMORY.md). Files exceeding the limit are silently truncated.
+
+Core monitors all five files on every \`ComponentWriter\` cycle:
+- Warning at 80% of budget (fixed threshold; not configurable via \`jeeves.config.json\`)
+- Over-budget alert when charCount exceeds the budget
+- Missing files are silently skipped
+
+### HEARTBEAT Integration
+
+When a workspace file exceeds the warning threshold, a \`## {filename}\` alert appears in HEARTBEAT.md (e.g., \`## AGENTS.md\`). The alert includes:
+- Character count, budget, and usage percentage
+- Trimming guidance in priority order: (1) move domain-specific content to a local skill, (2) extract reference material to companion files with a pointer, (3) summarize verbose instructions, (4) remove stale content
+
+Each file heading follows the same declined/active lifecycle as component headings. Users can decline alerts by changing the heading to \`## {filename}: declined\` (e.g., \`## AGENTS.md: declined\`).
 `;
 
 /**
@@ -843,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.
  *
@@ -919,16 +1113,18 @@ function patchAllowList(parent, key, label, pluginId, mode) {
  * Patch an OpenClaw config for plugin install or uninstall.
  *
  * @remarks
- * Manages `plugins.entries.{pluginId}` and `tools.alsoAllow`.
+ * Manages `plugins.entries.{pluginId}`, `plugins.installs.{pluginId}`,
+ * and `tools.alsoAllow`.
  * Idempotent: adding twice produces no duplicates; removing when absent
  * produces no errors.
  *
  * @param config - The parsed OpenClaw config object (mutated in place).
  * @param pluginId - The plugin identifier.
  * @param mode - Whether to add or remove the plugin.
+ * @param installRecord - Install provenance record (required when mode is 'add').
  * @returns Array of log messages describing changes made.
  */
-function patchConfig(config, pluginId, mode) {
+function patchConfig(config, pluginId, mode, installRecord) {
     const messages = [];
     // Ensure plugins section
     if (!config.plugins || typeof config.plugins !== 'object') {
@@ -950,6 +1146,24 @@ function patchConfig(config, pluginId, mode) {
         Reflect.deleteProperty(entries, pluginId);
         messages.push(`Removed "${pluginId}" from plugins.entries`);
     }
+    // plugins.installs
+    if (!plugins.installs || typeof plugins.installs !== 'object') {
+        plugins.installs = {};
+    }
+    const installs = plugins.installs;
+    if (mode === 'add' && installRecord) {
+        installs[pluginId] = {
+            source: 'path',
+            installPath: installRecord.installPath,
+            version: installRecord.version,
+            installedAt: installRecord.installedAt ?? new Date().toISOString(),
+        };
+        messages.push(`Wrote install record for "${pluginId}" to plugins.installs`);
+    }
+    else if (mode === 'remove' && pluginId in installs) {
+        Reflect.deleteProperty(installs, pluginId);
+        messages.push(`Removed install record for "${pluginId}" from plugins.installs`);
+    }
     // tools.alsoAllow
     if (!config.tools || typeof config.tools !== 'object') {
         config.tools = {};
@@ -1026,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`);
@@ -1042,23 +1261,38 @@ 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);
         // 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');
         // 2. Patch openclaw.json
         console.log('Patching OpenClaw config...');
         const config = readJsonFile(configPath);
-        const messages = patchConfig(config, pluginId, 'add');
+        const pkgJsonPathForVersion = join(extensionsDir, 'package.json');
+        let pluginVersionForRecord;
+        try {
+            const pkgJsonForRecord = readJsonFile(pkgJsonPathForVersion);
+            pluginVersionForRecord =
+                typeof pkgJsonForRecord.version === 'string'
+                    ? pkgJsonForRecord.version
+                    : undefined;
+        }
+        catch {
+            // best-effort: version may not be available yet
+        }
+        const messages = patchConfig(config, pluginId, 'add', {
+            installPath: extensionsDir,
+            version: pluginVersionForRecord,
+        });
         // 3. Memory slot claim
         if (opts.memory) {
             if (!config.agents || typeof config.agents !== 'object') {

package/dist/cli/service/index.js

@@ -696,6 +696,21 @@ function createServiceManager(descriptor) {
     }
 }
 
+/**
+ * Shared internal utility functions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extract a human-readable message from an unknown caught value.
+ *
+ * @param err - The caught value (typically `unknown`).
+ * @returns The error message string.
+ */
+function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Workspace-level shared configuration: `jeeves.config.json`.
  *
@@ -747,7 +762,13 @@ z.object({
     /** Memory hygiene shared defaults. */
     memory: workspaceMemoryConfigSchema.optional(),
 });
-/** Built-in workspace config defaults. */
+/**
+ * Built-in workspace config defaults.
+ *
+ * @remarks
+ * These defaults are used as the lowest-priority tier in config resolution
+ * (below CLI flags, env vars, and `jeeves.config.json` values).
+ */
 const WORKSPACE_CONFIG_DEFAULTS = {
     core: {
         workspace: '.',
@@ -773,6 +794,10 @@ const DEFAULT_CONFIG_ROOT = WORKSPACE_CONFIG_DEFAULTS.core.configRoot;
  * a component descriptor. Components add domain-specific commands
  * via `descriptor.customCliCommands`.
  */
+function handleCommandError(action, err) {
+    console.error(`${action} failed: ${getErrorMessage(err)}`);
+    process.exitCode = 1;
+}
 /**
  * Create a standard service CLI program from a component descriptor.
  *
@@ -825,8 +850,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Service unreachable: ${msg}`);
+            console.error(`Service unreachable: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -844,8 +868,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config query failed: ${msg}`);
+            console.error(`Config query failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -861,8 +884,7 @@ function createServiceCli(descriptor) {
             console.log('Config is valid.');
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Validation failed: ${msg}`);
+            console.error(`Validation failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -899,8 +921,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config apply failed: ${msg}`);
+            console.error(`Config apply failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -937,9 +958,7 @@ function createServiceCli(descriptor) {
             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;
+            handleCommandError('Install', err);
         }
     });
     serviceCmd
@@ -952,9 +971,7 @@ function createServiceCli(descriptor) {
             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;
+            handleCommandError('Uninstall', err);
         }
     });
     serviceCmd
@@ -967,9 +984,7 @@ function createServiceCli(descriptor) {
             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;
+            handleCommandError('Start', err);
         }
     });
     serviceCmd
@@ -982,9 +997,7 @@ function createServiceCli(descriptor) {
             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;
+            handleCommandError('Stop', err);
         }
     });
     serviceCmd
@@ -997,9 +1010,7 @@ function createServiceCli(descriptor) {
             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;
+            handleCommandError('Restart', err);
         }
     });
     serviceCmd
@@ -1012,9 +1023,7 @@ function createServiceCli(descriptor) {
             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;
+            handleCommandError('Status', err);
         }
     });
     // Apply custom CLI commands if provided