@karmaniverous/jeeves 0.1.5 → 0.2.0

package/dist/cli/jeeves/index.js

@@ -1,16 +1,15 @@
 #!/usr/bin/env node
 #!/usr/bin/env node
 import require$$0 from 'commander';
-import { createRequire } from 'node:module';
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, cpSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { packageDirectorySync } from 'package-directory';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, cpSync, rmSync } from 'node:fs';
 import { z } from 'zod';
+import { fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
-import { execSync } from 'node:child_process';
+import { packageDirectorySync } from 'package-directory';
+import semver, { gte } from 'semver';
 import { lock } from 'proper-lockfile';
-import { gte } from 'semver';
+import { execSync } from 'node:child_process';
 
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
@@ -95,6 +94,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 = {
@@ -102,6 +103,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.
@@ -138,6 +141,8 @@ const TEMPLATES_DIR = 'templates';
 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';
 
 /**
  * Default port assignments for Jeeves platform services.
@@ -198,24 +203,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';
 
 /**
  * Core configuration schema and resolution.
@@ -660,20 +658,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}}
@@ -740,6 +728,117 @@ Read these templates when creating new specs, onboarding to new projects, or whe
 {{/if}}
 `;
 
+/**
+ * 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');
+}
+
 /**
  * Service URL resolution.
  *
@@ -1163,10 +1262,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.
  *
@@ -1175,7 +1270,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"');
     }
@@ -1187,90 +1282,134 @@ 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();
+}
+
+/**
+ * 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);
             }
-            catch {
-                // Lock already released or file deleted — safe to ignore
+            if (entry.pluginPackage && entry.pluginVersion) {
+                const registryVersion = checkRegistryVersion(entry.pluginPackage, cacheDir);
+                availablePluginVersion = newerVersion(registryVersion, entry.pluginVersion);
             }
         }
-    }
+        return {
+            ...r,
+            pluginVersion: entry.pluginVersion,
+            availableServiceVersion,
+            availablePluginVersion,
+        };
+    });
 }
 
 /**
@@ -1326,60 +1465,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',
@@ -1388,7 +1546,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',
@@ -1396,7 +1554,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',
@@ -1404,7 +1562,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 8. Copy templates to config dir
+    // 9. Copy templates to config dir
     copyTemplates(coreConfigDir);
 }