@karmaniverous/jeeves-meta 0.13.0 → 0.13.1

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import fs, { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync, statSync, readdirSync, watchFile } from 'node:fs';
-import path, { join, dirname, relative, posix, resolve } from 'node:path';
+import path, { join, dirname, basename, relative, posix, resolve } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
 import require$$0$4 from 'path';
 import require$$0$3 from 'fs';
 import require$$0$1 from 'constants';
@@ -14,7 +15,6 @@ import * as commander from 'commander';
 import { homedir, tmpdir } from 'node:os';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { randomUUID, createHash } from 'node:crypto';
 import { readFile, unlink, mkdir, writeFile, copyFile } from 'node:fs/promises';
 import pino from 'pino';
 import Handlebars from 'handlebars';
@@ -7088,30 +7088,64 @@ function getComponentConfigDir(componentName) {
         throw new Error('jeeves-core: init() must be called first');
     return join(state.configRoot, `${COMPONENT_CONFIG_PREFIX}${componentName}`);
 }
+/** Maximum rename retry attempts on EPERM. */
+const ATOMIC_WRITE_MAX_RETRIES = 3;
+/** Delay between EPERM retries in milliseconds. */
+const ATOMIC_WRITE_RETRY_DELAY_MS = 100;
 /**
  * Write content to a file atomically via a temp file + rename.
  *
+ * @remarks
+ * Retries the rename up to three times on EPERM (Windows file-handle
+ * contention) with a 100 ms synchronous delay between attempts.
+ *
  * @param filePath - Absolute path to the target file.
  * @param content - Content to write.
  */
 function atomicWrite(filePath, content) {
     const dir = dirname(filePath);
-    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
+    const base = basename(filePath, '.md');
+    const tempPath = join(dir, `.${base}.${String(Date.now())}.${randomUUID().slice(0, 8)}.tmp`);
     writeFileSync(tempPath, content, 'utf-8');
-    try {
-        renameSync(tempPath, filePath);
-    }
-    catch (err) {
+    for (let attempt = 0; attempt < ATOMIC_WRITE_MAX_RETRIES; attempt++) {
         try {
-            unlinkSync(tempPath);
+            renameSync(tempPath, filePath);
+            return;
         }
-        catch {
-            /* best-effort cleanup */
+        catch (err) {
+            const isEperm = err instanceof Error &&
+                'code' in err &&
+                err.code === 'EPERM';
+            if (!isEperm || attempt === ATOMIC_WRITE_MAX_RETRIES - 1) {
+                try {
+                    unlinkSync(tempPath);
+                }
+                catch {
+                    /* best-effort cleanup */
+                }
+                throw err;
+            }
+            // Synchronous sleep before retry (acceptable in atomic write context)
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ATOMIC_WRITE_RETRY_DELAY_MS);
         }
-        throw err;
     }
 }
 
+/**
+ * Shared internal utility functions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extract a human-readable message from an unknown caught value.
+ *
+ * @param err - The caught value (typically `unknown`).
+ * @returns The error message string.
+ */
+function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Factory for a framework-agnostic config apply HTTP handler.
  *
@@ -7164,8 +7198,7 @@ function readConfigFile(filePath) {
         return JSON.parse(raw);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: Could not read config file ${filePath}: ${msg}`);
+        console.warn(`jeeves-core: Could not read config file ${filePath}: ${getErrorMessage(err)}`);
         return {};
     }
 }
@@ -7214,10 +7247,9 @@ function createConfigApplyHandler(descriptor) {
             atomicWrite(configPath, json);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
             return {
                 status: 500,
-                body: { error: `Failed to write config: ${message}` },
+                body: { error: `Failed to write config: ${getErrorMessage(err)}` },
             };
         }
         // Call onConfigApply callback if defined
@@ -7226,12 +7258,11 @@ function createConfigApplyHandler(descriptor) {
                 await descriptor.onConfigApply(validatedConfig);
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
                 return {
                     status: 200,
                     body: {
                         applied: true,
-                        warning: `Config written but callback failed: ${message}`,
+                        warning: `Config written but callback failed: ${getErrorMessage(err)}`,
                         config: validatedConfig,
                     },
                 };
@@ -7314,8 +7345,7 @@ function createStatusHandler(options) {
                 health = await options.getHealth();
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                health = { error: message };
+                health = { error: getErrorMessage(err) };
                 overallStatus = 'degraded';
             }
         }
@@ -7372,7 +7402,13 @@ z.object({
     /** Memory hygiene shared defaults. */
     memory: workspaceMemoryConfigSchema.optional(),
 });
-/** Built-in workspace config defaults. */
+/**
+ * Built-in workspace config defaults.
+ *
+ * @remarks
+ * These defaults are used as the lowest-priority tier in config resolution
+ * (below CLI flags, env vars, and `jeeves.config.json` values).
+ */
 const WORKSPACE_CONFIG_DEFAULTS = {
     core: {
         workspace: '.',
@@ -8028,6 +8064,10 @@ function createServiceManager(descriptor) {
  * a component descriptor. Components add domain-specific commands
  * via `descriptor.customCliCommands`.
  */
+function handleCommandError(action, err) {
+    console.error(`${action} failed: ${getErrorMessage(err)}`);
+    process.exitCode = 1;
+}
 /**
  * Create a standard service CLI program from a component descriptor.
  *
@@ -8080,8 +8120,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Service unreachable: ${msg}`);
+            console.error(`Service unreachable: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -8099,8 +8138,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config query failed: ${msg}`);
+            console.error(`Config query failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -8116,8 +8154,7 @@ function createServiceCli(descriptor) {
             console.log('Config is valid.');
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Validation failed: ${msg}`);
+            console.error(`Validation failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -8154,8 +8191,7 @@ function createServiceCli(descriptor) {
             console.log(JSON.stringify(result, null, 2));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Config apply failed: ${msg}`);
+            console.error(`Config apply failed: ${getErrorMessage(err)}`);
             process.exitCode = 1;
         }
     });
@@ -8192,9 +8228,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" installed.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Install failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Install', err);
         }
     });
     serviceCmd
@@ -8207,9 +8241,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" uninstalled.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Uninstall failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Uninstall', err);
         }
     });
     serviceCmd
@@ -8222,9 +8254,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" started.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Start failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Start', err);
         }
     });
     serviceCmd
@@ -8237,9 +8267,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" stopped.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Stop failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Stop', err);
         }
     });
     serviceCmd
@@ -8252,9 +8280,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}" restarted.`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Restart failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Restart', err);
         }
     });
     serviceCmd
@@ -8267,9 +8293,7 @@ function createServiceCli(descriptor) {
             console.log(`Service "${opts.name}": ${state}`);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Status failed: ${msg}`);
-            process.exitCode = 1;
+            handleCommandError('Status', err);
         }
     });
     // Apply custom CLI commands if provided

package/dist/index.js

@@ -1,8 +1,9 @@
 import fs, { readdirSync, readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, mkdirSync, copyFileSync, statSync, watchFile } from 'node:fs';
-import path, { join, dirname, resolve, relative, posix } from 'node:path';
+import path, { join, dirname, resolve, basename, relative, posix } from 'node:path';
 import { unlink, readFile, mkdir, writeFile, copyFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import process$1 from 'node:process';
+import { randomUUID, createHash } from 'node:crypto';
 import require$$0$4 from 'path';
 import require$$0$3 from 'fs';
 import require$$0$1 from 'constants';
@@ -15,7 +16,6 @@ import { z } from 'zod';
 import * as commander from 'commander';
 import { tmpdir } from 'node:os';
 import 'node:child_process';
-import { randomUUID, createHash } from 'node:crypto';
 import pino from 'pino';
 import Handlebars from 'handlebars';
 import { Cron } from 'croner';
@@ -7287,30 +7287,64 @@ function getCoreConfigDir() {
 function getComponentConfigDir(componentName) {
     throw new Error('jeeves-core: init() must be called first');
 }
+/** Maximum rename retry attempts on EPERM. */
+const ATOMIC_WRITE_MAX_RETRIES = 3;
+/** Delay between EPERM retries in milliseconds. */
+const ATOMIC_WRITE_RETRY_DELAY_MS = 100;
 /**
  * Write content to a file atomically via a temp file + rename.
  *
+ * @remarks
+ * Retries the rename up to three times on EPERM (Windows file-handle
+ * contention) with a 100 ms synchronous delay between attempts.
+ *
  * @param filePath - Absolute path to the target file.
  * @param content - Content to write.
  */
 function atomicWrite(filePath, content) {
     const dir = dirname(filePath);
-    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
+    const base = basename(filePath, '.md');
+    const tempPath = join(dir, `.${base}.${String(Date.now())}.${randomUUID().slice(0, 8)}.tmp`);
     writeFileSync(tempPath, content, 'utf-8');
-    try {
-        renameSync(tempPath, filePath);
-    }
-    catch (err) {
+    for (let attempt = 0; attempt < ATOMIC_WRITE_MAX_RETRIES; attempt++) {
         try {
-            unlinkSync(tempPath);
+            renameSync(tempPath, filePath);
+            return;
         }
-        catch {
-            /* best-effort cleanup */
+        catch (err) {
+            const isEperm = err instanceof Error &&
+                'code' in err &&
+                err.code === 'EPERM';
+            if (!isEperm || attempt === ATOMIC_WRITE_MAX_RETRIES - 1) {
+                try {
+                    unlinkSync(tempPath);
+                }
+                catch {
+                    /* best-effort cleanup */
+                }
+                throw err;
+            }
+            // Synchronous sleep before retry (acceptable in atomic write context)
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ATOMIC_WRITE_RETRY_DELAY_MS);
         }
-        throw err;
     }
 }
 
+/**
+ * Shared internal utility functions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extract a human-readable message from an unknown caught value.
+ *
+ * @param err - The caught value (typically `unknown`).
+ * @returns The error message string.
+ */
+function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Factory for a framework-agnostic config apply HTTP handler.
  *
@@ -7363,8 +7397,7 @@ function readConfigFile(filePath) {
         return JSON.parse(raw);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`jeeves-core: Could not read config file ${filePath}: ${msg}`);
+        console.warn(`jeeves-core: Could not read config file ${filePath}: ${getErrorMessage(err)}`);
         return {};
     }
 }
@@ -7413,10 +7446,9 @@ function createConfigApplyHandler(descriptor) {
             atomicWrite(configPath, json);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
             return {
                 status: 500,
-                body: { error: `Failed to write config: ${message}` },
+                body: { error: `Failed to write config: ${getErrorMessage(err)}` },
             };
         }
         // Call onConfigApply callback if defined
@@ -7425,12 +7457,11 @@ function createConfigApplyHandler(descriptor) {
                 await descriptor.onConfigApply(validatedConfig);
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
                 return {
                     status: 200,
                     body: {
                         applied: true,
-                        warning: `Config written but callback failed: ${message}`,
+                        warning: `Config written but callback failed: ${getErrorMessage(err)}`,
                         config: validatedConfig,
                     },
                 };
@@ -7513,8 +7544,7 @@ function createStatusHandler(options) {
                 health = await options.getHealth();
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                health = { error: message };
+                health = { error: getErrorMessage(err) };
                 overallStatus = 'degraded';
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-meta",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "author": "Jason Williscroft",
   "description": "Fastify HTTP service for the Jeeves Meta synthesis engine",
   "license": "BSD-3-Clause",
@@ -41,33 +41,33 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "^0.5.1",
+    "@karmaniverous/jeeves": "^0.5.3",
     "commander": "^14",
     "croner": "^10",
     "fastify": "^5.8",
-    "handlebars": "^4.7.8",
+    "handlebars": "^4.7.9",
     "package-directory": "^8.2.0",
     "pino": "^10",
     "zod": "^4.3"
   },
   "devDependencies": {
     "@commander-js/extra-typings": "^14.0.0",
-    "@dotenvx/dotenvx": "^1.55.1",
+    "@dotenvx/dotenvx": "^1.59.1",
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^4.1.0",
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.2",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
     "knip": "^5.87.0",
     "release-it": "^19.2.4",
-    "rollup": "^4.59.0",
+    "rollup": "^4.60.1",
     "rollup-plugin-copy": "^3.5.0",
-    "rollup-plugin-dts": "^6.4.0",
+    "rollup-plugin-dts": "^6.4.1",
     "tslib": "^2.8.1",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.2"
   },
   "scripts": {
     "build": "rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.mjs",