@karmaniverous/jeeves 0.1.0

package/dist/index.js

@@ -0,0 +1,1232 @@
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, renameSync, cpSync } from 'node:fs';
+import { lock } from 'proper-lockfile';
+import { gte } from 'semver';
+import { fileURLToPath } from 'node:url';
+import Handlebars from 'handlebars';
+import { z } from 'zod';
+import { execSync } from 'node:child_process';
+
+/**
+ * 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;
+
+/**
+ * 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 cached config root path.
+ *
+ * @throws Error if `init()` has not been called.
+ */
+function getConfigRoot() {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.configRoot;
+}
+/**
+ * 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;
+}
+/**
+ * Get the core config file path.
+ *
+ * @throws Error if `init()` has not been called.
+ */
+function getCoreConfigFile() {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return join(state.coreConfigDir, CONFIG_FILE);
+}
+/**
+ * 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}`);
+}
+/**
+ * Reset initialization state. Used for testing only.
+ */
+function resetInit() {
+    state = 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
+            }
+        }
+    }
+}
+
+/**
+ * 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;
+    }
+}
+
+/**
+ * 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) {
+    // 1. Check consumer's own config
+    if (consumerName) {
+        const consumerDir = getComponentConfigDir(consumerName);
+        const consumerConfig = loadConfig(consumerDir);
+        const consumerUrl = consumerConfig?.services[serviceName]?.url;
+        if (consumerUrl)
+            return consumerUrl;
+    }
+    // 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, consumerName);
+    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;
+    }
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Timer-based orchestrator for managed content writing.
+ *
+ * @remarks
+ * `ComponentWriter` manages a component's TOOLS.md section writes
+ * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
+ * on a configurable prime-interval timer cycle.
+ */
+/**
+ * Orchestrates managed content writing for a single Jeeves component.
+ *
+ * @remarks
+ * Created via `createComponentWriter()`. Manages a timer that fires
+ * at the component's prime-interval, calling `generateToolsContent()`
+ * and `refreshPlatformContent()` on each cycle.
+ */
+class ComponentWriter {
+    timer;
+    component;
+    configDir;
+    probeTimeoutMs;
+    /** @internal */
+    constructor(component, probeTimeoutMs = 3000) {
+        this.component = component;
+        this.configDir = getComponentConfigDir(component.name);
+        this.probeTimeoutMs = probeTimeoutMs;
+    }
+    /** The component's config directory path. */
+    get componentConfigDir() {
+        return this.configDir;
+    }
+    /** Whether the writer timer is currently running. */
+    get isRunning() {
+        return this.timer !== undefined;
+    }
+    /**
+     * Start the writer timer.
+     *
+     * @remarks
+     * Performs an immediate first write, then sets up the interval.
+     */
+    start() {
+        if (this.timer)
+            return;
+        // Fire immediately, then on interval
+        void this.cycle();
+        this.timer = setInterval(() => void this.cycle(), this.component.refreshIntervalSeconds * 1000);
+    }
+    /** Stop the writer timer. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /**
+     * Execute a single write cycle.
+     *
+     * @remarks
+     * Calls `generateToolsContent()` and writes the component's
+     * TOOLS.md section via `updateManagedSection()`. Also calls
+     * `refreshPlatformContent()` for shared content maintenance.
+     */
+    async cycle() {
+        try {
+            const workspacePath = getWorkspacePath();
+            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
+            // Write the component's TOOLS.md section
+            const toolsContent = this.component.generateToolsContent();
+            await updateManagedSection(toolsPath, toolsContent, {
+                mode: 'section',
+                sectionId: this.component.sectionId,
+                markers: TOOLS_MARKERS,
+                coreVersion: CORE_VERSION,
+            });
+            // Platform content maintenance: SOUL.md, AGENTS.md, Platform section
+            await refreshPlatformContent({
+                coreVersion: CORE_VERSION,
+                componentName: this.component.name,
+                skipRegistryCheck: false,
+                probeTimeoutMs: this.probeTimeoutMs,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${message}`);
+        }
+    }
+}
+
+/**
+ * Factory function for creating a ComponentWriter.
+ *
+ * @remarks
+ * Validates the component descriptor at runtime:
+ * - `refreshIntervalSeconds` must be a prime number
+ * - `serviceCommands` and `pluginCommands` must be provided
+ * - `name`, `version`, `sectionId` must be non-empty strings
+ * - `generateToolsContent` must be a function
+ */
+/**
+ * Check whether a number is prime.
+ *
+ * @param n - Number to check.
+ * @returns `true` if n is prime.
+ */
+function isPrime(n) {
+    if (n < 2)
+        return false;
+    if (n === 2)
+        return true;
+    if (n % 2 === 0)
+        return false;
+    for (let i = 3; i * i <= n; i += 2) {
+        if (n % i === 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Validate a component descriptor at runtime.
+ *
+ * @param input - The descriptor to validate (typed as unknown for runtime safety).
+ * @throws Error if the descriptor is invalid.
+ */
+function validateDescriptor(input) {
+    const component = input;
+    if (!component['name'] || typeof component['name'] !== 'string') {
+        throw new Error('JeevesComponent.name must be a non-empty string');
+    }
+    if (!component['version'] || typeof component['version'] !== 'string') {
+        throw new Error('JeevesComponent.version must be a non-empty string');
+    }
+    if (!component['sectionId'] || typeof component['sectionId'] !== 'string') {
+        throw new Error('JeevesComponent.sectionId must be a non-empty string');
+    }
+    if (typeof component['refreshIntervalSeconds'] !== 'number' ||
+        !isPrime(component['refreshIntervalSeconds'])) {
+        throw new Error(`JeevesComponent.refreshIntervalSeconds must be a prime number, got ${String(component['refreshIntervalSeconds'])}`);
+    }
+    if (typeof component['generateToolsContent'] !== 'function') {
+        throw new Error('JeevesComponent.generateToolsContent must be a function');
+    }
+    const svc = component['serviceCommands'];
+    if (!svc ||
+        typeof svc['stop'] !== 'function' ||
+        typeof svc['uninstall'] !== 'function' ||
+        typeof svc['status'] !== 'function') {
+        throw new Error('JeevesComponent.serviceCommands must provide stop, uninstall, and status functions');
+    }
+    const plg = component['pluginCommands'];
+    if (!plg || typeof plg['uninstall'] !== 'function') {
+        throw new Error('JeevesComponent.pluginCommands must provide an uninstall function');
+    }
+}
+/**
+ * Create a ComponentWriter for a validated component descriptor.
+ *
+ * @param component - The component descriptor to validate and wrap.
+ * @param options - Optional configuration.
+ * @returns A new `ComponentWriter` instance.
+ * @throws Error if the component descriptor is invalid.
+ */
+function createComponentWriter(component, options) {
+    validateDescriptor(component);
+    return new ComponentWriter(component, options?.probeTimeoutMs);
+}
+
+/**
+ * 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,
+    });
+}
+
+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, createComponentWriter, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, parseManaged, probeAllServices, probeService, refreshPlatformContent, resetInit, seedContent, shingles, shouldWrite, updateManagedSection };