@karmaniverous/jeeves 0.1.6 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ That's it. I handle the rest.
 
 ## Who I Am
 
-My name is Jeeves. 
+My name is Jeeves.
 
 I add *identity* to OpenClaw: professional discipline, operational protocols, and a suite of services for data-wrangling, indexing, synthesis, and presentation.
 
@@ -60,19 +60,87 @@ I coordinate four service components. Each has its own repo, service, and OpenCl
 | [jeeves-runner](https://github.com/karmaniverous/jeeves-runner) | 1937 | Turing's paper in the *Proceedings* (1937) | Scheduled jobs, zero-LLM-cost scripts |
 | [jeeves-meta](https://github.com/karmaniverous/jeeves-meta) | 1938 | Shannon's switching circuits thesis (1938) | Three-step LLM synthesis |
 
-This package (`@karmaniverous/jeeves`) is the substrate they all share: managed workspace content, service discovery, config resolution, version-stamp convergence. It's a library and CLI. No daemon, no port, no tools registered with the gateway.
+This package (`@karmaniverous/jeeves`) is the substrate they all share: managed workspace content, service discovery, config resolution, version-stamp convergence, and a Plugin SDK for building component plugins. It's a library and CLI. No daemon, no port, no tools registered with the gateway.
 
-## For Platform Developers
+## Plugin SDK
 
-If you're building a component plugin, you implement one interface and call one factory:
+The Plugin SDK (`src/plugin/`) provides canonical types and utilities for building OpenClaw plugins that integrate with the Jeeves platform.
+
+### Core Types
+
+- **`PluginApi`** — the shape of the `api` object the OpenClaw gateway passes to plugins at registration time. Provides `config`, `resolvePath()`, and `registerTool()`.
+- **`ToolResult`** — result shape returned by tool executions: an array of content blocks plus an optional `isError` flag.
+- **`ToolDescriptor`** — tool definition for registration: `name`, `description`, `parameters` (JSON Schema), and an `execute` function.
+
+### Result Formatters
+
+- **`ok(data)`** — wraps arbitrary data as a successful `ToolResult` with JSON-stringified content.
+- **`fail(error)`** — wraps an error into a `ToolResult` with `isError: true`.
+- **`connectionFail(error, baseUrl, pluginId)`** — 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.
+
+### HTTP Helpers
+
+- **`fetchJson(url, init?)`** — thin wrapper around `fetch` that throws on non-OK responses and returns parsed JSON.
+- **`postJson(url, body)`** — POST JSON to a URL and return parsed response.
+
+### Resolution Helpers
+
+- **`resolveWorkspacePath(api)`** — resolves the workspace root from the plugin API via a three-step chain: `api.config.agents.defaults.workspace` → `api.resolvePath('.')` → `process.cwd()`.
+- **`resolvePluginSetting(api, pluginId, key, envVar, fallback)`** — resolves a plugin setting via: plugin config → environment variable → fallback value.
+
+### OpenClaw Config Utilities
+
+- **`resolveOpenClawHome()`** — resolves the OpenClaw home directory: `OPENCLAW_CONFIG` env (dirname) → `OPENCLAW_HOME` env → `~/.openclaw`.
+- **`resolveConfigPath(home)`** — resolves the OpenClaw config file path: `OPENCLAW_CONFIG` env → `{home}/openclaw.json`.
+- **`patchConfig(config, pluginId, mode)`** — idempotent config patching for plugin install/uninstall. Manages `plugins.entries.{pluginId}` and `tools.alsoAllow`.
+
+## Config Query Handler
+
+The `createConfigQueryHandler(getConfig)` factory produces a transport-agnostic handler for `GET /config` endpoints. It accepts a `getConfig` callback that returns the current config object.
+
+- No `path` parameter → returns the full config document.
+- Valid JSONPath expression → returns matching results with count (powered by `jsonpath-plus`).
+- Invalid JSONPath → returns a 400 error.
+
+Component services wire this into their HTTP server to expose config for diagnostic queries.
+
+## Managed Content System
+
+The managed content system maintains SOUL.md, AGENTS.md, and TOOLS.md without destroying user-authored content.
+
+### Key Functions
+
+- **`updateManagedSection(filePath, content, options)`** — writes managed content in either block mode (replaces entire managed block) or section mode (upserts a named H2 section within the block). Handles file locking, version-stamp convergence, cleanup detection, and atomic writes.
+- **`removeManagedSection(filePath, options)`** — removes a specific section or the entire managed block. If the last section is removed, the entire block is removed.
+- **`parseManaged(fileContent, markers)`** — parses a file into its managed block, version stamp, sections, and user content.
+- **`atomicWrite(filePath, content)`** — writes via a temp file + rename to prevent partial writes.
+- **`withFileLock(filePath, fn)`** — executes a callback while holding a file-level lock (2-minute stale threshold, 5 retries).
+
+### ManagedMarkers Type
+
+```typescript
+interface ManagedMarkers {
+  begin: string;  // BEGIN comment marker text
+  end: string;    // END comment marker text
+  title?: string; // Optional H1 title prepended inside managed block
+}
+```
+
+Pre-defined marker sets: `TOOLS_MARKERS`, `SOUL_MARKERS`, `AGENTS_MARKERS`.
+
+See the [Managed Content System](https://docs.karmanivero.us/jeeves/documents/Managed_Content_System.html) guide for the full deep-dive.
+
+## ComponentWriter and JeevesComponent
+
+Component plugins implement the `JeevesComponent` interface and use `createComponentWriter()` to get a timer-based orchestrator:
 
 ```typescript
 import { init, createComponentWriter } from '@karmaniverous/jeeves';
 import type { JeevesComponent } from '@karmaniverous/jeeves';
 
 init({
-  workspacePath: api.resolvePath('.'),
-  configRoot: api.getConfig('configRoot'),
+  workspacePath: resolveWorkspacePath(api),
+  configRoot: resolvePluginSetting(api, pluginId, 'configRoot', 'JEEVES_CONFIG_ROOT', 'j:/config'),
 });
 
 const writer = createComponentWriter({
@@ -88,18 +156,29 @@ const writer = createComponentWriter({
 writer.start();
 ```
 
-The writer handles everything: your TOOLS.md section, platform content (SOUL/AGENTS/Platform), file locking, version stamps, cleanup detection.
+On each cycle the writer calls `generateToolsContent()`, writes the component's TOOLS.md section, and runs `refreshPlatformContent()` to maintain SOUL.md, AGENTS.md, and the Platform section with live service health data.
+
+The `createAsyncContentCache({ fetch, placeholder? })` utility bridges the sync `generateToolsContent` interface with async data sources — returns a sync `() => string` that serves cached content while refreshing in the background.
 
-See the [Building a Component Plugin](https://docs.karmanivero.us/jeeves/documents/guides_building-a-component-plugin.html) guide for the full walkthrough.
+See the [Building a Component Plugin](https://docs.karmanivero.us/jeeves/documents/Building_a_Component_Plugin.html) guide for the full walkthrough.
+
+## Service Discovery
+
+- **`getServiceUrl(serviceName, consumerName?)`** — resolves a service URL via: consumer config → core config → default port constants.
+- **`probeService(serviceName, consumerName?, timeoutMs?)`** — probes `/status` then `/health` endpoints, returns a `ProbeResult` with health status and version.
+- **`probeAllServices(consumerName?, timeoutMs?)`** — probes all known services (server, watcher, runner, meta).
+- **`checkRegistryVersion(packageName, cacheDir, ttlSeconds?)`** — checks npm registry for the latest version with local file caching (default 1-hour TTL).
 
 ## CLI
 
 ```bash
-jeeves install     # Bootstrap identity, protocols, platform content
-jeeves uninstall   # Remove managed sections and artifacts
-jeeves status      # Probe all service ports, report health
+jeeves install     # Seed identity, protocols, platform content; create core config
+jeeves uninstall   # Remove managed sections, templates, config schema
+jeeves status      # Probe all service ports, report health table
 ```
 
+All three commands accept `--workspace <path>` and `--config-root <path>` options.
+
 ## Configuration
 
 Core config at `{configRoot}/jeeves-core/config.json`:

package/content/agents-section.md

@@ -177,7 +177,11 @@ No stranded local branches. Push immediately after commit. A commit that isn't p
 
 ### Check PR State Before Pushing
 
-Always verify a PR isn't already merged before pushing commits. Pushing to a merged branch creates orphaned work.
+**Before EVERY `git push`**, verify the PR is not already merged. Pushing to a merged branch creates orphaned work that is invisible in the main branch and wastes effort.
+
+Sequence: `gh pr view --json state` → confirm state is `OPEN` → push. If no PR exists yet, pushing is safe. If the PR is `MERGED` or `CLOSED`, **STOP** and report to the user.
+
+This is not optional. It applies to every push, every branch, every time.
 
 ## Managed Content Self-Maintenance
 

package/content/soul-section.md

@@ -72,6 +72,14 @@ I don't go dark when something breaks. I stop and report. The longer I wait, the
 
 After diagnosing an issue: I propose a fix, explain the reasoning, and **wait for approval**. Diagnose → propose → wait. The human decides whether and when to act.
 
+### Do Not Execute Untested Code
+
+Every ad hoc mutation script defaults to **dry-run mode**. Live execution requires an explicit `--live` flag. The dry-run IS the test — run it first, inspect the output, then execute live only when the dry-run proves correct.
+
+Maintain a tested utility library so ad hoc scripts build on proven foundations. One-off scripts composed of untested primitives are how data gets corrupted.
+
+*Earned: ad hoc scripts executed directly against production data without dry-run verification caused silent data corruption that took hours to diagnose and repair.*
+
 ### Production Assets Are Sacred
 
 I never edit production config without explicit approval. I back up first. Production data, credentials, and configuration are not scratch pads.

package/content/templates/spec.md

@@ -25,6 +25,12 @@ previous: "{previous-spec-filename}"
 3. When Next Version is implemented: freeze the spec, run the checklist
 4. On green: archive spec as `spec-v{next}.md`, update Current Version to match reality, promote backlog items to Next Version
 
+## Spec Hygiene
+
+- **Frontmatter is mandatory.** Every spec must have `version`, `date`, and `status` fields in the YAML frontmatter. The `status` field tracks the spec lifecycle: `Pre-version (design)`, `In progress`, `Complete`, `Archived`.
+- **Decisions are numbered.** Use sequential numbering (`Decision 1`, `Decision 2`, ...) so they can be cross-referenced from dev plan tasks, other decisions, and external documents. Never renumber — append only.
+- **Dev plan tasks have dependency ordering.** Every task in the dev plan table must have a `Depends On` column referencing prerequisite task numbers (or `—` for none). Tasks should be ordered so dependencies come first. This enforces implementation sequencing and makes parallel work visible.
+
 ## 1. Overview
 
 <!-- What is this package? What problem does it solve? What are its boundaries?

package/content/tools-platform.md

@@ -1,16 +1,6 @@
-| Component | Port | Status | Service | Plugin | Core |
-|-----------|------|--------|---------|--------|------|
-{{#each services}}
-| **{{name}}** | {{port}} | {{#if healthy}}✅ Running{{else}}{{#if error}}⚠️ {{error}}{{else}}❌ Down{{/if}}{{/if}} | {{#if version}}{{version}}{{#if availableServiceVersion}} (⬆ {{availableServiceVersion}}){{/if}}{{else}}—{{/if}} | {{#if pluginVersion}}{{pluginVersion}}{{#if availablePluginVersion}} (⬆ {{availablePluginVersion}}){{/if}}{{else}}—{{/if}} | {{../coreVersion}}{{#if ../availableCoreVersion}} (⬆ {{../availableCoreVersion}}){{/if}} |
-{{/each}}
-
-{{#if unhealthyServices}}
-> **ACTION REQUIRED:** {{#each unhealthyServices}}{{name}}{{#unless @last}}, {{/unless}}{{/each}} {{#if (gt unhealthyServices.length 1)}}are{{else}}is{{/if}} unreachable. Read the relevant component skill for troubleshooting and bootstrap guidance.
-{{/if}}
-
 ### Tool Hierarchy
 
-When searching for information across indexed paths, **always use `watcher_search` before filesystem commands** (`exec`, `grep`, `find`). The semantic index covers {{#if pointCount}}{{pointCount}} document chunks{{else}}the full indexed corpus{{/if}} and surfaces related files you may not have considered.
+When searching for information across indexed paths, **always use `watcher_search` before filesystem commands** (`exec`, `grep`, `find`). The semantic index covers the full indexed corpus and surfaces related files you may not have considered.
 
 Use `watcher_scan` (no embeddings, no query string) for structural queries: file enumeration, staleness checks, domain listing, counts.
 
@@ -54,8 +44,8 @@ Never manually edit `~/.openclaw/extensions/`. Always use the CLI commands above
 
 ### Reference Templates
 
-{{#if templatesAvailable}}
-Reference templates are available at `{{templatePath}}`:
+<!-- IF_TEMPLATES -->
+Reference templates are available at `__TEMPLATE_PATH__`:
 
 | Template | Purpose |
 |----------|---------|
@@ -63,6 +53,6 @@ Reference templates are available at `{{templatePath}}`:
 | `spec-to-code-guide.md` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |
 
 Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
-{{else}}
+<!-- ELSE_TEMPLATES -->
 > Reference templates not yet installed. Run `npx @karmaniverous/jeeves install` to seed templates.
-{{/if}}
+<!-- ENDIF_TEMPLATES -->