@karmaniverous/jeeves 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,180 @@
 import { z } from 'zod';
 
+/**
+ * Generic config query handler with JSONPath support.
+ *
+ * @remarks
+ * Provides a transport-agnostic config query function that can be
+ * used by any Jeeves component's HTTP API. Returns the full config
+ * document or filters it via JSONPath expressions.
+ */
+/** Response shape for config query results. */
+interface ConfigQueryResponse {
+    /** HTTP status code. */
+    status: number;
+    /** Response body. */
+    body: unknown;
+}
+/**
+ * Handler function type for config queries.
+ *
+ * @param query - Query parameters.
+ * @returns Response with status code and body.
+ */
+type ConfigQueryHandler = (query: {
+    path?: string;
+}) => Promise<ConfigQueryResponse>;
+/**
+ * Create a config query handler.
+ *
+ * @remarks
+ * - No `path` parameter → returns the full config document.
+ * - Valid JSONPath → returns matching results with count.
+ * - Invalid JSONPath → returns 400 error.
+ *
+ * @param getConfig - Function that returns the current config object.
+ * @returns A config query handler function.
+ */
+declare function createConfigQueryHandler(getConfig: () => unknown): ConfigQueryHandler;
+
+/**
+ * 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.
+ */
+/** Version entry for a single component. */
+interface ComponentVersionEntry {
+    /** Service version from health probe. */
+    serviceVersion?: string;
+    /** Plugin version (the OpenClaw plugin package version). */
+    pluginVersion?: string;
+    /** npm package name for the service. */
+    servicePackage?: string;
+    /** npm package name for the plugin. */
+    pluginPackage?: string;
+    /** ISO timestamp of last update. */
+    updatedAt: string;
+}
+/** Shape of the component-versions.json file. */
+type ComponentVersionsState = Record<string, ComponentVersionEntry>;
+/**
+ * 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.
+ */
+declare function readComponentVersions(coreConfigDir: string): ComponentVersionsState;
+/** Options for writing a component version entry. */
+interface WriteComponentVersionOptions {
+    /** Component name. */
+    componentName: string;
+    /** Service version from probe, if available. */
+    serviceVersion?: string;
+    /** Plugin version. */
+    pluginVersion?: string;
+    /** Service npm package name. */
+    servicePackage?: string;
+    /** Plugin npm package name. */
+    pluginPackage?: string;
+}
+/**
+ * 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.
+ */
+declare function writeComponentVersion(coreConfigDir: string, options: WriteComponentVersionOptions): void;
+
+/**
+ * Core types for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * These types define the contract between plugins and the OpenClaw gateway.
+ * They unify the various `PluginApi` definitions previously duplicated
+ * across component plugins into a single canonical source.
+ */
+/** Result shape returned by tool executions. */
+interface ToolResult {
+    /** Content blocks — typically a single text block. */
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    /** Whether this result represents an error. */
+    isError?: boolean;
+}
+/** Tool descriptor for registration with the OpenClaw gateway. */
+interface ToolDescriptor {
+    /** Unique tool name. */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** JSON Schema for the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /** Execute the tool with the given parameters. */
+    execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Options for tool registration. */
+interface ToolRegistrationOptions {
+    /** Whether the tool is optional (non-fatal if registration fails). */
+    optional?: boolean;
+}
+/**
+ * Canonical OpenClaw plugin API interface.
+ *
+ * @remarks
+ * This is the shape of the `api` object passed to plugins by the
+ * OpenClaw gateway at registration time. Fields are optional where
+ * the gateway may not provide them in all versions.
+ */
+interface PluginApi {
+    /** OpenClaw configuration object. */
+    config?: {
+        /** Agent configuration block. */
+        agents?: {
+            /** Default agent settings. */
+            defaults?: {
+                /** Absolute path to the workspace root directory. */
+                workspace?: string;
+            };
+        };
+        /** Installed plugin configuration. */
+        plugins?: {
+            /** Plugin entries keyed by plugin ID. */
+            entries?: Record<string, {
+                config?: Record<string, unknown>;
+            }>;
+        };
+    };
+    /**
+     * Resolve a path relative to the OpenClaw workspace.
+     *
+     * @remarks
+     * Present on newer OpenClaw builds; optional for backwards compatibility.
+     */
+    resolvePath?: (input: string) => string;
+    /**
+     * Register a tool with the OpenClaw gateway.
+     *
+     * @param tool - Tool descriptor.
+     * @param options - Registration options.
+     */
+    registerTool(tool: ToolDescriptor, options?: ToolRegistrationOptions): void;
+}
+/**
+ * Alias for `PluginApi`, retained for backward compatibility.
+ *
+ * Prefer `PluginApi` for new code. This alias will be removed in v0.3.0.
+ */
+type PluginApiLike = PluginApi;
+
 /**
  * Component interface types for the Jeeves platform.
  *
@@ -8,6 +183,7 @@ import { z } from 'zod';
  * to participate in the platform. The `JeevesComponent` interface is
  * the primary integration point.
  */
+
 /** Service health status. */
 interface ServiceStatus {
     /** Whether the service is running. */
@@ -38,8 +214,12 @@ interface PluginCommands {
 interface JeevesComponent {
     /** Component name (e.g., 'watcher', 'runner', 'server', 'meta'). */
     name: string;
-    /** Component's own version. */
+    /** Component's own version (plugin package version). */
     version: string;
+    /** npm package name for the service (e.g., `\@karmaniverous/jeeves-watcher`). */
+    servicePackage?: string;
+    /** npm package name for the plugin (e.g., `\@karmaniverous/jeeves-watcher-openclaw`). */
+    pluginPackage?: string;
     /** TOOLS.md section name (e.g., 'Watcher'). */
     sectionId: string;
     /** Refresh interval in seconds (must be a prime number). */
@@ -184,51 +364,39 @@ interface CreateComponentWriterOptions {
 declare function createComponentWriter(component: JeevesComponent, options?: CreateComponentWriterOptions): ComponentWriter;
 
 /**
- * Resolve the OpenClaw workspace root from the plugin API.
+ * Plugin resolution helpers for the OpenClaw plugin SDK.
  *
  * @remarks
- * Tries three sources in order:
- * 1. `api.config.agents.defaults.workspace` — explicit config (most authoritative)
- * 2. `api.resolvePath('.')` — gateway-provided path resolver
- * 3. `process.cwd()` — last resort (unsafe when gateway runs from system32)
- *
- * The config value is checked first because `api.resolvePath('.')` delegates
- * to `path.resolve('.')`, which returns `process.cwd()` — not the workspace.
- * When the gateway runs as a Windows service from `C:\Windows\system32`,
- * `resolvePath('.')` returns system32, not the configured workspace.
- *
- * Plugins should call this once at registration time and pass the result
- * to `init({ workspacePath })`.
+ * Provides workspace path resolution and plugin setting resolution
+ * with a standard three-step fallback chain:
+ * plugin config → environment variable → default value.
  */
+
 /**
- * Minimal shape of the OpenClaw plugin API needed for workspace resolution.
+ * Resolve the workspace root from the OpenClaw plugin API.
  *
  * @remarks
- * Intentionally loose — plugins define their own full `PluginApi` type.
- * This captures only the fields `resolveWorkspacePath` inspects.
+ * Tries three sources in order:
+ * 1. `api.config.agents.defaults.workspace` — explicit config
+ * 2. `api.resolvePath('.')` — gateway-provided path resolver
+ * 3. `process.cwd()` — last resort
+ *
+ * @param api - The plugin API object provided by the gateway.
+ * @returns Absolute path to the workspace root.
  */
-interface PluginApiLike {
-    /** Gateway-provided path resolver. May not exist in all gateway versions. */
-    resolvePath?: (input: string) => string;
-    /** OpenClaw configuration object. */
-    config?: {
-        /** Agent configuration block. */
-        agents?: {
-            /** Default agent settings. */
-            defaults?: {
-                /** Absolute path to the workspace root directory. */
-                workspace?: string;
-            };
-        };
-    };
-}
+declare function resolveWorkspacePath(api: PluginApi): string;
 /**
- * Resolve the workspace root from the OpenClaw plugin API.
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → fallback value.
  *
- * @param api - The plugin API object provided by the gateway at registration.
- * @returns Absolute path to the workspace root.
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
+ * @returns The resolved setting value.
  */
-declare function resolveWorkspacePath(api: PluginApiLike): string;
+declare function resolvePluginSetting(api: PluginApi, pluginId: string, key: string, envVar: string, fallback: string): string;
 
 /**
  * Comment markers for managed content blocks.
@@ -239,29 +407,21 @@ declare function resolveWorkspacePath(api: PluginApiLike): string;
  * atomically on each writer cycle. User content outside the markers
  * is never touched.
  */
-/** Default markers for TOOLS.md managed block. */
-declare const TOOLS_MARKERS: {
+/** Shape of managed content markers used by updateManagedSection and removeManagedSection. */
+interface ManagedMarkers {
     /** BEGIN comment marker text. */
-    readonly begin: "BEGIN JEEVES PLATFORM TOOLS — DO NOT EDIT THIS SECTION";
+    begin: string;
     /** END comment marker text. */
-    readonly end: "END JEEVES PLATFORM TOOLS";
-    /** H1 title prepended in section mode. */
-    readonly title: "Jeeves Platform Tools";
-};
+    end: string;
+    /** Optional H1 title prepended inside the managed block. */
+    title?: string;
+}
+/** Default markers for TOOLS.md managed block. */
+declare const TOOLS_MARKERS: ManagedMarkers;
 /** Default markers for SOUL.md managed block. */
-declare const SOUL_MARKERS: {
-    /** BEGIN comment marker text. */
-    readonly begin: "BEGIN JEEVES SOUL — DO NOT EDIT THIS SECTION";
-    /** END comment marker text. */
-    readonly end: "END JEEVES SOUL";
-};
+declare const SOUL_MARKERS: ManagedMarkers;
 /** Default markers for AGENTS.md managed block. */
-declare const AGENTS_MARKERS: {
-    /** BEGIN comment marker text. */
-    readonly begin: "BEGIN JEEVES AGENTS — DO NOT EDIT THIS SECTION";
-    /** END comment marker text. */
-    readonly end: "END JEEVES AGENTS";
-};
+declare const AGENTS_MARKERS: ManagedMarkers;
 /**
  * Regex pattern to extract version stamp from a BEGIN marker comment.
  *
@@ -297,6 +457,8 @@ declare const TEMPLATES_DIR = "templates";
 declare const REGISTRY_CACHE_FILE = "registry-cache.json";
 /** Core config file name. */
 declare const CONFIG_FILE = "config.json";
+/** Component versions state file name. */
+declare const COMPONENT_VERSIONS_FILE = "component-versions.json";
 
 /**
  * Default port assignments for Jeeves platform services.
@@ -348,17 +510,16 @@ type SectionId = (typeof SECTION_IDS)[keyof typeof SECTION_IDS];
 declare const SECTION_ORDER: readonly string[];
 
 /**
- * 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 `__JEEVES_CORE_VERSION__` placeholder is replaced by
+ * `@rollup/plugin-replace` during the build with the actual version
+ * from `package.json`. This ensures the correct version survives
+ * when consumers bundle core into their own dist (where runtime
+ * `import.meta.url`-based resolution would find the wrong package.json).
  */
-/** The core library version from package.json. */
+/** The core library version from package.json (inlined at build time). */
 declare const CORE_VERSION: string;
 
 /**
@@ -592,6 +753,38 @@ declare function jaccard(a: Set<string>, b: Set<string>): number;
  */
 declare function needsCleanup(managedContent: string, userContent: string, threshold?: number): boolean;
 
+/**
+ * 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). */
+declare const STALE_LOCK_MS = 120000;
+/** Default core version when none provided. */
+declare const DEFAULT_CORE_VERSION = "0.0.0";
+/**
+ * Write content to a file atomically via a temp file + rename.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param content - Content to write.
+ */
+declare function atomicWrite(filePath: string, content: string): void;
+/**
+ * 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.
+ */
+declare function withFileLock(filePath: string, fn: () => void | Promise<void>): Promise<void>;
+
 /**
  * Parse managed block from file content.
  *
@@ -641,6 +834,35 @@ declare function parseManaged(fileContent: string, markers?: {
     end: string;
 }): ParseManagedResult;
 
+/**
+ * Remove a managed section or entire managed block from a file.
+ *
+ * @remarks
+ * Supports two modes:
+ * - No `sectionId`: Remove the entire managed block (markers + content),
+ *   leaving user content intact.
+ * - With `sectionId`: Remove a specific H2 section from within the
+ *   managed block. If it was the last section, remove the entire block.
+ *
+ * Provides file-level locking and atomic writes (temp file + rename).
+ * Missing markers or nonexistent sections are no-ops (no error thrown).
+ */
+
+/** Options for removeManagedSection. */
+interface RemoveManagedSectionOptions {
+    /** Section ID to remove. If omitted, removes the entire managed block. */
+    sectionId?: string;
+    /** Custom markers. Defaults to TOOLS markers. */
+    markers?: ManagedMarkers;
+}
+/**
+ * Remove a managed section or entire managed block from a file.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param options - Optional section ID and custom markers.
+ */
+declare function removeManagedSection(filePath: string, options?: RemoveManagedSectionOptions): Promise<void>;
+
 /**
  * Generic managed-section writer with block and section modes.
  *
@@ -651,6 +873,7 @@ declare function parseManaged(fileContent: string, markers?: {
  *
  * Provides file-level locking, version-stamp convergence, and atomic writes.
  */
+
 /** Options for updateManagedSection. */
 interface UpdateManagedSectionOptions {
     /** Write mode. Default: 'block'. */
@@ -658,14 +881,7 @@ interface UpdateManagedSectionOptions {
     /** Section ID — required when mode is 'section'. */
     sectionId?: string;
     /** Custom markers. Defaults to TOOLS markers. */
-    markers?: {
-        /** BEGIN comment marker text. */
-        begin: string;
-        /** END comment marker text. */
-        end: string;
-        /** Optional H1 title prepended in section mode. */
-        title?: string;
-    };
+    markers?: ManagedMarkers;
     /** Core library version for version-stamp convergence. */
     coreVersion?: string;
     /** Staleness threshold in ms for version-stamp convergence. */
@@ -730,6 +946,12 @@ interface RefreshPlatformContentOptions {
     coreVersion: string;
     /** Component name (for registry cache directory). */
     componentName?: string;
+    /** Component plugin version (e.g., '0.2.0'). */
+    componentVersion?: string;
+    /** npm package name for the service (for registry update check). */
+    servicePackage?: string;
+    /** npm package name for the plugin (for registry update check). */
+    pluginPackage?: string;
     /** Staleness threshold override in ms. */
     stalenessThresholdMs?: number;
     /** Timeout for health probes in ms. */
@@ -773,5 +995,113 @@ interface SeedContentOptions {
  */
 declare function seedContent(options: SeedContentOptions): Promise<void>;
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, checkRegistryVersion, coreConfigSchema, createAsyncContentCache, createComponentWriter, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, parseManaged, probeAllServices, probeService, refreshPlatformContent, resetInit, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection };
-export type { AsyncContentCacheOptions, CoreConfig, CreateComponentWriterOptions, InitOptions, JeevesComponent, ManagedSection, ParseManagedResult, PluginApiLike, PluginCommands, ProbeResult, RefreshPlatformContentOptions, SectionId, SeedContentOptions, ServiceCommands, ServiceStatus, UpdateManagedSectionOptions, VersionStamp };
+/**
+ * HTTP helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Thin wrappers around `fetch` that throw on non-OK responses
+ * and handle JSON serialisation/deserialisation.
+ */
+/**
+ * Fetch JSON from a URL, throwing on non-OK responses.
+ *
+ * @param url - URL to fetch.
+ * @param init - Optional `fetch` init options.
+ * @returns Parsed JSON response body.
+ * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
+ */
+declare function fetchJson(url: string, init?: RequestInit): Promise<unknown>;
+/**
+ * POST JSON to a URL and return parsed response.
+ *
+ * @param url - URL to POST to.
+ * @param body - Request body (will be JSON-stringified).
+ * @returns Parsed JSON response body.
+ */
+declare function postJson(url: string, body: unknown): Promise<unknown>;
+
+/**
+ * OpenClaw configuration helpers for plugin CLI installers.
+ *
+ * @remarks
+ * Provides resolution of OpenClaw home directory and config file path,
+ * plus idempotent config patching for plugin install/uninstall.
+ */
+/**
+ * Resolve the OpenClaw home directory.
+ *
+ * @remarks
+ * Resolution order:
+ * 1. `OPENCLAW_CONFIG` env var → dirname of the config file path
+ * 2. `OPENCLAW_HOME` env var → resolved path
+ * 3. Default: `~/.openclaw`
+ *
+ * @returns Absolute path to the OpenClaw home directory.
+ */
+declare function resolveOpenClawHome(): string;
+/**
+ * Resolve the OpenClaw config file path.
+ *
+ * @remarks
+ * If `OPENCLAW_CONFIG` is set, uses that directly.
+ * Otherwise defaults to `{home}/openclaw.json`.
+ *
+ * @param home - The OpenClaw home directory.
+ * @returns Absolute path to the config file.
+ */
+declare function resolveConfigPath(home: string): string;
+/**
+ * Patch an OpenClaw config for plugin install or uninstall.
+ *
+ * @remarks
+ * Manages `plugins.entries.{pluginId}` and `tools.alsoAllow`.
+ * Idempotent: adding twice produces no duplicates; removing when absent
+ * produces no errors.
+ *
+ * @param config - The parsed OpenClaw config object (mutated in place).
+ * @param pluginId - The plugin identifier.
+ * @param mode - Whether to add or remove the plugin.
+ * @returns Array of log messages describing changes made.
+ */
+declare function patchConfig(config: Record<string, unknown>, pluginId: string, mode: 'add' | 'remove'): string[];
+
+/**
+ * Tool result formatters for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Provides standardised helpers for building `ToolResult` objects:
+ * success, error, and connection-error variants.
+ */
+
+/**
+ * Format a successful tool result.
+ *
+ * @param data - Arbitrary data to return as JSON.
+ * @returns A `ToolResult` with JSON-stringified content.
+ */
+declare function ok(data: unknown): ToolResult;
+/**
+ * Format an error tool result.
+ *
+ * @param error - Error instance, string, or other value.
+ * @returns A `ToolResult` with `isError: true`.
+ */
+declare function fail(error: unknown): ToolResult;
+/**
+ * Format a connection error with actionable guidance.
+ *
+ * @remarks
+ * Detects `ECONNREFUSED`, `ENOTFOUND`, and `ETIMEDOUT` from
+ * `error.cause.code` and returns a user-friendly message referencing
+ * the plugin's `config.apiUrl` setting. Falls back to `fail()` for
+ * non-connection errors.
+ *
+ * @param error - Error instance (typically from `fetch`).
+ * @param baseUrl - The URL that was being contacted.
+ * @param pluginId - The plugin identifier for config guidance.
+ * @returns A `ToolResult` with `isError: true`.
+ */
+declare function connectionFail(error: unknown, baseUrl: string, pluginId: string): ToolResult;
+
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_CORE_VERSION, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, probeAllServices, probeService, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };
+export type { AsyncContentCacheOptions, ComponentVersionEntry, ComponentVersionsState, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreateComponentWriterOptions, InitOptions, JeevesComponent, ManagedMarkers, ManagedSection, ParseManagedResult, PluginApi, PluginApiLike, PluginCommands, ProbeResult, RefreshPlatformContentOptions, RemoveManagedSectionOptions, SectionId, SeedContentOptions, ServiceCommands, ServiceStatus, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WriteComponentVersionOptions };