@hanna84/mcp-writing 1.13.1 → 1.14.0

package/CHANGELOG.md

@@ -4,11 +4,31 @@ 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).
 
+#### [v1.14.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.13.2...v1.14.0)
+
+- feat(scrivener-direct): graduate from beta to stable [`#72`](https://github.com/hannasdev/mcp-writing.git
+/pull/72)
+
+#### [v1.13.2](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.13.1...v1.13.2)
+
+> 24 April 2026
+
+- fix(scrivener-direct): add Phase E data safety hardening [`#71`](https://github.com/hannasdev/mcp-writing.git
+/pull/71)
+- Release 1.13.2 [`8b98c80`](https://github.com/hannasdev/mcp-writing.git
+/commit/8b98c80e27446d41f42c88217253ab5d30b065f2)
+
 #### [v1.13.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.13.0...v1.13.1)
 
+> 24 April 2026
+
 - fix(mcp): report server version from package metadata [`#70`](https://github.com/hannasdev/mcp-writing.git
 /pull/70)
+- Release 1.13.1 [`c9a5ff5`](https://github.com/hannasdev/mcp-writing.git
+/commit/c9a5ff5e847767cad2d73c170af7b28aede1ec59)
 
 #### [v1.13.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.12.0...v1.13.0)

package/git.js

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -14,7 +14,7 @@ export function isGitRepository(dirPath) {
       stdio: "pipe",
       encoding: "utf8",
     }).trim();
-    return path.resolve(gitRoot) === path.resolve(dirPath);
+    return fs.realpathSync(gitRoot) === fs.realpathSync(dirPath);
   } catch {
     return false;
   }
@@ -52,26 +52,35 @@ export function isGitAvailable() {
 }
 
 /**
- * Create a git commit for a scene file (pre-edit snapshot)
+ * Create a git commit for one or more scene-related files
  * Returns { commit_hash: string, commit_message: string }
  */
-export function createSnapshot(dirPath, filePath, sceneId, instruction) {
+export function createSnapshot(dirPath, filePath, sceneId, instruction, options = {}) {
   try {
-    const relPath = path.relative(dirPath, filePath);
-    execSync(`git add "${relPath}"`, { cwd: dirPath, stdio: "pipe" });
+    const { messagePrefix = "pre-edit snapshot" } = options;
+    const inputPaths = Array.isArray(filePath) ? filePath : [filePath];
+    const relPaths = [...new Set(inputPaths
+      .filter(Boolean)
+      .map(p => path.relative(dirPath, p)))];
+    if (!relPaths.length) {
+      throw new Error("No file paths provided for snapshot");
+    }
+    // Use -A so removed/renamed paths are staged as part of relocation snapshots.
+    execFileSync("git", ["add", "-A", "--", ...relPaths], { cwd: dirPath, stdio: "pipe" });
 
-    const commitMessage = `pre-edit snapshot: ${sceneId} — ${instruction}`;
-    // Use 2>&1 so git's stderr (where it prints "[branch hash] msg") is captured in stdout
-    const output = execSync(`git commit -m "${commitMessage.replace(/"/g, '\\"')}" 2>&1`, {
+    const commitMessage = messagePrefix
+      ? `${messagePrefix}: ${sceneId} — ${instruction}`
+      : String(instruction);
+
+    execFileSync("git", ["commit", "-m", commitMessage], {
       cwd: dirPath,
-      encoding: "utf8",
       stdio: "pipe",
     });
-
-    // git outputs "[branch hash] message" to stderr; redirect 2>&1 captures it in stdout
-    // Regex handles any branch name, with or without (root-commit)
-    const match = output.match(/\[\S+(?:\s+\(root-commit\))?\s+([a-f0-9]+)\]/);
-    const commitHash = match ? match[1] : null;
+    const commitHash = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: dirPath,
+      stdio: "pipe",
+      encoding: "utf8",
+    }).trim();
 
     return {
       commit_hash: commitHash,
@@ -79,7 +88,10 @@ export function createSnapshot(dirPath, filePath, sceneId, instruction) {
     };
   } catch (err) {
     // Check if nothing changed (no error, just no commit)
-    if (err.message.includes("nothing to commit") || err.status === 1) {
+    const stderr = err?.stderr ? String(err.stderr) : "";
+    const stdout = err?.stdout ? String(err.stdout) : "";
+    const text = `${stderr}\n${stdout}\n${err?.message ?? ""}`;
+    if (text.includes("nothing to commit") || err.status === 1) {
       return {
         commit_hash: null,
         commit_message: null,

package/index.js

@@ -980,7 +980,7 @@ function createMcpServer() {
 
   s.tool(
     "merge_scrivener_project_beta",
-    "[BETA] Merge metadata directly from a Scrivener .scriv project into existing scene sidecars by starting a background job. This path is opt-in, requires sidecars to already exist (for example, from import_scrivener_sync), and may be sensitive to Scrivener internal format changes. Returns immediately with a job_id to poll via get_async_job_status.",
+    "Merge metadata directly from a Scrivener .scriv project into existing scene sidecars by starting a background job. This path is opt-in and requires sidecars to already exist (for example, from import_scrivener_sync). Returns immediately with a job_id to poll via get_async_job_status.",
     {
       source_project_dir: z.string().describe("Path to a Scrivener .scriv bundle directory."),
       project_id: z.string().optional().describe("Project ID containing existing sidecars (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb')."),
@@ -1052,7 +1052,6 @@ function createMcpServer() {
       return jsonResponse({
         ok: true,
         async: true,
-        beta: true,
         job: toPublicJob(job, false),
         next_step: "Call get_async_job_status with job_id until status is 'completed' or 'failed'.",
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",

package/scripts/async-job-runner.mjs

@@ -52,7 +52,6 @@ function normalizeImportResult(importResult) {
 function normalizeMergeResult(mergeResult) {
   return {
     ok: true,
-    beta: true,
     merge: {
       source_project_dir: mergeResult.scrivPath,
       sync_dir: mergeResult.mcpSyncDir,
@@ -77,10 +76,7 @@ function normalizeMergeResult(mergeResult) {
       },
     },
     sync: null,
-    warnings: [
-      "BETA_FEATURE: Direct Scrivener project parsing may be sensitive to Scrivener internal format changes.",
-      "If this fails, use import_scrivener_sync with an External Folder Sync export as the stable fallback.",
-    ],
+    warnings: [],
   };
 }
 

package/scrivener-direct.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { DOMParser } from "@xmldom/xmldom";
 import yaml from "js-yaml";
 import { validateProjectId } from "./importer.js";
+import { createSnapshot, isGitRepository, isGitAvailable } from "./git.js";
 
 function attr(el, name) {
   return el?.getAttribute?.(name) ?? null;
@@ -93,8 +94,60 @@ function moveFileIfNeeded(fromPath, toPath) {
     if (!error || typeof error !== "object" || error.code !== "EXDEV") {
       throw error;
     }
-    fs.copyFileSync(fromPath, toPath);
-    fs.unlinkSync(fromPath);
+    // Cross-filesystem: copy then verify before unlink
+    try {
+      fs.copyFileSync(fromPath, toPath);
+      // Verify copy succeeded before deleting source
+      if (!fs.existsSync(toPath)) {
+        return {
+          moved: false,
+          warning: {
+            code: "relocate_copy_verification_failed",
+            message: "Failed to verify file copy to destination; source file preserved.",
+            from_path: fromPath,
+            to_path: toPath,
+          },
+        };
+      }
+      try {
+        fs.unlinkSync(fromPath);
+      } catch (unlinkErr) {
+        if (fs.existsSync(toPath)) {
+          try {
+            fs.unlinkSync(toPath);
+          } catch {
+            // Best effort; already in error state
+          }
+        }
+        return {
+          moved: false,
+          warning: {
+            code: "relocate_cross_filesystem_unlink_failed",
+            message: `Copied prose file but failed to remove source file: ${unlinkErr.message}. Source file preserved.`,
+            from_path: fromPath,
+            to_path: toPath,
+          },
+        };
+      }
+    } catch (copyErr) {
+      // Copy failed; ensure we don't leave partial destination files
+      if (fs.existsSync(toPath)) {
+        try {
+          fs.unlinkSync(toPath);
+        } catch {
+          // Best effort; already in error state
+        }
+      }
+      return {
+        moved: false,
+        warning: {
+          code: "relocate_cross_filesystem_copy_failed",
+          message: `Failed to copy prose file across filesystem: ${copyErr.message}. Source file preserved.`,
+          from_path: fromPath,
+          to_path: toPath,
+        },
+      };
+    }
   }
 
   return { moved: true };
@@ -339,7 +392,8 @@ export function mergeSidecarData(existing, mergeData) {
   };
 }
 
-export function loadScrivenerProjectData(scrivPath) {
+export function loadScrivenerProjectData(scrivPath, options = {}) {
+  const { onWarning } = options;
   const scrivPathAbs = path.resolve(scrivPath);
   if (!fs.existsSync(scrivPathAbs)) {
     throw new Error(`Scrivener bundle not found: ${scrivPathAbs}`);
@@ -361,6 +415,19 @@ export function loadScrivenerProjectData(scrivPath) {
   const scrivxPath = path.join(scrivPathAbs, preferredScrivx);
   const dataDir = path.join(scrivPathAbs, "Files", "Data");
 
+  // XML size guardrail: surface warning if .scrivx is very large.
+  const scrivxStat = fs.statSync(scrivxPath);
+  const MAX_SCRIVX_SIZE = 50 * 1024 * 1024; // 50MB
+  if (scrivxStat.size > MAX_SCRIVX_SIZE) {
+    onWarning?.({
+      code: "large_scrivx_file",
+      message: `Scrivener project .scrivx file is unusually large (${Math.round(scrivxStat.size / 1024 / 1024)}MB). This is an advisory warning; parsing will continue but may take longer and use significantly more memory because XML is parsed in-memory.`,
+      scrivx_path: scrivxPath,
+      size_bytes: scrivxStat.size,
+      threshold_bytes: MAX_SCRIVX_SIZE,
+    });
+  }
+
   const xml = fs.readFileSync(scrivxPath, "utf8");
   const dom = new DOMParser().parseFromString(xml, "text/xml");
 
@@ -517,7 +584,16 @@ export function mergeScrivenerProjectMetadata({
     throw new Error(`Scenes directory not found or not a directory: ${scenesDir}`);
   }
 
-  const projectData = loadScrivenerProjectData(scrivPath);
+  const warnings = [];
+  const warningSummary = {};
+  let warningsTruncated = false;
+
+  const projectData = loadScrivenerProjectData(scrivPath, {
+    onWarning: (warning) => {
+      warningsTruncated = pushWarning(warnings, warningSummary, warning) || warningsTruncated;
+      logger(`  WARN  ${warning.message}`);
+    },
+  });
   logger(`Sync map: ${Object.keys(projectData.syncNumToUUID).length} entries`);
   logger(`Keyword map: ${Object.keys(projectData.keywordMap).length} entries`);
   logger(`Binder items collected: ${Object.keys(projectData.metaByUUID).length}`);
@@ -533,10 +609,7 @@ export function mergeScrivenerProjectMetadata({
   let relocated = 0;
   const fieldAddCounts = {};
   const previewChanges = [];
-  const warnings = [];
-  const warningSummary = {};
-  let warningsTruncated = false;
-
+  const canCreateSnapshots = !dryRun && isGitAvailable() && isGitRepository(mcpSyncDirAbs);
   for (const sidecarPath of sidecarFiles) {
     const filename = path.basename(sidecarPath);
     const prosePath = findProsePathForSidecar(sidecarPath);
@@ -599,7 +672,20 @@ export function mergeScrivenerProjectMetadata({
     const targetProsePath = prosePath
       ? (organizeByChapters ? path.join(targetDir, path.basename(prosePath)) : prosePath)
       : null;
-    const needsMove = path.resolve(sidecarPath) !== path.resolve(targetSidecarPath)
+    const desiredSidecarRelocation = organizeByChapters
+      && path.resolve(sidecarPath) !== path.resolve(targetSidecarPath);
+
+    // Orphan detection: warn once if sidecar has no matching prose and relocation would be attempted.
+    if (!prosePath && desiredSidecarRelocation) {
+      warningsTruncated = pushWarning(warnings, warningSummary, {
+        code: "sidecar_missing_prose",
+        message: "Sidecar has no matching prose file (.md or .txt); relocation skipped to preserve consistency.",
+        file: filename,
+        uuid,
+      }) || warningsTruncated;
+    }
+
+    const needsMove = desiredSidecarRelocation
       || (prosePath && targetProsePath && path.resolve(prosePath) !== path.resolve(targetProsePath));
 
     if (!changed && !needsMove) {
@@ -629,10 +715,14 @@ export function mergeScrivenerProjectMetadata({
       if (needsMove) {
         logger(`        -> ${path.relative(scenesDir, targetSidecarPath) || filename}`);
       }
-      didRelocate = needsMove;
+      const dryRunRelocateEligible = desiredSidecarRelocation
+        && prosePath
+        && (!fs.existsSync(targetSidecarPath))
+        && (!targetProsePath || path.resolve(prosePath) === path.resolve(targetProsePath) || !fs.existsSync(targetProsePath));
+      didRelocate = needsMove && dryRunRelocateEligible;
     } else {
       let proseMoveWarning = null;
-      let shouldRelocateSidecar = organizeByChapters;
+      let shouldRelocateSidecar = desiredSidecarRelocation;
 
       if (
         shouldRelocateSidecar
@@ -653,6 +743,11 @@ export function mergeScrivenerProjectMetadata({
         ) || warningsTruncated;
       }
 
+      // Prevent relocation if sidecar is orphaned (no matching prose)
+      if (shouldRelocateSidecar && !prosePath) {
+        shouldRelocateSidecar = false;
+      }
+
       if (shouldRelocateSidecar && prosePath && targetProsePath) {
         const moveResult = moveFileIfNeeded(prosePath, targetProsePath);
         if (moveResult?.warning) {
@@ -680,6 +775,25 @@ export function mergeScrivenerProjectMetadata({
         fs.unlinkSync(sidecarPath);
       }
 
+      // Create git snapshot for audit trail (only on actual writes, not dry-run)
+      if (canCreateSnapshots) {
+        try {
+          const sceneId = existing?.scene_id ?? `[${syncNum}]`;
+          const commitMessage = `beta merge Scrivener project metadata [${uuid}]`;
+          let snapshotPaths = finalSidecarPath;
+          if (shouldRelocateSidecar) {
+            snapshotPaths = [finalSidecarPath, sidecarPath];
+            if (prosePath && targetProsePath && path.resolve(prosePath) !== path.resolve(targetProsePath)) {
+              snapshotPaths.push(prosePath, targetProsePath);
+            }
+          }
+          createSnapshot(mcpSyncDirAbs, snapshotPaths, sceneId, commitMessage, { messagePrefix: null });
+        } catch (err) {
+          // Snapshot creation errors should not block the merge; log and continue
+          logger(`  WARN  git snapshot creation failed for ${filename}: ${err.message}`);
+        }
+      }
+
       const changes = [];
       if (newKeys.length) changes.push(`+${newKeys.join(", ")}`);
       if (needsMove && shouldRelocateSidecar) {