@karmaniverous/jeeves-meta 0.15.2 → 0.15.3

package/dist/cli/jeeves-meta/index.js

@@ -15,9 +15,9 @@ import * as commander from 'commander';
 import { execSync } from 'node:child_process';
 import { homedir, tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import Handlebars from 'handlebars';
 import { readFile, unlink, mkdir, writeFile, copyFile } from 'node:fs/promises';
 import pino from 'pino';
-import Handlebars from 'handlebars';
 import process$1 from 'node:process';
 import { Cron } from 'croner';
 import Fastify from 'fastify';
@@ -7239,6 +7239,11 @@ const workspaceCoreConfigSchema = z
     configRoot: z.string().optional().describe('Platform config root path'),
     /** OpenClaw gateway URL. */
     gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+    /** Dev repo paths keyed by component name. */
+    devRepos: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Dev repo paths by component name'),
 })
     .partial();
 /** Memory shared config section. */
@@ -7253,13 +7258,6 @@ const workspaceMemoryConfigSchema = z
         .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. */
@@ -8167,16 +8165,115 @@ function createServiceCli(descriptor) {
     });
     // Apply custom CLI commands if provided
     if (descriptor.customCliCommands) {
-        // Cast required: @commander-js/extra-typings Command has generic type
-        // parameters that don't align with the descriptor's base Command type.
-        // The descriptor can't know the parent Command's exact generic parameters
-        // at definition time. The cast is safe — customCliCommands only adds
-        // subcommands and doesn't depend on the parent's generic state.
         descriptor.customCliCommands(program);
     }
     return program;
 }
 
+var toolsPlatformTemplate = `### Tool Hierarchy
+
+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.
+
+Direct filesystem access is for **acting on** search results, not bypassing them.
+
+### Shell Scripting
+
+Default to \`node -e\` or \`.js\` scripts for \`exec\` calls. PowerShell corrupts multi-byte UTF-8 characters and mangles escaping. Use PowerShell only for Windows service management, registry operations, and similar platform-specific tasks.
+
+### File Bridge for External Repos
+
+When editing files outside the workspace, use the bridge pattern: copy in → edit the workspace copy → bridge out. Never write temp patch scripts. The workspace is the authoritative working directory.
+
+### Gateway Self-Destruction Warning
+
+⚠️ Any command that stops the gateway **stops the assistant**. Never run \`openclaw gateway stop\` or \`openclaw gateway restart\` without explicit owner approval. When approved, it must be the **absolute last action** — all other work must be complete first, all messages sent, all files saved.
+
+### Messaging
+
+**Same-channel replies:** Don't use the \`message\` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response.
+
+**Cross-channel sends:** Use the \`message\` tool with an explicit \`target\` to send to a different channel or DM.
+
+### Plugin Lifecycle
+
+\`\`\`bash
+# Platform bootstrap (content seeding)
+npx @karmaniverous/jeeves install
+
+# Component plugin install
+npx @karmaniverous/jeeves-{component}-openclaw install
+
+# Component plugin uninstall
+npx @karmaniverous/jeeves-{component}-openclaw uninstall
+
+# Platform teardown (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+\`\`\`
+
+Never manually edit \`~/.openclaw/extensions/\`. Always use the CLI commands above.
+
+### Reference Templates
+
+{{#if templatePath}}
+Reference templates are available at \`{{templatePath}}\`:
+
+| Template | Purpose |
+|----------|---------|
+| \`spec.md\` | Skeleton for new product specifications — all section headers, decision format, dev plan format |
+| \`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}}
+> Reference templates not yet installed. Run \`npx @karmaniverous/jeeves install\` to seed templates.
+{{/if}}
+
+### Post-Upgrade Maintenance
+
+After updating OpenClaw (\`npm install -g openclaw@latest\` or equivalent), reinstall all Jeeves component plugins to repair install state:
+
+\`\`\`bash
+npx @karmaniverous/jeeves install
+npx @karmaniverous/jeeves-runner-openclaw install
+npx @karmaniverous/jeeves-watcher-openclaw install
+npx @karmaniverous/jeeves-server-openclaw install
+npx @karmaniverous/jeeves-meta-openclaw install
+\`\`\`
+
+Then restart the gateway. Plugin installers copy dist files and patch config; reinstalling after an OpenClaw update ensures the extensions directory stays consistent.
+
+### Source Code Preference
+
+{{#if devRepos}}
+When investigating, debugging, or analyzing Jeeves components, always read TypeScript source from dev repos — never compiled \`dist/\` from the global npm install. Dev repos:
+
+| Component | Dev Repo |
+|-----------|----------|
+{{#each devRepos}}
+| {{@key}} | \`{{this}}\` |
+{{/each}}
+
+Built code is minified, harder to reason about, and wastes context. Always \`git pull\` before analysis.
+{{else}}
+> Dev repo paths not configured. Add \`core.devRepos\` to \`jeeves.config.json\` to enable source code preference guidance.
+{{/if}}
+`;
+
+/**
+ * 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.
+ * Reads content files from the package's `content/` directory, renders the
+ * Platform template with live data, and writes managed sections using
+ * `updateManagedSection`.
+ */
+/** Compiled Handlebars template for the Platform section (cached at module level). */
+Handlebars.compile(toolsPlatformTemplate, {
+    noEscape: true,
+});
+
 /**
  * Core configuration schema and resolution.
  *
@@ -8273,10 +8370,10 @@ function getServiceUrl(serviceName, consumerName) {
     if (coreUrl)
         return coreUrl;
     // 3. Fall back to port constants
-    const port = DEFAULT_PORTS[serviceName];
-    {
-        return `http://127.0.0.1:${String(port)}`;
+    if (serviceName in DEFAULT_PORTS) {
+        return `http://127.0.0.1:${String(DEFAULT_PORTS[serviceName])}`;
     }
+    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
 
 /**
@@ -9335,7 +9432,7 @@ class GatewayExecutor {
             'Write your complete output to a file using the Write tool at:\n' +
             outputPath +
             '\n\n' +
-            'Reply with ONLY the file path you wrote to. No other text.';
+            'After writing the file, reply with ONLY: NO_REPLY';
         // Step 1: Spawn the sub-agent session (unique label per cycle to avoid
         // "label already in use" errors — gateway labels persist after session completion)
         const labelBase = options?.label ?? 'jeeves-meta-synthesis';

package/dist/index.js

@@ -16,8 +16,8 @@ import { z } from 'zod';
 import * as commander from 'commander';
 import 'node:child_process';
 import { tmpdir } from 'node:os';
-import pino from 'pino';
 import Handlebars from 'handlebars';
+import pino from 'pino';
 import { Cron } from 'croner';
 import Fastify from 'fastify';
 
@@ -7437,6 +7437,11 @@ const workspaceCoreConfigSchema = z
     configRoot: z.string().optional().describe('Platform config root path'),
     /** OpenClaw gateway URL. */
     gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+    /** Dev repo paths keyed by component name. */
+    devRepos: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Dev repo paths by component name'),
 })
     .partial();
 /** Memory shared config section. */
@@ -7451,13 +7456,6 @@ const workspaceMemoryConfigSchema = z
         .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. */
@@ -7716,6 +7714,110 @@ async function postJson(url, body) {
     });
 }
 
+var toolsPlatformTemplate = `### Tool Hierarchy
+
+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.
+
+Direct filesystem access is for **acting on** search results, not bypassing them.
+
+### Shell Scripting
+
+Default to \`node -e\` or \`.js\` scripts for \`exec\` calls. PowerShell corrupts multi-byte UTF-8 characters and mangles escaping. Use PowerShell only for Windows service management, registry operations, and similar platform-specific tasks.
+
+### File Bridge for External Repos
+
+When editing files outside the workspace, use the bridge pattern: copy in → edit the workspace copy → bridge out. Never write temp patch scripts. The workspace is the authoritative working directory.
+
+### Gateway Self-Destruction Warning
+
+⚠️ Any command that stops the gateway **stops the assistant**. Never run \`openclaw gateway stop\` or \`openclaw gateway restart\` without explicit owner approval. When approved, it must be the **absolute last action** — all other work must be complete first, all messages sent, all files saved.
+
+### Messaging
+
+**Same-channel replies:** Don't use the \`message\` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response.
+
+**Cross-channel sends:** Use the \`message\` tool with an explicit \`target\` to send to a different channel or DM.
+
+### Plugin Lifecycle
+
+\`\`\`bash
+# Platform bootstrap (content seeding)
+npx @karmaniverous/jeeves install
+
+# Component plugin install
+npx @karmaniverous/jeeves-{component}-openclaw install
+
+# Component plugin uninstall
+npx @karmaniverous/jeeves-{component}-openclaw uninstall
+
+# Platform teardown (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+\`\`\`
+
+Never manually edit \`~/.openclaw/extensions/\`. Always use the CLI commands above.
+
+### Reference Templates
+
+{{#if templatePath}}
+Reference templates are available at \`{{templatePath}}\`:
+
+| Template | Purpose |
+|----------|---------|
+| \`spec.md\` | Skeleton for new product specifications — all section headers, decision format, dev plan format |
+| \`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}}
+> Reference templates not yet installed. Run \`npx @karmaniverous/jeeves install\` to seed templates.
+{{/if}}
+
+### Post-Upgrade Maintenance
+
+After updating OpenClaw (\`npm install -g openclaw@latest\` or equivalent), reinstall all Jeeves component plugins to repair install state:
+
+\`\`\`bash
+npx @karmaniverous/jeeves install
+npx @karmaniverous/jeeves-runner-openclaw install
+npx @karmaniverous/jeeves-watcher-openclaw install
+npx @karmaniverous/jeeves-server-openclaw install
+npx @karmaniverous/jeeves-meta-openclaw install
+\`\`\`
+
+Then restart the gateway. Plugin installers copy dist files and patch config; reinstalling after an OpenClaw update ensures the extensions directory stays consistent.
+
+### Source Code Preference
+
+{{#if devRepos}}
+When investigating, debugging, or analyzing Jeeves components, always read TypeScript source from dev repos — never compiled \`dist/\` from the global npm install. Dev repos:
+
+| Component | Dev Repo |
+|-----------|----------|
+{{#each devRepos}}
+| {{@key}} | \`{{this}}\` |
+{{/each}}
+
+Built code is minified, harder to reason about, and wastes context. Always \`git pull\` before analysis.
+{{else}}
+> Dev repo paths not configured. Add \`core.devRepos\` to \`jeeves.config.json\` to enable source code preference guidance.
+{{/if}}
+`;
+
+/**
+ * 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.
+ * Reads content files from the package's `content/` directory, renders the
+ * Platform template with live data, and writes managed sections using
+ * `updateManagedSection`.
+ */
+/** Compiled Handlebars template for the Platform section (cached at module level). */
+Handlebars.compile(toolsPlatformTemplate, {
+    noEscape: true,
+});
+
 /**
  * Core configuration schema and resolution.
  *
@@ -7812,10 +7914,10 @@ function getServiceUrl(serviceName, consumerName) {
     if (coreUrl)
         return coreUrl;
     // 3. Fall back to port constants
-    const port = DEFAULT_PORTS[serviceName];
-    {
-        return `http://127.0.0.1:${String(port)}`;
+    if (serviceName in DEFAULT_PORTS) {
+        return `http://127.0.0.1:${String(DEFAULT_PORTS[serviceName])}`;
     }
+    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
 
 /**
@@ -9069,7 +9171,7 @@ class GatewayExecutor {
             'Write your complete output to a file using the Write tool at:\n' +
             outputPath +
             '\n\n' +
-            'Reply with ONLY the file path you wrote to. No other text.';
+            'After writing the file, reply with ONLY: NO_REPLY';
         // Step 1: Spawn the sub-agent session (unique label per cycle to avoid
         // "label already in use" errors — gateway labels persist after session completion)
         const labelBase = options?.label ?? 'jeeves-meta-synthesis';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-meta",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "author": "Jason Williscroft",
   "description": "Fastify HTTP service for the Jeeves Meta synthesis engine",
   "license": "BSD-3-Clause",
@@ -41,7 +41,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "^0.5.8",
+    "@karmaniverous/jeeves": "^0.5.9",
     "commander": "^14",
     "croner": "^10",
     "fastify": "^5.8",