@hanna84/mcp-writing 2.10.5 → 2.10.6

package/CHANGELOG.md

@@ -4,11 +4,21 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v2.10.6](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.10.5...v2.10.6)
+
+- refactor(index): extract getRuntimeDiagnostics into runtime-diagnostics.js [`#110`](https://github.com/hannasdev/mcp-writing.git
+/pull/110)
+
 #### [v2.10.5](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.10.4...v2.10.5)
 
+> 27 April 2026
+
 - refactor(index): extract workflow catalogue module [`#109`](https://github.com/hannasdev/mcp-writing.git
 /pull/109)
+- Release 2.10.5 [`bee9b2b`](https://github.com/hannasdev/mcp-writing.git
+/commit/bee9b2bee5992cfc69571d95ab1dc281d89d8812)
 
 #### [v2.10.4](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.10.3...v2.10.4)

package/index.js

@@ -26,6 +26,7 @@ import { registerReviewBundleTools } from "./tools/review-bundles.js";
 import { registerStyleguideTools } from "./tools/styleguide.js";
 import { registerEditingTools } from "./tools/editing.js";
 import { WORKFLOW_CATALOGUE } from "./workflow-catalogue.js";
+import { getRuntimeDiagnostics } from "./runtime-diagnostics.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
@@ -200,78 +201,16 @@ function generateProposalId() {
   return `proposal-${randomUUID()}`;
 }
 
-function getRuntimeDiagnostics() {
-  const warnings = [];
-  const recommendations = [];
-
-  if (OWNERSHIP_GUARD_MODE_RAW !== OWNERSHIP_GUARD_MODE) {
-    warnings.push(
-      `OWNERSHIP_GUARD_MODE_INVALID: Unsupported OWNERSHIP_GUARD_MODE=${OWNERSHIP_GUARD_MODE_RAW_DISPLAY}. Falling back to 'warn'.`
-    );
-    recommendations.push("Set OWNERSHIP_GUARD_MODE to either 'warn' or 'fail'.");
-  }
-
-  if (SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid_override_ignored) {
-    warnings.push("RUNTIME_UID_OVERRIDE_IGNORED: RUNTIME_UID_OVERRIDE is ignored unless NODE_ENV=test or ALLOW_RUNTIME_UID_OVERRIDE=1.");
-    recommendations.push("Avoid RUNTIME_UID_OVERRIDE in production runtime environments.");
-  }
-
-  if (SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid_override_invalid) {
-    warnings.push("RUNTIME_UID_OVERRIDE_INVALID: RUNTIME_UID_OVERRIDE must be a non-negative integer when enabled.");
-    recommendations.push("Set RUNTIME_UID_OVERRIDE to a non-negative integer, or unset it.");
-  }
-
-  if (!SYNC_DIR_WRITABLE) {
-    warnings.push("SYNC_DIR_READ_ONLY: sync dir is read-only; metadata write-back and prose editing tools are unavailable.");
-    recommendations.push("Mount WRITING_SYNC_DIR with write access (avoid read-only mounts like ':ro').");
-    recommendations.push("If running in Docker/OpenClaw, verify volume ownership and permissions for the container user.");
-  }
-
-  if (SYNC_OWNERSHIP_DIAGNOSTICS.supported && SYNC_OWNERSHIP_DIAGNOSTICS.non_runtime_owned_paths > 0) {
-    warnings.push(
-      `OWNERSHIP_MISMATCH: ${SYNC_OWNERSHIP_DIAGNOSTICS.non_runtime_owned_paths} sampled path(s) are not owned by runtime UID ${SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid}.`
-    );
-    recommendations.push(
-      `Repair ownership once on host: sudo chown -R "$(id -u):$(id -g)" "${SYNC_DIR_ABS}"`
-    );
-    recommendations.push(
-      "For Docker/OpenClaw, run container as host user (compose: user: \"${OPENCLAW_UID:-1000}:${OPENCLAW_GID:-1000}\")."
-    );
-  }
-
-  if (OWNERSHIP_GUARD_MODE === "fail" && SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid === 0) {
-    warnings.push(
-      "OWNERSHIP_GUARD_SKIPPED_FOR_ROOT: OWNERSHIP_GUARD_MODE=fail is skipped because runtime UID is 0 (root)."
-    );
-    recommendations.push("Prefer running as a non-root host-mapped UID/GID to make ownership guard checks meaningful.");
-  }
-
-  if (SYNC_OWNERSHIP_DIAGNOSTICS.supported && SYNC_OWNERSHIP_DIAGNOSTICS.root_owned_paths > 0) {
-    warnings.push(
-      `ROOT_OWNED_PATHS: ${SYNC_OWNERSHIP_DIAGNOSTICS.root_owned_paths} sampled path(s) are owned by UID 0 (root).`
-    );
-  }
-
-  if (!GIT_AVAILABLE) {
-    warnings.push("GIT_NOT_FOUND: git is not available on PATH; snapshot/edit tools are unavailable.");
-    recommendations.push("Install git in the runtime image/environment.");
-  }
-
-  if (GIT_AVAILABLE && SYNC_DIR_WRITABLE && !GIT_ENABLED) {
-    warnings.push("GIT_DISABLED: git is available but repository snapshot tools are not active.");
-    recommendations.push("Ensure WRITING_SYNC_DIR points to a writable git repository root, or allow mcp-writing to initialize one.");
-  }
-
-  if (GIT_AVAILABLE && !SYNC_DIR_WRITABLE) {
-    recommendations.push("If git reports 'dubious ownership' for mounted repos, add: git config --system --add safe.directory /sync");
-  }
-
-  recommendations.push("If indexing finds many files without scene_id, run scripts/import.js first for Scrivener Draft exports, then run sync.");
-
-  return { warnings, recommendations };
-}
-
-const RUNTIME_DIAGNOSTICS = getRuntimeDiagnostics();
+const RUNTIME_DIAGNOSTICS = getRuntimeDiagnostics({
+  ownershipGuardModeRaw: OWNERSHIP_GUARD_MODE_RAW,
+  ownershipGuardMode: OWNERSHIP_GUARD_MODE,
+  ownershipGuardModeRawDisplay: OWNERSHIP_GUARD_MODE_RAW_DISPLAY,
+  syncDirWritable: SYNC_DIR_WRITABLE,
+  syncDirAbs: SYNC_DIR_ABS,
+  syncOwnershipDiagnostics: SYNC_OWNERSHIP_DIAGNOSTICS,
+  gitAvailable: GIT_AVAILABLE,
+  gitEnabled: GIT_ENABLED,
+});
 if (RUNTIME_DIAGNOSTICS.warnings.length) {
   process.stderr.write(`[mcp-writing] Runtime diagnostics:\n`);
   for (const line of RUNTIME_DIAGNOSTICS.warnings) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.10.5",
+  "version": "2.10.6",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -17,6 +17,7 @@
     "git.js",
     "world-entity-templates.js",
     "workflow-catalogue.js",
+    "runtime-diagnostics.js",
     "metadata-lint.js",
     "scene-character-normalization.js",
     "review-bundles.js",

package/runtime-diagnostics.js

@@ -0,0 +1,97 @@
+/**
+ * getRuntimeDiagnostics
+ *
+ * Inspects the startup environment and returns { warnings, recommendations }.
+ * All inputs are passed explicitly so this module has no side effects and
+ * is straightforward to test.
+ *
+ * @param {object} opts
+ * @param {string}  opts.ownershipGuardModeRaw      Raw env value before normalisation
+ * @param {string}  opts.ownershipGuardMode          Normalised value ("warn" | "fail")
+ * @param {string}  opts.ownershipGuardModeRawDisplay JSON.stringify of the raw value
+ * @param {boolean} opts.syncDirWritable
+ * @param {string}  opts.syncDirAbs                 Resolved absolute path shown in messages
+ * @param {object}  opts.syncOwnershipDiagnostics   Result of getSyncOwnershipDiagnostics()
+ * @param {boolean} opts.gitAvailable
+ * @param {boolean} opts.gitEnabled
+ * @returns {{ warnings: string[], recommendations: string[] }}
+ */
+export function getRuntimeDiagnostics({
+  ownershipGuardModeRaw,
+  ownershipGuardMode,
+  ownershipGuardModeRawDisplay,
+  syncDirWritable,
+  syncDirAbs,
+  syncOwnershipDiagnostics,
+  gitAvailable,
+  gitEnabled,
+}) {
+  const warnings = [];
+  const recommendations = [];
+
+  if (ownershipGuardModeRaw !== ownershipGuardMode) {
+    warnings.push(
+      `OWNERSHIP_GUARD_MODE_INVALID: Unsupported OWNERSHIP_GUARD_MODE=${ownershipGuardModeRawDisplay}. Falling back to 'warn'.`
+    );
+    recommendations.push("Set OWNERSHIP_GUARD_MODE to either 'warn' or 'fail'.");
+  }
+
+  if (syncOwnershipDiagnostics.runtime_uid_override_ignored) {
+    warnings.push("RUNTIME_UID_OVERRIDE_IGNORED: RUNTIME_UID_OVERRIDE is ignored unless NODE_ENV=test or ALLOW_RUNTIME_UID_OVERRIDE=1.");
+    recommendations.push("Avoid RUNTIME_UID_OVERRIDE in production runtime environments.");
+  }
+
+  if (syncOwnershipDiagnostics.runtime_uid_override_invalid) {
+    warnings.push("RUNTIME_UID_OVERRIDE_INVALID: RUNTIME_UID_OVERRIDE must be a non-negative integer when enabled.");
+    recommendations.push("Set RUNTIME_UID_OVERRIDE to a non-negative integer, or unset it.");
+  }
+
+  if (!syncDirWritable) {
+    warnings.push("SYNC_DIR_READ_ONLY: sync dir is read-only; metadata write-back and prose editing tools are unavailable.");
+    recommendations.push("Mount WRITING_SYNC_DIR with write access (avoid read-only mounts like ':ro').");
+    recommendations.push("If running in Docker/OpenClaw, verify volume ownership and permissions for the container user.");
+  }
+
+  if (syncOwnershipDiagnostics.supported && syncOwnershipDiagnostics.non_runtime_owned_paths > 0) {
+    warnings.push(
+      `OWNERSHIP_MISMATCH: ${syncOwnershipDiagnostics.non_runtime_owned_paths} sampled path(s) are not owned by runtime UID ${syncOwnershipDiagnostics.runtime_uid}.`
+    );
+    recommendations.push(
+      `Repair ownership once on host: sudo chown -R "$(id -u):$(id -g)" "${syncDirAbs}"`
+    );
+    recommendations.push(
+      "For Docker/OpenClaw, run container as host user (compose: user: \"${OPENCLAW_UID:-1000}:${OPENCLAW_GID:-1000}\")."
+    );
+  }
+
+  if (ownershipGuardMode === "fail" && syncOwnershipDiagnostics.runtime_uid === 0) {
+    warnings.push(
+      "OWNERSHIP_GUARD_SKIPPED_FOR_ROOT: OWNERSHIP_GUARD_MODE=fail is skipped because runtime UID is 0 (root)."
+    );
+    recommendations.push("Prefer running as a non-root host-mapped UID/GID to make ownership guard checks meaningful.");
+  }
+
+  if (syncOwnershipDiagnostics.supported && syncOwnershipDiagnostics.root_owned_paths > 0) {
+    warnings.push(
+      `ROOT_OWNED_PATHS: ${syncOwnershipDiagnostics.root_owned_paths} sampled path(s) are owned by UID 0 (root).`
+    );
+  }
+
+  if (!gitAvailable) {
+    warnings.push("GIT_NOT_FOUND: git is not available on PATH; snapshot/edit tools are unavailable.");
+    recommendations.push("Install git in the runtime image/environment.");
+  }
+
+  if (gitAvailable && syncDirWritable && !gitEnabled) {
+    warnings.push("GIT_DISABLED: git is available but repository snapshot tools are not active.");
+    recommendations.push("Ensure WRITING_SYNC_DIR points to a writable git repository root, or allow mcp-writing to initialize one.");
+  }
+
+  if (gitAvailable && !syncDirWritable) {
+    recommendations.push("If git reports 'dubious ownership' for mounted repos, add: git config --system --add safe.directory /sync");
+  }
+
+  recommendations.push("If indexing finds many files without scene_id, run scripts/import.js first for Scrivener Draft exports, then run sync.");
+
+  return { warnings, recommendations };
+}