@hanna84/mcp-writing 2.9.9 → 2.10.1

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.1](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.10.0...v2.10.1)
+
+- refactor(review-bundles): split 997-line module into planner/renderer/writer [`#105`](https://github.com/hannasdev/mcp-writing.git
+/pull/105)
+
+#### [v2.10.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.9.9...v2.10.0)
+
+> 26 April 2026
+
+- feat(db): persist async job state to SQLite for restart recovery [`#104`](https://github.com/hannasdev/mcp-writing.git
+/pull/104)
+- Release 2.10.0 [`0ec1fcb`](https://github.com/hannasdev/mcp-writing.git
+/commit/0ec1fcb77dc112270940b6f2ea56cd58f4da1c6a)
+
 #### [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)

package/db.js

@@ -124,6 +124,17 @@ export const SCHEMA = `
     id      INTEGER PRIMARY KEY CHECK (id = 1),
     version INTEGER NOT NULL
   );
+
+  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
+  );
 `;
 
 // Each function is applied exactly once, in order, when version < its index+1.
@@ -193,3 +204,65 @@ export function openDb(dbPath) {
   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.9",
+  "version": "2.10.1",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -17,6 +17,9 @@
     "metadata-lint.js",
     "scene-character-normalization.js",
     "review-bundles.js",
+    "review-bundles-planner.js",
+    "review-bundles-renderer.js",
+    "review-bundles-writer.js",
     "prose-styleguide.js",
     "prose-styleguide-drift.js",
     "prose-styleguide-skill.js",

package/review-bundles-planner.js

@@ -0,0 +1,325 @@
+const MAX_SORT_VALUE = Number.MAX_SAFE_INTEGER;
+
+export const REVIEW_BUNDLE_PROFILES = ["outline_discussion", "editor_detailed", "beta_reader_personalized"];
+export const REVIEW_BUNDLE_STRICTNESS = ["warn", "fail"];
+export const REVIEW_BUNDLE_FORMATS = ["pdf", "markdown", "both"];
+
+export class ReviewBundlePlanError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = "ReviewBundlePlanError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function normalizeRecipientDisplayName(recipientName) {
+  const normalized = String(recipientName ?? "")
+    .replace(/[\x00-\x1f\x7f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 100);
+
+  return normalized || "Beta Reader";
+}
+
+function normalizeSortNumber(value) {
+  return Number.isInteger(value) ? value : MAX_SORT_VALUE;
+}
+
+function sceneSort(a, b) {
+  const partDiff = normalizeSortNumber(a.part) - normalizeSortNumber(b.part);
+  if (partDiff !== 0) return partDiff;
+
+  const chapterDiff = normalizeSortNumber(a.chapter) - normalizeSortNumber(b.chapter);
+  if (chapterDiff !== 0) return chapterDiff;
+
+  const timelineDiff = normalizeSortNumber(a.timeline_position) - normalizeSortNumber(b.timeline_position);
+  if (timelineDiff !== 0) return timelineDiff;
+
+  return String(a.scene_id).localeCompare(String(b.scene_id));
+}
+
+function buildWarningSummary(warnings) {
+  const summary = {};
+  for (const warning of warnings) {
+    const type = warning.type ?? "unknown";
+    if (!summary[type]) {
+      summary[type] = { count: 0, examples: [] };
+    }
+    summary[type].count += 1;
+    if (summary[type].examples.length < 5) {
+      summary[type].examples.push(warning.message);
+    }
+  }
+  return summary;
+}
+
+function slugifyBundleName(value) {
+  const slug = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "review-bundle";
+}
+
+function assertProfile(profile) {
+  if (!REVIEW_BUNDLE_PROFILES.includes(profile)) {
+    throw new ReviewBundlePlanError(
+      "INVALID_PROFILE",
+      `Unsupported review bundle profile '${profile}'.`,
+      { supported_profiles: REVIEW_BUNDLE_PROFILES }
+    );
+  }
+}
+
+function assertStrictness(strictness) {
+  if (!REVIEW_BUNDLE_STRICTNESS.includes(strictness)) {
+    throw new ReviewBundlePlanError(
+      "INVALID_STRICTNESS",
+      `Unsupported strictness '${strictness}'.`,
+      { supported_strictness: REVIEW_BUNDLE_STRICTNESS }
+    );
+  }
+}
+
+function assertFormat(format) {
+  if (!REVIEW_BUNDLE_FORMATS.includes(format)) {
+    throw new ReviewBundlePlanError(
+      "INVALID_FORMAT",
+      `Unsupported format '${format}'.`,
+      { supported_formats: REVIEW_BUNDLE_FORMATS }
+    );
+  }
+}
+
+function resolveRequestedSceneIds(dbHandle, projectId, sceneIds) {
+  if (!Array.isArray(sceneIds) || sceneIds.length === 0) {
+    return { requested: [], existing: new Set() };
+  }
+
+  const placeholders = sceneIds.map(() => "?").join(",");
+  const rows = dbHandle.prepare(
+    `SELECT scene_id FROM scenes WHERE project_id = ? AND scene_id IN (${placeholders})`
+  ).all(projectId, ...sceneIds);
+
+  return {
+    requested: sceneIds,
+    existing: new Set(rows.map(row => row.scene_id)),
+  };
+}
+
+export function buildReviewBundlePlan(dbHandle, {
+  project_id,
+  profile,
+  part,
+  chapter,
+  tag,
+  scene_ids,
+  strictness = "warn",
+  include_scene_ids = true,
+  include_metadata_sidebar = false,
+  include_paragraph_anchors = false,
+  bundle_name,
+  recipient_name,
+  format = "pdf",
+} = {}) {
+  if (!project_id) {
+    throw new ReviewBundlePlanError("INVALID_PROJECT_ID", "project_id is required.");
+  }
+
+  assertProfile(profile);
+  assertStrictness(strictness);
+  assertFormat(format);
+
+  const projectRow = dbHandle.prepare(`SELECT project_id FROM projects WHERE project_id = ?`).get(project_id);
+  if (!projectRow) {
+    throw new ReviewBundlePlanError("NOT_FOUND", `Project '${project_id}' not found.`);
+  }
+
+  const requestedSceneIds = resolveRequestedSceneIds(dbHandle, project_id, scene_ids);
+  const conditions = ["s.project_id = ?"];
+  const params = [project_id];
+  const joins = [];
+
+  if (tag) {
+    joins.push("JOIN scene_tags st ON st.scene_id = s.scene_id AND st.tag = ?");
+    params.push(tag);
+  }
+  if (Array.isArray(scene_ids) && scene_ids.length > 0) {
+    const placeholders = scene_ids.map(() => "?").join(",");
+    conditions.push(`s.scene_id IN (${placeholders})`);
+    params.push(...scene_ids);
+  }
+  if (part !== undefined) {
+    conditions.push("s.part = ?");
+    params.push(part);
+  }
+  if (chapter !== undefined) {
+    conditions.push("s.chapter = ?");
+    params.push(chapter);
+  }
+
+  let query = `
+    SELECT DISTINCT
+      s.scene_id,
+      s.project_id,
+      s.title,
+      s.part,
+      s.chapter,
+      s.timeline_position,
+      s.word_count,
+      s.logline,
+      s.pov,
+      s.save_the_cat_beat,
+      s.metadata_stale
+    FROM scenes s
+  `;
+
+  if (joins.length > 0) {
+    query += ` ${joins.join(" ")}`;
+  }
+  query += ` WHERE ${conditions.join(" AND ")}`;
+
+  const rows = dbHandle.prepare(query).all(...params).sort(sceneSort);
+  if (rows.length === 0) {
+    throw new ReviewBundlePlanError(
+      "NO_RESULTS",
+      "No scenes matched the requested review bundle scope.",
+      {
+        project_id,
+        filters: {
+          ...(part !== undefined ? { part } : {}),
+          ...(chapter !== undefined ? { chapter } : {}),
+          ...(tag ? { tag } : {}),
+          ...(Array.isArray(scene_ids) ? { scene_ids } : {}),
+        },
+      }
+    );
+  }
+
+  const includedSceneIds = new Set(rows.map(row => row.scene_id));
+  const excludedSceneIds = requestedSceneIds.requested.filter(sceneId => !includedSceneIds.has(sceneId));
+  const notFoundSceneIds = requestedSceneIds.requested.filter(sceneId => !requestedSceneIds.existing.has(sceneId));
+  const filteredOutSceneIds = excludedSceneIds.filter(sceneId => requestedSceneIds.existing.has(sceneId));
+
+  const warnings = [];
+
+  if (notFoundSceneIds.length > 0) {
+    warnings.push({
+      type: "requested_scene_ids_not_found",
+      message: `${notFoundSceneIds.length} requested scene_id value(s) do not exist in project '${project_id}'.`,
+      scene_ids: notFoundSceneIds,
+    });
+  }
+
+  if (filteredOutSceneIds.length > 0) {
+    warnings.push({
+      type: "requested_scene_ids_filtered_out",
+      message: `${filteredOutSceneIds.length} requested scene_id value(s) were excluded by additional filters.`,
+      scene_ids: filteredOutSceneIds,
+    });
+  }
+
+  const staleRows = rows.filter(row => Number(row.metadata_stale) === 1);
+  if (staleRows.length > 0) {
+    warnings.push({
+      type: "metadata_stale",
+      message: `${staleRows.length} scene(s) have stale metadata and may need re-enrichment before editorial use.`,
+      count: staleRows.length,
+    });
+  }
+
+  const missingOrderingRows = rows.filter(
+    row => row.part == null || row.chapter == null || row.timeline_position == null
+  );
+  if (missingOrderingRows.length > 0) {
+    warnings.push({
+      type: "missing_ordering_fields",
+      message: `${missingOrderingRows.length} scene(s) are missing part/chapter/timeline_position metadata; fallback ordering was applied.`,
+      count: missingOrderingRows.length,
+    });
+  }
+
+  const missingWordCountRows = rows.filter(row => row.word_count == null);
+  if (missingWordCountRows.length > 0) {
+    warnings.push({
+      type: "missing_word_count",
+      message: `${missingWordCountRows.length} scene(s) are missing word_count; estimated_word_count may be low.`,
+      count: missingWordCountRows.length,
+    });
+  }
+
+  const blockers = [];
+  if (strictness === "fail" && staleRows.length > 0) {
+    blockers.push({
+      code: "STALE_METADATA",
+      message: `${staleRows.length} scene(s) are marked metadata_stale.`,
+      scene_ids: staleRows.map(row => row.scene_id),
+    });
+  }
+
+  const estimatedWordCount = rows.reduce((sum, row) => {
+    const count = Number(row.word_count);
+    return sum + (Number.isFinite(count) ? count : 0);
+  }, 0);
+  const resolvedRecipientName = profile === "beta_reader_personalized"
+    ? normalizeRecipientDisplayName(recipient_name)
+    : undefined;
+
+  const safeBundleName = slugifyBundleName(bundle_name || `${project_id}-${profile}`);
+  const appliedFilters = {
+    ...(part !== undefined ? { part } : {}),
+    ...(chapter !== undefined ? { chapter } : {}),
+    ...(tag ? { tag } : {}),
+    ...(Array.isArray(scene_ids) ? { scene_ids } : {}),
+  };
+
+  return {
+    ok: true,
+    profile,
+    resolved_scope: {
+      project_id,
+      filters: appliedFilters,
+      options: {
+        include_scene_ids: Boolean(include_scene_ids),
+        include_metadata_sidebar: Boolean(include_metadata_sidebar),
+        include_paragraph_anchors: Boolean(include_paragraph_anchors),
+        ...(resolvedRecipientName ? { recipient_name: resolvedRecipientName } : {}),
+      },
+    },
+    ordering: rows.map(row => ({
+      scene_id: row.scene_id,
+      project_id: row.project_id,
+      title: row.title,
+      part: row.part,
+      chapter: row.chapter,
+      timeline_position: row.timeline_position,
+      metadata_stale: Number(row.metadata_stale) === 1,
+    })),
+    summary: {
+      scene_count: rows.length,
+      estimated_word_count: estimatedWordCount,
+      excluded_scene_ids: excludedSceneIds,
+    },
+    warnings,
+    warning_summary: buildWarningSummary(warnings),
+    strictness_result: {
+      strictness,
+      can_proceed: blockers.length === 0,
+      blockers,
+    },
+    planned_outputs: [
+      ...(format === "markdown" || format === "both" ? [`${safeBundleName}.md`] : []),
+      ...(format === "pdf" || format === "both" ? [`${safeBundleName}.pdf`] : []),
+      ...(profile === "beta_reader_personalized"
+        ? [
+            `${safeBundleName}.notice.md`,
+            `${safeBundleName}.feedback-form.md`,
+          ]
+        : []),
+      `${safeBundleName}.manifest.json`,
+    ],
+  };
+}