@hanna84/mcp-writing 1.6.0 → 1.6.1

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).
 
+#### [v1.6.1](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.6.0...v1.6.1)
+
+- fix: preflight prose writes and make canonical sheet creation idempotent [`#46`](https://github.com/hannasdev/mcp-writing.git
+/pull/46)
+
 #### [v1.6.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.5.2...v1.6.0)
 
+> 19 April 2026
+
 - feat: add permission preflight diagnostics and ops contract [`#45`](https://github.com/hannasdev/mcp-writing.git
 /pull/45)
+- Release 1.6.0 [`bfab6d2`](https://github.com/hannasdev/mcp-writing.git
+/commit/bfab6d205f4c60bf9e59cb4097796fc7cef63158)
 
 #### [v1.5.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.5.1...v1.5.2)

package/index.js

@@ -7,7 +7,7 @@ import matter from "gray-matter";
 import yaml from "js-yaml";
 import { z } from "zod";
 import { openDb } from "./db.js";
-import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, sidecarPath } from "./sync.js";
+import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, getFileWriteDiagnostics, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, sidecarPath } from "./sync.js";
 import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit } from "./git.js";
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
 import { importScrivenerSync, validateProjectId } from "./importer.js";
@@ -180,28 +180,72 @@ function createCanonicalWorldEntity({ kind, name, notes, projectId, universeId,
   const { dir } = resolveWorldEntityDir({ kind, projectId, universeId, name });
   const prosePath = path.join(dir, "sheet.md");
   const metaPath = sidecarPath(prosePath);
-  if (fs.existsSync(prosePath) || fs.existsSync(metaPath)) {
-    throw new Error(`Canonical sheet already exists at ${dir}`);
+  const hadProse = fs.existsSync(prosePath);
+  const hadMeta = fs.existsSync(metaPath);
+
+  let shouldWriteMeta = !hadMeta;
+  let payload;
+  const derivedId = `${prefix}-${slug}`;
+  if (hadMeta) {
+    let parsedMeta;
+    try {
+      parsedMeta = yaml.load(fs.readFileSync(metaPath, "utf8"));
+    } catch (err) {
+      throw new Error(
+        `Existing metadata sidecar is invalid YAML at ${metaPath}: ${err.message}`,
+        { cause: err }
+      );
+    }
+
+    if (parsedMeta != null && (typeof parsedMeta !== "object" || Array.isArray(parsedMeta))) {
+      throw new Error(`Existing metadata sidecar must be a YAML mapping at ${metaPath}.`);
+    }
+
+    const existingMeta = parsedMeta ?? {};
+
+    const backfilledId = existingMeta[idKey] ?? derivedId;
+    const backfilledName = existingMeta.name ?? name;
+    shouldWriteMeta = existingMeta[idKey] == null || existingMeta.name == null;
+    payload = shouldWriteMeta
+      ? {
+        ...existingMeta,
+        [idKey]: backfilledId,
+        name: backfilledName,
+      }
+      : existingMeta;
+  } else {
+    payload = {
+      [idKey]: derivedId,
+      name,
+      ...(meta ?? {}),
+    };
   }
 
   fs.mkdirSync(dir, { recursive: true });
-  const defaultSheet = kind === "character"
-    ? renderCharacterSheetTemplate(name)
-    : renderPlaceSheetTemplate(name);
-  fs.writeFileSync(prosePath, `${notes?.trim() ?? defaultSheet}${(notes?.trim() ?? defaultSheet) ? "\n" : ""}`, "utf8");
+
+  if (!hadProse) {
+    const defaultSheet = kind === "character"
+      ? renderCharacterSheetTemplate(name)
+      : renderPlaceSheetTemplate(name);
+    const body = notes?.trim() ?? defaultSheet;
+    fs.writeFileSync(prosePath, `${body}${body ? "\n" : ""}`, "utf8");
+  }
+
   if (kind === "character") {
-    fs.writeFileSync(path.join(dir, "arc.md"), `${renderCharacterArcTemplate(name)}\n`, "utf8");
+    const arcPath = path.join(dir, "arc.md");
+    if (!fs.existsSync(arcPath)) {
+      fs.writeFileSync(arcPath, `${renderCharacterArcTemplate(name)}\n`, "utf8");
+    }
+  }
+
+  if (shouldWriteMeta) {
+    fs.writeFileSync(metaPath, yaml.dump(payload, { lineWidth: 120 }), "utf8");
   }
-  const payload = {
-    [idKey]: `${prefix}-${slug}`,
-    name,
-    ...meta,
-  };
-  fs.writeFileSync(metaPath, yaml.dump(payload, { lineWidth: 120 }), "utf8");
 
   syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
 
   return {
+    created: !hadProse && !hadMeta,
     id: payload[idKey],
     prose_path: prosePath,
     meta_path: metaPath,
@@ -711,7 +755,7 @@ function createMcpServer() {
   // ---- create_character_sheet ---------------------------------------------
   s.tool(
     "create_character_sheet",
-    "Create a canonical character sheet folder with sheet.md and sheet.meta.yaml so the character can be indexed immediately. Use this before migrating freeform notes into the new folder structure.",
+    "Create or reuse a canonical character sheet folder with sheet.md and sheet.meta.yaml so the character can be indexed immediately. If the folder already exists, missing canonical files are backfilled and the existing sheet is preserved.",
     {
       name: z.string().describe("Display name of the character (e.g. 'Mira Nystrom')."),
       project_id: z.string().optional().describe("Project scope for a book-local character (e.g. 'universe-1/book-1-the-lamb' or 'test-novel')."),
@@ -733,7 +777,7 @@ function createMcpServer() {
       }
 
       try {
-        const created = createCanonicalWorldEntity({
+        const result = createCanonicalWorldEntity({
           kind: "character",
           name,
           notes,
@@ -742,7 +786,7 @@ function createMcpServer() {
           meta: fields ?? {},
         });
 
-        return jsonResponse({ ok: true, action: "created", kind: "character", ...created });
+        return jsonResponse({ ok: true, action: result.created ? "created" : "exists", kind: "character", ...result });
       } catch (err) {
         return errorResponse("IO_ERROR", `Failed to create character sheet: ${err.message}`);
       }
@@ -777,7 +821,7 @@ function createMcpServer() {
   // ---- create_place_sheet -------------------------------------------------
   s.tool(
     "create_place_sheet",
-    "Create a canonical place sheet folder with sheet.md and sheet.meta.yaml so the place can be indexed immediately. Use this before migrating freeform notes into the new folder structure.",
+    "Create or reuse a canonical place sheet folder with sheet.md and sheet.meta.yaml so the place can be indexed immediately. If the folder already exists, missing canonical files are backfilled and the existing sheet is preserved.",
     {
       name: z.string().describe("Display name of the place (e.g. 'University Hospital')."),
       project_id: z.string().optional().describe("Project scope for a book-local place (e.g. 'universe-1/book-1-the-lamb' or 'test-novel')."),
@@ -797,7 +841,7 @@ function createMcpServer() {
       }
 
       try {
-        const created = createCanonicalWorldEntity({
+        const result = createCanonicalWorldEntity({
           kind: "place",
           name,
           notes,
@@ -806,7 +850,7 @@ function createMcpServer() {
           meta: fields ?? {},
         });
 
-        return jsonResponse({ ok: true, action: "created", kind: "place", ...created });
+        return jsonResponse({ ok: true, action: result.created ? "created" : "exists", kind: "place", ...result });
       } catch (err) {
         return errorResponse("IO_ERROR", `Failed to create place sheet: ${err.message}`);
       }
@@ -1383,6 +1427,54 @@ function createMcpServer() {
       }
 
       try {
+        const proseWriteDiagnostics = getFileWriteDiagnostics(proposal.scene_file_path);
+        if (proseWriteDiagnostics.stat_error_code === "EACCES" || proseWriteDiagnostics.stat_error_code === "EPERM") {
+          return errorResponse(
+            "PROSE_FILE_NOT_WRITABLE",
+            "Scene prose file cannot be accessed by the current runtime user.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
+        if (proseWriteDiagnostics.stat_error_code && proseWriteDiagnostics.stat_error_code !== "ENOENT" && proseWriteDiagnostics.stat_error_code !== "ENOTDIR") {
+          return errorResponse(
+            "IO_ERROR",
+            "Failed to inspect scene prose path before writing.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
+        if (!proseWriteDiagnostics.exists) {
+          return errorResponse("STALE_PATH", "Prose file not found at indexed path.", {
+            indexed_path: proposal.scene_file_path,
+            prose_write_diagnostics: proseWriteDiagnostics,
+          });
+        }
+
+        if (!proseWriteDiagnostics.is_file) {
+          return errorResponse("INVALID_PROSE_PATH", "Indexed prose path is not a regular file.", {
+            indexed_path: proposal.scene_file_path,
+            prose_write_diagnostics: proseWriteDiagnostics,
+          });
+        }
+
+        if (!proseWriteDiagnostics.writable) {
+          return errorResponse(
+            "PROSE_FILE_NOT_WRITABLE",
+            "Scene prose file is not writable by the current runtime user.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
         // Reconstruct file content, preserving frontmatter only if the original had it
         const hasFrontmatter = proposal.metadata && Object.keys(proposal.metadata).length > 0;
         const content = hasFrontmatter

package/package.json

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

package/sync.js

@@ -297,6 +297,54 @@ export function getSyncOwnershipDiagnostics(syncDir, { sampleLimit = 200 } = {})
   return diagnostics;
 }
 
+export function getFileWriteDiagnostics(filePath) {
+  const runtimeUid = typeof process.getuid === "function" ? process.getuid() : null;
+  const resolvedPath = path.resolve(filePath);
+  const parentDir = path.dirname(resolvedPath);
+  const diagnostics = {
+    path: resolvedPath,
+    parent_dir: parentDir,
+    exists: false,
+    is_file: false,
+    writable: false,
+    parent_dir_writable: false,
+    supported: runtimeUid !== null,
+    runtime_uid: runtimeUid,
+    owner_uid: null,
+    root_owned: false,
+    stat_error_code: null,
+    stat_error_message: null,
+  };
+
+  try {
+    fs.accessSync(parentDir, fs.constants.W_OK);
+    diagnostics.parent_dir_writable = true;
+  } catch {
+    diagnostics.parent_dir_writable = false;
+  }
+
+  try {
+    const stat = fs.statSync(resolvedPath);
+    diagnostics.exists = true;
+    diagnostics.is_file = stat.isFile();
+    diagnostics.owner_uid = typeof stat.uid === "number" ? stat.uid : null;
+    diagnostics.root_owned = stat.uid === 0;
+  } catch (err) {
+    diagnostics.stat_error_code = typeof err?.code === "string" ? err.code : null;
+    diagnostics.stat_error_message = typeof err?.message === "string" ? err.message : String(err);
+    return diagnostics;
+  }
+
+  try {
+    fs.accessSync(resolvedPath, fs.constants.W_OK);
+    diagnostics.writable = diagnostics.is_file;
+  } catch {
+    diagnostics.writable = false;
+  }
+
+  return diagnostics;
+}
+
 // ---------------------------------------------------------------------------
 // DB-dependent sync (takes db + syncDir as arguments for testability)
 // ---------------------------------------------------------------------------