@karmaniverous/jeeves 0.4.6 → 0.5.0

package/dist/cli/plugin/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, rmSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
+import { writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync, readFileSync, readdirSync, copyFileSync, rmSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import * as commander from 'commander';
+import { packageDirectorySync } from 'package-directory';
 import { lock } from 'proper-lockfile';
 import 'semver';
 import { homedir } from 'node:os';
@@ -111,7 +112,13 @@ const WORKSPACE_FILES = {
     agents: 'AGENTS.md',
     /** HEARTBEAT.md — platform status and health alerts. */
     heartbeat: 'HEARTBEAT.md',
+    /** MEMORY.md — curated long-term memory. */
+    memory: 'MEMORY.md',
 };
+/** Skill directory name within workspace. */
+const SKILLS_DIR = 'skills';
+/** Jeeves skill directory name. */
+const JEEVES_SKILL_DIR = 'jeeves';
 /** Component versions state file name. */
 const COMPONENT_VERSIONS_FILE = 'component-versions.json';
 
@@ -119,14 +126,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.5` placeholder is replaced by
+ * The `0.4.7` 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 (inlined at build time). */
-const CORE_VERSION = '0.4.5';
+const CORE_VERSION = '0.4.7';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -224,6 +231,30 @@ function readComponentVersions(coreConfigDir) {
         return {};
     }
 }
+/**
+ * Write a component's version entry to the shared state file.
+ *
+ * @remarks
+ * Reads the existing file, merges the new entry, and writes atomically.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param options - Component version data to write.
+ */
+function writeComponentVersion(coreConfigDir, options) {
+    const existing = readComponentVersions(coreConfigDir);
+    existing[options.componentName] = {
+        pluginVersion: options.pluginVersion,
+        servicePackage: options.servicePackage,
+        pluginPackage: options.pluginPackage,
+        updatedAt: new Date().toISOString(),
+    };
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
 /**
  * Remove a component's version entry from the shared state file.
  *
@@ -683,6 +714,129 @@ function buildWithSections(beforeContent, userContent, sections, markers, coreVe
     return parts.join('\n');
 }
 
+var skillContent = `---
+name: jeeves
+description: Jeeves platform architecture, data flow, component interaction, scripts repo, and coordination knowledge. Use when making architectural decisions, coordinating across components, checking platform health, managing service lifecycle, or working with the scripts repo.
+---
+
+# Jeeves Platform Skill
+
+## Platform Architecture
+
+Jeeves is a four-component platform coordinated by a shared library (\`@karmaniverous/jeeves\`):
+
+| Component | Role | Port |
+|-----------|------|------|
+| **jeeves-runner** | Execute: scheduled jobs, SQLite state, HTTP API | 1937 |
+| **jeeves-watcher** | Index: file→Qdrant semantic indexing, inference rules | 1936 |
+| **jeeves-server** | Present: web UI, file browser, doc render, export | 1934 |
+| **jeeves-meta** | Distill: LLM synthesis, .meta/ directories, scheduling | 1938 |
+
+Core (\`@karmaniverous/jeeves\`) is a **library + CLI**, not a service. No port.
+
+## Data Flow
+
+\`\`\`
+Files → Watcher (index) → Qdrant → Meta (synthesize) → .meta/ → Watcher (re-index)
+                                                                      ↓
+Runner (schedule) → Scripts → Services ← Server (present) ← Browser
+\`\`\`
+
+## Component Interaction
+
+- **Watcher** indexes files into Qdrant with inference rules and enrichments.
+- **Meta** reads from Qdrant, synthesizes \`.meta/\` directories, which watcher re-indexes.
+- **Runner** executes scheduled scripts that may call any service's HTTP API.
+- **Server** presents files, renders documents, and provides the event gateway.
+- **Core** provides shared content management (TOOLS.md, SOUL.md, AGENTS.md), service discovery, config resolution, and the component SDK.
+
+## Service Discovery
+
+Services find each other via config resolution:
+1. Component's own config file (\`{configRoot}/jeeves-{name}/config.json\`)
+2. Core config file (\`{configRoot}/jeeves-core/config.json\`)
+3. Default port constants
+
+## Scripts Repo
+
+Location: \`{configRoot}/jeeves-core/scripts/\`
+Template: \`@karmaniverous/jeeves-scripts-template\`
+
+Scripts use utilities from \`@karmaniverous/jeeves\` (general) and \`@karmaniverous/jeeves-runner\` (runner-specific). Any script that could be useful outside runner scheduling belongs in core.
+
+## Managed Content System
+
+Core maintains managed sections in workspace files using comment markers:
+- **TOOLS.md** — Component sections (section mode) + Platform section
+- **SOUL.md** — Professional discipline and behavioral foundations (block mode)
+- **AGENTS.md** — Operational protocols and memory architecture (block mode)
+- **HEARTBEAT.md** — Platform health status (heading-based)
+
+Managed blocks are stationary after initial insertion. Cleanup detection uses Jaccard similarity on 3-word shingles. Cleanup escalation spawns a gateway session when orphaned content is detected.
+
+## Workspace Configuration
+
+\`jeeves.config.json\` at workspace root provides shared defaults:
+- Precedence: CLI flags → env vars → file → defaults
+- Namespaced: \`core.*\` (workspace, configRoot, gatewayUrl) and \`memory.*\` (budget, warningThreshold, staleDays)
+- Inspect with \`jeeves config [jsonpath]\`
+
+## HEARTBEAT Protocol
+
+The HEARTBEAT system uses a state machine per component:
+\`not_installed → deps_missing → config_missing → service_not_installed → service_stopped → healthy\`
+
+Dependency-aware: hard deps block alerts, soft deps add informational notes. Declined components are tracked via heading suffix.
+
+## Plugin Lifecycle
+
+\`\`\`bash
+# Core install (seed workspace content)
+npx @karmaniverous/jeeves install
+
+# Component plugin install
+npx @karmaniverous/jeeves-{component}-openclaw install
+
+# Component plugin uninstall
+npx @karmaniverous/jeeves-{component}-openclaw uninstall
+
+# Core uninstall (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+\`\`\`
+
+## Memory Hygiene
+
+MEMORY.md has a character budget (default 20,000). Core tracks:
+- Character count and usage percentage
+- Warning at 80% of budget
+- Stale section candidates (H2 sections whose most recent ISO date exceeds the staleness threshold)
+- Evergreen sections (no dates) are never flagged
+
+Review is human/agent-mediated — core does not auto-delete.
+`;
+
+/**
+ * Skill seeding: write the `jeeves` workspace skill unconditionally.
+ *
+ * @remarks
+ * The skill file is entirely generated — no user-authored content (Decision 48).
+ * Every installer (core CLI and component plugins) writes it unconditionally.
+ * Content is inlined at build time via `rollup-plugin-md.ts`.
+ */
+/**
+ * Seed the jeeves workspace skill file.
+ *
+ * @param workspacePath - Workspace root directory.
+ */
+function seedSkill(workspacePath) {
+    const skillDir = join(workspacePath, SKILLS_DIR, JEEVES_SKILL_DIR);
+    if (!existsSync(skillDir)) {
+        mkdirSync(skillDir, { recursive: true });
+    }
+    const skillPath = join(skillDir, 'SKILL.md');
+    writeFileSync(skillPath, skillContent, 'utf-8');
+}
+
 /**
  * OpenClaw configuration helpers for plugin CLI installers.
  *
@@ -802,13 +956,9 @@ function patchConfig(config, pluginId, mode) {
 }
 
 /**
- * Factory for the standard `-openclaw` plugin installer CLI.
+ * Internal helpers for the plugin installer CLI.
  *
- * @remarks
- * Produces a Commander program with `install` and `uninstall` commands
- * that handle the full plugin lifecycle: copy dist to extensions,
- * patch OpenClaw config, manage HEARTBEAT entries, and clean up
- * managed sections on uninstall.
+ * @module
  */
 /**
  * Derive a component name from a plugin ID.
@@ -823,7 +973,7 @@ function deriveComponentName(pluginId) {
     return pluginId.replace(/^jeeves-/, '').replace(/-openclaw$/, '');
 }
 /**
- * Copy all files from source directory to destination.
+ * Copy all files from source directory to destination, recursively.
  *
  * @param srcDir - Source directory.
  * @param destDir - Destination directory.
@@ -857,6 +1007,12 @@ function readJsonFile(filePath) {
         return {};
     }
 }
+
+/**
+ * Factory for the standard `-openclaw` plugin installer CLI.
+ *
+ * @module
+ */
 /**
  * Create a standard plugin installer CLI program.
  *
@@ -882,6 +1038,16 @@ function createPluginCli(options) {
         const extensionsDir = join(openClawHome, 'extensions', pluginId);
         console.log(`Copying dist to ${extensionsDir}...`);
         copyDistFiles(distDir, extensionsDir);
+        // Copy package.json and openclaw.plugin.json from package root
+        const pkgRoot = packageDirectorySync({ cwd: distDir });
+        if (pkgRoot) {
+            for (const file of ['package.json', 'openclaw.plugin.json']) {
+                const src = join(pkgRoot, file);
+                if (existsSync(src)) {
+                    copyFileSync(src, join(extensionsDir, file));
+                }
+            }
+        }
         console.log('  ✓ Dist files copied');
         // 2. Patch openclaw.json
         console.log('Patching OpenClaw config...');
@@ -910,7 +1076,7 @@ function createPluginCli(options) {
         for (const msg of messages) {
             console.log(`  ✓ ${msg}`);
         }
-        // 4. Write initial HEARTBEAT entry
+        // 4. Write initial HEARTBEAT entry and seed jeeves skill
         try {
             const cfgRoot = opts.configRoot;
             const agents = config.agents;
@@ -925,7 +1091,6 @@ function createPluginCli(options) {
                         : '';
                     const parsed = parseHeartbeat(existing);
                     const fullName = `jeeves-${componentName}`;
-                    // Only add if not already present
                     const hasEntry = parsed.entries.some((e) => e.name === fullName);
                     if (!hasEntry) {
                         parsed.entries.push({
@@ -941,10 +1106,36 @@ function createPluginCli(options) {
                 catch {
                     console.log('  ⚠ Could not write HEARTBEAT entry');
                 }
+                try {
+                    seedSkill(ws);
+                    console.log('  ✓ Jeeves skill seeded');
+                }
+                catch {
+                    console.log('  ⚠ Could not seed Jeeves skill');
+                }
             }
         }
         catch {
-            // HEARTBEAT is best-effort during install
+            // HEARTBEAT + skill seeding are best-effort during install
+        }
+        // 5. Write component version
+        try {
+            init({
+                workspacePath: opts.workspace ?? '.',
+                configRoot: opts.configRoot,
+            });
+            const pkgJsonPath = join(extensionsDir, 'package.json');
+            const pkgJson = readJsonFile(pkgJsonPath);
+            const pluginVersion = typeof pkgJson.version === 'string' ? pkgJson.version : undefined;
+            writeComponentVersion(getCoreConfigDir(), {
+                componentName,
+                pluginPackage,
+                pluginVersion,
+            });
+            console.log('  ✓ Component version written');
+        }
+        catch {
+            console.log('  ⚠ Could not write component version');
         }
         console.log();
         console.log(`✅ ${pluginPackage} installed.`);
@@ -974,10 +1165,9 @@ function createPluginCli(options) {
         }
         // 3. Remove TOOLS.md section
         try {
-            const cfgRoot = opts.configRoot;
             const ws = opts.workspace;
             if (ws) {
-                init({ workspacePath: ws, configRoot: cfgRoot });
+                init({ workspacePath: ws, configRoot: opts.configRoot });
                 const sectionId = componentName.charAt(0).toUpperCase() + componentName.slice(1);
                 const toolsPath = join(ws, WORKSPACE_FILES.tools);
                 if (existsSync(toolsPath)) {
@@ -994,10 +1184,9 @@ function createPluginCli(options) {
         }
         // 4. Remove component-versions.json entry
         try {
-            const cfgRoot = opts.configRoot;
             init({
                 workspacePath: opts.workspace ?? '.',
-                configRoot: cfgRoot,
+                configRoot: opts.configRoot,
             });
             removeComponentVersion(getCoreConfigDir(), componentName);
             console.log('  ✓ Component version entry removed');

package/dist/cli/service/index.js

@@ -697,17 +697,73 @@ function createServiceManager(descriptor) {
 }
 
 /**
- * Shared CLI defaults and option registration for Jeeves CLI commands.
+ * Workspace-level shared configuration: `jeeves.config.json`.
  *
  * @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.
+ * Lives at the OpenClaw workspace root alongside TOOLS.md and SOUL.md.
+ * Provides namespaced shared defaults consumed by the root Jeeves CLI.
+ * Resolution precedence: CLI flags → env vars → jeeves.config.json → defaults.
+ *
+ * This does not replace component-owned config schemas (Decision 41).
+ */
+/** Core shared config section. */
+const workspaceCoreConfigSchema = z
+    .object({
+    /** Workspace root path. */
+    workspace: z.string().optional().describe('Workspace root path'),
+    /** Platform config root path. */
+    configRoot: z.string().optional().describe('Platform config root path'),
+    /** OpenClaw gateway URL. */
+    gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+})
+    .partial();
+/** Memory shared config section. */
+const workspaceMemoryConfigSchema = z
+    .object({
+    /** MEMORY.md character budget. */
+    budget: z.number().int().positive().optional().describe('Memory budget'),
+    /** Warning threshold as a fraction of budget. */
+    warningThreshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Memory warning threshold'),
+    /** Staleness threshold in days. */
+    staleDays: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Memory staleness threshold in days'),
+})
+    .partial();
+/** Workspace config Zod schema. */
+z.object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: z.string().optional().describe('JSON Schema pointer'),
+    /** Core shared defaults. */
+    core: workspaceCoreConfigSchema.optional(),
+    /** Memory hygiene shared defaults. */
+    memory: workspaceMemoryConfigSchema.optional(),
+});
+/** Built-in workspace config defaults. */
+const WORKSPACE_CONFIG_DEFAULTS = {
+    core: {
+        workspace: '.',
+        configRoot: './config'}};
+
+/**
+ * Shared CLI defaults and resolution for Jeeves CLI commands.
+ *
+ * @remarks
+ * All root CLI commands share workspace/config-root resolution. Values follow
+ * the shared precedence model: flags → env → jeeves.config.json → defaults.
  */
-/** Default workspace path (current directory). */
-const DEFAULT_WORKSPACE = '.';
+/** Default workspace path. */
+const DEFAULT_WORKSPACE = WORKSPACE_CONFIG_DEFAULTS.core.workspace;
 /** Default config root path. */
-const DEFAULT_CONFIG_ROOT = './config';
+const DEFAULT_CONFIG_ROOT = WORKSPACE_CONFIG_DEFAULTS.core.configRoot;
 
 /**
  * Factory for the standard Jeeves service CLI.