@hanna84/mcp-writing 2.9.8 → 2.10.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).
 
+#### [v2.10.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.9.9...v2.10.0)
+
+- feat(db): persist async job state to SQLite for restart recovery [`#104`](https://github.com/hannasdev/mcp-writing.git
+/pull/104)
+
+#### [v2.9.9](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.9.8...v2.9.9)
+
+> 26 April 2026
+
+- refactor(db): replace ad-hoc migration checks with numbered migration… [`#102`](https://github.com/hannasdev/mcp-writing.git
+/pull/102)
+- Release 2.9.9 [`22babc1`](https://github.com/hannasdev/mcp-writing.git
+/commit/22babc1e857a3401240c28b5ac59164e01fd3784)
+
 #### [v2.9.8](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.9.7...v2.9.8)
 
+> 26 April 2026
+
 - refactor(tools): extract registerEditingTools into tools/editing.js [`#101`](https://github.com/hannasdev/mcp-writing.git
 /pull/101)
+- Release 2.9.8 [`6e7d649`](https://github.com/hannasdev/mcp-writing.git
+/commit/6e7d64997cd22b6111a7053ef6050b568443c6b5)
 
 #### [v2.9.7](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.9.6...v2.9.7)

package/db.js

@@ -119,28 +119,42 @@ export const SCHEMA = `
   CREATE VIRTUAL TABLE IF NOT EXISTS scenes_fts USING fts5(
     scene_id, project_id, logline, title, keywords
   );
-`;
 
-export function openDb(dbPath) {
-  const db = new DatabaseSync(dbPath);
-  db.exec(SCHEMA);
+  CREATE TABLE IF NOT EXISTS schema_version (
+    id      INTEGER PRIMARY KEY CHECK (id = 1),
+    version INTEGER NOT NULL
+  );
 
-  const sceneColumns = db.prepare(`PRAGMA table_info(scenes)`).all();
-  if (!sceneColumns.some(column => column.name === "chapter_title")) {
-    db.exec(`ALTER TABLE scenes ADD COLUMN chapter_title TEXT;`);
-  }
+  CREATE TABLE IF NOT EXISTS async_jobs (
+    job_id      TEXT NOT NULL PRIMARY KEY,
+    kind        TEXT NOT NULL,
+    status      TEXT NOT NULL,
+    created_at  TEXT NOT NULL,
+    started_at  TEXT,
+    finished_at TEXT,
+    error       TEXT,
+    result_json TEXT
+  );
+`;
 
-  // Rebuild legacy FTS table if it predates keyword indexing.
-  // Preserve existing indexed rows so metadata search remains available
-  // even before the next sync pass repopulates from source files.
-  const ftsSql = db.prepare(`
-    SELECT sql
-    FROM sqlite_master
-    WHERE type = 'table' AND name = 'scenes_fts'
-  `).get()?.sql;
-  if (typeof ftsSql === "string" && !ftsSql.toLowerCase().includes("keywords")) {
-    db.exec(`BEGIN IMMEDIATE;`);
-    try {
+// Each function is applied exactly once, in order, when version < its index+1.
+// Each migration runs inside a transaction with the version bump — crash-safe.
+// Migrations must be idempotent (guard against already-applied state).
+// Never edit existing entries — add new ones at the end.
+const MIGRATIONS = [
+  // 1: add chapter_title column to scenes
+  (db) => {
+    const sceneColumns = db.prepare(`PRAGMA table_info(scenes)`).all();
+    if (!sceneColumns.some(c => c.name === "chapter_title")) {
+      db.exec(`ALTER TABLE scenes ADD COLUMN chapter_title TEXT;`);
+    }
+  },
+  // 2: rebuild FTS table to include keywords column (preserve existing rows)
+  (db) => {
+    const ftsSql = db.prepare(`
+      SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'scenes_fts'
+    `).get()?.sql;
+    if (typeof ftsSql === "string" && !ftsSql.toLowerCase().includes("keywords")) {
       db.exec(`
         CREATE VIRTUAL TABLE scenes_fts_migrating USING fts5(
           scene_id, project_id, logline, title, keywords
@@ -153,12 +167,102 @@ export function openDb(dbPath) {
       `);
       db.exec(`DROP TABLE scenes_fts;`);
       db.exec(`ALTER TABLE scenes_fts_migrating RENAME TO scenes_fts;`);
+    }
+  },
+];
+
+// The version every database should reach after openDb. Not the current DB value —
+// query schema_version directly if you need the live version of a specific database.
+export const CURRENT_SCHEMA_VERSION = MIGRATIONS.length;
+
+function applyMigrations(db) {
+  db.prepare(`INSERT OR IGNORE INTO schema_version (id, version) VALUES (1, 0)`).run();
+  for (;;) {
+    db.exec(`BEGIN IMMEDIATE;`);
+    try {
+      const { version } = db.prepare(`SELECT version FROM schema_version WHERE id = 1`).get();
+      if (version >= MIGRATIONS.length) {
+        db.exec(`COMMIT;`);
+        break;
+      }
+      MIGRATIONS[version](db);
+      // WHERE version = ? ensures the bump is monotonic: a concurrent opener
+      // that advanced the version first will cause this UPDATE to match 0 rows,
+      // which is safe — the migration is already applied.
+      db.prepare(`UPDATE schema_version SET version = ? WHERE id = 1 AND version = ?`).run(version + 1, version);
       db.exec(`COMMIT;`);
     } catch (err) {
       db.exec(`ROLLBACK;`);
       throw err;
     }
   }
+}
 
+export function openDb(dbPath) {
+  const db = new DatabaseSync(dbPath);
+  db.exec(SCHEMA);
+  applyMigrations(db);
   return db;
 }
+
+export function checkpointJobCreate(db, job) {
+  db.prepare(`
+    INSERT OR IGNORE INTO async_jobs (job_id, kind, status, created_at, started_at)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(job.id, job.kind, job.status, job.createdAt, job.startedAt ?? null);
+}
+
+export function checkpointJobFinish(db, job) {
+  // UPSERT so a terminal state is always recorded even if checkpointJobCreate
+  // was skipped due to a best-effort failure.
+  db.prepare(`
+    INSERT INTO async_jobs
+      (job_id, kind, status, created_at, started_at, finished_at, error, result_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(job_id) DO UPDATE SET
+      status      = excluded.status,
+      finished_at = excluded.finished_at,
+      error       = excluded.error,
+      result_json = excluded.result_json
+  `).run(
+    job.id,
+    job.kind,
+    job.status,
+    job.createdAt,
+    job.startedAt ?? null,
+    job.finishedAt ?? null,
+    job.error ?? null,
+    job.result != null ? JSON.stringify(job.result) : null
+  );
+}
+
+export function pruneJobCheckpoints(db, ttlMs) {
+  const cutoff = new Date(Date.now() - ttlMs).toISOString();
+  db.prepare(`
+    DELETE FROM async_jobs WHERE finished_at IS NOT NULL AND finished_at < ?
+  `).run(cutoff);
+}
+
+export function loadStalledJobs(db) {
+  // 'cancelling' included defensively; in practice only 'running' rows exist
+  // since we never write a 'cancelling' checkpoint between create and finish.
+  return db.prepare(`
+    SELECT job_id, kind, status, created_at, started_at
+    FROM async_jobs WHERE status IN ('running', 'cancelling')
+  `).all().map(row => ({
+    id: row.job_id,
+    kind: row.kind,
+    status: row.status,
+    createdAt: row.created_at,
+    startedAt: row.started_at ?? null,
+    finishedAt: null,
+    error: null,
+    result: null,
+    progress: null,
+    child: null,
+    onComplete: null,
+    tmpDir: null,
+    requestPath: null,
+    resultPath: null,
+  }));
+}

package/index.js

@@ -10,7 +10,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import matter from "gray-matter";
 import yaml from "js-yaml";
-import { openDb } from "./db.js";
+import { openDb, checkpointJobCreate, checkpointJobFinish, loadStalledJobs, pruneJobCheckpoints } from "./db.js";
 import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, sidecarPath, isStructuralProjectId } from "./sync.js";
 import { isGitAvailable, isGitRepository, initGitRepository, getSceneProseAtCommit } from "./git.js";
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
@@ -158,6 +158,7 @@ const asyncJobs = new Map();
 
 function pruneAsyncJobs() {
   const now = Date.now();
+  let anyPruned = false;
   for (const [id, job] of asyncJobs.entries()) {
     if (!job.finishedAt) continue;
     if (now - Date.parse(job.finishedAt) > ASYNC_JOB_TTL_MS) {
@@ -172,8 +173,12 @@ function pruneAsyncJobs() {
         // best effort cleanup
       }
       asyncJobs.delete(id);
+      anyPruned = true;
     }
   }
+  if (anyPruned) {
+    try { pruneJobCheckpoints(db, ASYNC_JOB_TTL_MS); } catch { /* best effort */ }
+  }
 }
 
 function readJsonIfExists(filePath) {
@@ -240,6 +245,11 @@ function startAsyncJob({ kind, requestPayload, onComplete }) {
     child,
   };
   asyncJobs.set(id, job);
+  try {
+    checkpointJobCreate(db, job);
+  } catch (err) {
+    process.stderr.write(`[mcp-writing] WARNING: failed to checkpoint job ${id}: ${err.message}\n`);
+  }
 
   let stdoutBuffer = "";
   child.stdout.on("data", (chunk) => {
@@ -276,12 +286,14 @@ function startAsyncJob({ kind, requestPayload, onComplete }) {
       job.status = "cancelled";
       job.error = error.message;
       job.finishedAt = new Date().toISOString();
+      try { checkpointJobFinish(db, job); } catch { /* best effort */ }
       pruneAsyncJobs();
       return;
     }
     job.status = "failed";
     job.error = error.message;
     job.finishedAt = new Date().toISOString();
+    try { checkpointJobFinish(db, job); } catch { /* best effort */ }
     pruneAsyncJobs();
   });
 
@@ -322,6 +334,7 @@ function startAsyncJob({ kind, requestPayload, onComplete }) {
         job.error = cancelledBySignal
           ? `Async job cancelled by signal ${signal}.`
           : payload?.error?.message ?? payload?.error ?? "Async job cancelled.";
+        try { checkpointJobFinish(db, job); } catch { /* best effort */ }
         pruneAsyncJobs();
         return;
       }
@@ -344,6 +357,7 @@ function startAsyncJob({ kind, requestPayload, onComplete }) {
         job.error = error instanceof Error ? error.message : String(error);
       }
     }
+    try { checkpointJobFinish(db, job); } catch { /* best effort */ }
     pruneAsyncJobs();
   });
 
@@ -646,6 +660,28 @@ function createCanonicalWorldEntity({ kind, name, notes, projectId, universeId,
 // ---------------------------------------------------------------------------
 const db = openDb(DB_PATH);
 
+// Recover jobs that were in-flight when the server last exited.
+const stalledJobs = loadStalledJobs(db);
+for (const job of stalledJobs) {
+  job.status = "failed";
+  job.error = "server restarted while job was running";
+  job.finishedAt = new Date().toISOString();
+  try {
+    checkpointJobFinish(db, job);
+  } catch (err) {
+    process.stderr.write(`[mcp-writing] WARNING: failed to checkpoint recovered stalled job ${job.id}: ${err.message}\n`);
+  }
+  asyncJobs.set(job.id, job);
+}
+// Prune expired rows from previous sessions unconditionally — completed/failed
+// jobs from prior runs are never loaded into asyncJobs, so anyPruned in
+// pruneAsyncJobs() would never be true for them.
+try { pruneJobCheckpoints(db, ASYNC_JOB_TTL_MS); } catch { /* best effort */ }
+
+if (stalledJobs.length > 0) {
+  process.stderr.write(`[mcp-writing] Marked ${stalledJobs.length} stalled job(s) as failed after restart.\n`);
+}
+
 process.stderr.write(`[mcp-writing] Sync dir: ${SYNC_DIR_ABS}\n`);
 process.stderr.write(`[mcp-writing] DB path: ${DB_PATH_DISPLAY}\n`);
 

package/package.json

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