@hanna84/mcp-writing 3.18.0 → 3.19.0

package/src/tools/metadata.js

@@ -28,9 +28,58 @@ import {
   upsertExplicitReferenceLinkRow,
   upsertSerializedReferenceLinks,
 } from "./reference-link-persistence.js";
+import {
+  createToolActor,
+  refreshProjectBackupAfterMutation,
+} from "../structure/project-backup-refresh.js";
 
 const STRUCTURAL_SCENE_METADATA_FIELDS = ["part", "chapter", "chapter_id", "timeline_position"];
 
+function emptyBackupMutationResult() {
+  return {
+    operation_history: null,
+    backup_refresh: null,
+    backup_warnings: [],
+  };
+}
+
+function refreshProjectScopedBackupAfterMutation(db, {
+  syncDir,
+  projectId,
+  applicationVersion,
+  operation,
+  actor,
+  affected,
+  before,
+  after,
+  summary,
+  metadata,
+}) {
+  if (!projectId) {
+    return emptyBackupMutationResult();
+  }
+  return refreshProjectBackupAfterMutation(db, {
+    syncDir,
+    projectId,
+    applicationVersion,
+    operation,
+    actor,
+    affected,
+    before,
+    after,
+    summary,
+    metadata,
+  });
+}
+
+function backupMutationFields(backupResult) {
+  return {
+    operation_history: backupResult.operation_history,
+    backup_refresh: backupResult.backup_refresh,
+    backup_warnings: backupResult.backup_warnings,
+  };
+}
+
 function getProvidedStructuralSceneMetadataFields(fields) {
   return STRUCTURAL_SCENE_METADATA_FIELDS.filter((field) => Object.hasOwn(fields, field));
 }
@@ -317,6 +366,7 @@ export function registerMetadataTools(s, {
   db,
   SYNC_DIR,
   SYNC_DIR_WRITABLE,
+  MCP_SERVER_VERSION = "0.0.0",
   errorResponse,
   jsonResponse,
   createCanonicalWorldEntity,
@@ -364,8 +414,34 @@ export function registerMetadataTools(s, {
           universeId: universe_id,
           meta: fields ?? {},
         });
+        const backupResult = refreshProjectScopedBackupAfterMutation(db, {
+          syncDir: SYNC_DIR,
+          projectId: project_id,
+          applicationVersion: MCP_SERVER_VERSION,
+          operation: "create_character_sheet",
+          actor: createToolActor("create_character_sheet"),
+          affected: {
+            characters: [result.id],
+          },
+          summary: `${result.created ? "Created" : "Reused"} character sheet "${result.id}".`,
+          before: null,
+          after: {
+            character: {
+              character_id: result.id,
+              project_id: result.project_id,
+              universe_id: result.universe_id,
+              name,
+            },
+          },
+        });
 
-        return jsonResponse({ ok: true, action: result.created ? "created" : "exists", kind: "character", ...result });
+        return jsonResponse({
+          ok: true,
+          action: result.created ? "created" : "exists",
+          kind: "character",
+          ...result,
+          ...backupMutationFields(backupResult),
+        });
       } catch (err) {
         if (err?.name === "CoreValidationError") {
           return errorResponse(err.code, err.message, err.details);
@@ -416,8 +492,34 @@ export function registerMetadataTools(s, {
           universeId: universe_id,
           meta: fields ?? {},
         });
+        const backupResult = refreshProjectScopedBackupAfterMutation(db, {
+          syncDir: SYNC_DIR,
+          projectId: project_id,
+          applicationVersion: MCP_SERVER_VERSION,
+          operation: "create_place_sheet",
+          actor: createToolActor("create_place_sheet"),
+          affected: {
+            places: [result.id],
+          },
+          summary: `${result.created ? "Created" : "Reused"} place sheet "${result.id}".`,
+          before: null,
+          after: {
+            place: {
+              place_id: result.id,
+              project_id: result.project_id,
+              universe_id: result.universe_id,
+              name,
+            },
+          },
+        });
 
-        return jsonResponse({ ok: true, action: result.created ? "created" : "exists", kind: "place", ...result });
+        return jsonResponse({
+          ok: true,
+          action: result.created ? "created" : "exists",
+          kind: "place",
+          ...result,
+          ...backupMutationFields(backupResult),
+        });
       } catch (err) {
         if (err?.name === "CoreValidationError") {
           return errorResponse(err.code, err.message, err.details);
@@ -443,6 +545,10 @@ export function registerMetadataTools(s, {
       if (!SYNC_DIR_WRITABLE) {
         return errorResponse("READ_ONLY", "Cannot write thread links: sync dir is read-only.");
       }
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
 
       const existingThread = db.prepare(`SELECT thread_id, project_id FROM threads WHERE thread_id = ?`).get(thread_id);
       if (existingThread && existingThread.project_id !== project_id) {
@@ -475,12 +581,30 @@ export function registerMetadataTools(s, {
       const thread = db.prepare(`SELECT * FROM threads WHERE thread_id = ?`).get(thread_id);
       const link = db.prepare(`SELECT scene_id, project_id, thread_id, beat FROM scene_threads WHERE scene_id = ? AND project_id = ? AND thread_id = ?`)
         .get(scene_id, project_id, thread_id);
+      const backupResult = refreshProjectScopedBackupAfterMutation(db, {
+        syncDir: SYNC_DIR,
+        projectId: project_id,
+        applicationVersion: MCP_SERVER_VERSION,
+        operation: "upsert_thread_link",
+        actor: createToolActor("upsert_thread_link"),
+        affected: {
+          threads: [thread_id],
+          scenes: [scene_id],
+        },
+        summary: `Upserted thread "${thread_id}" link for scene "${scene_id}".`,
+        before: null,
+        after: {
+          thread,
+          link,
+        },
+      });
 
       return jsonResponse({
         ok: true,
         action: "upserted",
         thread,
         link,
+        ...backupMutationFields(backupResult),
       });
     }
   );
@@ -511,7 +635,7 @@ export function registerMetadataTools(s, {
       }
 
       const targetDoc = db.prepare(`
-        SELECT doc_id
+        SELECT doc_id, project_id
         FROM reference_docs
         WHERE doc_id = ?
       `).get(target_doc_id);
@@ -623,11 +747,29 @@ export function registerMetadataTools(s, {
         FROM reference_links
         WHERE source_kind = ? AND source_project_id = ? AND source_id = ? AND target_doc_id = ? AND relation = ?
       `).get(source_kind, resolvedSourceProjectId, source_id, target_doc_id, normalizedRelation);
+      const backupProjectId = resolvedSourceProjectId || targetDoc.project_id || null;
+      const backupResult = refreshProjectScopedBackupAfterMutation(db, {
+        syncDir: SYNC_DIR,
+        projectId: backupProjectId,
+        applicationVersion: MCP_SERVER_VERSION,
+        operation: "upsert_reference_link",
+        actor: createToolActor("upsert_reference_link"),
+        affected: {
+          reference_docs: [target_doc_id],
+          sources: [`${source_kind}:${source_id}`],
+        },
+        summary: `Upserted ${source_kind} reference link from "${source_id}" to "${target_doc_id}".`,
+        before: null,
+        after: {
+          link,
+        },
+      });
 
       return jsonResponse({
         ok: true,
         action: "upserted",
         link,
+        ...backupMutationFields(backupResult),
       });
     }
   );
@@ -683,6 +825,29 @@ export function registerMetadataTools(s, {
         return errorResponse("IO_ERROR", `Failed to create chapter '${plan.chapter.chapter_id}': ${err.message}`);
       }
 
+      const backupResult = refreshProjectBackupAfterMutation(db, {
+        syncDir: SYNC_DIR,
+        projectId: project_id,
+        applicationVersion: MCP_SERVER_VERSION,
+        operation: "create_chapter",
+        actor: createToolActor("create_chapter"),
+        affected: {
+          chapters: [plan.chapter.chapter_id],
+        },
+        summary: `Created chapter "${plan.chapter.title}" at sort_index ${plan.chapter.sort_index}.`,
+        before: null,
+        after: {
+          chapter: {
+            chapter_id: plan.chapter.chapter_id,
+            project_id: plan.chapter.project_id,
+            title: plan.chapter.title,
+            sort_index: plan.chapter.sort_index,
+            logline: plan.chapter.logline,
+            metadata_stale: plan.chapter.metadata_stale,
+          },
+        },
+      });
+
       return jsonResponse({
         ok: true,
         action: "created",
@@ -695,6 +860,9 @@ export function registerMetadataTools(s, {
           metadata_stale: plan.chapter.metadata_stale,
         },
         diagnostics: plan.diagnostics,
+        operation_history: backupResult.operation_history,
+        backup_refresh: backupResult.backup_refresh,
+        backup_warnings: backupResult.backup_warnings,
         next_steps: [
           "Use assign_scene_to_chapter to place unchaptered scenes in this chapter.",
           "Run diagnose_structure if existing folders or sidecars may imply conflicting structure.",
@@ -781,6 +949,39 @@ export function registerMetadataTools(s, {
         failureCode: "SCENE_SIDECAR_UPDATE_FAILED",
         syncDir: SYNC_DIR,
       });
+      const backupResult = refreshProjectBackupAfterMutation(db, {
+        syncDir: SYNC_DIR,
+        projectId: project_id,
+        applicationVersion: MCP_SERVER_VERSION,
+        operation: "rename_chapter",
+        actor: createToolActor("rename_chapter"),
+        affected: {
+          chapters: [plan.chapter.chapter_id],
+          scenes: linkedScenes.map(scene => scene.scene_id),
+        },
+        summary: `Renamed chapter "${plan.previousChapter.title}" to "${plan.chapter.title}".`,
+        before: {
+          chapter: {
+            chapter_id: plan.previousChapter.chapter_id,
+            title: plan.previousChapter.title,
+            sort_index: plan.previousChapter.sort_index,
+          },
+        },
+        after: {
+          chapter: {
+            chapter_id: plan.chapter.chapter_id,
+            project_id: plan.chapter.project_id,
+            title: plan.chapter.title,
+            sort_index: plan.chapter.sort_index,
+            logline: plan.chapter.logline,
+            metadata_stale: plan.chapter.metadata_stale,
+          },
+        },
+        metadata: {
+          updated_scene_count: linkedScenes.length,
+          updated_sidecar_count: sidecarWriteResult.updatedCount,
+        },
+      });
 
       return jsonResponse({
         ok: true,
@@ -800,6 +1001,9 @@ export function registerMetadataTools(s, {
           ...plan.diagnostics,
           ...sidecarWriteResult.diagnostics,
         ],
+        operation_history: backupResult.operation_history,
+        backup_refresh: backupResult.backup_refresh,
+        backup_warnings: backupResult.backup_warnings,
         next_steps: [
           "Use list_chapters to confirm the canonical title.",
           "Run diagnose_structure if folder-derived structure may still use the previous chapter title.",
@@ -887,6 +1091,39 @@ export function registerMetadataTools(s, {
         failureCode: "SCENE_SIDECAR_UPDATE_FAILED",
         syncDir: SYNC_DIR,
       });
+      const backupResult = refreshProjectBackupAfterMutation(db, {
+        syncDir: SYNC_DIR,
+        projectId: project_id,
+        applicationVersion: MCP_SERVER_VERSION,
+        operation: "reorder_chapter",
+        actor: createToolActor("reorder_chapter"),
+        affected: {
+          chapters: [plan.chapter.chapter_id],
+          scenes: linkedScenes.map(scene => scene.scene_id),
+        },
+        summary: `Reordered chapter "${plan.chapter.title}" from ${plan.previousChapter.sort_index} to ${plan.chapter.sort_index}.`,
+        before: {
+          chapter: {
+            chapter_id: plan.previousChapter.chapter_id,
+            title: plan.previousChapter.title,
+            sort_index: plan.previousChapter.sort_index,
+          },
+        },
+        after: {
+          chapter: {
+            chapter_id: plan.chapter.chapter_id,
+            project_id: plan.chapter.project_id,
+            title: plan.chapter.title,
+            sort_index: plan.chapter.sort_index,
+            logline: plan.chapter.logline,
+            metadata_stale: plan.chapter.metadata_stale,
+          },
+        },
+        metadata: {
+          updated_scene_count: linkedScenes.length,
+          updated_sidecar_count: sidecarWriteResult.updatedCount,
+        },
+      });
 
       return jsonResponse({
         ok: true,
@@ -906,6 +1143,9 @@ export function registerMetadataTools(s, {
           ...plan.diagnostics,
           ...sidecarWriteResult.diagnostics,
         ],
+        operation_history: backupResult.operation_history,
+        backup_refresh: backupResult.backup_refresh,
+        backup_warnings: backupResult.backup_warnings,
         next_steps: [
           "Use list_chapters to confirm canonical order.",
           "Run diagnose_structure if folder-derived structure may still use the previous order.",
@@ -969,6 +1209,40 @@ export function registerMetadataTools(s, {
           failureCode: "EPIGRAPH_SIDECAR_UPDATE_FAILED",
           syncDir: SYNC_DIR,
         });
+        const backupResult = refreshProjectBackupAfterMutation(db, {
+          syncDir: SYNC_DIR,
+          projectId: project_id,
+          applicationVersion: MCP_SERVER_VERSION,
+          operation: "attach_epigraph",
+          actor: createToolActor("attach_epigraph"),
+          affected: {
+            epigraphs: [plan.epigraph.epigraph_id],
+            chapters: [plan.chapter.chapter_id],
+          },
+          summary: `Attached epigraph "${plan.epigraph.epigraph_id}" to chapter "${plan.chapter.title}".`,
+          before: {
+            epigraph: {
+              epigraph_id: plan.epigraph.epigraph_id,
+              chapter_id: plan.previousChapter?.chapter_id ?? null,
+            },
+          },
+          after: {
+            epigraph: {
+              epigraph_id: plan.epigraph.epigraph_id,
+              project_id: plan.epigraph.project_id,
+              chapter_id: plan.epigraph.chapter_id,
+              metadata_stale: plan.epigraph.metadata_stale,
+            },
+            chapter: {
+              chapter_id: plan.chapter.chapter_id,
+              title: plan.chapter.title,
+              sort_index: plan.chapter.sort_index,
+            },
+          },
+          metadata: {
+            updated_sidecar_count: sidecarWriteResult.updatedCount,
+          },
+        });
 
         return jsonResponse({
           ok: true,
@@ -996,6 +1270,9 @@ export function registerMetadataTools(s, {
             ...plan.diagnostics,
             ...sidecarWriteResult.diagnostics,
           ],
+          operation_history: backupResult.operation_history,
+          backup_refresh: backupResult.backup_refresh,
+          backup_warnings: backupResult.backup_warnings,
           next_steps: [
             "Use find_epigraphs to confirm the canonical epigraph attachment.",
             "Run diagnose_structure if folder-derived structure may still imply the previous chapter.",
@@ -1146,6 +1423,40 @@ export function registerMetadataTools(s, {
             managedStructure: isManagedStructureProject(db, project_id),
           });
         }
+        const backupResult = refreshProjectBackupAfterMutation(db, {
+          syncDir: SYNC_DIR,
+          projectId: project_id,
+          applicationVersion: MCP_SERVER_VERSION,
+          operation: "move_scene",
+          actor: createToolActor("move_scene"),
+          affected: {
+            scenes: [scene_id],
+            chapters: [
+              plan.previousChapterId ?? null,
+              plan.assignedChapter?.chapter_id ?? null,
+            ].filter(Boolean),
+          },
+          summary: `Moved scene "${scene_id}" to ${plan.assignedChapter?.chapter_id ?? "no chapter"} at timeline_position ${plan.timelinePosition ?? "unchanged"}.`,
+          before: {
+            scene: {
+              scene_id,
+              project_id,
+              chapter_id: plan.previousChapterId ?? null,
+              timeline_position: plan.previousTimelinePosition ?? null,
+            },
+          },
+          after: {
+            scene: {
+              scene_id,
+              project_id,
+              chapter_id: plan.assignedChapter?.chapter_id ?? null,
+              timeline_position: plan.timelinePosition ?? null,
+            },
+          },
+          metadata: {
+            updated_sidecar_count: sidecarMirror.updatedCount,
+          },
+        });
 
         return jsonResponse({
           ok: true,
@@ -1169,6 +1480,9 @@ export function registerMetadataTools(s, {
             },
             ...sidecarMirror.diagnostics,
           ],
+          operation_history: backupResult.operation_history,
+          backup_refresh: backupResult.backup_refresh,
+          backup_warnings: backupResult.backup_warnings,
           next_steps: [
             "Use find_scenes to confirm the scene's canonical chapter and timeline_position.",
             "Run diagnose_structure if folder-derived structure may still imply the previous placement.",
@@ -1264,6 +1578,40 @@ export function registerMetadataTools(s, {
             managedStructure: isManagedStructureProject(db, project_id),
           });
         }
+        const backupResult = refreshProjectBackupAfterMutation(db, {
+          syncDir: SYNC_DIR,
+          projectId: project_id,
+          applicationVersion: MCP_SERVER_VERSION,
+          operation: "assign_scene_to_chapter",
+          actor: createToolActor("assign_scene_to_chapter"),
+          affected: {
+            scenes: [scene_id],
+            chapters: [
+              plan.previousChapterId ?? scene.chapter_id ?? null,
+              plan.assignedChapter?.chapter_id ?? null,
+            ].filter(Boolean),
+          },
+          summary: chapter === null
+            ? `Cleared chapter assignment for scene "${scene_id}".`
+            : `Assigned scene "${scene_id}" to chapter "${plan.assignedChapter.chapter_id}".`,
+          before: {
+            scene: {
+              scene_id,
+              project_id,
+              chapter_id: plan.previousChapterId ?? scene.chapter_id ?? null,
+            },
+          },
+          after: {
+            scene: {
+              scene_id,
+              project_id,
+              chapter_id: plan.assignedChapter?.chapter_id ?? null,
+            },
+          },
+          metadata: {
+            updated_sidecar_count: sidecarMirror.updatedCount,
+          },
+        });
 
         return jsonResponse({
           ok: true,
@@ -1274,6 +1622,9 @@ export function registerMetadataTools(s, {
           chapter: plan.assignedChapter,
           updated_sidecar_count: sidecarMirror.updatedCount,
           diagnostics: sidecarMirror.diagnostics,
+          operation_history: backupResult.operation_history,
+          backup_refresh: backupResult.backup_refresh,
+          backup_warnings: backupResult.backup_warnings,
         });
       } catch (err) {
         if (err?.name === "CoreValidationError") {
@@ -1341,8 +1692,46 @@ export function registerMetadataTools(s, {
         indexSceneFile(db, SYNC_DIR, scene.file_path, updated, prose, {
           managedStructure: isManagedStructureProject(db, project_id),
         });
+        const backupResult = refreshProjectScopedBackupAfterMutation(db, {
+          syncDir: SYNC_DIR,
+          projectId: project_id,
+          applicationVersion: MCP_SERVER_VERSION,
+          operation: "update_scene_metadata",
+          actor: createToolActor("update_scene_metadata"),
+          affected: {
+            scenes: [scene_id],
+          },
+          summary: `Updated metadata for scene "${scene_id}".`,
+          before: {
+            scene: {
+              scene_id,
+              project_id,
+              fields: Object.keys(fields).sort().reduce((acc, key) => {
+                acc[key] = meta[key] ?? null;
+                return acc;
+              }, {}),
+            },
+          },
+          after: {
+            scene: {
+              scene_id,
+              project_id,
+              fields: Object.keys(fields).sort().reduce((acc, key) => {
+                acc[key] = updated[key] ?? null;
+                return acc;
+              }, {}),
+            },
+          },
+        });
 
-        return { content: [{ type: "text", text: `Updated metadata for scene '${scene_id}'.` }] };
+        return jsonResponse({
+          ok: true,
+          action: "updated",
+          message: `Updated metadata for scene '${scene_id}'.`,
+          scene_id,
+          project_id,
+          ...backupMutationFields(backupResult),
+        });
       } catch (err) {
         if (err.code === "ENOENT") {
           return errorResponse("STALE_PATH", `Prose file for scene '${scene_id}' not found at indexed path — the file may have moved. Run sync() to refresh.`, { indexed_path: scene.file_path });
@@ -1370,7 +1759,7 @@ export function registerMetadataTools(s, {
       if (!SYNC_DIR_WRITABLE) {
         return errorResponse("READ_ONLY", "Cannot update character: sync dir is read-only.");
       }
-      const char = db.prepare(`SELECT file_path FROM characters WHERE character_id = ?`).get(character_id);
+      const char = db.prepare(`SELECT character_id, project_id, universe_id, file_path, name, role, arc_summary, first_appearance FROM characters WHERE character_id = ?`).get(character_id);
       if (!char) {
         return errorResponse("NOT_FOUND", `Character '${character_id}' not found.`);
       }
@@ -1393,8 +1782,47 @@ export function registerMetadataTools(s, {
             db.prepare(`INSERT OR IGNORE INTO character_traits (character_id, trait) VALUES (?, ?)`).run(character_id, t);
           }
         }
+        const backupResult = refreshProjectScopedBackupAfterMutation(db, {
+          syncDir: SYNC_DIR,
+          projectId: char.project_id,
+          applicationVersion: MCP_SERVER_VERSION,
+          operation: "update_character_sheet",
+          actor: createToolActor("update_character_sheet"),
+          affected: {
+            characters: [character_id],
+          },
+          summary: `Updated character sheet "${character_id}".`,
+          before: {
+            character: {
+              character_id,
+              project_id: char.project_id,
+              universe_id: char.universe_id,
+              name: char.name,
+              role: char.role,
+              arc_summary: char.arc_summary,
+              first_appearance: char.first_appearance,
+            },
+          },
+          after: {
+            character: {
+              character_id,
+              project_id: char.project_id,
+              universe_id: char.universe_id,
+              name: updated.name ?? meta.name ?? null,
+              role: updated.role ?? null,
+              arc_summary: updated.arc_summary ?? null,
+              first_appearance: updated.first_appearance ?? null,
+            },
+          },
+        });
 
-        return { content: [{ type: "text", text: `Updated character sheet for '${character_id}'.` }] };
+        return jsonResponse({
+          ok: true,
+          action: "updated",
+          message: `Updated character sheet for '${character_id}'.`,
+          character_id,
+          ...backupMutationFields(backupResult),
+        });
       } catch (err) {
         if (err?.name === "CoreValidationError") {
           return errorResponse(err.code, err.message, err.details);
@@ -1423,7 +1851,7 @@ export function registerMetadataTools(s, {
       if (!SYNC_DIR_WRITABLE) {
         return errorResponse("READ_ONLY", "Cannot update place: sync dir is read-only.");
       }
-      const place = db.prepare(`SELECT file_path FROM places WHERE place_id = ?`).get(place_id);
+      const place = db.prepare(`SELECT place_id, project_id, universe_id, file_path, name FROM places WHERE place_id = ?`).get(place_id);
       if (!place) {
         return errorResponse("NOT_FOUND", `Place '${place_id}' not found.`);
       }
@@ -1434,8 +1862,41 @@ export function registerMetadataTools(s, {
 
         db.prepare(`UPDATE places SET name = ? WHERE place_id = ?`)
           .run(updated.name ?? meta.name ?? place_id, place_id);
+        const backupResult = refreshProjectScopedBackupAfterMutation(db, {
+          syncDir: SYNC_DIR,
+          projectId: place.project_id,
+          applicationVersion: MCP_SERVER_VERSION,
+          operation: "update_place_sheet",
+          actor: createToolActor("update_place_sheet"),
+          affected: {
+            places: [place_id],
+          },
+          summary: `Updated place sheet "${place_id}".`,
+          before: {
+            place: {
+              place_id,
+              project_id: place.project_id,
+              universe_id: place.universe_id,
+              name: place.name,
+            },
+          },
+          after: {
+            place: {
+              place_id,
+              project_id: place.project_id,
+              universe_id: place.universe_id,
+              name: updated.name ?? meta.name ?? place_id,
+            },
+          },
+        });
 
-        return { content: [{ type: "text", text: `Updated place sheet for '${place_id}'.` }] };
+        return jsonResponse({
+          ok: true,
+          action: "updated",
+          message: `Updated place sheet for '${place_id}'.`,
+          place_id,
+          ...backupMutationFields(backupResult),
+        });
       } catch (err) {
         if (err?.name === "CoreValidationError") {
           return errorResponse(err.code, err.message, err.details);