@karmaniverous/jeeves 0.1.0

package/dist/cli/jeeves/index.js

@@ -0,0 +1,1341 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+import require$$0 from 'commander';
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, cpSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { z } from 'zod';
+import { fileURLToPath } from 'node:url';
+import Handlebars from 'handlebars';
+import { execSync } from 'node:child_process';
+import { lock } from 'proper-lockfile';
+import { gte } from 'semver';
+
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+var extraTypings = {exports: {}};
+
+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;
+
+/**
+ * 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',
+};
+/** Default markers for SOUL.md managed block. */
+const SOUL_MARKERS = {
+    /** BEGIN comment marker text. */
+    begin: 'BEGIN JEEVES SOUL — DO NOT EDIT THIS SECTION',
+    /** END comment marker text. */
+    end: 'END JEEVES SOUL',
+};
+/** Default markers for AGENTS.md managed block. */
+const AGENTS_MARKERS = {
+    /** BEGIN comment marker text. */
+    begin: 'BEGIN JEEVES AGENTS — DO NOT EDIT THIS SECTION',
+    /** END comment marker text. */
+    end: 'END JEEVES AGENTS',
+};
+/**
+ * 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*-->/;
+/** Staleness threshold for version-stamp convergence in milliseconds. */
+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.
+ *
+ * @remarks
+ * Each port number is a historical reference:
+ * - 1934: Wodehouse's *Thank You, Jeeves*; Popper's *Logic of Scientific Discovery*
+ * - 1936: Turing's "On Computable Numbers"; Church's lambda calculus
+ * - 1937: Turing's paper in *Proceedings of the London Mathematical Society*
+ * - 1938: Wodehouse's *The Code of the Woosters*; Shannon's relay/switching paper
+ */
+/** Default port for jeeves-server. */
+const SERVER_PORT = 1934;
+/** Default port for jeeves-watcher. */
+const WATCHER_PORT = 1936;
+/** Default port for jeeves-runner. */
+const RUNNER_PORT = 1937;
+/** Default port for jeeves-meta. */
+const META_PORT = 1938;
+/** Map of service names to their default ports. */
+const DEFAULT_PORTS = {
+    server: SERVER_PORT,
+    watcher: WATCHER_PORT,
+    runner: RUNNER_PORT,
+    meta: META_PORT,
+};
+
+/**
+ * Managed section IDs and their stable ordering for TOOLS.md.
+ *
+ * @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,
+];
+
+/**
+ * Core library version, read from package.json at runtime.
+ *
+ * @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.
+ */
+const require$1 = createRequire(import.meta.url);
+const pkg = require$1('../../package.json');
+/** The core library version from package.json. */
+const CORE_VERSION = pkg.version;
+
+/**
+ * Core configuration schema and resolution.
+ *
+ * @remarks
+ * Core config lives at `{configRoot}/jeeves-core/config.json`.
+ * Config resolution order:
+ * 1. Component's own config file
+ * 2. Core config file
+ * 3. Hardcoded library defaults
+ */
+/** Zod schema for a service entry in core config. */
+const serviceEntrySchema = z.object({
+    /** Service URL (must be a valid URL). */
+    url: z.string().url().describe('Service URL'),
+});
+/** Zod schema for the core config file. */
+const coreConfigSchema = z.object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: z.string().optional().describe('JSON Schema pointer'),
+    /** Owner identity keys (canonical identityLinks references). */
+    owners: z.array(z.string()).default([]).describe('Owner identity keys'),
+    /** Service URL overrides keyed by service name. */
+    services: z
+        .record(z.string(), serviceEntrySchema)
+        .default({})
+        .describe('Service URL overrides'),
+    /** Registry cache configuration. */
+    registryCache: z
+        .object({
+        /** Cache TTL in seconds for npm registry queries. */
+        ttlSeconds: z
+            .number()
+            .int()
+            .positive()
+            .default(3600)
+            .describe('Cache TTL in seconds'),
+    })
+        .default({})
+        .describe('Registry cache settings'),
+});
+/**
+ * Generate a JSON Schema from the Zod schema for `$schema` pointer support.
+ *
+ * @returns A JSON Schema object.
+ */
+function generateJsonSchema() {
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        title: 'Jeeves Core Configuration',
+        type: 'object',
+        properties: {
+            $schema: { type: 'string' },
+            owners: {
+                type: 'array',
+                items: { type: 'string' },
+                default: [],
+            },
+            services: {
+                type: 'object',
+                additionalProperties: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', format: 'uri' },
+                    },
+                    required: ['url'],
+                },
+                default: {},
+            },
+            registryCache: {
+                type: 'object',
+                properties: {
+                    ttlSeconds: {
+                        type: 'integer',
+                        minimum: 1,
+                        default: 3600,
+                    },
+                },
+                default: {},
+            },
+        },
+    };
+}
+/**
+ * Load and parse a config file, returning undefined if missing or invalid.
+ *
+ * @param configDir - Directory containing config.json.
+ * @returns Parsed config or undefined.
+ */
+function loadConfig(configDir) {
+    const configPath = join(configDir, CONFIG_FILE);
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return coreConfigSchema.parse(parsed);
+    }
+    catch {
+        return undefined;
+    }
+}
+
+/**
+ * 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 cached workspace path.
+ *
+ * @throws Error if `init()` has not been called.
+ */
+function getWorkspacePath() {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.workspacePath;
+}
+/**
+ * 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;
+}
+/**
+ * Derive the component config directory from the component name.
+ *
+ * @param componentName - The component name (e.g., 'watcher', 'runner').
+ * @returns Absolute path to the component's config directory.
+ * @throws Error if `init()` has not been called.
+ */
+function getComponentConfigDir(componentName) {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return join(state.configRoot, `${COMPONENT_CONFIG_PREFIX}${componentName}`);
+}
+
+/**
+ * Service URL resolution.
+ *
+ * @remarks
+ * Resolves the URL for a named Jeeves service using the following
+ * resolution order:
+ * 1. Consumer's own component config
+ * 2. Core config (`{configRoot}/jeeves-core/config.json`)
+ * 3. Default port constants
+ */
+/**
+ * Resolve the URL for a named Jeeves service.
+ *
+ * @param serviceName - The service name (e.g., 'watcher', 'runner').
+ * @param consumerName - Optional consumer component name for config override.
+ * @returns The resolved service URL.
+ * @throws Error if `init()` has not been called or the service is unknown.
+ */
+function getServiceUrl(serviceName, consumerName) {
+    // 2. Check core config
+    const coreDir = getCoreConfigDir();
+    const coreConfig = loadConfig(coreDir);
+    const coreUrl = coreConfig?.services[serviceName]?.url;
+    if (coreUrl)
+        return coreUrl;
+    // 3. Fall back to port constants
+    const port = DEFAULT_PORTS[serviceName];
+    if (port !== undefined) {
+        return `http://127.0.0.1:${String(port)}`;
+    }
+    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
+}
+
+/**
+ * HTTP health probing for Jeeves platform services.
+ *
+ * @remarks
+ * Probes service ports for health endpoints (HTTP GET to /status or /health).
+ * Returns structured health data for rendering into TOOLS.md Platform section.
+ */
+/**
+ * Extract port number from a URL string.
+ *
+ * @param url - Service URL.
+ * @returns Port number.
+ */
+function extractPort(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.port ? parseInt(parsed.port, 10) : 80;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Probe a single service for health.
+ *
+ * @param serviceName - The service name (e.g., 'server', 'watcher').
+ * @param consumerName - Optional consumer name for URL resolution.
+ * @param timeoutMs - Request timeout in milliseconds (default 3000).
+ * @returns Probe result.
+ */
+async function probeService(serviceName, consumerName, timeoutMs = 3000) {
+    const url = getServiceUrl(serviceName);
+    const port = extractPort(url);
+    const endpoints = ['/status', '/health'];
+    for (const endpoint of endpoints) {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => {
+                controller.abort();
+            }, timeoutMs);
+            const response = await fetch(`${url}${endpoint}`, {
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (response.ok) {
+                let version;
+                try {
+                    const body = await response.json();
+                    if (typeof body === 'object' &&
+                        body !== null &&
+                        'version' in body &&
+                        typeof body['version'] === 'string') {
+                        version = body['version'];
+                    }
+                }
+                catch {
+                    // Non-JSON response is fine — we just don't get version info
+                }
+                return { name: serviceName, port, healthy: true, version };
+            }
+        }
+        catch {
+            // Try next endpoint
+        }
+    }
+    return { name: serviceName, port, healthy: false };
+}
+/**
+ * Probe all known Jeeves services for health.
+ *
+ * @param consumerName - Optional consumer name for URL resolution.
+ * @param timeoutMs - Request timeout in milliseconds (default 3000).
+ * @returns Array of probe results for all services.
+ */
+async function probeAllServices(consumerName, timeoutMs = 3000) {
+    const serviceNames = Object.keys(DEFAULT_PORTS);
+    const results = await Promise.all(serviceNames.map((name) => probeService(name, consumerName, timeoutMs)));
+    return results;
+}
+
+/**
+ * Registry version cache for npm package update awareness.
+ *
+ * @remarks
+ * Caches the latest npm registry version in a local JSON file
+ * to avoid expensive `npm view` calls on every refresh cycle.
+ */
+/**
+ * Check the npm registry for the latest version of a package.
+ *
+ * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
+ * @param cacheDir - Directory to store the cache file.
+ * @param ttlSeconds - Cache TTL in seconds (default 3600).
+ * @returns The latest version string, or undefined if the check fails.
+ */
+function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
+    const cachePath = join(cacheDir, REGISTRY_CACHE_FILE);
+    // Check cache first
+    if (existsSync(cachePath)) {
+        try {
+            const raw = readFileSync(cachePath, 'utf-8');
+            const entry = JSON.parse(raw);
+            const age = Date.now() - new Date(entry.checkedAt).getTime();
+            if (age < ttlSeconds * 1000) {
+                return entry.version;
+            }
+        }
+        catch {
+            // Cache corrupt — proceed with fresh check
+        }
+    }
+    // Query npm registry
+    try {
+        const result = execSync(`npm view ${packageName} version`, {
+            encoding: 'utf-8',
+            timeout: 15_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (!result)
+            return undefined;
+        // Write cache
+        if (!existsSync(cacheDir)) {
+            mkdirSync(cacheDir, { recursive: true });
+        }
+        const entry = {
+            version: result,
+            checkedAt: new Date().toISOString(),
+        };
+        writeFileSync(cachePath, JSON.stringify(entry, null, 2), 'utf-8');
+        return result;
+    }
+    catch {
+        return undefined;
+    }
+}
+
+/**
+ * Similarity-based cleanup detection for orphaned managed content.
+ *
+ * @remarks
+ * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
+ * when orphaned managed content exists in the user content zone.
+ */
+/** Default similarity threshold for cleanup detection. */
+const DEFAULT_THRESHOLD = 0.15;
+/**
+ * Generate a set of n-word shingles from text.
+ *
+ * @param text - Input text.
+ * @param n - Shingle size (default 3).
+ * @returns Set of n-word shingles.
+ */
+function shingles(text, n = 3) {
+    const words = text.toLowerCase().split(/\s+/).filter(Boolean);
+    const set = new Set();
+    for (let i = 0; i <= words.length - n; i++) {
+        set.add(words.slice(i, i + n).join(' '));
+    }
+    return set;
+}
+/**
+ * Compute Jaccard similarity between two sets.
+ *
+ * @param a - First set.
+ * @param b - Second set.
+ * @returns Jaccard similarity coefficient (0 to 1).
+ */
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const item of a) {
+        if (b.has(item))
+            intersection++;
+    }
+    return intersection / (a.size + b.size - intersection);
+}
+/**
+ * Check whether user content contains orphaned managed content.
+ *
+ * @param managedContent - The current managed block content.
+ * @param userContent - Content below the END marker.
+ * @param threshold - Jaccard threshold (default 0.15).
+ * @returns `true` if cleanup is needed.
+ */
+function needsCleanup(managedContent, userContent, threshold = DEFAULT_THRESHOLD) {
+    if (!userContent.trim())
+        return false;
+    return jaccard(shingles(managedContent), shingles(userContent)) > threshold;
+}
+
+/**
+ * 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} -->`;
+}
+/**
+ * Determine whether this writer should proceed based on version-stamp
+ * convergence rules.
+ *
+ * @param myVersion - The current core library version.
+ * @param existing - The existing version stamp (if any).
+ * @param stalenessThresholdMs - Staleness threshold in ms (default: 5 min).
+ * @returns `true` if the writer should proceed with the write.
+ */
+function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRESHOLD_MS) {
+    // No existing stamp — always write
+    if (!existing)
+        return true;
+    // My version >= stamped version — always write (I'm current or newer)
+    if (gte(myVersion, existing.version))
+        return true;
+    // My version < stamped version — check staleness
+    const stampAge = Date.now() - new Date(existing.timestamp).getTime();
+    return stampAge >= stalenessThresholdMs;
+}
+
+/**
+ * Generic managed-section writer with block and section modes.
+ *
+ * @remarks
+ * Supports two modes:
+ * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
+ * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
+ *
+ * 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.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param content - New content to write.
+ * @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;
+    if (mode === 'section' && !sectionId) {
+        throw new Error('sectionId is required when mode is "section"');
+    }
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Create file if it doesn't exist
+    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 };
+            }
+            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 (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('');
+            parts.push(CLEANUP_FLAG);
+        }
+        parts.push('');
+        parts.push(newManagedBody);
+        parts.push('');
+        parts.push(endLine);
+        if (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);
+    }
+    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
+            }
+        }
+    }
+}
+
+/**
+ * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
+ *
+ * @remarks
+ * Called by `ComponentWriter` on each cycle. Not directly exposed to components.
+ * Probes service ports for health, reads content files from the package's
+ * `content/` directory, renders the Platform template with live service data,
+ * and writes managed sections using `updateManagedSection`.
+ */
+/**
+ * Resolve the package's content directory.
+ *
+ * @returns Absolute path to the content/ directory.
+ */
+function getContentDir() {
+    const thisFile = fileURLToPath(import.meta.url);
+    // From src/platform/refreshPlatformContent.ts → ../../content/
+    // From dist/platform/refreshPlatformContent.js → ../../content/
+    return join(dirname(thisFile), '..', '..', 'content');
+}
+/**
+ * Read a content file from the package's content/ directory.
+ *
+ * @param fileName - File name within content/.
+ * @returns File content as string, or empty string if missing.
+ */
+function readContentFile(fileName) {
+    const filePath = join(getContentDir(), fileName);
+    if (!existsSync(filePath)) {
+        console.warn(`jeeves-core: content file missing: ${filePath}`);
+        return '';
+    }
+    return readFileSync(filePath, 'utf-8');
+}
+/**
+ * Copy templates from content/templates/ to the core config directory.
+ *
+ * @param coreConfigDir - Core config directory path.
+ */
+function copyTemplates(coreConfigDir) {
+    const sourceDir = join(getContentDir(), 'templates');
+    if (!existsSync(sourceDir))
+        return;
+    const destDir = join(coreConfigDir, TEMPLATES_DIR);
+    if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
+    }
+    cpSync(sourceDir, destDir, { recursive: true });
+}
+/** Whether Handlebars helpers have been registered. */
+let helpersRegistered = false;
+/**
+ * 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);
+}
+/**
+ * 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 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);
+    }
+    const versionInfo = probeResults.map((r) => ({
+        name: r.name,
+        serviceVersion: r.version,
+        coreVersion,
+        availableVersion: availableVersion && availableVersion !== coreVersion
+            ? availableVersion
+            : undefined,
+    }));
+    // 3. Check if templates are available
+    const templatePath = join(coreConfigDir, TEMPLATES_DIR);
+    const templatesAvailable = existsSync(templatePath);
+    // 4. Render Platform template
+    registerHelpers();
+    const templateSrc = readContentFile('tools-platform.md');
+    const template = Handlebars.compile(templateSrc);
+    const templateData = {
+        services: probeResults,
+        unhealthyServices,
+        versionInfo: versionInfo.some((v) => v.serviceVersion)
+            ? versionInfo
+            : undefined,
+        templatesAvailable,
+        templatePath,
+    };
+    const platformContent = template(templateData);
+    // 5. Write TOOLS.md Platform section
+    const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
+    await updateManagedSection(toolsPath, platformContent, {
+        mode: 'section',
+        sectionId: 'Platform',
+        markers: TOOLS_MARKERS,
+        coreVersion,
+        stalenessThresholdMs,
+    });
+    // 6. Write SOUL.md managed block
+    const soulContent = readContentFile('soul-section.md');
+    const soulPath = join(workspacePath, WORKSPACE_FILES.soul);
+    await updateManagedSection(soulPath, soulContent, {
+        mode: 'block',
+        markers: SOUL_MARKERS,
+        coreVersion,
+        stalenessThresholdMs,
+    });
+    // 7. Write AGENTS.md managed block
+    const agentsContent = readContentFile('agents-section.md');
+    const agentsPath = join(workspacePath, WORKSPACE_FILES.agents);
+    await updateManagedSection(agentsPath, agentsContent, {
+        mode: 'block',
+        markers: AGENTS_MARKERS,
+        coreVersion,
+        stalenessThresholdMs,
+    });
+    // 8. Copy templates to config dir
+    copyTemplates(coreConfigDir);
+}
+
+/**
+ * One-shot content seeding used by the CLI install command.
+ *
+ * @remarks
+ * Seeds SOUL.md, AGENTS.md, and TOOLS.md Platform section using the same
+ * `updateManagedSection()` code path as writer cycles. Also copies templates
+ * and creates core config with defaults if missing.
+ */
+/**
+ * Create the core config file with defaults if it doesn't already exist.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ */
+function ensureCoreConfig(coreConfigDir) {
+    if (!existsSync(coreConfigDir)) {
+        mkdirSync(coreConfigDir, { recursive: true });
+    }
+    const configPath = join(coreConfigDir, CONFIG_FILE);
+    if (existsSync(configPath))
+        return;
+    const defaults = coreConfigSchema.parse({});
+    const configWithSchema = {
+        $schema: './config.schema.json',
+        ...defaults,
+    };
+    writeFileSync(configPath, JSON.stringify(configWithSchema, null, 2), 'utf-8');
+    // Write JSON schema file alongside config
+    const schemaPath = join(coreConfigDir, 'config.schema.json');
+    const jsonSchema = generateJsonSchema();
+    writeFileSync(schemaPath, JSON.stringify(jsonSchema, null, 2), 'utf-8');
+}
+/**
+ * Seed all platform content into the workspace.
+ *
+ * @remarks
+ * Uses the same `updateManagedSection()` code path as writer cycles.
+ * Creates core config with defaults if missing. Copies templates.
+ * Jaccard cleanup detection runs automatically via `updateManagedSection`.
+ *
+ * @param options - Seeding configuration.
+ */
+async function seedContent(options) {
+    const coreConfigDir = getCoreConfigDir();
+    // Ensure core config exists
+    ensureCoreConfig(coreConfigDir);
+    // Seed content via the same code path as writer cycles
+    await refreshPlatformContent({
+        coreVersion: options.coreVersion,
+        probeTimeoutMs: options.probeTimeoutMs ?? 3000,
+        skipRegistryCheck: options.skipRegistryCheck ?? true,
+    });
+}
+
+/**
+ * Shared CLI defaults and option registration for Jeeves CLI commands.
+ *
+ * @remarks
+ * All three CLI commands (install, uninstall, status) share the same
+ * `--workspace` and `--config-root` options with the same defaults.
+ * This module centralizes them to eliminate duplication.
+ */
+/** Default workspace path (current directory). */
+const DEFAULT_WORKSPACE = '.';
+/** Default config root path. */
+const DEFAULT_CONFIG_ROOT = './config';
+/**
+ * Initialize core from standard CLI options.
+ *
+ * @param opts - Parsed Commander options with workspace and configRoot.
+ */
+function initFromOptions(opts) {
+    init({ workspacePath: opts.workspace, configRoot: opts.configRoot });
+}
+
+/**
+ * CLI install command: seed platform content into the workspace.
+ *
+ * @remarks
+ * Seeds SOUL.md, AGENTS.md, TOOLS.md Platform section using the same
+ * `updateManagedSection()` code path as writer cycles. Copies templates
+ * to config dir. Creates core config with defaults if missing.
+ * Jaccard cleanup detection runs on install (Decision 22).
+ */
+/**
+ * Register the install subcommand on the parent CLI program.
+ *
+ * @param program - The parent Commander program.
+ */
+function registerInstallCommand(program) {
+    program
+        .command('install')
+        .description('Seed Jeeves platform content into the workspace')
+        .option('-w, --workspace <path>', 'Workspace root path', DEFAULT_WORKSPACE)
+        .option('-c, --config-root <path>', 'Platform config root path', DEFAULT_CONFIG_ROOT)
+        .action(async (opts) => {
+        console.log('Jeeves platform install');
+        console.log(`  Workspace: ${opts.workspace}`);
+        console.log(`  Config root: ${opts.configRoot}`);
+        console.log();
+        initFromOptions(opts);
+        await seedContent({
+            coreVersion: CORE_VERSION,
+            skipRegistryCheck: true,
+        });
+        console.log('✅ Platform content seeded successfully.');
+        console.log('  - SOUL.md managed section written');
+        console.log('  - AGENTS.md managed section written');
+        console.log('  - TOOLS.md Platform section written');
+        console.log('  - Templates copied to config directory');
+        console.log('  - Core config created (if not present)');
+    });
+}
+
+/**
+ * CLI status command: probe all service ports and report health summary.
+ *
+ * @remarks
+ * Displays a table of all Jeeves platform services with port and
+ * health status. Exits with code 0 if all services are healthy,
+ * code 1 if any are unreachable.
+ */
+/**
+ * Register the status subcommand on the parent CLI program.
+ *
+ * @param program - The parent Commander program.
+ */
+function registerStatusCommand(program) {
+    program
+        .command('status')
+        .description('Probe all Jeeves service ports and report health summary')
+        .option('-w, --workspace <path>', 'Workspace root path', DEFAULT_WORKSPACE)
+        .option('-c, --config-root <path>', 'Platform config root path', DEFAULT_CONFIG_ROOT)
+        .option('-t, --timeout <ms>', 'Probe timeout in milliseconds', '3000')
+        .action(async (opts) => {
+        const timeoutMs = parseInt(opts.timeout, 10);
+        initFromOptions(opts);
+        console.log('Jeeves Platform Status');
+        console.log('='.repeat(60));
+        console.log();
+        const probeResults = await probeAllServices(undefined, timeoutMs);
+        const nameWidth = 10;
+        const portWidth = 6;
+        const statusWidth = 30;
+        const header = [
+            'Service'.padEnd(nameWidth),
+            'Port'.padEnd(portWidth),
+            'Status'.padEnd(statusWidth),
+        ].join('  ');
+        const separator = [
+            '-'.repeat(nameWidth),
+            '-'.repeat(portWidth),
+            '-'.repeat(statusWidth),
+        ].join('  ');
+        console.log(header);
+        console.log(separator);
+        let allHealthy = true;
+        for (const r of probeResults) {
+            let status;
+            if (r.healthy) {
+                status = r.version ? `✅ Running (v${r.version})` : '✅ Running';
+            }
+            else {
+                status = r.error ? `❌ ${r.error}` : '❌ Down';
+                allHealthy = false;
+            }
+            const row = [
+                r.name.padEnd(nameWidth),
+                String(r.port).padEnd(portWidth),
+                status.padEnd(statusWidth),
+            ].join('  ');
+            console.log(row);
+        }
+        console.log();
+        const healthy = probeResults.filter((r) => r.healthy).length;
+        const total = probeResults.length;
+        console.log(`${String(healthy)}/${String(total)} services healthy`);
+        if (!allHealthy) {
+            process.exitCode = 1;
+        }
+    });
+}
+
+/**
+ * Shared helpers for the uninstall command.
+ *
+ * @remarks
+ * Extracted for testability — these are the core uninstall operations.
+ */
+/**
+ * Remove managed block from a file, keeping user content.
+ *
+ * @param filePath - Absolute path to the workspace file.
+ * @param markers - Begin/end marker pair.
+ */
+function removeManagedBlockFromFile(filePath, markers) {
+    if (!existsSync(filePath))
+        return;
+    const content = readFileSync(filePath, 'utf-8');
+    const parsed = parseManaged(content, markers);
+    if (!parsed.found)
+        return;
+    // Reconstruct file with only user content
+    const parts = [];
+    if (parsed.beforeContent) {
+        parts.push(parsed.beforeContent);
+    }
+    if (parsed.userContent) {
+        if (parts.length > 0)
+            parts.push('');
+        parts.push(parsed.userContent);
+    }
+    const newContent = parts.join('\n').trim() + '\n';
+    writeFileSync(filePath, newContent, 'utf-8');
+}
+
+/**
+ * CLI uninstall command: remove managed sections and platform artifacts.
+ *
+ * @remarks
+ * Removes managed sections from SOUL.md, AGENTS.md, TOOLS.md.
+ * Removes templates and config dir artifacts. Warns if services
+ * still responding on known ports.
+ */
+/**
+ * Register the uninstall subcommand on the parent CLI program.
+ *
+ * @param program - The parent Commander program.
+ */
+function registerUninstallCommand(program) {
+    program
+        .command('uninstall')
+        .description('Remove Jeeves managed sections and platform artifacts')
+        .option('-w, --workspace <path>', 'Workspace root path', DEFAULT_WORKSPACE)
+        .option('-c, --config-root <path>', 'Platform config root path', DEFAULT_CONFIG_ROOT)
+        .action(async (opts) => {
+        console.log('Jeeves platform uninstall');
+        console.log(`  Workspace: ${opts.workspace}`);
+        console.log(`  Config root: ${opts.configRoot}`);
+        console.log();
+        initFromOptions(opts);
+        const wsPath = getWorkspacePath();
+        const coreConfigDir = getCoreConfigDir();
+        // Remove managed sections from workspace files
+        const toolsPath = join(wsPath, WORKSPACE_FILES.tools);
+        removeManagedBlockFromFile(toolsPath, TOOLS_MARKERS);
+        console.log('  ✓ TOOLS.md managed section removed');
+        const soulPath = join(wsPath, WORKSPACE_FILES.soul);
+        removeManagedBlockFromFile(soulPath, SOUL_MARKERS);
+        console.log('  ✓ SOUL.md managed section removed');
+        const agentsPath = join(wsPath, WORKSPACE_FILES.agents);
+        removeManagedBlockFromFile(agentsPath, AGENTS_MARKERS);
+        console.log('  ✓ AGENTS.md managed section removed');
+        // Remove templates directory
+        const templatesDir = join(coreConfigDir, TEMPLATES_DIR);
+        if (existsSync(templatesDir)) {
+            rmSync(templatesDir, { recursive: true, force: true });
+            console.log('  ✓ Templates removed');
+        }
+        // Remove config schema file
+        const schemaPath = join(coreConfigDir, 'config.schema.json');
+        if (existsSync(schemaPath)) {
+            rmSync(schemaPath);
+            console.log('  ✓ Config schema removed');
+        }
+        console.log();
+        // Warn if services still responding
+        try {
+            const probeResults = await probeAllServices(undefined, 2000);
+            const running = probeResults.filter((r) => r.healthy);
+            if (running.length > 0) {
+                console.log('⚠️  The following services are still responding:');
+                for (const r of running) {
+                    const ver = r.version ? ` (v${r.version})` : '';
+                    console.log(`    - ${r.name} on port ${String(r.port)}${ver}`);
+                }
+                console.log('   Consider stopping them before fully removing Jeeves.');
+                console.log();
+            }
+        }
+        catch {
+            // Probe failure is non-fatal during uninstall
+        }
+        console.log('✅ Jeeves platform artifacts removed.');
+    });
+}
+
+/**
+ * Jeeves CLI — platform content seeding, teardown, and status.
+ *
+ * @remarks
+ * Entry point for the `jeeves` CLI command. Provides install, uninstall,
+ * and status subcommands.
+ */
+const cli = new Command()
+    .name('jeeves')
+    .description('Jeeves AI assistant platform — shared library and CLI')
+    .version(CORE_VERSION)
+    .enablePositionalOptions()
+    .passThroughOptions();
+registerInstallCommand(cli);
+registerUninstallCommand(cli);
+registerStatusCommand(cli);
+cli.parse();