@karmaniverous/jeeves-meta 0.18.0 → 0.19.0

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

@@ -5,7 +5,7 @@ import fs, { unlinkSync, writeFileSync, existsSync, readFileSync, statSync, mkdi
 import path, { join, dirname, relative, posix, sep, resolve } from 'node:path';
 import { readFile, unlink, mkdir, writeFile, copyFile } from 'node:fs/promises';
 import { z } from 'zod';
-import { randomUUID, createHash } from 'node:crypto';
+import { randomUUID, createHash, createHmac } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import pino from 'pino';
 import { fileURLToPath } from 'node:url';
@@ -763,11 +763,14 @@ function applyHotReloadedConfig(newConfig) {
  *
  * @module schema/config
  */
-/** Default Handlebars template strings for progress reporting. Single source of truth. */
+/**
+ * Default Handlebars template strings for progress reporting. Single source of truth.
+ * Links are empty when jeeves-server refuses `serverKey`, so each is guarded.
+ */
 const DEFAULT_TEMPLATE_STRINGS = {
-    phaseStart: ':gear: Started meta synthesis {{phase}} phase of <{{dirLink}}>',
-    phaseEnd: ':white_check_mark: Completed meta synthesis {{phase}} phase ({{tokens}} tokens / {{seconds}}s) at <{{metaLink}}>',
-    phaseError: ':x: Meta synthesis {{phase}} phase failed at <{{dirLink}}>\n   Error: {{error}}',
+    phaseStart: ':gear: Started meta synthesis {{phase}} phase{{#if dirLink}} of <{{dirLink}}>{{/if}}',
+    phaseEnd: ':white_check_mark: Completed meta synthesis {{phase}} phase ({{tokens}} tokens / {{seconds}}s){{#if metaLink}} at <{{metaLink}}>{{/if}}',
+    phaseError: ':x: Meta synthesis {{phase}} phase failed{{#if dirLink}} at <{{dirLink}}>{{/if}}\n   Error: {{error}}',
 };
 /** Zod schema for logging configuration. */
 const loggingSchema = z.object({
@@ -803,6 +806,13 @@ const serviceConfigSchema = metaConfigSchema.extend({
      * Default: http://127.0.0.1:1934
      */
     serverUrl: z.string().default('http://127.0.0.1:1934'),
+    /**
+     * jeeves-server machine key seed (a `keys` entry in jeeves-server config).
+     * The seed is never sent: the resolve-path API receives only the key
+     * derived from it, as the `k` parameter. Required from jeeves-server 3.15.0.
+     * Supports `${ENV}` substitution. Redacted in `GET /config`.
+     */
+    serverKey: z.string().optional(),
     /**
      * Handlebars templates for progress reporting messages.
      * Each template receives a standard set of data keys (dirLink, metaLink,
@@ -3018,13 +3028,82 @@ async function executePhase(node, currentMeta, phaseState, phase, config, execut
 }
 
 /**
- * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
+ * Resolve filesystem paths to jeeves-server browse links via
+ * `GET /api/resolve-path`, authenticated with a jeeves-server machine key.
+ * Network I/O only; no logging (callers decide how to report auth failures).
+ *
+ * @module progress/resolveLink
+ */
+/** Timeout for resolve-path API calls (ms). */
+const RESOLVE_PATH_TIMEOUT_MS = 3000;
+/** The fields of a resolve-path 200 response this module uses. */
+const resolvePathResponseSchema = z.object({
+    browseUrl: z.string().optional(),
+    publicUrl: z.string().optional(),
+});
+/**
+ * Derive the URL key jeeves-server accepts for a machine key seed.
  *
- * Progress events are rendered using Handlebars templates. Owner-path links
- * are resolved via the jeeves-server resolve-path API, with graceful
- * fallback to raw filesystem paths when the server is unreachable.
+ * Mirrors `computeInsiderKey` in `@karmaniverous/jeeves-server-core`:
+ * the first 32 hex chars of HMAC-SHA256(seed, 'insider'). Kept local so this
+ * service does not pull in a second copy of `@karmaniverous/jeeves`.
  *
- * @module progress
+ * @param seed - Machine key seed, as configured under `keys` in jeeves-server.
+ * @returns The derived URL key.
+ */
+function deriveServerUrlKey(seed) {
+    return createHmac('sha256', seed)
+        .update('insider')
+        .digest('hex')
+        .substring(0, 32);
+}
+/**
+ * Resolve a filesystem path to a browse URL.
+ *
+ * Sends the derived machine key as the `k` query parameter when `serverKey`
+ * is set. On HTTP 200 uses `publicUrl` if present, otherwise prefixes
+ * `serverUrl` to `browseUrl`. A malformed 200 response falls back.
+ *
+ * @param fsPath - Absolute filesystem path to resolve.
+ * @param serverUrl - jeeves-server base URL.
+ * @param serverKey - Optional jeeves-server machine key seed.
+ * @returns The lookup outcome.
+ */
+async function resolveLink(fsPath, serverUrl, serverKey) {
+    const fallback = { kind: 'fallback', link: fsPath };
+    try {
+        const url = new URL('/api/resolve-path', serverUrl);
+        url.searchParams.set('fsPath', fsPath);
+        if (serverKey)
+            url.searchParams.set('k', deriveServerUrlKey(serverKey));
+        const res = await fetchWithTimeout(url.toString(), RESOLVE_PATH_TIMEOUT_MS);
+        if (res.status === 401 || res.status === 403)
+            return { kind: 'unauthorized', status: res.status };
+        if (!res.ok)
+            return fallback;
+        const parsed = resolvePathResponseSchema.safeParse(await res.json());
+        if (!parsed.success)
+            return fallback;
+        const data = parsed.data;
+        if (data.publicUrl)
+            return { kind: 'resolved', link: data.publicUrl };
+        if (data.browseUrl)
+            return {
+                kind: 'resolved',
+                link: serverUrl.replace(/\/+$/, '') + data.browseUrl,
+            };
+        return fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+
+/**
+ * Render progress events with Handlebars templates, resolving owner-path
+ * browse links through jeeves-server. Network I/O via resolveLink only.
+ *
+ * @module progress/render
  */
 /** Compile raw template strings into Handlebars delegates. */
 function compileTemplates(raw) {
@@ -3043,40 +3122,24 @@ function formatNumber(n) {
     return n.toLocaleString('en-US');
 }
 /**
- * Resolve a filesystem path to a browse URL via the jeeves-server
- * resolve-path API. Returns the raw path as fallback on any failure.
- *
- * On HTTP 200, uses publicUrl if present, otherwise prefixes serverUrl
- * to browseUrl. On any error or non-200 response, returns fsPath as-is.
+ * Resolve the path and link fields for an owner directory and its meta.json.
+ * When the server refuses the key, every field is empty: no raw filesystem
+ * path reaches any template, default or custom.
  */
-/** Timeout for resolve-path API calls (ms). */
-const RESOLVE_PATH_TIMEOUT_MS = 3000;
-async function resolveLink(fsPath, serverUrl) {
-    try {
-        const url = new URL('/api/resolve-path', serverUrl);
-        url.searchParams.set('fsPath', fsPath);
-        const res = await fetchWithTimeout(url.toString(), RESOLVE_PATH_TIMEOUT_MS);
-        if (!res.ok)
-            return fsPath;
-        const data = (await res.json());
-        if (data.publicUrl)
-            return data.publicUrl;
-        if (data.browseUrl) {
-            const base = serverUrl.replace(/\/+$/, '');
-            return base + data.browseUrl;
-        }
-        return fsPath;
+async function resolvePathFields(ownerPath, serverUrl, options) {
+    const result = await resolveLink(ownerPath, serverUrl, options.serverKey);
+    if (result.kind === 'unauthorized') {
+        options.onUnauthorized?.(result.status);
+        return { dirPath: '', metaPath: '', dirLink: '', metaLink: '' };
     }
-    catch {
-        return fsPath;
-    }
-}
-/** Resolve browse links for both the owner directory and its meta.json. */
-async function resolveLinks(ownerPath, serverUrl) {
-    const dirLink = await resolveLink(ownerPath, serverUrl);
-    // Derive metaLink by appending /.meta/meta.json to the resolved dir link
-    const metaLink = dirLink.replace(/\/+$/, '') + '/.meta/meta.json';
-    return { dirLink, metaLink };
+    const dirLink = result.link;
+    return {
+        dirPath: ownerPath,
+        metaPath: ownerPath.replace(/\/+$/, '') + '/.meta/meta.json',
+        dirLink,
+        // Derive metaLink by appending /.meta/meta.json to the resolved dir link
+        metaLink: dirLink.replace(/\/+$/, '') + '/.meta/meta.json',
+    };
 }
 /**
  * Render the appropriate template for a progress event.
@@ -3084,18 +3147,13 @@ async function resolveLinks(ownerPath, serverUrl) {
  * @param event - The progress event to render.
  * @param templates - Compiled Handlebars templates.
  * @param serverUrl - jeeves-server URL for resolve-path API.
+ * @param options - Machine key and unauthorized-response callback.
  * @returns Rendered message string.
  */
-async function renderProgressEvent(event, templates, serverUrl) {
-    const ownerPath = event.path;
-    const metaPath = ownerPath.replace(/\/+$/, '') + '/.meta/meta.json';
+async function renderProgressEvent(event, templates, serverUrl, options = {}) {
     const phase = (event.phase ?? 'unknown').toUpperCase();
-    const { dirLink, metaLink } = await resolveLinks(ownerPath, serverUrl);
     const base = {
-        dirPath: ownerPath,
-        metaPath,
-        dirLink,
-        metaLink,
+        ...(await resolvePathFields(event.path, serverUrl, options)),
         phase,
     };
     switch (event.type) {
@@ -3119,6 +3177,18 @@ async function renderProgressEvent(event, templates, serverUrl) {
             return 'Unknown progress event';
     }
 }
+
+/**
+ * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
+ *
+ * Progress events are rendered using Handlebars templates (see
+ * `progress/render`). Owner-path links are resolved via the jeeves-server
+ * resolve-path API (authenticated with `serverKey`), falling back to raw
+ * filesystem paths when the server is unreachable and omitting links when
+ * the server refuses the key.
+ *
+ * @module progress
+ */
 class ProgressReporter {
     config;
     logger;
@@ -3126,6 +3196,8 @@ class ProgressReporter {
     /** Snapshot of template source strings used to compile `this.templates`. */
     lastTemplateSource;
     serverUrl;
+    /** Unauthorized causes already warned about; each is logged once. */
+    reportedAuthCauses = new Set();
     constructor(config, logger) {
         this.config = config;
         this.logger = logger;
@@ -3154,7 +3226,12 @@ class ProgressReporter {
         }
         let message;
         try {
-            message = await renderProgressEvent(event, this.templates, this.serverUrl);
+            message = await renderProgressEvent(event, this.templates, this.serverUrl, {
+                serverKey: this.config.serverKey,
+                onUnauthorized: (status) => {
+                    this.warnUnauthorized(status);
+                },
+            });
         }
         catch (err) {
             this.logger.warn({ err }, 'Progress event rendering failed');
@@ -3191,6 +3268,16 @@ class ProgressReporter {
             this.logger.warn({ err }, 'Progress reporting threw');
         }
     }
+    /** Warn once per distinct cause when jeeves-server refuses resolve-path. */
+    warnUnauthorized(status) {
+        const reason = this.config.serverKey ? 'rejected' : 'missing';
+        if (this.reportedAuthCauses.has(reason))
+            return;
+        this.reportedAuthCauses.add(reason);
+        this.logger.warn({ status, serverUrl: this.serverUrl }, reason === 'missing'
+            ? 'jeeves-server requires a machine key for resolve-path; set serverKey in meta config. Progress reports omit links until then.'
+            : 'jeeves-server rejected serverKey for resolve-path; check the machine key. Progress reports omit links until then.');
+    }
 }
 
 /**
@@ -4001,11 +4088,12 @@ class Scheduler {
  *
  * @module routes/config
  */
-/** Return a sanitized copy of the config (redact gatewayApiKey). */
+/** Return a sanitized copy of the config (redact gatewayApiKey and serverKey). */
 function sanitizeConfig(config) {
     return {
         ...config,
         gatewayApiKey: config.gatewayApiKey ? '[REDACTED]' : undefined,
+        serverKey: config.serverKey ? '[REDACTED]' : undefined,
     };
 }
 function registerConfigRoute(app, deps) {

package/package.json

@@ -7,31 +7,31 @@
     "url": "https://github.com/karmaniverous/jeeves-meta/issues"
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "0.6.0",
-    "@karmaniverous/jeeves-meta-core": "^0.2.2",
+    "@karmaniverous/jeeves": "0.7.0",
+    "@karmaniverous/jeeves-meta-core": "^0.3.0",
     "commander": "^15",
     "croner": "^10",
     "fastify": "^5.12",
-    "handlebars": "^4.7.9",
+    "handlebars": "^4.7.10",
     "package-directory": "^8.2.0",
     "pino": "^10",
     "zod": "^4.6"
   },
   "description": "Fastify HTTP service for the Jeeves Meta synthesis engine",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^2.30.0",
+    "@dotenvx/dotenvx": "^2.35.0",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^26.6.3",
-    "@vitest/coverage-v8": "^5.0.2",
+    "@types/node": "^26.6.5",
+    "@vitest/coverage-v8": "^5.0.4",
     "cross-env": "^10.1.0",
-    "release-it": "^21.1.0",
-    "rollup": "^4.63.5",
+    "release-it": "^21.1.1",
+    "rollup": "^4.64.6",
     "rollup-plugin-copy": "^3.5.0",
     "tslib": "^2.8.1",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.4"
   },
   "engines": {
     "node": ">=22"
@@ -62,7 +62,9 @@
       "tagName": "service/${version}"
     },
     "github": {
-      "release": true
+      "release": true,
+      "releaseName": "${name.split('/').pop()}@${version}",
+      "releaseNotes": "npx git-cliff --tag service/${version} --unreleased --strip header"
     },
     "hooks": {
       "after:bump": [
@@ -81,7 +83,7 @@
         "git switch ${branchName}"
       ],
       "before:npm:release": [
-        "npx git-cliff -o CHANGELOG.md",
+        "npx git-cliff --tag service/${version} -o CHANGELOG.md",
         "git add -A"
       ]
     },
@@ -106,5 +108,5 @@
     "typecheck": "tsc"
   },
   "type": "module",
-  "version": "0.18.0"
+  "version": "0.19.0"
 }