@hanna84/mcp-writing 2.10.1 → 2.10.3

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.3](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.10.2...v2.10.3)
+
+- refactor(helpers): extract domain helpers and path safety utilities from index.js [`#107`](https://github.com/hannasdev/mcp-writing.git
+/pull/107)
+
+#### [v2.10.2](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.10.1...v2.10.2)
+
+> 26 April 2026
+
+- refactor(async-jobs): extract startAsyncJob/pruneAsyncJobs/toPublicJob into async-jobs.js [`#106`](https://github.com/hannasdev/mcp-writing.git
+/pull/106)
+- Release 2.10.2 [`7478041`](https://github.com/hannasdev/mcp-writing.git
+/commit/7478041fb85b7c7ccb35b9cd54e8a75171a8270c)
+
 #### [v2.10.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.10.0...v2.10.1)
 
+> 26 April 2026
+
 - refactor(review-bundles): split 997-line module into planner/renderer/writer [`#105`](https://github.com/hannasdev/mcp-writing.git
 /pull/105)
+- Release 2.10.1 [`6d5702b`](https://github.com/hannasdev/mcp-writing.git
+/commit/6d5702bb679dcacea9d6a4fe3b5305648e1c1100)
 
 #### [v2.10.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.9.9...v2.10.0)

package/async-jobs.js

@@ -0,0 +1,218 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { ASYNC_PROGRESS_PREFIX } from "./async-progress.js";
+import { checkpointJobCreate, checkpointJobFinish, pruneJobCheckpoints } from "./db.js";
+
+export function readJsonIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function createAsyncJobManager({ db, asyncJobs, ttlMs, runnerDir }) {
+  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) > ttlMs) {
+        try {
+          if (job.tmpDir && fs.existsSync(job.tmpDir)) {
+            fs.rmSync(job.tmpDir, { recursive: true, force: true });
+          } else {
+            if (job.requestPath && fs.existsSync(job.requestPath)) fs.unlinkSync(job.requestPath);
+            if (job.resultPath && fs.existsSync(job.resultPath)) fs.unlinkSync(job.resultPath);
+          }
+        } catch {
+          // best effort cleanup
+        }
+        asyncJobs.delete(id);
+        anyPruned = true;
+      }
+    }
+    if (anyPruned) {
+      try { pruneJobCheckpoints(db, ttlMs); } catch { /* best effort */ }
+    }
+  }
+
+  function toPublicJob(job, includeResult = true) {
+    return {
+      job_id: job.id,
+      kind: job.kind,
+      status: job.status,
+      created_at: job.createdAt,
+      started_at: job.startedAt,
+      finished_at: job.finishedAt,
+      pid: job.pid,
+      error: job.error,
+      ...(job.progress ? { progress: job.progress } : {}),
+      ...(includeResult ? { result: job.result } : {}),
+    };
+  }
+
+  function startAsyncJob({ kind, requestPayload, onComplete }) {
+    pruneAsyncJobs();
+
+    const id = randomUUID();
+    const tmpPrefix = path.join(os.tmpdir(), "mcp-writing-job-");
+    const tmpDir = fs.mkdtempSync(tmpPrefix);
+    const requestPath = path.join(tmpDir, `${id}.request.json`);
+    const resultPath = path.join(tmpDir, `${id}.result.json`);
+
+    fs.writeFileSync(requestPath, JSON.stringify(requestPayload, null, 2), "utf8");
+
+    const runnerPath = path.join(runnerDir, "scripts", "async-job-runner.mjs");
+    const child = spawn(
+      process.execPath,
+      ["--experimental-sqlite", runnerPath, requestPath, resultPath],
+      {
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+      }
+    );
+
+    const job = {
+      id,
+      kind,
+      status: "running",
+      createdAt: new Date().toISOString(),
+      startedAt: new Date().toISOString(),
+      finishedAt: null,
+      pid: child.pid,
+      tmpDir,
+      requestPath,
+      resultPath,
+      result: null,
+      progress: null,
+      error: null,
+      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) => {
+      stdoutBuffer += chunk.toString("utf8");
+      const lines = stdoutBuffer.split("\n");
+      stdoutBuffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith(ASYNC_PROGRESS_PREFIX)) continue;
+        const payload = trimmed.slice(ASYNC_PROGRESS_PREFIX.length);
+        try {
+          const progress = JSON.parse(payload);
+          if (progress && typeof progress === "object") {
+            const nextProgress = {
+              total_scenes: Number(progress.total_scenes ?? 0),
+              processed_scenes: Number(progress.processed_scenes ?? 0),
+              scenes_changed: Number(progress.scenes_changed ?? 0),
+              failed_scenes: Number(progress.failed_scenes ?? 0),
+            };
+            job.progress = nextProgress;
+          }
+        } catch {
+          // Ignore malformed progress lines; they are best-effort telemetry.
+        }
+      }
+    });
+    child.stderr.on("data", () => {
+      // avoid crashing on stderr backpressure for noisy runs
+    });
+
+    child.on("error", (error) => {
+      if (job.status === "cancelling") {
+        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();
+    });
+
+    child.on("exit", (code, signal) => {
+      const payload = readJsonIfExists(resultPath);
+      const successful = payload?.ok === true;
+      const cancelledBySignal = signal === "SIGTERM" || signal === "SIGKILL";
+      const cancelledByPayload = payload?.cancelled === true;
+
+      job.finishedAt = new Date().toISOString();
+      job.result = payload;
+
+      const hasProgressFields = payload && (
+        payload.total_scenes !== undefined
+        || payload.processed_scenes !== undefined
+        || payload.scenes_changed !== undefined
+        || payload.failed_scenes !== undefined
+      );
+
+      if (payload && payload.ok === true && hasProgressFields) {
+        job.progress = {
+          total_scenes: Number(payload.total_scenes ?? job.progress?.total_scenes ?? 0),
+          processed_scenes: Number(payload.processed_scenes ?? job.progress?.processed_scenes ?? 0),
+          scenes_changed: Number(payload.scenes_changed ?? job.progress?.scenes_changed ?? 0),
+          failed_scenes: Number(payload.failed_scenes ?? job.progress?.failed_scenes ?? 0),
+        };
+      }
+
+      if (job.status === "cancelling") {
+        if (cancelledByPayload) {
+          job.status = "cancelled";
+          job.error = "Async job cancelled after returning partial results.";
+        } else if (successful && !cancelledBySignal) {
+          // Race: cancellation was requested as work completed successfully.
+          job.status = "completed";
+        } else {
+          job.status = "cancelled";
+          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;
+        }
+      } else {
+        job.status = successful ? "completed" : "failed";
+        if (!successful) {
+          job.error = payload?.error?.message
+            ?? payload?.error
+            ?? (signal
+              ? `Async job exited due to signal ${signal}.`
+              : `Async job exited with code ${code}.`);
+        }
+      }
+
+      if (job.status === "completed" && typeof job.onComplete === "function") {
+        try {
+          job.onComplete(job);
+        } catch (error) {
+          job.status = "failed";
+          job.error = error instanceof Error ? error.message : String(error);
+        }
+      }
+      try { checkpointJobFinish(db, job); } catch { /* best effort */ }
+      pruneAsyncJobs();
+    });
+
+    return job;
+  }
+
+  return { pruneAsyncJobs, toPublicJob, startAsyncJob };
+}

package/helpers.js

@@ -0,0 +1,345 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import yaml from "js-yaml";
+import { sidecarPath, syncAll } from "./sync.js";
+import {
+  slugifyEntityName,
+  renderCharacterSheetTemplate,
+  renderPlaceSheetTemplate,
+  renderCharacterArcTemplate,
+} from "./world-entity-templates.js";
+import { ReviewBundlePlanError } from "./review-bundles.js";
+
+export function deriveLoglineFromProse(prose) {
+  const compact = prose.replace(/\s+/g, " ").trim();
+  if (!compact) return null;
+  const sentence = compact.match(/^(.+?[.!?])(?:\s|$)/);
+  const candidate = (sentence?.[1] ?? compact).trim();
+  if (candidate.length <= 220) return candidate;
+  return `${candidate.slice(0, 217).trimEnd()}...`;
+}
+
+export function inferCharacterIdsFromProse(dbHandle, prose, projectId) {
+  const lower = prose.toLowerCase();
+  const rows = dbHandle.prepare(`
+    SELECT character_id, name
+    FROM characters
+    WHERE project_id = ? OR universe_id = (SELECT universe_id FROM projects WHERE project_id = ?)
+    ORDER BY length(name) DESC
+  `).all(projectId, projectId);
+
+  const found = [];
+  for (const row of rows) {
+    if (!row.name) continue;
+    const words = row.name.toLowerCase().split(/\s+/).filter(Boolean);
+    if (words.length && words.every(w => lower.includes(w))) {
+      found.push(row.character_id);
+    }
+  }
+  return [...new Set(found)].slice(0, 12);
+}
+
+export function readSupportingNotesForEntity(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const base = path.basename(filePath, ext).toLowerCase();
+  if (base !== "sheet") return [];
+
+  const dir = path.dirname(filePath);
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter(entry => entry.isFile())
+    .map(entry => entry.name)
+    .filter(name => /\.(md|txt)$/i.test(name))
+    .filter(name => !/^sheet\.(md|txt)$/i.test(name))
+    .sort((a, b) => a.localeCompare(b))
+    .map(name => {
+      const notePath = path.join(dir, name);
+      try {
+        const raw = fs.readFileSync(notePath, "utf8");
+        const { content } = matter(raw);
+        return {
+          file_name: name,
+          content: content.trim(),
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .filter(note => note.content);
+}
+
+export function readEntityMetadata(filePath) {
+  const metaPath = sidecarPath(filePath);
+  if (fs.existsSync(metaPath)) {
+    try {
+      return yaml.load(fs.readFileSync(metaPath, "utf8")) ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  try {
+    return matter(fs.readFileSync(filePath, "utf8")).data ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export function resolveBatchTargetScenes(dbHandle, {
+  projectId,
+  sceneIds,
+  part,
+  chapter,
+  onlyStale,
+}) {
+  const projectExists = Boolean(
+    dbHandle.prepare(`SELECT 1 FROM projects WHERE project_id = ? LIMIT 1`).get(projectId)
+  );
+
+  if (sceneIds?.length) {
+    const placeholders = sceneIds.map(() => "?").join(",");
+    const existingRows = dbHandle.prepare(
+      `SELECT scene_id FROM scenes WHERE project_id = ? AND scene_id IN (${placeholders})`
+    ).all(projectId, ...sceneIds);
+    const existing = new Set(existingRows.map(row => row.scene_id));
+    const missing = sceneIds.filter(sceneId => !existing.has(sceneId));
+    if (missing.length > 0) {
+      return { ok: false, code: "NOT_FOUND", message: `Requested scene IDs were not found in project '${projectId}'.`, details: { missing_scene_ids: missing, project_id: projectId } };
+    }
+  }
+
+  const conditions = ["project_id = ?"];
+  const params = [projectId];
+
+  if (sceneIds?.length) {
+    const placeholders = sceneIds.map(() => "?").join(",");
+    conditions.push(`scene_id IN (${placeholders})`);
+    params.push(...sceneIds);
+  }
+  if (part !== undefined) {
+    conditions.push("part = ?");
+    params.push(part);
+  }
+  if (chapter !== undefined) {
+    conditions.push("chapter = ?");
+    params.push(chapter);
+  }
+  if (onlyStale) {
+    conditions.push("metadata_stale = 1");
+  }
+
+  const query = `
+    SELECT scene_id, project_id, file_path
+    FROM scenes
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY part, chapter, timeline_position
+  `;
+
+  return {
+    ok: true,
+    rows: dbHandle.prepare(query).all(...params),
+    project_exists: projectExists,
+  };
+}
+
+export function createHelpers({ syncDir, syncDirReal, syncDirAbs, db, syncDirWritable }) {
+  function isPathInsideSyncDir(candidatePath) {
+    const resolvedCandidate = path.resolve(candidatePath);
+    const canonicalCandidate = (() => {
+      try {
+        return fs.realpathSync(resolvedCandidate);
+      } catch {
+        return resolvedCandidate;
+      }
+    })();
+
+    const rel = path.relative(syncDirReal, canonicalCandidate);
+    return !(rel.startsWith("..") || path.isAbsolute(rel));
+  }
+
+  // Like isPathInsideSyncDir, but works for paths that do not yet exist by
+  // walking up to the nearest existing ancestor before canonicalising.
+  function isPathCandidateInsideSyncDir(candidatePath) {
+    const resolvedCandidate = path.resolve(candidatePath);
+
+    let existingAncestor = resolvedCandidate;
+    while (!fs.existsSync(existingAncestor)) {
+      const parent = path.dirname(existingAncestor);
+      if (parent === existingAncestor) break;
+      existingAncestor = parent;
+    }
+
+    const canonicalBase = (() => {
+      try {
+        return fs.realpathSync(existingAncestor);
+      } catch {
+        return existingAncestor;
+      }
+    })();
+
+    const canonical = path.resolve(canonicalBase, path.relative(existingAncestor, resolvedCandidate));
+    const rel = path.relative(syncDirReal, canonical);
+    return !(rel.startsWith("..") || path.isAbsolute(rel));
+  }
+
+  function resolveOutputDirWithinSync(outputDir) {
+    let resolvedOutputDir = path.resolve(outputDir);
+    let existingAncestor = resolvedOutputDir;
+
+    while (!fs.existsSync(existingAncestor)) {
+      const parentDir = path.dirname(existingAncestor);
+      if (parentDir === existingAncestor) {
+        throw new ReviewBundlePlanError(
+          "INVALID_OUTPUT_DIR",
+          "output_dir must be inside WRITING_SYNC_DIR.",
+          { output_dir: resolvedOutputDir, sync_dir: syncDirAbs }
+        );
+      }
+      existingAncestor = parentDir;
+    }
+
+    let realExistingAncestor;
+    try {
+      realExistingAncestor = fs.realpathSync.native(existingAncestor);
+    } catch (err) {
+      throw new ReviewBundlePlanError(
+        "INVALID_OUTPUT_DIR",
+        "output_dir ancestor could not be resolved: path may be inaccessible.",
+        { output_dir: outputDir, existing_ancestor: existingAncestor, cause: err.message }
+      );
+    }
+    const relativeFromAncestor = path.relative(existingAncestor, resolvedOutputDir);
+    resolvedOutputDir = path.resolve(realExistingAncestor, relativeFromAncestor);
+
+    const relativeToSyncDir = path.relative(syncDirReal, resolvedOutputDir);
+    if (relativeToSyncDir.startsWith("..") || path.isAbsolute(relativeToSyncDir)) {
+      throw new ReviewBundlePlanError(
+        "INVALID_OUTPUT_DIR",
+        "output_dir must be inside WRITING_SYNC_DIR.",
+        { output_dir: resolvedOutputDir, sync_dir: syncDirAbs }
+      );
+    }
+
+    return { resolvedOutputDir, relativeToSyncDir };
+  }
+
+  function resolveProjectRoot(projectId) {
+    if (projectId.includes("/")) {
+      const [universeId, projectSlug] = projectId.split("/");
+      return path.join(syncDir, "universes", universeId, projectSlug);
+    }
+    return path.join(syncDir, "projects", projectId);
+  }
+
+  function resolveWorldEntityDir({ kind, projectId, universeId, name }) {
+    const slug = slugifyEntityName(name);
+    const baseDir = projectId
+      ? path.join(resolveProjectRoot(projectId), "world")
+      : path.join(syncDir, "universes", universeId, "world");
+    const bucket = kind === "character" ? "characters" : "places";
+    return {
+      slug,
+      dir: path.join(baseDir, bucket, slug),
+    };
+  }
+
+  function createCanonicalWorldEntity({ kind, name, notes, projectId, universeId, meta }) {
+    const prefix = kind === "character" ? "char" : "place";
+    const idKey = kind === "character" ? "character_id" : "place_id";
+    const slug = slugifyEntityName(name);
+    if (!slug) throw new Error("Name must contain at least one alphanumeric character.");
+
+    const { dir } = resolveWorldEntityDir({ kind, projectId, universeId, name });
+    const prosePath = path.join(dir, "sheet.md");
+    const metaPath = sidecarPath(prosePath);
+    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 });
+
+    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") {
+      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");
+    }
+
+    syncAll(db, syncDir, { writable: syncDirWritable });
+
+    return {
+      created: !hadProse && !hadMeta,
+      id: payload[idKey],
+      prose_path: prosePath,
+      meta_path: metaPath,
+      project_id: projectId ?? null,
+      universe_id: universeId ?? null,
+    };
+  }
+
+  return {
+    isPathInsideSyncDir,
+    isPathCandidateInsideSyncDir,
+    resolveOutputDirWithinSync,
+    resolveProjectRoot,
+    resolveWorldEntityDir,
+    createCanonicalWorldEntity,
+  };
+}

package/index.js

@@ -4,19 +4,21 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 import { randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import matter from "gray-matter";
-import yaml from "js-yaml";
-import { openDb, checkpointJobCreate, checkpointJobFinish, loadStalledJobs, pruneJobCheckpoints } from "./db.js";
-import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, sidecarPath, isStructuralProjectId } from "./sync.js";
+import { openDb, checkpointJobFinish, loadStalledJobs, pruneJobCheckpoints } from "./db.js";
+import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, isStructuralProjectId } from "./sync.js";
 import { isGitAvailable, isGitRepository, initGitRepository, getSceneProseAtCommit } from "./git.js";
-import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
-import { ASYNC_PROGRESS_PREFIX } from "./async-progress.js";
+import { createAsyncJobManager, readJsonIfExists } from "./async-jobs.js";
+import {
+  createHelpers,
+  deriveLoglineFromProse,
+  inferCharacterIdsFromProse,
+  readSupportingNotesForEntity,
+  readEntityMetadata,
+  resolveBatchTargetScenes,
+} from "./helpers.js";
 import { STYLEGUIDE_CONFIG_BASENAME } from "./prose-styleguide.js";
-import { ReviewBundlePlanError } from "./review-bundles.js";
 import { registerSyncTools } from "./tools/sync.js";
 import { registerSearchTools } from "./tools/search.js";
 import { registerMetadataTools } from "./tools/metadata.js";
@@ -36,86 +38,6 @@ const SYNC_DIR_REAL = (() => {
 })();
 const DB_PATH_DISPLAY = DB_PATH === ":memory:" ? DB_PATH : path.resolve(DB_PATH);
 
-function isPathInsideSyncDir(candidatePath) {
-  const resolvedCandidate = path.resolve(candidatePath);
-  const canonicalCandidate = (() => {
-    try {
-      return fs.realpathSync(resolvedCandidate);
-    } catch {
-      return resolvedCandidate;
-    }
-  })();
-
-  const rel = path.relative(SYNC_DIR_REAL, canonicalCandidate);
-  return !(rel.startsWith("..") || path.isAbsolute(rel));
-}
-
-// Like isPathInsideSyncDir, but works for paths that do not yet exist by
-// walking up to the nearest existing ancestor before canonicalising.
-function isPathCandidateInsideSyncDir(candidatePath) {
-  const resolvedCandidate = path.resolve(candidatePath);
-
-  let existingAncestor = resolvedCandidate;
-  while (!fs.existsSync(existingAncestor)) {
-    const parent = path.dirname(existingAncestor);
-    if (parent === existingAncestor) break;
-    existingAncestor = parent;
-  }
-
-  const canonicalBase = (() => {
-    try {
-      return fs.realpathSync(existingAncestor);
-    } catch {
-      return existingAncestor;
-    }
-  })();
-
-  const canonical = path.resolve(canonicalBase, path.relative(existingAncestor, resolvedCandidate));
-  const rel = path.relative(SYNC_DIR_REAL, canonical);
-  return !(rel.startsWith("..") || path.isAbsolute(rel));
-}
-
-function resolveOutputDirWithinSync(outputDir) {
-  let resolvedOutputDir = path.resolve(outputDir);
-  let existingAncestor = resolvedOutputDir;
-
-  while (!fs.existsSync(existingAncestor)) {
-    const parentDir = path.dirname(existingAncestor);
-    if (parentDir === existingAncestor) {
-      throw new ReviewBundlePlanError(
-        "INVALID_OUTPUT_DIR",
-        "output_dir must be inside WRITING_SYNC_DIR.",
-        { output_dir: resolvedOutputDir, sync_dir: SYNC_DIR_ABS }
-      );
-    }
-    existingAncestor = parentDir;
-  }
-
-  let realExistingAncestor;
-  try {
-    realExistingAncestor = fs.realpathSync.native(existingAncestor);
-  } catch (err) {
-    throw new ReviewBundlePlanError(
-      "INVALID_OUTPUT_DIR",
-      "output_dir ancestor could not be resolved: path may be inaccessible.",
-      { output_dir: outputDir, existing_ancestor: existingAncestor, cause: err.message }
-    );
-  }
-  const relativeFromAncestor = path.relative(existingAncestor, resolvedOutputDir);
-  resolvedOutputDir = path.resolve(realExistingAncestor, relativeFromAncestor);
-
-  const relativeToSyncDir = path.relative(SYNC_DIR_REAL, resolvedOutputDir);
-  if (relativeToSyncDir.startsWith("..") || path.isAbsolute(relativeToSyncDir)) {
-    throw new ReviewBundlePlanError(
-      "INVALID_OUTPUT_DIR",
-      "output_dir must be inside WRITING_SYNC_DIR.",
-      { output_dir: resolvedOutputDir, sync_dir: SYNC_DIR_ABS }
-    );
-  }
-
-  return { resolvedOutputDir, relativeToSyncDir };
-}
-
 function parsePositiveIntEnv(rawValue, defaultValue) {
   const parsed = parseInt(rawValue ?? String(defaultValue), 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
@@ -156,214 +78,6 @@ const MCP_SERVER_VERSION = typeof pkg.version === "string" && pkg.version.trim()
   : "0.0.0";
 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) {
-      try {
-        if (job.tmpDir && fs.existsSync(job.tmpDir)) {
-          fs.rmSync(job.tmpDir, { recursive: true, force: true });
-        } else {
-          if (job.requestPath && fs.existsSync(job.requestPath)) fs.unlinkSync(job.requestPath);
-          if (job.resultPath && fs.existsSync(job.resultPath)) fs.unlinkSync(job.resultPath);
-        }
-      } catch {
-        // best effort cleanup
-      }
-      asyncJobs.delete(id);
-      anyPruned = true;
-    }
-  }
-  if (anyPruned) {
-    try { pruneJobCheckpoints(db, ASYNC_JOB_TTL_MS); } catch { /* best effort */ }
-  }
-}
-
-function readJsonIfExists(filePath) {
-  if (!filePath || !fs.existsSync(filePath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function toPublicJob(job, includeResult = true) {
-  return {
-    job_id: job.id,
-    kind: job.kind,
-    status: job.status,
-    created_at: job.createdAt,
-    started_at: job.startedAt,
-    finished_at: job.finishedAt,
-    pid: job.pid,
-    error: job.error,
-    ...(job.progress ? { progress: job.progress } : {}),
-    ...(includeResult ? { result: job.result } : {}),
-  };
-}
-
-function startAsyncJob({ kind, requestPayload, onComplete }) {
-  pruneAsyncJobs();
-  const progressPrefix = ASYNC_PROGRESS_PREFIX;
-
-  const id = randomUUID();
-  const tmpPrefix = path.join(os.tmpdir(), "mcp-writing-job-");
-  const tmpDir = fs.mkdtempSync(tmpPrefix);
-  const requestPath = path.join(tmpDir, `${id}.request.json`);
-  const resultPath = path.join(tmpDir, `${id}.result.json`);
-
-  fs.writeFileSync(requestPath, JSON.stringify(requestPayload, null, 2), "utf8");
-
-  const runnerPath = path.join(__dirname, "scripts", "async-job-runner.mjs");
-  const child = spawn(
-    process.execPath,
-    ["--experimental-sqlite", runnerPath, requestPath, resultPath],
-    {
-      env: process.env,
-      stdio: ["ignore", "pipe", "pipe"],
-    }
-  );
-
-  const job = {
-    id,
-    kind,
-    status: "running",
-    createdAt: new Date().toISOString(),
-    startedAt: new Date().toISOString(),
-    finishedAt: null,
-    pid: child.pid,
-    tmpDir,
-    requestPath,
-    resultPath,
-    result: null,
-    progress: null,
-    error: null,
-    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) => {
-    stdoutBuffer += chunk.toString("utf8");
-    const lines = stdoutBuffer.split("\n");
-    stdoutBuffer = lines.pop() ?? "";
-
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed.startsWith(progressPrefix)) continue;
-      const payload = trimmed.slice(progressPrefix.length);
-      try {
-        const progress = JSON.parse(payload);
-        if (progress && typeof progress === "object") {
-          const nextProgress = {
-            total_scenes: Number(progress.total_scenes ?? 0),
-            processed_scenes: Number(progress.processed_scenes ?? 0),
-            scenes_changed: Number(progress.scenes_changed ?? 0),
-            failed_scenes: Number(progress.failed_scenes ?? 0),
-          };
-          job.progress = nextProgress;
-        }
-      } catch {
-        // Ignore malformed progress lines; they are best-effort telemetry.
-      }
-    }
-  });
-  child.stderr.on("data", () => {
-    // avoid crashing on stderr backpressure for noisy runs
-  });
-
-  child.on("error", (error) => {
-    if (job.status === "cancelling") {
-      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();
-  });
-
-  child.on("exit", (code, signal) => {
-    const payload = readJsonIfExists(resultPath);
-    const successful = payload?.ok === true;
-    const cancelledBySignal = signal === "SIGTERM" || signal === "SIGKILL";
-    const cancelledByPayload = payload?.cancelled === true;
-
-    job.finishedAt = new Date().toISOString();
-    job.result = payload;
-
-    const hasProgressFields = payload && (
-      payload.total_scenes !== undefined
-      || payload.processed_scenes !== undefined
-      || payload.scenes_changed !== undefined
-      || payload.failed_scenes !== undefined
-    );
-
-    if (payload && payload.ok === true && hasProgressFields) {
-      job.progress = {
-        total_scenes: Number(payload.total_scenes ?? job.progress?.total_scenes ?? 0),
-        processed_scenes: Number(payload.processed_scenes ?? job.progress?.processed_scenes ?? 0),
-        scenes_changed: Number(payload.scenes_changed ?? job.progress?.scenes_changed ?? 0),
-        failed_scenes: Number(payload.failed_scenes ?? job.progress?.failed_scenes ?? 0),
-      };
-    }
-
-    if (job.status === "cancelling") {
-      if (cancelledByPayload) {
-        job.status = "cancelled";
-        job.error = "Async job cancelled after returning partial results.";
-      } else if (successful && !cancelledBySignal) {
-        // Race: cancellation was requested as work completed successfully.
-        job.status = "completed";
-      } else {
-        job.status = "cancelled";
-        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;
-      }
-    } else {
-      job.status = successful ? "completed" : "failed";
-      if (!successful) {
-        job.error = payload?.error?.message
-          ?? payload?.error
-          ?? (signal
-            ? `Async job exited due to signal ${signal}.`
-            : `Async job exited with code ${code}.`);
-      }
-    }
-
-    if (job.status === "completed" && typeof job.onComplete === "function") {
-      try {
-        job.onComplete(job);
-      } catch (error) {
-        job.status = "failed";
-        job.error = error instanceof Error ? error.message : String(error);
-      }
-    }
-    try { checkpointJobFinish(db, job); } catch { /* best effort */ }
-    pruneAsyncJobs();
-  });
-
-  return job;
-}
-
 function paginateRows(rows, { page, pageSize, forcePagination = false }) {
   const totalCount = rows.length;
   const shouldPaginate = forcePagination || page !== undefined || pageSize !== undefined;
@@ -413,248 +127,6 @@ function errorResponse(code, message, details) {
   return jsonResponse(payload);
 }
 
-function deriveLoglineFromProse(prose) {
-  const compact = prose.replace(/\s+/g, " ").trim();
-  if (!compact) return null;
-  const sentence = compact.match(/^(.+?[.!?])(?:\s|$)/);
-  const candidate = (sentence?.[1] ?? compact).trim();
-  if (candidate.length <= 220) return candidate;
-  return `${candidate.slice(0, 217).trimEnd()}...`;
-}
-
-function inferCharacterIdsFromProse(dbHandle, prose, projectId) {
-  const lower = prose.toLowerCase();
-  const rows = dbHandle.prepare(`
-    SELECT character_id, name
-    FROM characters
-    WHERE project_id = ? OR universe_id = (SELECT universe_id FROM projects WHERE project_id = ?)
-    ORDER BY length(name) DESC
-  `).all(projectId, projectId);
-
-  const found = [];
-  for (const row of rows) {
-    if (!row.name) continue;
-    const words = row.name.toLowerCase().split(/\s+/).filter(Boolean);
-    if (words.length && words.every(w => lower.includes(w))) {
-      found.push(row.character_id);
-    }
-  }
-  return [...new Set(found)].slice(0, 12);
-}
-
-function readSupportingNotesForEntity(filePath) {
-  const ext = path.extname(filePath).toLowerCase();
-  const base = path.basename(filePath, ext).toLowerCase();
-  if (base !== "sheet") return [];
-
-  const dir = path.dirname(filePath);
-  let entries;
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-
-  return entries
-    .filter(entry => entry.isFile())
-    .map(entry => entry.name)
-    .filter(name => /\.(md|txt)$/i.test(name))
-    .filter(name => !/^sheet\.(md|txt)$/i.test(name))
-    .sort((a, b) => a.localeCompare(b))
-    .map(name => {
-      const notePath = path.join(dir, name);
-      try {
-        const raw = fs.readFileSync(notePath, "utf8");
-        const { content } = matter(raw);
-        return {
-          file_name: name,
-          content: content.trim(),
-        };
-      } catch {
-        return null;
-      }
-    })
-    .filter(Boolean)
-    .filter(note => note.content);
-}
-
-function readEntityMetadata(filePath) {
-  const metaPath = sidecarPath(filePath);
-  if (fs.existsSync(metaPath)) {
-    try {
-      return yaml.load(fs.readFileSync(metaPath, "utf8")) ?? {};
-    } catch {
-      return {};
-    }
-  }
-
-  try {
-    return matter(fs.readFileSync(filePath, "utf8")).data ?? {};
-  } catch {
-    return {};
-  }
-}
-
-function resolveProjectRoot(projectId) {
-  if (projectId.includes("/")) {
-    const [universeId, projectSlug] = projectId.split("/");
-    return path.join(SYNC_DIR, "universes", universeId, projectSlug);
-  }
-  return path.join(SYNC_DIR, "projects", projectId);
-}
-
-function resolveWorldEntityDir({ kind, projectId, universeId, name }) {
-  const slug = slugifyEntityName(name);
-  const baseDir = projectId
-    ? path.join(resolveProjectRoot(projectId), "world")
-    : path.join(SYNC_DIR, "universes", universeId, "world");
-  const bucket = kind === "character" ? "characters" : "places";
-  return {
-    slug,
-    dir: path.join(baseDir, bucket, slug),
-  };
-}
-
-function resolveBatchTargetScenes(dbHandle, {
-  projectId,
-  sceneIds,
-  part,
-  chapter,
-  onlyStale,
-}) {
-  const projectExists = Boolean(
-    dbHandle.prepare(`SELECT 1 FROM projects WHERE project_id = ? LIMIT 1`).get(projectId)
-  );
-
-  if (sceneIds?.length) {
-    const placeholders = sceneIds.map(() => "?").join(",");
-    const existingRows = dbHandle.prepare(
-      `SELECT scene_id FROM scenes WHERE project_id = ? AND scene_id IN (${placeholders})`
-    ).all(projectId, ...sceneIds);
-    const existing = new Set(existingRows.map(row => row.scene_id));
-    const missing = sceneIds.filter(sceneId => !existing.has(sceneId));
-    if (missing.length > 0) {
-      return { ok: false, code: "NOT_FOUND", message: `Requested scene IDs were not found in project '${projectId}'.`, details: { missing_scene_ids: missing, project_id: projectId } };
-    }
-  }
-
-  const conditions = ["project_id = ?"];
-  const params = [projectId];
-
-  if (sceneIds?.length) {
-    const placeholders = sceneIds.map(() => "?").join(",");
-    conditions.push(`scene_id IN (${placeholders})`);
-    params.push(...sceneIds);
-  }
-  if (part !== undefined) {
-    conditions.push("part = ?");
-    params.push(part);
-  }
-  if (chapter !== undefined) {
-    conditions.push("chapter = ?");
-    params.push(chapter);
-  }
-  if (onlyStale) {
-    conditions.push("metadata_stale = 1");
-  }
-
-  const query = `
-    SELECT scene_id, project_id, file_path
-    FROM scenes
-    WHERE ${conditions.join(" AND ")}
-    ORDER BY part, chapter, timeline_position
-  `;
-
-  return {
-    ok: true,
-    rows: dbHandle.prepare(query).all(...params),
-    project_exists: projectExists,
-  };
-}
-
-function createCanonicalWorldEntity({ kind, name, notes, projectId, universeId, meta }) {
-  const prefix = kind === "character" ? "char" : "place";
-  const idKey = kind === "character" ? "character_id" : "place_id";
-  const slug = slugifyEntityName(name);
-  if (!slug) throw new Error("Name must contain at least one alphanumeric character.");
-
-  const { dir } = resolveWorldEntityDir({ kind, projectId, universeId, name });
-  const prosePath = path.join(dir, "sheet.md");
-  const metaPath = sidecarPath(prosePath);
-  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 });
-
-  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") {
-    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");
-  }
-
-  syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
-
-  return {
-    created: !hadProse && !hadMeta,
-    id: payload[idKey],
-    prose_path: prosePath,
-    meta_path: metaPath,
-    project_id: projectId ?? null,
-    universe_id: universeId ?? null,
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Database setup
 // ---------------------------------------------------------------------------
@@ -682,6 +154,13 @@ if (stalledJobs.length > 0) {
   process.stderr.write(`[mcp-writing] Marked ${stalledJobs.length} stalled job(s) as failed after restart.\n`);
 }
 
+const { pruneAsyncJobs, startAsyncJob, toPublicJob } = createAsyncJobManager({
+  db,
+  asyncJobs,
+  ttlMs: ASYNC_JOB_TTL_MS,
+  runnerDir: __dirname,
+});
+
 process.stderr.write(`[mcp-writing] Sync dir: ${SYNC_DIR_ABS}\n`);
 process.stderr.write(`[mcp-writing] DB path: ${DB_PATH_DISPLAY}\n`);
 
@@ -813,6 +292,20 @@ if (SHOULD_ENFORCE_OWNERSHIP_FAIL_GUARD && SYNC_OWNERSHIP_DIAGNOSTICS.non_runtim
   process.exit(1);
 }
 
+const {
+  isPathInsideSyncDir,
+  isPathCandidateInsideSyncDir,
+  resolveOutputDirWithinSync,
+  resolveProjectRoot,
+  createCanonicalWorldEntity,
+} = createHelpers({
+  syncDir: SYNC_DIR,
+  syncDirReal: SYNC_DIR_REAL,
+  syncDirAbs: SYNC_DIR_ABS,
+  db,
+  syncDirWritable: SYNC_DIR_WRITABLE,
+});
+
 // Run sync on startup
 syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
 

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.10.1",
+  "version": "2.10.3",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
   "files": [
     "index.js",
+    "async-jobs.js",
     "async-progress.js",
+    "helpers.js",
     "scene-character-batch.js",
     "scrivener-direct.js",
     "importer.js",