@karmaniverous/jeeves 0.4.0 → 0.4.1

package/dist/cli/plugin/index.js

@@ -0,0 +1,1003 @@
+#!/usr/bin/env node
+import { writeFileSync, renameSync, 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';
+import 'semver';
+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;
+
+/**
+ * Directory and file path conventions for the Jeeves platform.
+ */
+/** Core config directory name within the config root. */
+const CORE_CONFIG_DIR = 'jeeves-core';
+/** Default workspace file names. */
+const WORKSPACE_FILES = {
+    /** TOOLS.md — live platform state and component sections. */
+    tools: 'TOOLS.md',
+    /** SOUL.md — professional discipline and behavioral foundations. */
+    soul: 'SOUL.md',
+    /** AGENTS.md — operational protocols and memory architecture. */
+    agents: 'AGENTS.md',
+    /** HEARTBEAT.md — platform status and health alerts. */
+    heartbeat: 'HEARTBEAT.md',
+};
+/** Component versions state file name. */
+const COMPONENT_VERSIONS_FILE = 'component-versions.json';
+
+/**
+ * Core library version, inlined at build time.
+ *
+ * @remarks
+ * The `0.4.0` 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.0';
+
+/**
+ * Shared file I/O helpers for managed section operations.
+ *
+ * @remarks
+ * Extracts the atomic write pattern and file-level locking into
+ * reusable utilities, eliminating duplication between
+ * `updateManagedSection` and `removeManagedSection`.
+ */
+/** Stale lock threshold in ms (2 minutes). */
+const STALE_LOCK_MS = 120_000;
+/** Default core version when none provided. */
+const DEFAULT_CORE_VERSION = CORE_VERSION;
+/** Lock retry options. */
+const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+/**
+ * Write content to a file atomically via a temp file + rename.
+ *
+ * @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`);
+    writeFileSync(tempPath, content, 'utf-8');
+    renameSync(tempPath, filePath);
+}
+/**
+ * Execute a callback while holding a file lock.
+ *
+ * @remarks
+ * Acquires a lock on the file, executes the callback, and releases
+ * the lock in a finally block. The lock uses a 2-minute stale threshold
+ * and retries up to 5 times.
+ *
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withFileLock(filePath, fn) {
+    let release;
+    try {
+        release = await lock(filePath, {
+            stale: STALE_LOCK_MS,
+            retries: LOCK_RETRIES,
+        });
+        await fn();
+    }
+    finally {
+        if (release) {
+            try {
+                await release();
+            }
+            catch {
+                // Lock already released or file deleted — safe to ignore
+            }
+        }
+    }
+}
+
+/**
+ * Shared component version state file management.
+ *
+ * @remarks
+ * Each `ComponentWriter` cycle writes its component's entry to
+ * `{coreConfigDir}/component-versions.json`. The Platform Handlebars
+ * template reads this file to populate ALL rows in the service health
+ * table, not just the calling component's.
+ */
+/**
+ * Read the component versions state file.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @returns The parsed state, or an empty object if the file doesn't exist.
+ */
+function readComponentVersions(coreConfigDir) {
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Remove a component's version entry from the shared state file.
+ *
+ * @remarks
+ * Called during plugin uninstall to prevent the HEARTBEAT writer from
+ * probing a service that's intentionally gone. If the component isn't
+ * in the file, this is a no-op.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param componentName - The component name to remove.
+ */
+function removeComponentVersion(coreConfigDir, componentName) {
+    const existing = readComponentVersions(coreConfigDir);
+    if (!(componentName in existing))
+        return;
+    const updated = Object.fromEntries(Object.entries(existing).filter(([key]) => key !== componentName));
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    atomicWrite(filePath, JSON.stringify(updated, null, 2) + '\n');
+}
+
+/**
+ * Comment markers for managed content blocks.
+ *
+ * @remarks
+ * Managed content in TOOLS.md, SOUL.md, and AGENTS.md is enclosed
+ * in HTML comment markers. Content between markers is refreshed
+ * atomically on each writer cycle. User content outside the markers
+ * is never touched.
+ */
+/** Default markers for TOOLS.md managed block. */
+const TOOLS_MARKERS = {
+    /** BEGIN comment marker text. */
+    begin: 'BEGIN JEEVES PLATFORM TOOLS — DO NOT EDIT THIS SECTION',
+    /** END comment marker text. */
+    end: 'END JEEVES PLATFORM TOOLS',
+    /** H1 title prepended in section mode. */
+    title: 'Jeeves Platform Tools',
+    /** Managed block at bottom of file. */
+    position: 'bottom',
+};
+/**
+ * Regex pattern to extract version stamp from a BEGIN marker comment.
+ *
+ * @remarks
+ * Format: `\<!-- BEGIN MARKER | core:X.Y.Z | ISO-TIMESTAMP --\>`
+ * Captures: [1] marker text, [2] version, [3] timestamp
+ */
+const VERSION_STAMP_PATTERN = /<!--\s*(.+?)\s*\|\s*core:(\S+)\s*\|\s*(\S+)\s*-->/;
+
+/**
+ * Managed section IDs, stable ordering, and platform component registry.
+ *
+ * @remarks
+ * Section ordering is fixed to prevent diff churn regardless of which
+ * component writes last. Sections always appear in this order.
+ */
+/** Known section IDs for TOOLS.md managed block. */
+const SECTION_IDS = {
+    /** Platform health and guidance section. */
+    Platform: 'Platform',
+    /** Watcher index stats and search configuration. */
+    Watcher: 'Watcher',
+    /** Server export capabilities and connected services. */
+    Server: 'Server',
+    /** Runner job status and active scripts. */
+    Runner: 'Runner',
+    /** Meta synthesis entity summary and tools. */
+    Meta: 'Meta',
+};
+/**
+ * Stable ordering of sections within the managed TOOLS.md block.
+ * Sections always appear in this order regardless of write order.
+ */
+const SECTION_ORDER = [
+    SECTION_IDS.Platform,
+    SECTION_IDS.Watcher,
+    SECTION_IDS.Server,
+    SECTION_IDS.Runner,
+    SECTION_IDS.Meta,
+];
+
+/**
+ * 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
+ */
+let state;
+/**
+ * Initialize the core library with workspace and config root paths.
+ *
+ * @param options - Workspace and config root paths.
+ */
+function init(options) {
+    state = {
+        workspacePath: options.workspacePath,
+        configRoot: options.configRoot,
+        coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+    };
+}
+/**
+ * Get the core config directory path.
+ *
+ * @throws Error if `init()` has not been called.
+ */
+function getCoreConfigDir() {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.coreConfigDir;
+}
+
+/**
+ * Heading-based HEARTBEAT section writer.
+ *
+ * @remarks
+ * Manages the `# Jeeves Platform Status` section in HEARTBEAT.md.
+ * Unlike TOOLS/SOUL/AGENTS (which use HTML comment markers), HEARTBEAT
+ * uses markdown headings as markers — this ensures the file passes
+ * OpenClaw's heartbeat emptiness check when only headings remain.
+ *
+ * The section is always at the bottom of the file (H1 to EOF).
+ * User heartbeat items above the section are preserved.
+ */
+/** The H1 heading that anchors the platform status section. */
+const HEARTBEAT_HEADING = '# Jeeves Platform Status';
+/**
+ * Parse the HEARTBEAT.md file content.
+ *
+ * @param fileContent - Full file content.
+ * @returns Parsed result with user zone and component entries.
+ */
+function parseHeartbeat(fileContent) {
+    const headingIndex = fileContent.indexOf(HEARTBEAT_HEADING);
+    if (headingIndex === -1) {
+        return {
+            userContent: fileContent.trim(),
+            found: false,
+            entries: [],
+        };
+    }
+    const userContent = fileContent.slice(0, headingIndex).trim();
+    const sectionContent = fileContent.slice(headingIndex + HEARTBEAT_HEADING.length);
+    const entries = [];
+    const h2Re = /^## (jeeves-\S+?)(?:: declined)?$/gm;
+    let match;
+    const h2Positions = [];
+    while ((match = h2Re.exec(sectionContent)) !== null) {
+        const fullHeading = match[0];
+        const name = match[1];
+        const declined = fullHeading.endsWith(': declined');
+        h2Positions.push({ name, declined, start: match.index });
+    }
+    for (let i = 0; i < h2Positions.length; i++) {
+        const pos = h2Positions[i];
+        const headingLine = pos.declined
+            ? `## ${pos.name}: declined`
+            : `## ${pos.name}`;
+        const contentStart = pos.start + headingLine.length;
+        const contentEnd = i + 1 < h2Positions.length
+            ? h2Positions[i + 1].start
+            : sectionContent.length;
+        const content = sectionContent.slice(contentStart, contentEnd).trim();
+        entries.push({
+            name: pos.name,
+            declined: pos.declined,
+            content,
+        });
+    }
+    return { userContent, found: true, entries };
+}
+/**
+ * Build the HEARTBEAT section content from entries.
+ *
+ * @param entries - Component entries to write.
+ * @returns The full section string (H1 + H2s).
+ */
+function buildHeartbeatSection(entries) {
+    const parts = [HEARTBEAT_HEADING];
+    for (const entry of entries) {
+        if (entry.declined) {
+            parts.push(`## ${entry.name}: declined`);
+        }
+        else if (entry.content) {
+            parts.push(`## ${entry.name}`);
+            parts.push(entry.content);
+        }
+        // Healthy components (no content, not declined) get no H2 section
+    }
+    return parts.join('\n');
+}
+
+/**
+ * Stable section ordering for managed TOOLS.md blocks.
+ *
+ * @remarks
+ * Sorts sections by the canonical SECTION_ORDER: known sections
+ * appear in their defined order, unknown sections are appended after.
+ * Used by both parseManaged (for consistent output) and
+ * updateManagedSection (for reassembly).
+ */
+/**
+ * Sort sections in place by stable ordering.
+ *
+ * @param sections - Array of managed sections to sort.
+ * @returns The sorted array (same reference, mutated in place).
+ */
+function sortSectionsByOrder(sections) {
+    return sections.sort((a, b) => {
+        const aIdx = SECTION_ORDER.indexOf(a.id);
+        const bIdx = SECTION_ORDER.indexOf(b.id);
+        const aOrder = aIdx === -1 ? SECTION_ORDER.length : aIdx;
+        const bOrder = bIdx === -1 ? SECTION_ORDER.length : bIdx;
+        return aOrder - bOrder;
+    });
+}
+
+/**
+ * Parse managed block from file content.
+ *
+ * @remarks
+ * Extracts managed content delimited by comment markers, parses H2
+ * sections within the block, and returns the structured result plus
+ * user content outside the markers.
+ */
+/**
+ * Build regex patterns for the given markers.
+ *
+ * @param markers - Begin/end marker strings.
+ * @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'),
+    };
+}
+/**
+ * Parse H2 sections from managed block content.
+ *
+ * @param content - Raw managed block content.
+ * @returns Array of parsed sections in stable order.
+ */
+function parseSections(content) {
+    const lines = content.split('\n');
+    const sections = [];
+    let currentId;
+    let currentLines = [];
+    for (const line of lines) {
+        const h2Match = /^## (.+)$/.exec(line);
+        if (h2Match) {
+            if (currentId !== undefined) {
+                sections.push({
+                    id: currentId,
+                    content: currentLines.join('\n').trim(),
+                });
+            }
+            currentId = h2Match[1];
+            currentLines = [];
+        }
+        else if (currentId !== undefined) {
+            currentLines.push(line);
+        }
+    }
+    if (currentId !== undefined) {
+        sections.push({
+            id: currentId,
+            content: currentLines.join('\n').trim(),
+        });
+    }
+    return sortSectionsByOrder(sections);
+}
+/**
+ * Parse a managed block from file content.
+ *
+ * @param fileContent - Full file content.
+ * @param markers - Optional custom markers (defaults to TOOLS markers).
+ * @returns Parsed result with sections, version stamp, and user content.
+ */
+function parseManaged(fileContent, markers = TOOLS_MARKERS) {
+    const { beginRe, endRe } = buildMarkerPatterns(markers);
+    const beginMatch = beginRe.exec(fileContent);
+    if (!beginMatch) {
+        return {
+            found: false,
+            versionStamp: undefined,
+            managedContent: '',
+            sections: [],
+            beforeContent: '',
+            userContent: fileContent,
+        };
+    }
+    const endMatch = endRe.exec(fileContent.slice(beginMatch.index + beginMatch[0].length));
+    if (!endMatch) {
+        // Corrupt: BEGIN without END — treat as fresh file
+        return {
+            found: false,
+            versionStamp: undefined,
+            managedContent: '',
+            sections: [],
+            beforeContent: '',
+            userContent: fileContent,
+        };
+    }
+    const beforeContent = fileContent.slice(0, beginMatch.index).trim();
+    const managedStart = beginMatch.index + beginMatch[0].length;
+    const managedEnd = managedStart + endMatch.index;
+    const managedContent = fileContent.slice(managedStart, managedEnd).trim();
+    const afterEnd = managedStart + endMatch.index + endMatch[0].length;
+    const userContent = fileContent.slice(afterEnd).trim();
+    // Extract version stamp from BEGIN marker line
+    let versionStamp;
+    const stampMatch = VERSION_STAMP_PATTERN.exec(beginMatch[0]);
+    if (stampMatch?.[2] && stampMatch[3]) {
+        versionStamp = {
+            version: stampMatch[2],
+            timestamp: stampMatch[3],
+        };
+    }
+    const sections = parseSections(managedContent);
+    return {
+        found: true,
+        versionStamp,
+        managedContent,
+        sections,
+        beforeContent,
+        userContent,
+    };
+}
+
+/**
+ * Version-stamp parsing and convergence logic.
+ *
+ * @remarks
+ * When multiple component plugins bundle different core library versions,
+ * they independently maintain shared managed content. The version-stamp
+ * mechanism ensures convergence without coordination state.
+ */
+/**
+ * Format the BEGIN marker comment with a version stamp.
+ *
+ * @param markerText - The marker text (e.g., 'BEGIN JEEVES PLATFORM TOOLS').
+ * @param version - The core library version.
+ * @returns Formatted comment line.
+ */
+function formatBeginMarker(markerText, version) {
+    const timestamp = new Date().toISOString();
+    return `<!-- ${markerText} | core:${version} | ${timestamp} -->`;
+}
+/**
+ * Format the END marker comment.
+ *
+ * @param markerText - The marker text (e.g., 'END JEEVES PLATFORM TOOLS').
+ * @returns Formatted comment line.
+ */
+function formatEndMarker(markerText) {
+    return `<!-- ${markerText} -->`;
+}
+
+/**
+ * Remove a managed section or entire managed block from a file.
+ *
+ * @remarks
+ * Supports two modes:
+ * - No `sectionId`: Remove the entire managed block (markers + content),
+ *   leaving user content intact.
+ * - With `sectionId`: Remove a specific H2 section from within the
+ *   managed block. If it was the last section, remove the entire block.
+ *
+ * Provides file-level locking and atomic writes (temp file + rename).
+ * Missing markers or nonexistent sections are no-ops (no error thrown).
+ */
+/**
+ * Remove a managed section or entire managed block from a file.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param options - Optional section ID and custom markers.
+ */
+async function removeManagedSection(filePath, options = {}) {
+    const { sectionId, markers = TOOLS_MARKERS } = options;
+    if (!existsSync(filePath))
+        return;
+    await withFileLock(filePath, () => {
+        const fileContent = readFileSync(filePath, 'utf-8');
+        const parsed = parseManaged(fileContent, markers);
+        if (!parsed.found)
+            return;
+        let newContent;
+        if (!sectionId) {
+            // Remove entire managed block
+            newContent = buildWithoutBlock(parsed.beforeContent, parsed.userContent);
+        }
+        else {
+            // Remove specific section
+            const remaining = parsed.sections.filter((s) => s.id !== sectionId);
+            if (remaining.length === parsed.sections.length) {
+                // Section not found — no-op
+                return;
+            }
+            if (remaining.length === 0) {
+                // Last section removed — remove entire block
+                newContent = buildWithoutBlock(parsed.beforeContent, parsed.userContent);
+            }
+            else {
+                // Rebuild managed block without the removed section
+                newContent = buildWithSections(parsed.beforeContent, parsed.userContent, remaining, markers, parsed.versionStamp?.version);
+            }
+        }
+        atomicWrite(filePath, newContent);
+    });
+}
+/** Build file content without the managed block. */
+function buildWithoutBlock(beforeContent, userContent) {
+    const parts = [];
+    if (beforeContent)
+        parts.push(beforeContent);
+    if (userContent) {
+        if (parts.length > 0)
+            parts.push('');
+        parts.push(userContent);
+    }
+    if (parts.length === 0)
+        return '';
+    return parts.join('\n') + '\n';
+}
+/** Rebuild file content with remaining sections. */
+function buildWithSections(beforeContent, userContent, sections, markers, coreVersion) {
+    const sorted = sortSectionsByOrder([...sections]);
+    const sectionText = sorted
+        .map((s) => `## ${s.id}\n\n${s.content}`)
+        .join('\n\n');
+    const managedBody = markers.title
+        ? `# ${markers.title}\n\n${sectionText}`
+        : sectionText;
+    const beginLine = formatBeginMarker(markers.begin, coreVersion ?? DEFAULT_CORE_VERSION);
+    const endLine = formatEndMarker(markers.end);
+    const parts = [];
+    if (beforeContent) {
+        parts.push(beforeContent);
+        parts.push('');
+    }
+    parts.push(beginLine);
+    parts.push('');
+    parts.push(managedBody);
+    parts.push('');
+    parts.push(endLine);
+    if (userContent) {
+        parts.push('');
+        parts.push(userContent);
+    }
+    parts.push('');
+    return parts.join('\n');
+}
+
+/**
+ * OpenClaw configuration helpers for plugin CLI installers.
+ *
+ * @remarks
+ * Provides resolution of OpenClaw home directory and config file path,
+ * plus idempotent config patching for plugin install/uninstall.
+ */
+/**
+ * Resolve the OpenClaw home directory.
+ *
+ * @remarks
+ * Resolution order:
+ * 1. `OPENCLAW_CONFIG` env var → dirname of the config file path
+ * 2. `OPENCLAW_HOME` env var → resolved path
+ * 3. Default: `~/.openclaw`
+ *
+ * @returns Absolute path to the OpenClaw home directory.
+ */
+function resolveOpenClawHome() {
+    if (process.env.OPENCLAW_CONFIG) {
+        return dirname(resolve(process.env.OPENCLAW_CONFIG));
+    }
+    if (process.env.OPENCLAW_HOME) {
+        return resolve(process.env.OPENCLAW_HOME);
+    }
+    return join(homedir(), '.openclaw');
+}
+/**
+ * Resolve the OpenClaw config file path.
+ *
+ * @remarks
+ * If `OPENCLAW_CONFIG` is set, uses that directly.
+ * Otherwise defaults to `{home}/openclaw.json`.
+ *
+ * @param home - The OpenClaw home directory.
+ * @returns Absolute path to the config file.
+ */
+function resolveConfigPath(home) {
+    if (process.env.OPENCLAW_CONFIG) {
+        return resolve(process.env.OPENCLAW_CONFIG);
+    }
+    return join(home, 'openclaw.json');
+}
+/**
+ * Patch an allowlist array: add or remove the plugin ID.
+ *
+ * @returns A log message if a change was made, or undefined.
+ */
+function patchAllowList(parent, key, label, pluginId, mode) {
+    if (mode === 'add') {
+        if (!Array.isArray(parent[key])) {
+            parent[key] = [pluginId];
+            return `Created ${label} with "${pluginId}"`;
+        }
+        const list = parent[key];
+        if (!list.includes(pluginId)) {
+            list.push(pluginId);
+            return `Added "${pluginId}" to ${label}`;
+        }
+    }
+    else {
+        if (!Array.isArray(parent[key]))
+            return undefined;
+        const list = parent[key];
+        const filtered = list.filter((id) => id !== pluginId);
+        if (filtered.length !== list.length) {
+            parent[key] = filtered;
+            return `Removed "${pluginId}" from ${label}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Patch an OpenClaw config for plugin install or uninstall.
+ *
+ * @remarks
+ * Manages `plugins.entries.{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.
+ * @returns Array of log messages describing changes made.
+ */
+function patchConfig(config, pluginId, mode) {
+    const messages = [];
+    // Ensure plugins section
+    if (!config.plugins || typeof config.plugins !== 'object') {
+        config.plugins = {};
+    }
+    const plugins = config.plugins;
+    // plugins.entries
+    if (!plugins.entries || typeof plugins.entries !== 'object') {
+        plugins.entries = {};
+    }
+    const entries = plugins.entries;
+    if (mode === 'add') {
+        if (!entries[pluginId]) {
+            entries[pluginId] = { enabled: true };
+            messages.push(`Added "${pluginId}" to plugins.entries`);
+        }
+    }
+    else if (pluginId in entries) {
+        Reflect.deleteProperty(entries, pluginId);
+        messages.push(`Removed "${pluginId}" from plugins.entries`);
+    }
+    // tools.alsoAllow
+    if (!config.tools || typeof config.tools !== 'object') {
+        config.tools = {};
+    }
+    const tools = config.tools;
+    const toolAlsoAllow = patchAllowList(tools, 'alsoAllow', 'tools.alsoAllow', pluginId, mode);
+    if (toolAlsoAllow)
+        messages.push(toolAlsoAllow);
+    return messages;
+}
+
+/**
+ * Factory for the standard `-openclaw` plugin installer CLI.
+ *
+ * @remarks
+ * Produces a Commander program with `install` and `uninstall` commands
+ * that handle the full plugin lifecycle: copy dist to extensions,
+ * patch OpenClaw config, manage HEARTBEAT entries, and clean up
+ * managed sections on uninstall.
+ */
+/**
+ * Derive a component name from a plugin ID.
+ *
+ * @remarks
+ * Strips `jeeves-` prefix and `-openclaw` suffix.
+ *
+ * @param pluginId - The plugin identifier.
+ * @returns Component short name.
+ */
+function deriveComponentName(pluginId) {
+    return pluginId.replace(/^jeeves-/, '').replace(/-openclaw$/, '');
+}
+/**
+ * Copy all files from source directory to destination.
+ *
+ * @param srcDir - Source directory.
+ * @param destDir - Destination directory.
+ */
+function copyDistFiles(srcDir, destDir) {
+    mkdirSync(destDir, { recursive: true });
+    const entries = readdirSync(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(srcDir, entry.name);
+        const destPath = join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDistFiles(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+/**
+ * Read and parse a JSON file, returning an empty object if not found.
+ *
+ * @param filePath - Path to the JSON file.
+ * @returns Parsed object.
+ */
+function readJsonFile(filePath) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Create a standard plugin installer CLI program.
+ *
+ * @param options - Plugin CLI configuration.
+ * @returns A Commander program ready for `.parse()`.
+ */
+function createPluginCli(options) {
+    const { pluginId, distDir, pluginPackage, configRoot = 'j:/config', } = options;
+    const componentName = options.componentName ?? deriveComponentName(pluginId);
+    const program = new Command()
+        .name(pluginPackage)
+        .description(`Jeeves ${componentName} plugin installer`);
+    program
+        .command('install')
+        .description(`Install the ${componentName} plugin`)
+        .option('--memory', 'Claim a memory slot for this plugin')
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('-c, --config-root <path>', 'Platform config root path', configRoot)
+        .action((opts) => {
+        const openClawHome = resolveOpenClawHome();
+        const configPath = resolveConfigPath(openClawHome);
+        // 1. Copy dist to extensions
+        const extensionsDir = join(openClawHome, 'extensions', pluginId);
+        console.log(`Copying dist to ${extensionsDir}...`);
+        copyDistFiles(distDir, extensionsDir);
+        console.log('  ✓ Dist files copied');
+        // 2. Patch openclaw.json
+        console.log('Patching OpenClaw config...');
+        const config = readJsonFile(configPath);
+        const messages = patchConfig(config, pluginId, 'add');
+        // 3. Memory slot claim
+        if (opts.memory) {
+            if (!config.agents || typeof config.agents !== 'object') {
+                config.agents = {};
+            }
+            const agents = config.agents;
+            if (!agents.defaults || typeof agents.defaults !== 'object') {
+                agents.defaults = {};
+            }
+            const defaults = agents.defaults;
+            if (!defaults.memory || typeof defaults.memory !== 'object') {
+                defaults.memory = {};
+            }
+            const memory = defaults.memory;
+            if (!memory[componentName]) {
+                memory[componentName] = {};
+                messages.push(`Claimed memory slot for "${componentName}"`);
+            }
+        }
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+        for (const msg of messages) {
+            console.log(`  ✓ ${msg}`);
+        }
+        // 4. Write initial HEARTBEAT entry
+        try {
+            const cfgRoot = opts.configRoot;
+            const agents = config.agents;
+            const defaults = agents?.defaults;
+            const ws = opts.workspace ?? defaults?.workspace;
+            if (ws) {
+                init({ workspacePath: ws, configRoot: cfgRoot });
+                const heartbeatPath = join(ws, WORKSPACE_FILES.heartbeat);
+                try {
+                    const existing = existsSync(heartbeatPath)
+                        ? readFileSync(heartbeatPath, 'utf-8')
+                        : '';
+                    const parsed = parseHeartbeat(existing);
+                    const fullName = `jeeves-${componentName}`;
+                    // Only add if not already present
+                    const hasEntry = parsed.entries.some((e) => e.name === fullName);
+                    if (!hasEntry) {
+                        parsed.entries.push({
+                            name: fullName,
+                            declined: false,
+                            content: `- Plugin installed. Awaiting service configuration.`,
+                        });
+                        const section = buildHeartbeatSection(parsed.entries);
+                        atomicWrite(heartbeatPath, section);
+                        console.log('  ✓ HEARTBEAT entry written');
+                    }
+                }
+                catch {
+                    console.log('  ⚠ Could not write HEARTBEAT entry');
+                }
+            }
+        }
+        catch {
+            // HEARTBEAT is best-effort during install
+        }
+        console.log();
+        console.log(`✅ ${pluginPackage} installed.`);
+    });
+    program
+        .command('uninstall')
+        .description(`Uninstall the ${componentName} plugin`)
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('-c, --config-root <path>', 'Platform config root path', configRoot)
+        .action(async (opts) => {
+        const openClawHome = resolveOpenClawHome();
+        const cfgPath = resolveConfigPath(openClawHome);
+        // 1. Remove from extensions
+        const extensionsDir = join(openClawHome, 'extensions', pluginId);
+        if (existsSync(extensionsDir)) {
+            rmSync(extensionsDir, { recursive: true, force: true });
+            console.log('  ✓ Extension files removed');
+        }
+        // 2. Unpatch openclaw.json
+        if (existsSync(cfgPath)) {
+            const config = readJsonFile(cfgPath);
+            const messages = patchConfig(config, pluginId, 'remove');
+            writeFileSync(cfgPath, JSON.stringify(config, null, 2) + '\n');
+            for (const msg of messages) {
+                console.log(`  ✓ ${msg}`);
+            }
+        }
+        // 3. Remove TOOLS.md section
+        try {
+            const cfgRoot = opts.configRoot;
+            const ws = opts.workspace;
+            if (ws) {
+                init({ workspacePath: ws, configRoot: cfgRoot });
+                const sectionId = componentName.charAt(0).toUpperCase() + componentName.slice(1);
+                const toolsPath = join(ws, WORKSPACE_FILES.tools);
+                if (existsSync(toolsPath)) {
+                    await removeManagedSection(toolsPath, {
+                        sectionId,
+                        markers: TOOLS_MARKERS,
+                    });
+                    console.log('  ✓ TOOLS.md section removed');
+                }
+            }
+        }
+        catch {
+            console.log('  ⚠ Could not remove TOOLS.md section');
+        }
+        // 4. Remove component-versions.json entry
+        try {
+            const cfgRoot = opts.configRoot;
+            init({
+                workspacePath: opts.workspace ?? '.',
+                configRoot: cfgRoot,
+            });
+            removeComponentVersion(getCoreConfigDir(), componentName);
+            console.log('  ✓ Component version entry removed');
+        }
+        catch {
+            console.log('  ⚠ Could not remove component version entry');
+        }
+        console.log();
+        console.log(`✅ ${pluginPackage} uninstalled.`);
+    });
+    return program;
+}
+
+export { createPluginCli };