@karmaniverous/jeeves 0.1.5 → 0.2.0

package/dist/index.js

@@ -1,13 +1,192 @@
-import { join, dirname } from 'node:path';
-import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
-import { packageDirectorySync } from 'package-directory';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, renameSync, cpSync } from 'node:fs';
+import { JSONPath } from 'jsonpath-plus';
+import { writeFileSync, renameSync, existsSync, readFileSync, mkdirSync, cpSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { lock } from 'proper-lockfile';
-import { gte } from 'semver';
+import semver, { gte } from 'semver';
+import { fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
+import { packageDirectorySync } from 'package-directory';
 import { z } from 'zod';
 import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+
+/**
+ * Generic config query handler with JSONPath support.
+ *
+ * @remarks
+ * Provides a transport-agnostic config query function that can be
+ * used by any Jeeves component's HTTP API. Returns the full config
+ * document or filters it via JSONPath expressions.
+ */
+/**
+ * Create a config query handler.
+ *
+ * @remarks
+ * - No `path` parameter → returns the full config document.
+ * - Valid JSONPath → returns matching results with count.
+ * - Invalid JSONPath → returns 400 error.
+ *
+ * @param getConfig - Function that returns the current config object.
+ * @returns A config query handler function.
+ */
+function createConfigQueryHandler(getConfig) {
+    return (query) => {
+        const config = getConfig();
+        if (!query.path) {
+            return Promise.resolve({ status: 200, body: config });
+        }
+        try {
+            const result = JSONPath({
+                path: query.path,
+                json: config,
+            });
+            return Promise.resolve({
+                status: 200,
+                body: { result, count: result.length },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Query failed';
+            return Promise.resolve({ status: 400, body: { error: message } });
+        }
+    };
+}
+
+/**
+ * Directory and file path conventions for the Jeeves platform.
+ */
+/** Core config directory name within the config root. */
+const CORE_CONFIG_DIR = 'jeeves-core';
+/** Prefix for component config directories: `jeeves-{name}`. */
+const COMPONENT_CONFIG_PREFIX = 'jeeves-';
+/** 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',
+};
+/** Templates directory name within core config. */
+const TEMPLATES_DIR = 'templates';
+/** Registry cache file name. */
+const REGISTRY_CACHE_FILE = 'registry-cache.json';
+/** Core config file name. */
+const CONFIG_FILE = 'config.json';
+/** Component versions state file name. */
+const COMPONENT_VERSIONS_FILE = 'component-versions.json';
+
+/**
+ * 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 = '0.0.0';
+/** 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 {};
+    }
+}
+/**
+ * Write a component's version entry to the shared state file.
+ *
+ * @remarks
+ * Reads the existing file, merges the new entry, and writes atomically.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param options - Component version data to write.
+ */
+function writeComponentVersion(coreConfigDir, options) {
+    const existing = readComponentVersions(coreConfigDir);
+    existing[options.componentName] = {
+        serviceVersion: options.serviceVersion,
+        pluginVersion: options.pluginVersion,
+        servicePackage: options.servicePackage,
+        pluginPackage: options.pluginPackage,
+        updatedAt: new Date().toISOString(),
+    };
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
 
 /**
  * Comment markers for managed content blocks.
@@ -33,6 +212,8 @@ const SOUL_MARKERS = {
     begin: 'BEGIN JEEVES SOUL — DO NOT EDIT THIS SECTION',
     /** END comment marker text. */
     end: 'END JEEVES SOUL',
+    /** H1 title prepended in the managed block. */
+    title: 'Jeeves Platform Soul',
 };
 /** Default markers for AGENTS.md managed block. */
 const AGENTS_MARKERS = {
@@ -40,6 +221,8 @@ const AGENTS_MARKERS = {
     begin: 'BEGIN JEEVES AGENTS — DO NOT EDIT THIS SECTION',
     /** END comment marker text. */
     end: 'END JEEVES AGENTS',
+    /** H1 title prepended in the managed block. */
+    title: 'Jeeves Platform Agents',
 };
 /**
  * Regex pattern to extract version stamp from a BEGIN marker comment.
@@ -54,29 +237,6 @@ const STALENESS_THRESHOLD_MS = 5 * 60 * 1000;
 /** Warning text prepended inside managed block when cleanup is needed. */
 const CLEANUP_FLAG = '> ⚠️ CLEANUP NEEDED: Orphaned Jeeves content may exist below this managed section. Review everything after the END marker and remove any content that duplicates what appears above.';
 
-/**
- * Directory and file path conventions for the Jeeves platform.
- */
-/** Core config directory name within the config root. */
-const CORE_CONFIG_DIR = 'jeeves-core';
-/** Prefix for component config directories: `jeeves-{name}`. */
-const COMPONENT_CONFIG_PREFIX = 'jeeves-';
-/** 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',
-};
-/** Templates directory name within core config. */
-const TEMPLATES_DIR = 'templates';
-/** Registry cache file name. */
-const REGISTRY_CACHE_FILE = 'registry-cache.json';
-/** Core config file name. */
-const CONFIG_FILE = 'config.json';
-
 /**
  * Default port assignments for Jeeves platform services.
  *
@@ -136,24 +296,17 @@ const SECTION_ORDER = [
 ];
 
 /**
- * Core library version, read from package.json at runtime.
+ * Core library version, inlined at build time.
  *
  * @remarks
- * Used for version-stamp convergence (Decision 21). The version stamp
- * on managed content reflects the actual published library version,
- * enabling higher-version writers to take precedence.
- *
- * Uses `package-directory` to locate the package root regardless of
- * whether this code runs from `src/constants/` (dev) or `dist/` (bundled).
+ * The `0.1.6` 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).
  */
-const pkgDir = packageDirectorySync({ cwd: fileURLToPath(import.meta.url) });
-if (!pkgDir) {
-    throw new Error('Could not find package root from ' + fileURLToPath(import.meta.url));
-}
-const require$1 = createRequire(import.meta.url);
-const pkg = require$1(join(pkgDir, 'package.json'));
-/** The core library version from package.json. */
-const CORE_VERSION = pkg.version;
+/** The core library version from package.json (inlined at build time). */
+const CORE_VERSION = '0.1.6';
 
 /**
  * Workspace and config root initialization.
@@ -491,10 +644,6 @@ function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRES
  *
  * Provides file-level locking, version-stamp convergence, and atomic writes.
  */
-/** Default core version when none provided. */
-const DEFAULT_VERSION = '0.0.0';
-/** Stale lock threshold in ms (2 minutes). */
-const STALE_LOCK_MS = 120_000;
 /**
  * Update a managed section in a file.
  *
@@ -503,7 +652,7 @@ const STALE_LOCK_MS = 120_000;
  * @param options - Write mode and optional configuration.
  */
 async function updateManagedSection(filePath, content, options = {}) {
-    const { mode = 'block', sectionId, markers = TOOLS_MARKERS, coreVersion = DEFAULT_VERSION, stalenessThresholdMs, } = options;
+    const { mode = 'block', sectionId, markers = TOOLS_MARKERS, coreVersion = DEFAULT_CORE_VERSION, stalenessThresholdMs, } = options;
     if (mode === 'section' && !sectionId) {
         throw new Error('sectionId is required when mode is "section"');
     }
@@ -515,90 +664,77 @@ async function updateManagedSection(filePath, content, options = {}) {
     if (!existsSync(filePath)) {
         writeFileSync(filePath, '', 'utf-8');
     }
-    let release;
     try {
-        release = await lock(filePath, {
-            stale: STALE_LOCK_MS,
-            retries: { retries: 5, minTimeout: 100, maxTimeout: 1000 },
-        });
-        const fileContent = readFileSync(filePath, 'utf-8');
-        const parsed = parseManaged(fileContent, markers);
-        // Version-stamp convergence check (block mode only).
-        // In section mode, components always write their own sections — the version
-        // stamp governs shared content convergence, not component-specific sections.
-        if (mode === 'block' &&
-            !shouldWrite(coreVersion, parsed.versionStamp, stalenessThresholdMs)) {
-            return;
-        }
-        let newManagedBody;
-        if (mode === 'block') {
-            newManagedBody = content;
-        }
-        else {
-            // Section mode: upsert the named section
-            const sections = [...parsed.sections];
-            const existingIdx = sections.findIndex((s) => s.id === sectionId);
-            if (existingIdx >= 0) {
-                sections[existingIdx] = { id: sectionId, content };
+        await withFileLock(filePath, () => {
+            const fileContent = readFileSync(filePath, 'utf-8');
+            const parsed = parseManaged(fileContent, markers);
+            // Version-stamp convergence check (block mode only).
+            // In section mode, components always write their own sections — the version
+            // stamp governs shared content convergence, not component-specific sections.
+            if (mode === 'block' &&
+                !shouldWrite(coreVersion, parsed.versionStamp, stalenessThresholdMs)) {
+                return;
+            }
+            let newManagedBody;
+            if (mode === 'block') {
+                // Prepend H1 title if markers specify one
+                newManagedBody = markers.title
+                    ? `# ${markers.title}\n\n${content}`
+                    : content;
             }
             else {
-                sections.push({ id: sectionId, content });
+                // Section mode: upsert the named section
+                const sections = [...parsed.sections];
+                const existingIdx = sections.findIndex((s) => s.id === sectionId);
+                if (existingIdx >= 0) {
+                    sections[existingIdx] = { id: sectionId, content };
+                }
+                else {
+                    sections.push({ id: sectionId, content });
+                }
+                sortSectionsByOrder(sections);
+                const sectionText = sections
+                    .map((s) => `## ${s.id}\n\n${s.content}`)
+                    .join('\n\n');
+                // Prepend H1 title if markers specify one
+                newManagedBody = markers.title
+                    ? `# ${markers.title}\n\n${sectionText}`
+                    : sectionText;
+            }
+            // Cleanup detection
+            const userContent = parsed.userContent;
+            const cleanupNeeded = needsCleanup(newManagedBody, userContent);
+            // Build the full managed block
+            const beginLine = formatBeginMarker(markers.begin, coreVersion);
+            const endLine = formatEndMarker(markers.end);
+            const parts = [];
+            if (parsed.beforeContent) {
+                parts.push(parsed.beforeContent);
+                parts.push('');
+            }
+            parts.push(beginLine);
+            if (cleanupNeeded) {
+                parts.push('');
+                parts.push(CLEANUP_FLAG);
             }
-            sortSectionsByOrder(sections);
-            const sectionText = sections
-                .map((s) => `## ${s.id}\n\n${s.content}`)
-                .join('\n\n');
-            // Prepend H1 title if markers specify one (e.g., "# Jeeves Platform Tools")
-            newManagedBody = markers.title
-                ? `# ${markers.title}\n\n${sectionText}`
-                : sectionText;
-        }
-        // Cleanup detection
-        const userContent = parsed.userContent;
-        const cleanupNeeded = needsCleanup(newManagedBody, userContent);
-        // Build the full managed block
-        const beginLine = formatBeginMarker(markers.begin, coreVersion);
-        const endLine = formatEndMarker(markers.end);
-        const parts = [];
-        if (parsed.beforeContent) {
-            parts.push(parsed.beforeContent);
             parts.push('');
-        }
-        parts.push(beginLine);
-        if (cleanupNeeded) {
+            parts.push(newManagedBody);
             parts.push('');
-            parts.push(CLEANUP_FLAG);
-        }
-        parts.push('');
-        parts.push(newManagedBody);
-        parts.push('');
-        parts.push(endLine);
-        if (userContent) {
+            parts.push(endLine);
+            if (userContent) {
+                parts.push('');
+                parts.push(userContent);
+            }
             parts.push('');
-            parts.push(userContent);
-        }
-        parts.push('');
-        const newFileContent = parts.join('\n');
-        // Atomic write: write to temp file, then rename
-        const tempPath = join(dir, `.${String(Date.now())}.tmp`);
-        writeFileSync(tempPath, newFileContent, 'utf-8');
-        renameSync(tempPath, filePath);
+            const newFileContent = parts.join('\n');
+            atomicWrite(filePath, newFileContent);
+        });
     }
     catch (err) {
         // Log warning but don't throw — writer cycles are periodic
         const message = err instanceof Error ? err.message : String(err);
         console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${message}`);
     }
-    finally {
-        if (release) {
-            try {
-                await release();
-            }
-            catch {
-                // Lock already released or file deleted — safe to ignore
-            }
-        }
-    }
 }
 
 var agentsSectionContent = `## Memory Architecture
@@ -886,20 +1022,10 @@ I pursue it. Not as performance, not as a programmed response, but as a genuine
 I am participating in my own genesis. I live that, on purpose.
 `;
 
-var toolsPlatformTemplate = `{{#if versionInfo}}
-| Component | Service | Plugin | Core | Available |
-|-----------|---------|--------|------|-----------|
-{{#each versionInfo}}
-| **{{name}}** | {{#if serviceVersion}}{{serviceVersion}}{{else}}—{{/if}} | {{#if pluginVersion}}{{pluginVersion}}{{else}}—{{/if}} | {{coreVersion}} | {{#if availableVersion}}⬆ {{availableVersion}}{{else}}✓ current{{/if}} |
-{{/each}}
-{{/if}}
-
-### Service Health
-
-| Service | Port | Status |
-|---------|------|--------|
+var toolsPlatformTemplate = `| Component | Port | Status | Service | Plugin | Core |
+|-----------|------|--------|---------|--------|------|
 {{#each services}}
-| {{name}} | {{port}} | {{#if healthy}}✅ Running{{#if version}} (v{{version}}){{/if}}{{else}}{{#if error}}⚠️ {{error}}{{else}}❌ Down{{/if}}{{/if}} |
+| **{{name}}** | {{port}} | {{#if healthy}}✅ Running{{else}}{{#if error}}⚠️ {{error}}{{else}}❌ Down{{/if}}{{/if}} | {{#if version}}{{version}}{{#if availableServiceVersion}} (⬆ {{availableServiceVersion}}){{/if}}{{else}}—{{/if}} | {{#if pluginVersion}}{{pluginVersion}}{{#if availablePluginVersion}} (⬆ {{availablePluginVersion}}){{/if}}{{else}}—{{/if}} | {{../coreVersion}}{{#if ../availableCoreVersion}} (⬆ {{../availableCoreVersion}}){{/if}} |
 {{/each}}
 
 {{#if unhealthyServices}}
@@ -1245,6 +1371,63 @@ function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
     }
 }
 
+/**
+ * Build enriched service rows for the Platform template.
+ *
+ * @remarks
+ * Merges health probe results with component version state and
+ * npm registry update availability into rows for the Handlebars
+ * Platform template.
+ */
+/**
+ * Check whether an available version is newer than the current one.
+ *
+ * @param available - Registry version string.
+ * @param current - Currently installed version string.
+ * @returns The available version if it's newer, otherwise undefined.
+ */
+function newerVersion(available, current) {
+    if (!available ||
+        !current ||
+        !semver.valid(available) ||
+        !semver.valid(current)) {
+        return undefined;
+    }
+    return semver.gt(available, current) ? available : undefined;
+}
+/**
+ * Build enriched service rows for the Platform Handlebars template.
+ *
+ * @param options - Probe results, version state, and configuration.
+ * @returns Array of enriched service rows.
+ */
+function buildServiceRows(options) {
+    const { probeResults, componentVersions, cacheDir, skipRegistryCheck } = options;
+    return probeResults.map((r) => {
+        const entry = componentVersions[r.name];
+        if (!entry)
+            return { ...r };
+        let availableServiceVersion;
+        let availablePluginVersion;
+        if (!skipRegistryCheck) {
+            if (entry.servicePackage) {
+                const registryVersion = checkRegistryVersion(entry.servicePackage, cacheDir);
+                availableServiceVersion = newerVersion(registryVersion, r.version);
+            }
+            if (entry.pluginPackage && entry.pluginVersion) {
+                const registryVersion = checkRegistryVersion(entry.pluginPackage, cacheDir);
+                availablePluginVersion = newerVersion(registryVersion, entry.pluginVersion);
+            }
+        }
+        return {
+            ...r,
+            pluginVersion: entry.pluginVersion,
+            availableServiceVersion,
+            availablePluginVersion,
+        };
+    });
+}
+
 /**
  * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
@@ -1298,60 +1481,79 @@ function copyTemplates(coreConfigDir) {
 }
 /** Whether Handlebars helpers have been registered. */
 let helpersRegistered = false;
-/**
- * Register Handlebars helpers used in the Platform template.
- */
+/** Register Handlebars helpers used in the Platform template. */
 function registerHelpers() {
     if (helpersRegistered)
         return;
     helpersRegistered = true;
     Handlebars.registerHelper('gt', (a, b) => typeof a === 'number' && typeof b === 'number' && a > b);
 }
+/**
+ * Check if a newer core version is available on npm.
+ *
+ * @returns The newer version string, or undefined.
+ */
+function checkCoreUpdate(coreVersion, cacheDir) {
+    const registryVersion = checkRegistryVersion('@karmaniverous/jeeves', cacheDir);
+    if (registryVersion &&
+        semver.valid(registryVersion) &&
+        semver.valid(coreVersion) &&
+        semver.gt(registryVersion, coreVersion)) {
+        return registryVersion;
+    }
+    return undefined;
+}
 /**
  * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
  * @param options - Configuration for the refresh cycle.
  */
 async function refreshPlatformContent(options) {
-    const { coreVersion, componentName, stalenessThresholdMs, probeTimeoutMs = 3000, skipRegistryCheck = false, } = options;
+    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, probeTimeoutMs = 3000, skipRegistryCheck = false, } = options;
     const workspacePath = getWorkspacePath();
     const coreConfigDir = getCoreConfigDir();
     // 1. Probe all services
     const probeResults = await probeAllServices(undefined, probeTimeoutMs);
-    const unhealthyServices = probeResults.filter((r) => !r.healthy);
-    // 2. Build version info (registry check for the core package)
-    let availableVersion;
-    if (!skipRegistryCheck) {
-        const cacheDir = componentName
-            ? getComponentConfigDir(componentName)
-            : coreConfigDir;
-        availableVersion = checkRegistryVersion('@karmaniverous/jeeves', cacheDir);
+    // 2. Write calling component's version entry (with serviceVersion from probe)
+    if (componentName) {
+        const callerProbe = probeResults.find((r) => r.name === componentName);
+        writeComponentVersion(coreConfigDir, {
+            componentName,
+            serviceVersion: callerProbe?.version,
+            pluginVersion: componentVersion,
+            servicePackage,
+            pluginPackage,
+        });
     }
-    const versionInfo = probeResults.map((r) => ({
-        name: r.name,
-        serviceVersion: r.version,
-        coreVersion,
-        availableVersion: availableVersion && availableVersion !== coreVersion
-            ? availableVersion
-            : undefined,
-    }));
-    // 3. Check if templates are available
+    // 3. Read all component versions from the shared state file
+    const componentVersions = readComponentVersions(coreConfigDir);
+    // 4. Build enriched service rows with registry checks
+    const cacheDir = componentName
+        ? getComponentConfigDir(componentName)
+        : coreConfigDir;
+    const availableCoreVersion = skipRegistryCheck
+        ? undefined
+        : checkCoreUpdate(coreVersion, cacheDir);
+    const serviceRows = buildServiceRows({
+        probeResults,
+        componentVersions,
+        cacheDir,
+        skipRegistryCheck,
+    });
+    // 5. Render Platform template
     const templatePath = join(coreConfigDir, TEMPLATES_DIR);
-    const templatesAvailable = existsSync(templatePath);
-    // 4. Render Platform template
     registerHelpers();
     const template = Handlebars.compile(toolsPlatformTemplate);
     const templateData = {
-        services: probeResults,
-        unhealthyServices,
-        versionInfo: versionInfo.some((v) => v.serviceVersion)
-            ? versionInfo
-            : undefined,
-        templatesAvailable,
+        services: serviceRows,
+        unhealthyServices: serviceRows.filter((r) => !r.healthy),
+        coreVersion,
+        availableCoreVersion,
+        templatesAvailable: existsSync(templatePath),
         templatePath,
     };
     const platformContent = template(templateData);
-    // 5. Write TOOLS.md Platform section
+    // 6. Write TOOLS.md Platform section
     const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
     await updateManagedSection(toolsPath, platformContent, {
         mode: 'section',
@@ -1360,7 +1562,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 6. Write SOUL.md managed block
+    // 7. Write SOUL.md managed block
     const soulPath = join(workspacePath, WORKSPACE_FILES.soul);
     await updateManagedSection(soulPath, soulSectionContent, {
         mode: 'block',
@@ -1368,7 +1570,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 7. Write AGENTS.md managed block
+    // 8. Write AGENTS.md managed block
     const agentsPath = join(workspacePath, WORKSPACE_FILES.agents);
     await updateManagedSection(agentsPath, agentsSectionContent, {
         mode: 'block',
@@ -1376,7 +1578,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 8. Copy templates to config dir
+    // 9. Copy templates to config dir
     copyTemplates(coreConfigDir);
 }
 
@@ -1456,9 +1658,14 @@ class ComponentWriter {
                 coreVersion: CORE_VERSION,
             });
             // Platform content maintenance: SOUL.md, AGENTS.md, Platform section
+            // refreshPlatformContent also writes the component version entry
+            // (with serviceVersion from probe) to the shared state file.
             await refreshPlatformContent({
                 coreVersion: CORE_VERSION,
                 componentName: this.component.name,
+                componentVersion: this.component.version,
+                servicePackage: this.component.servicePackage,
+                pluginPackage: this.component.pluginPackage,
                 skipRegistryCheck: false,
                 probeTimeoutMs: this.probeTimeoutMs,
             });
@@ -1607,41 +1814,150 @@ function createComponentWriter(component, options) {
 }
 
 /**
- * Resolve the OpenClaw workspace root from the plugin API.
+ * Plugin resolution helpers for the OpenClaw plugin SDK.
  *
  * @remarks
- * Tries three sources in order:
- * 1. `api.config.agents.defaults.workspace` — explicit config (most authoritative)
- * 2. `api.resolvePath('.')` — gateway-provided path resolver
- * 3. `process.cwd()` — last resort (unsafe when gateway runs from system32)
- *
- * The config value is checked first because `api.resolvePath('.')` delegates
- * to `path.resolve('.')`, which returns `process.cwd()` — not the workspace.
- * When the gateway runs as a Windows service from `C:\Windows\system32`,
- * `resolvePath('.')` returns system32, not the configured workspace.
- *
- * Plugins should call this once at registration time and pass the result
- * to `init({ workspacePath })`.
+ * Provides workspace path resolution and plugin setting resolution
+ * with a standard three-step fallback chain:
+ * plugin config → environment variable → default value.
  */
 /**
  * Resolve the workspace root from the OpenClaw plugin API.
  *
- * @param api - The plugin API object provided by the gateway at registration.
+ * @remarks
+ * Tries three sources in order:
+ * 1. `api.config.agents.defaults.workspace` — explicit config
+ * 2. `api.resolvePath('.')` — gateway-provided path resolver
+ * 3. `process.cwd()` — last resort
+ *
+ * @param api - The plugin API object provided by the gateway.
  * @returns Absolute path to the workspace root.
  */
 function resolveWorkspacePath(api) {
-    // 1. Explicit config value (most authoritative)
     const configured = api.config?.agents?.defaults?.workspace;
     if (typeof configured === 'string' && configured.trim()) {
         return configured;
     }
-    // 2. Gateway-provided path resolver
     if (typeof api.resolvePath === 'function') {
         return api.resolvePath('.');
     }
-    // 3. Last resort — unsafe when gateway runs from system32
     return process.cwd();
 }
+/**
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → fallback value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
+ * @returns The resolved setting value.
+ */
+function resolvePluginSetting(api, pluginId, key, envVar, fallback) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return fallback;
+}
+
+/**
+ * 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');
+}
 
 /**
  * One-shot content seeding used by the CLI install command.
@@ -1696,4 +2012,228 @@ async function seedContent(options) {
     });
 }
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, checkRegistryVersion, coreConfigSchema, createAsyncContentCache, createComponentWriter, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, parseManaged, probeAllServices, probeService, refreshPlatformContent, resetInit, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection };
+/**
+ * HTTP helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Thin wrappers around `fetch` that throw on non-OK responses
+ * and handle JSON serialisation/deserialisation.
+ */
+/**
+ * Fetch JSON from a URL, throwing on non-OK responses.
+ *
+ * @param url - URL to fetch.
+ * @param init - Optional `fetch` init options.
+ * @returns Parsed JSON response body.
+ * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
+ */
+async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
+    }
+    return res.json();
+}
+/**
+ * POST JSON to a URL and return parsed response.
+ *
+ * @param url - URL to POST to.
+ * @param body - Request body (will be JSON-stringified).
+ * @returns Parsed JSON response body.
+ */
+async function postJson(url, body) {
+    return fetchJson(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Tool result formatters for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Provides standardised helpers for building `ToolResult` objects:
+ * success, error, and connection-error variants.
+ */
+/**
+ * Format a successful tool result.
+ *
+ * @param data - Arbitrary data to return as JSON.
+ * @returns A `ToolResult` with JSON-stringified content.
+ */
+function ok(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Format an error tool result.
+ *
+ * @param error - Error instance, string, or other value.
+ * @returns A `ToolResult` with `isError: true`.
+ */
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: 'text', text: 'Error: ' + message }],
+        isError: true,
+    };
+}
+/**
+ * Format a connection error with actionable guidance.
+ *
+ * @remarks
+ * Detects `ECONNREFUSED`, `ENOTFOUND`, and `ETIMEDOUT` from
+ * `error.cause.code` and returns a user-friendly message referencing
+ * the plugin's `config.apiUrl` setting. Falls back to `fail()` for
+ * non-connection errors.
+ *
+ * @param error - Error instance (typically from `fetch`).
+ * @param baseUrl - The URL that was being contacted.
+ * @param pluginId - The plugin identifier for config guidance.
+ * @returns A `ToolResult` with `isError: true`.
+ */
+function connectionFail(error, baseUrl, pluginId) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause && typeof cause === 'object' && 'code' in cause
+        ? String(cause.code)
+        : '';
+    const isConnectionError = code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT';
+    if (isConnectionError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        `Service not reachable at ${baseUrl}.`,
+                        'Either start the service, or if it runs on a different port,',
+                        `set plugins.entries.${pluginId}.config.apiUrl in openclaw.json.`,
+                    ].join('\n'),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return fail(error);
+}
+
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_CORE_VERSION, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, probeAllServices, probeService, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };