@hanna84/mcp-writing 3.18.1 → 3.19.0

package/CHANGELOG.md

@@ -4,9 +4,16 @@ 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).
 
+#### [v3.19.0](https://github.com/hannasdev/mcp-writing/compare/v3.18.1...v3.19.0)
+
+- feat: add project database backup foundation [`#219`](https://github.com/hannasdev/mcp-writing/pull/219)
+
 #### [v3.18.1](https://github.com/hannasdev/mcp-writing/compare/v3.18.0...v3.18.1)
 
+> 23 May 2026
+
 - docs(product): activate database backup initiative [`#218`](https://github.com/hannasdev/mcp-writing/pull/218)
+- Release 3.18.1 [`1a04eb9`](https://github.com/hannasdev/mcp-writing/commit/1a04eb905f20c54e5712300aa15bd1e837bc9ba4)
 
 #### [v3.18.0](https://github.com/hannasdev/mcp-writing/compare/v3.17.2...v3.18.0)
 

package/README.md

@@ -30,7 +30,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 - **Core platform complete:** Metadata-first analysis, sidecar-backed metadata maintenance, AI-assisted prose editing with confirmation + git history, review bundles, and Scrivener Direct extraction are all implemented.
 - **Recently completed:** Docker, CI, and Deployment Workflow made Docker a supported way to build, run, smoke-test, and deploy Writing MCP.
 - **Previous milestone:** Filesystem Boundary Hardening centralized local file mutation through application-aware helpers and lint guardrails.
-- **Active development:** Database Backup and Recovery is defining deterministic Git-reviewable backup artifacts for SQLite-canonical project state.
+- **Active development:** Database Backup and Recovery now has project backup export, freshness diagnostics, advisory operation history, and automatic backup refresh after sanctioned project-scoped canonical mutations; the next slice focuses on dry-run restore planning.
 - **Deferred backlog:** OpenClaw integration, client-agnostic setup, divisions, and embeddings search.
 - **Ideas and open questions:** tracked separately so future exploration does not distort the active roadmap.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.18.1",
+  "version": "3.19.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",

package/src/core/filesystem-boundary.js

@@ -454,6 +454,18 @@ export function writeGeneratedOutputFile(filePath, data, {
   }
 }
 
+export function appendGeneratedOutputFile(filePath, data, {
+  encoding,
+  errorCode = "INVALID_OUTPUT_PATH",
+} = {}) {
+  assertRegularFileWriteTarget(filePath, { errorCode });
+  if (encoding) {
+    fs.appendFileSync(filePath, data, encoding);
+  } else {
+    fs.appendFileSync(filePath, data);
+  }
+}
+
 export function copyFileInsideBoundary(sourcePath, targetPath, {
   sourceBoundaryRoot,
   sourceBoundaryRootReal = sourceBoundaryRoot,

package/src/index.js

@@ -469,6 +469,7 @@ function createMcpServer() {
     SYNC_DIR_ABS,
     SYNC_DIR_REAL,
     SYNC_DIR_WRITABLE,
+    MCP_SERVER_VERSION,
     GIT_ENABLED,
     asyncJobs,
     errorResponse,

package/src/structure/project-backup-diagnostics.js

@@ -0,0 +1,346 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  buildProjectBackup,
+  computeProjectBackupBundleChecksum,
+  computeProjectBackupSnapshotChecksum,
+  PROJECT_BACKUP_SCHEMA_VERSION,
+} from "./project-backup.js";
+
+const MANIFEST_FILE = "manifest.json";
+const SNAPSHOT_FILE = "canonical.snapshot.json";
+
+function countBy(items, key) {
+  const result = {};
+  for (const item of items) {
+    const value = item[key] ?? "unknown";
+    result[value] = (result[value] ?? 0) + 1;
+  }
+  return result;
+}
+
+function normalizeRelativePath(syncDir, filePath) {
+  return path.relative(syncDir, filePath).split(path.sep).filter(Boolean).join("/");
+}
+
+function createDiagnostic(type, message, details = {}, {
+  severity = "warning",
+  nextStep = null,
+} = {}) {
+  return {
+    type,
+    severity,
+    message,
+    details,
+    ...(nextStep ? { next_step: nextStep } : {}),
+  };
+}
+
+function addDiagnostic(diagnostics, type, message, details = {}, options = {}) {
+  diagnostics.push(createDiagnostic(type, message, details, options));
+}
+
+function fileState(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, readable: false, regular: false, symlink: false };
+  }
+  let stat;
+  try {
+    stat = fs.lstatSync(filePath);
+  } catch (error) {
+    return {
+      exists: true,
+      readable: false,
+      regular: false,
+      symlink: false,
+      error: "lstat_failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+  return {
+    exists: true,
+    readable: true,
+    regular: stat.isFile(),
+    symlink: stat.isSymbolicLink(),
+  };
+}
+
+function readJsonFile(filePath) {
+  const state = fileState(filePath);
+  if (!state.exists) {
+    return { ok: false, state, error: "missing" };
+  }
+  if (state.symlink || !state.regular) {
+    return { ok: false, state, error: state.error ?? (state.symlink ? "symlink" : "not_regular"), message: state.message };
+  }
+  try {
+    return {
+      ok: true,
+      state,
+      value: JSON.parse(fs.readFileSync(filePath, "utf8")),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      state,
+      error: "unreadable_json",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function statusFromDiagnostics(diagnostics) {
+  if (diagnostics.some(diagnostic => diagnostic.type === "project_backup_stale")) return "stale";
+  if (diagnostics.length) return "untrusted";
+  return "current";
+}
+
+export function runProjectBackupDiagnostics(db, {
+  syncDir,
+  backupDir = null,
+  projectId,
+  applicationVersion = "0.0.0",
+} = {}) {
+  const diagnostics = [];
+  const resolvedBackupDir = path.resolve(backupDir ?? path.join(syncDir, "project-backups", projectId));
+  const relativeBackupDir = normalizeRelativePath(syncDir, resolvedBackupDir);
+  const backupLocation = relativeBackupDir ? `${relativeBackupDir}/` : "./";
+  const manifestPath = path.join(resolvedBackupDir, MANIFEST_FILE);
+  const snapshotPath = path.join(resolvedBackupDir, SNAPSHOT_FILE);
+  const manifestRead = readJsonFile(manifestPath);
+  const snapshotRead = readJsonFile(snapshotPath);
+
+  if (!manifestRead.state.exists && !snapshotRead.state.exists) {
+    addDiagnostic(
+      diagnostics,
+      "project_backup_missing",
+      `Project backup for "${projectId}" is missing.`,
+      {
+        project_id: projectId,
+        backup_dir: resolvedBackupDir,
+        relative_backup_dir: relativeBackupDir,
+      },
+      { nextStep: "Run export_project_backup for this project, then review or commit the generated backup bundle." }
+    );
+  } else if (!manifestRead.state.exists || !snapshotRead.state.exists) {
+    addDiagnostic(
+      diagnostics,
+      "project_backup_partial",
+      `Project backup for "${projectId}" is incomplete.`,
+      {
+        project_id: projectId,
+        backup_dir: resolvedBackupDir,
+        manifest_exists: manifestRead.state.exists,
+        canonical_snapshot_exists: snapshotRead.state.exists,
+      },
+      { nextStep: "Regenerate the backup with export_project_backup before using it for recovery." }
+    );
+  }
+
+  for (const [label, readResult, filePath] of [
+    ["manifest", manifestRead, manifestPath],
+    ["canonical_snapshot", snapshotRead, snapshotPath],
+  ]) {
+    if (!readResult.state.exists) continue;
+    if (!readResult.ok) {
+      addDiagnostic(
+        diagnostics,
+        "project_backup_unreadable",
+        `Project backup ${label} is not readable as trusted JSON.`,
+        {
+          project_id: projectId,
+          backup_dir: resolvedBackupDir,
+          file: filePath,
+          reason: readResult.error,
+          message: readResult.message ?? null,
+        },
+        { nextStep: "Regenerate the backup with export_project_backup before using it for recovery." }
+      );
+    }
+  }
+
+  let built;
+  try {
+    built = buildProjectBackup(db, {
+      projectId,
+      syncDir,
+      applicationVersion,
+      backupLocation,
+    });
+  } catch (error) {
+    built = {
+      ok: false,
+      error: {
+        message: error instanceof Error ? error.message : String(error),
+        details: {
+          project_id: projectId,
+          backup_dir: resolvedBackupDir,
+          phase: "current_snapshot",
+        },
+      },
+    };
+  }
+  if (!built.ok) {
+    addDiagnostic(
+      diagnostics,
+      "project_backup_current_snapshot_failed",
+      built.error.message,
+      built.error.details,
+      { severity: "error", nextStep: "Confirm the project_id exists before diagnosing its backup bundle." }
+    );
+  }
+
+  const manifest = manifestRead.ok ? manifestRead.value : null;
+  const snapshot = snapshotRead.ok ? snapshotRead.value : null;
+
+  if (manifest) {
+    if (manifest.artifact_kind !== "project_backup") {
+      addDiagnostic(
+        diagnostics,
+        "project_backup_wrong_artifact",
+        `Backup manifest for "${projectId}" is not a project backup artifact.`,
+        {
+          project_id: projectId,
+          backup_dir: resolvedBackupDir,
+          artifact_kind: manifest.artifact_kind ?? null,
+        },
+        { nextStep: "Regenerate the backup with export_project_backup." }
+      );
+    }
+    if (manifest.project_id !== projectId) {
+      addDiagnostic(
+        diagnostics,
+        "project_backup_wrong_project",
+        `Backup manifest belongs to project "${manifest.project_id ?? "unknown"}", not "${projectId}".`,
+        {
+          project_id: projectId,
+          backup_dir: resolvedBackupDir,
+          manifest_project_id: manifest.project_id ?? null,
+        },
+        { nextStep: "Choose the backup directory for the requested project or regenerate the backup." }
+      );
+    }
+    if (manifest.schema_version !== PROJECT_BACKUP_SCHEMA_VERSION) {
+      addDiagnostic(
+        diagnostics,
+        "project_backup_incompatible_schema",
+        `Backup manifest schema version "${manifest.schema_version ?? "unknown"}" is not compatible with this server.`,
+        {
+          project_id: projectId,
+          backup_dir: resolvedBackupDir,
+          backup_schema_version: manifest.schema_version ?? null,
+          expected_schema_version: PROJECT_BACKUP_SCHEMA_VERSION,
+        },
+        { nextStep: "Regenerate the backup with a compatible server version before using it for recovery." }
+      );
+    }
+  }
+
+  if (snapshot && snapshot.project?.project_id !== projectId) {
+    addDiagnostic(
+      diagnostics,
+      "project_backup_wrong_project",
+      `Backup snapshot belongs to project "${snapshot.project?.project_id ?? "unknown"}", not "${projectId}".`,
+      {
+        project_id: projectId,
+        backup_dir: resolvedBackupDir,
+        snapshot_project_id: snapshot.project?.project_id ?? null,
+      },
+      { nextStep: "Choose the backup directory for the requested project or regenerate the backup." }
+    );
+  }
+
+  if (manifest && snapshot) {
+    const exportedSnapshotChecksum = manifest.checksums?.canonical_snapshot_sha256 ?? null;
+    const computedSnapshotChecksum = computeProjectBackupSnapshotChecksum(snapshot);
+    if (!exportedSnapshotChecksum || exportedSnapshotChecksum !== computedSnapshotChecksum) {
+      addDiagnostic(
+        diagnostics,
+        "project_backup_checksum_mismatch",
+        `Project backup snapshot checksum does not match manifest for "${projectId}".`,
+        {
+          project_id: projectId,
+          backup_dir: resolvedBackupDir,
+          exported_checksum: exportedSnapshotChecksum,
+          computed_checksum: computedSnapshotChecksum,
+        },
+        { nextStep: "Regenerate the backup with export_project_backup before using it for recovery." }
+      );
+    }
+
+    const exportedBundleChecksum = manifest.checksums?.bundle_sha256 ?? null;
+    const computedBundleChecksum = computeProjectBackupBundleChecksum({ manifest, snapshot });
+    if (!exportedBundleChecksum || exportedBundleChecksum !== computedBundleChecksum) {
+      addDiagnostic(
+        diagnostics,
+        "project_backup_bundle_checksum_mismatch",
+        `Project backup bundle checksum does not match manifest for "${projectId}".`,
+        {
+          project_id: projectId,
+          backup_dir: resolvedBackupDir,
+          exported_checksum: exportedBundleChecksum,
+          computed_checksum: computedBundleChecksum,
+        },
+        { nextStep: "Regenerate the backup with export_project_backup before using it for recovery." }
+      );
+    }
+
+    const canCheckFreshness = diagnostics.length === 0;
+    if (canCheckFreshness && built.ok && exportedSnapshotChecksum === computedSnapshotChecksum) {
+      const currentChecksum = built.manifest.checksums.canonical_snapshot_sha256;
+      if (exportedSnapshotChecksum !== currentChecksum) {
+        addDiagnostic(
+          diagnostics,
+          "project_backup_stale",
+          `Project backup for "${projectId}" is stale relative to current SQLite canonical state.`,
+          {
+            project_id: projectId,
+            backup_dir: resolvedBackupDir,
+            exported_checksum: exportedSnapshotChecksum,
+            current_checksum: currentChecksum,
+          },
+          { nextStep: "Regenerate the backup with export_project_backup, then review the Git diff." }
+        );
+      }
+    }
+  }
+
+  diagnostics.sort((a, b) => {
+    const typeCompare = a.type.localeCompare(b.type);
+    if (typeCompare) return typeCompare;
+    return a.message.localeCompare(b.message);
+  });
+
+  const status = statusFromDiagnostics(diagnostics);
+  return {
+    ok: diagnostics.length === 0,
+    checked: {
+      project_id: projectId,
+      backup_dir: resolvedBackupDir,
+      relative_backup_dir: relativeBackupDir,
+      files: {
+        manifest: manifestPath,
+        canonical_snapshot: snapshotPath,
+      },
+      manifest_exists: manifestRead.state.exists,
+      canonical_snapshot_exists: snapshotRead.state.exists,
+    },
+    trust: {
+      trusted: diagnostics.length === 0,
+      status,
+      freshness: status === "current" ? "current" : status === "stale" ? "stale" : "unknown",
+      schema_version: manifest?.schema_version ?? null,
+      backup_location: manifest?.backup_location ?? null,
+      checksums: manifest?.checksums ?? null,
+    },
+    summary: {
+      total: diagnostics.length,
+      by_type: countBy(diagnostics, "type"),
+      by_severity: countBy(diagnostics, "severity"),
+    },
+    diagnostics,
+    next_steps: diagnostics.length
+      ? ["Follow diagnostic next_step guidance before treating this backup as recovery input."]
+      : ["Project backup is trusted and current relative to SQLite canonical state."],
+  };
+}

package/src/structure/project-backup-operations.js

@@ -0,0 +1,116 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  appendGeneratedOutputFile,
+  assertRegularFileWriteTarget,
+  ensureDirectoryInsideBoundary,
+  resolveGeneratedOutputPath,
+  writeGeneratedOutputFile,
+} from "../core/filesystem-boundary.js";
+import { CURRENT_SCHEMA_VERSION } from "../core/db.js";
+
+export const PROJECT_BACKUP_OPERATION_SCHEMA_VERSION = 1;
+export const PROJECT_BACKUP_OPERATION_LOG_FILE = "operations.jsonl";
+const PROJECT_BACKUP_SCHEMA_VERSION = 1;
+
+function stableStringify(value, indent = 0) {
+  const seen = new WeakSet();
+  function normalize(input) {
+    if (input === null || typeof input !== "object") return input;
+    if (seen.has(input)) {
+      throw new TypeError("Cannot stable-stringify circular structure.");
+    }
+    seen.add(input);
+    if (Array.isArray(input)) {
+      const array = input.map(normalize);
+      seen.delete(input);
+      return array;
+    }
+    const object = {};
+    for (const key of Object.keys(input).sort()) {
+      object[key] = normalize(input[key]);
+    }
+    seen.delete(input);
+    return object;
+  }
+
+  return JSON.stringify(normalize(value), null, indent);
+}
+
+export function buildProjectBackupOperationRecord({
+  operation,
+  projectId,
+  affected = {},
+  timestamp = new Date().toISOString(),
+  actor = null,
+  before = null,
+  after = null,
+  summary = null,
+  applicationVersion = "0.0.0",
+  metadata = {},
+} = {}) {
+  if (!operation || typeof operation !== "string") {
+    throw new TypeError("operation is required.");
+  }
+  if (!projectId || typeof projectId !== "string") {
+    throw new TypeError("projectId is required.");
+  }
+
+  return {
+    artifact_kind: "project_backup_operation",
+    schema_version: PROJECT_BACKUP_OPERATION_SCHEMA_VERSION,
+    backup_schema_version: PROJECT_BACKUP_SCHEMA_VERSION,
+    project_id: projectId,
+    operation,
+    timestamp,
+    actor,
+    affected,
+    summary,
+    before,
+    after,
+    metadata,
+    advisory: true,
+    restore_authority: false,
+    compatibility: {
+      application_version: applicationVersion,
+      current_sqlite_schema_version: CURRENT_SCHEMA_VERSION,
+    },
+  };
+}
+
+export function renderProjectBackupOperationRecord(record) {
+  return `${stableStringify(record, 0)}\n`;
+}
+
+export function ensureProjectBackupOperationLog({ outputDir }) {
+  const normalizedOutputDir = path.resolve(outputDir);
+  ensureDirectoryInsideBoundary(normalizedOutputDir, { label: "backup output_dir" });
+  const operationLogPath = resolveGeneratedOutputPath(normalizedOutputDir, PROJECT_BACKUP_OPERATION_LOG_FILE);
+  assertRegularFileWriteTarget(operationLogPath);
+
+  if (fs.existsSync(operationLogPath)) {
+    return {
+      operationLogPath,
+      written: false,
+    };
+  }
+
+  writeGeneratedOutputFile(operationLogPath, "", { encoding: "utf8" });
+  return {
+    operationLogPath,
+    written: true,
+  };
+}
+
+export function appendProjectBackupOperationRecord(record, { outputDir }) {
+  const { operationLogPath } = ensureProjectBackupOperationLog({ outputDir });
+  appendGeneratedOutputFile(
+    operationLogPath,
+    renderProjectBackupOperationRecord(record),
+    { encoding: "utf8" }
+  );
+  return {
+    operationLogPath,
+    appended: true,
+  };
+}

package/src/structure/project-backup-refresh.js

@@ -0,0 +1,160 @@
+import path from "node:path";
+import { validateProjectId } from "../sync/importer.js";
+import { buildProjectBackup, writeProjectBackupFiles } from "./project-backup.js";
+import {
+  appendProjectBackupOperationRecord,
+  buildProjectBackupOperationRecord,
+} from "./project-backup-operations.js";
+
+function relativePath(syncDirAbs, filePath) {
+  return path.relative(syncDirAbs, filePath).split(path.sep).filter(Boolean).join("/");
+}
+
+function createBackupWarning(code, message, details = {}) {
+  return {
+    code,
+    severity: "warning",
+    message,
+    details,
+  };
+}
+
+export function createToolActor(id) {
+  return {
+    type: "tool",
+    id,
+  };
+}
+
+export function buildPostMutationBackupWarning({
+  projectId,
+  operation,
+  phase,
+  error,
+  details = {},
+}) {
+  const message = error instanceof Error ? error.message : String(error);
+  return createBackupWarning(
+    phase === "operation_history"
+      ? "OPERATION_LOG_APPEND_FAILED"
+      : "PROJECT_BACKUP_REFRESH_FAILED",
+    phase === "operation_history"
+      ? `Canonical mutation '${operation}' succeeded, but the advisory backup operation log could not be updated: ${message}`
+      : `Canonical mutation '${operation}' succeeded, but generated project backup artifacts could not be refreshed: ${message}`,
+    {
+      project_id: projectId,
+      operation,
+      phase,
+      ...details,
+    }
+  );
+}
+
+export function refreshProjectBackupAfterMutation(db, {
+  syncDir,
+  projectId,
+  applicationVersion = "0.0.0",
+  operation,
+  actor = null,
+  affected = {},
+  before = null,
+  after = null,
+  summary = null,
+  metadata = {},
+  timestamp,
+  buildBackup = buildProjectBackup,
+  writeBackup = writeProjectBackupFiles,
+  appendOperation = appendProjectBackupOperationRecord,
+} = {}) {
+  if (!syncDir) throw new TypeError("syncDir is required.");
+  if (!projectId) throw new TypeError("projectId is required.");
+  if (!operation) throw new TypeError("operation is required.");
+  const projectIdCheck = validateProjectId(projectId);
+  if (!projectIdCheck.ok) {
+    throw new TypeError(projectIdCheck.reason);
+  }
+
+  const syncDirAbs = path.resolve(syncDir);
+  const outputDir = path.join(syncDirAbs, "project-backups", projectId);
+  const relativeOutputDir = relativePath(syncDirAbs, outputDir);
+  const backupLocation = relativeOutputDir ? `${relativeOutputDir}/` : "./";
+  const warnings = [];
+
+  let operationHistory = null;
+  const operationRecord = buildProjectBackupOperationRecord({
+    operation,
+    projectId,
+    timestamp,
+    actor,
+    affected,
+    before,
+    after,
+    summary,
+    applicationVersion,
+    metadata,
+  });
+
+  try {
+    const appended = appendOperation(operationRecord, { outputDir });
+    operationHistory = {
+      appended: appended.appended,
+      path: appended.operationLogPath,
+      relative_path: relativePath(syncDirAbs, appended.operationLogPath),
+      advisory: true,
+      restore_authority: false,
+    };
+  } catch (error) {
+    warnings.push(buildPostMutationBackupWarning({
+      projectId,
+      operation,
+      phase: "operation_history",
+      error,
+    }));
+  }
+
+  let backupRefresh = null;
+  try {
+    const built = buildBackup(db, {
+      projectId,
+      syncDir: syncDirAbs,
+      applicationVersion,
+      backupLocation,
+    });
+    if (!built.ok) {
+      throw new Error(built.error?.message ?? "Project backup could not be built.");
+    }
+    const written = writeBackup(built, { outputDir });
+    backupRefresh = {
+      ok: true,
+      output_dir: outputDir,
+      relative_output_dir: relativeOutputDir,
+      files: {
+        manifest: written.manifestPath,
+        canonical_snapshot: written.snapshotPath,
+        operations: written.operationLogPath,
+      },
+      relative_files: {
+        manifest: relativePath(syncDirAbs, written.manifestPath),
+        canonical_snapshot: relativePath(syncDirAbs, written.snapshotPath),
+        operations: relativePath(syncDirAbs, written.operationLogPath),
+      },
+      written: written.written,
+      generated_transparency: true,
+      restore_authority: "manifest_and_canonical_snapshot",
+      git_commit_created: false,
+    };
+  } catch (error) {
+    warnings.push(buildPostMutationBackupWarning({
+      projectId,
+      operation,
+      phase: "backup_refresh",
+      error,
+    }));
+  }
+
+  return {
+    operation_history: operationHistory,
+    backup_refresh: backupRefresh,
+    backup_warnings: warnings,
+  };
+}