@hanna84/mcp-writing 1.10.0 → 1.11.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).
 
+#### [v1.11.1](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.11.0...v1.11.1)
+
+- Implement graceful batch cancellation and complete Phase D coverage [`#59`](https://github.com/hannasdev/mcp-writing.git
+/pull/59)
+
+#### [v1.11.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.10.0...v1.11.0)
+
+> 21 April 2026
+
+- feat: add reusable manual real-data Scrivener test runner [`#58`](https://github.com/hannasdev/mcp-writing.git
+/pull/58)
+- Release 1.11.0 [`5938d51`](https://github.com/hannasdev/mcp-writing.git
+/commit/5938d51b277dcce2f5fcfe728ff2112d3af644e5)
+
 #### [v1.10.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.9.4...v1.10.0)
 
+> 21 April 2026
+
 - feat: Scrivener direct extraction beta (M1, M2, M2.5) [`#57`](https://github.com/hannasdev/mcp-writing.git
 /pull/57)
+- Release 1.10.0 [`504bd7f`](https://github.com/hannasdev/mcp-writing.git
+/commit/504bd7facfaf11052e98127e2ae0a104259d8a57)
 
 #### [v1.9.4](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.9.3...v1.9.4)

package/README.md

@@ -76,5 +76,17 @@ Goal: let AI propose prose edits without losing control of your draft.
 
 Outcome: you get AI speed with explicit approval and recoverable history for every applied change.
 
+### 5) Refreshing scene-character links after imports or major rewrites
+
+Goal: rebuild scene-to-character links in a controlled way after imported prose changes or metadata drift.
+
+1. Start with `enrich_scene_characters_batch` using the default `dry_run=true` to preview inferred links for a project, chapter, or explicit scene list.
+2. Poll `get_async_job_status` until the batch job completes, then review `job.result.results` for changed scenes, ambiguous matches, and partial failures.
+3. Spot-check a few affected scenes with `get_scene_prose` if the changes touch important continuity or cast-heavy chapters.
+4. Re-run `enrich_scene_characters_batch` with `dry_run=false` once the preview looks correct.
+5. If you want a destructive overwrite instead of additive merge behavior, use `replace_mode=replace` with `confirm_replace=true` deliberately.
+
+Outcome: character-link maintenance becomes a preview-first batch operation instead of a one-off regex script or manual sidecar cleanup.
+
 ## License
 AGPL-3.0-only

package/index.js

@@ -17,6 +17,7 @@ import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, lis
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
 import { importScrivenerSync, validateProjectId } from "./importer.js";
 import { mergeScrivenerProjectMetadata } from "./scrivener-direct.js";
+import { ASYNC_PROGRESS_PREFIX } from "./async-progress.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
@@ -119,12 +120,14 @@ function toPublicJob(job, includeResult = true) {
     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-");
@@ -156,14 +159,38 @@ function startAsyncJob({ kind, requestPayload, onComplete }) {
     requestPath,
     resultPath,
     result: null,
+    progress: null,
     error: null,
     onComplete,
     child,
   };
   asyncJobs.set(id, job);
 
-  child.stdout.on("data", () => {
-    // worker writes structured output to resultPath; stdout is ignored here
+  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
@@ -187,12 +214,32 @@ function startAsyncJob({ kind, requestPayload, onComplete }) {
     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 (successful && !cancelledBySignal) {
+      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 {
@@ -379,6 +426,63 @@ function resolveWorldEntityDir({ kind, projectId, universeId, name }) {
   };
 }
 
+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";
@@ -1062,9 +1166,129 @@ function createMcpServer() {
     }
   );
 
+  s.tool(
+    "enrich_scene_characters_batch",
+    "Start an asynchronous batch job that infers scene character mentions and updates scene metadata links. Version 1 uses canonical character names only (no aliases). Defaults to dry_run=true.",
+    {
+      project_id: z.string().describe("Project ID (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb')."),
+      scene_ids: z.array(z.string()).optional().describe("Optional allowlist of scene IDs to process before other filters are applied."),
+      part: z.number().int().optional().describe("Optional part number filter."),
+      chapter: z.number().int().optional().describe("Optional chapter number filter."),
+      only_stale: z.boolean().optional().describe("If true, only process scenes currently marked metadata_stale."),
+      dry_run: z.boolean().optional().describe("If true (default), returns preview results without writing sidecars."),
+      replace_mode: z.enum(["merge", "replace"]).optional().describe("merge (default): add inferred IDs; replace: overwrite characters with inferred IDs."),
+      max_scenes: z.number().int().positive().optional().describe("Hard guardrail for resolved scene count (default: 200)."),
+      include_match_details: z.boolean().optional().describe("If true, include extra match diagnostics per scene."),
+      confirm_replace: z.boolean().optional().describe("Must be true when replace_mode=replace."),
+    },
+    async ({
+      project_id,
+      scene_ids,
+      part,
+      chapter,
+      only_stale = false,
+      dry_run = true,
+      replace_mode = "merge",
+      max_scenes = 200,
+      include_match_details = false,
+      confirm_replace = false,
+    }) => {
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      if (replace_mode === "replace" && !confirm_replace) {
+        return errorResponse(
+          "VALIDATION_ERROR",
+          "replace_mode=replace requires confirm_replace=true.",
+          { replace_mode, confirm_replace }
+        );
+      }
+
+      if (!dry_run && !SYNC_DIR_WRITABLE) {
+        return errorResponse(
+          "READ_ONLY",
+          "Cannot run batch character enrichment in write mode: sync dir is read-only.",
+          { sync_dir: SYNC_DIR_ABS }
+        );
+      }
+
+      const characterRows = db.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(project_id, project_id);
+
+      const targetResolution = resolveBatchTargetScenes(db, {
+        projectId: project_id,
+        sceneIds: scene_ids,
+        part,
+        chapter,
+        onlyStale: Boolean(only_stale),
+      });
+      if (!targetResolution.ok) {
+        return errorResponse(targetResolution.code, targetResolution.message, targetResolution.details);
+      }
+
+      const targetScenes = targetResolution.rows;
+      const projectExists = targetResolution.project_exists !== false;
+      if (targetScenes.length > max_scenes) {
+        return errorResponse(
+          "VALIDATION_ERROR",
+          `Matched ${targetScenes.length} scenes, which exceeds max_scenes=${max_scenes}.`,
+          {
+            matched_scenes: targetScenes.length,
+            max_scenes,
+            project_id,
+          }
+        );
+      }
+
+      const job = startAsyncJob({
+        kind: "enrich_scene_characters_batch",
+        requestPayload: {
+          kind: "enrich_scene_characters_batch",
+          args: {
+            project_id,
+            dry_run: Boolean(dry_run),
+            replace_mode,
+            include_match_details: Boolean(include_match_details),
+            project_exists: projectExists,
+            target_scenes: targetScenes,
+            character_rows: characterRows,
+          },
+          context: { sync_dir: SYNC_DIR },
+        },
+        onComplete: (completedJob) => {
+          if (dry_run || completedJob.status !== "completed" || !completedJob.result?.ok) return;
+
+          syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
+
+          const changedScenes = (completedJob.result.results ?? [])
+            .filter(row => row.status === "changed")
+            .map(row => row.scene_id);
+
+          for (const sceneId of changedScenes) {
+            db.prepare(`UPDATE scenes SET metadata_stale = 0 WHERE scene_id = ? AND project_id = ?`)
+              .run(sceneId, project_id);
+          }
+        },
+      });
+
+      return jsonResponse({
+        ok: true,
+        async: true,
+        job: toPublicJob(job, false),
+        next_step: "Call get_async_job_status with job_id until status is 'completed', 'failed', or 'cancelled'.",
+      });
+    }
+  );
+
   s.tool(
     "get_async_job_status",
-    "Get status and result for an asynchronous job started by import_scrivener_sync_async or merge_scrivener_project_beta_async.",
+    "Get status and result for an asynchronous job started by async tools such as import_scrivener_sync_async, merge_scrivener_project_beta_async, or enrich_scene_characters_batch.",
     {
       job_id: z.string().describe("Job ID returned by an async start tool."),
       include_result: z.boolean().optional().describe("If true (default), includes completed result payload when available."),
@@ -1081,7 +1305,7 @@ function createMcpServer() {
 
   s.tool(
     "list_async_jobs",
-    "List asynchronous import/merge jobs currently known to this server.",
+    "List asynchronous jobs currently known to this server.",
     {
       include_results: z.boolean().optional().describe("If true, includes completed result payloads."),
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -23,6 +23,7 @@
   "scripts": {
     "start": "node --experimental-sqlite index.js",
     "new:entity": "node scripts/new-world-entity.js",
+    "manual:realtest": "node scripts/manual-scrivener-realtest.mjs",
     "setup:openclaw-env": "sh scripts/setup-openclaw-env.sh",
     "release": "release-it",
     "lint": "eslint index.js importer.js db.js sync.js metadata-lint.js scripts/",

package/scripts/async-job-runner.mjs

@@ -2,12 +2,24 @@ import fs from "node:fs";
 import path from "node:path";
 import { importScrivenerSync } from "../importer.js";
 import { mergeScrivenerProjectMetadata } from "../scrivener-direct.js";
+import { runSceneCharacterBatch } from "../scene-character-batch.js";
+import { ASYNC_PROGRESS_PREFIX } from "../async-progress.js";
+
+const PROGRESS_PREFIX = ASYNC_PROGRESS_PREFIX;
 
 function writeResult(resultPath, payload) {
   fs.mkdirSync(path.dirname(resultPath), { recursive: true });
   fs.writeFileSync(resultPath, JSON.stringify(payload, null, 2), "utf8");
 }
 
+function writeProgress(payload) {
+  try {
+    process.stdout.write(`${PROGRESS_PREFIX}${JSON.stringify(payload)}\n`);
+  } catch {
+    // Best-effort only; never fail the job due to progress telemetry.
+  }
+}
+
 function normalizeImportResult(importResult) {
   const importPayload = {
     source_dir: importResult.scrivenerDir,
@@ -68,7 +80,14 @@ function normalizeMergeResult(mergeResult) {
   };
 }
 
-function main() {
+function normalizeSceneCharacterBatchResult(batchResult) {
+  return {
+    ok: true,
+    ...batchResult,
+  };
+}
+
+async function main() {
   const requestPath = process.argv[2];
   const resultPath = process.argv[3];
 
@@ -107,11 +126,37 @@ function main() {
     return;
   }
 
+  if (request.kind === "enrich_scene_characters_batch") {
+    let cancellationRequested = false;
+    const handleSigterm = () => {
+      cancellationRequested = true;
+    };
+    process.on("SIGTERM", handleSigterm);
+
+    const result = await runSceneCharacterBatch({
+      syncDir,
+      args: {
+        project_id: request.args?.project_id,
+        dry_run: Boolean(request.args?.dry_run),
+        replace_mode: request.args?.replace_mode ?? "merge",
+        include_match_details: Boolean(request.args?.include_match_details),
+        project_exists: request.args?.project_exists !== false,
+        target_scenes: request.args?.target_scenes ?? [],
+        character_rows: request.args?.character_rows ?? [],
+      },
+      onProgress: progress => writeProgress({ kind: request.kind, ...progress }),
+      shouldCancel: () => cancellationRequested,
+    });
+    process.off("SIGTERM", handleSigterm);
+    writeResult(resultPath, normalizeSceneCharacterBatchResult(result));
+    return;
+  }
+
   throw new Error(`Unsupported async job kind '${request.kind}'.`);
 }
 
 try {
-  main();
+  await main();
 } catch (error) {
   const resultPath = process.argv[3];
   if (resultPath) {

package/scripts/manual-scrivener-realtest.mjs

@@ -0,0 +1,262 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { importScrivenerSync, validateProjectId } from "../importer.js";
+import { mergeScrivenerProjectMetadata } from "../scrivener-direct.js";
+
+function usage() {
+  return [
+    "Usage:",
+    "  node scripts/manual-scrivener-realtest.mjs \\",
+    "    --source-dir <external-sync-dir> \\",
+    "    --scriv-path <copied-project.scriv> \\",
+    "    --project-id <project|universe/project> [options]",
+    "",
+    "Keep large real-data test assets outside the repository so they cannot be",
+    "accidentally committed. Example external storage location:",
+    "  $HOME/.mcp-writing-manual-data/",
+    "",
+    "Options:",
+    "  --help                  Show this help message.",
+    "  --sync-dir <path>       Temp sync root to write into.",
+    "                         Default: ./tmp/manual-realtest-sync",
+    "  --sample-count <n>      Number of sample sidecars to include. Default: 5",
+    "  --no-clean              Reuse existing sync dir instead of recreating it.",
+    "",
+    "Example:",
+    "  npm run manual:realtest -- \\",
+    "    --source-dir <path-to-external-sync-source> \\",
+    "    --scriv-path <path-to-external-test-data>/<project-name>.scriv \\",
+    "    --project-id <universe>/<project-name> \\",
+    "    --sync-dir <path-to-external-test-data>/manual-realtest-sync",
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const options = {
+    syncDir: "./tmp/manual-realtest-sync",
+    sampleCount: 5,
+    clean: true,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--help") {
+      options.help = true;
+    } else if (arg === "--source-dir") {
+      if (index + 1 >= argv.length) throw new Error(`${arg} requires a value.`);
+      options.sourceDir = argv[++index];
+    } else if (arg === "--scriv-path") {
+      if (index + 1 >= argv.length) throw new Error(`${arg} requires a value.`);
+      options.scrivPath = argv[++index];
+    } else if (arg === "--project-id") {
+      if (index + 1 >= argv.length) throw new Error(`${arg} requires a value.`);
+      options.projectId = argv[++index];
+    } else if (arg === "--sync-dir") {
+      if (index + 1 >= argv.length) throw new Error(`${arg} requires a value.`);
+      options.syncDir = argv[++index];
+    } else if (arg === "--sample-count") {
+      if (index + 1 >= argv.length) throw new Error(`${arg} requires a value.`);
+      const sampleCountValue = argv[++index];
+      if (!/^\d+$/.test(sampleCountValue)) {
+        throw new Error("--sample-count must be a positive integer.");
+      }
+      options.sampleCount = Number(sampleCountValue);
+    } else if (arg === "--no-clean") {
+      options.clean = false;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function validateOptions(options) {
+  if (options.help) return;
+
+  if (!options.sourceDir || !options.scrivPath || !options.projectId) {
+    throw new Error("Missing required arguments: --source-dir, --scriv-path, --project-id are required.");
+  }
+
+  if (!Number.isInteger(options.sampleCount) || options.sampleCount < 1) {
+    throw new Error("--sample-count must be a positive integer.");
+  }
+}
+
+function walkSidecars(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkSidecars(fullPath, out);
+    else if (entry.name.endsWith(".meta.yaml")) out.push(fullPath);
+  }
+  return out;
+}
+
+function summarizeImport(result) {
+  return {
+    projectId: result.projectId,
+    scenesDir: result.scenesDir,
+    sourceFiles: result.sourceFiles,
+    created: result.created,
+    existing: result.existing,
+    skipped: result.skipped,
+    beatMarkersSeen: result.beatMarkersSeen,
+    ignoredFiles: result.ignoredFiles,
+    filesToProcess: result.filesToProcess,
+    existingSidecars: result.existingSidecars,
+    filePreviews: result.filePreviews,
+    dryRun: result.dryRun,
+    preflight: result.preflight,
+  };
+}
+
+function summarizeMerge(result) {
+  return {
+    projectId: result.projectId,
+    scenesDir: result.scenesDir,
+    sidecarFiles: result.sidecarFiles,
+    updated: result.updated,
+    unchanged: result.unchanged,
+    skippedNoBracketId: result.skippedNoBracketId,
+    noData: result.noData,
+    fieldAddCounts: result.fieldAddCounts,
+    previewChanges: result.previewChanges,
+    stats: result.stats,
+  };
+}
+
+function runStep(name, fn) {
+  try {
+    return { name, ok: true, result: fn() };
+  } catch (error) {
+    return {
+      name,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function isSafeToDeleteSync(syncDir) {
+  const resolvedPath = path.resolve(syncDir);
+
+  // Never delete root or home directory
+  const parsed = path.parse(resolvedPath);
+  if (resolvedPath === parsed.root || resolvedPath === path.resolve(process.env.HOME || os.homedir())) {
+    return false;
+  }
+
+  // Allow deletion only if path contains a manual-realtest marker or is in ./tmp or /tmp
+  const hasMarker = resolvedPath.includes("manual-realtest");
+  
+  // Check if in tmp directories with proper path boundary checking
+  const localTmpDir = path.resolve("./tmp");
+  const isInLocalTmp =
+    resolvedPath === localTmpDir || resolvedPath.startsWith(localTmpDir + path.sep);
+  const isInSystemTmp =
+    resolvedPath === "/tmp" || resolvedPath.startsWith("/tmp" + path.sep);
+  const inTmpDir = isInLocalTmp || isInSystemTmp;
+  
+  return hasMarker || inTmpDir;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    console.log(usage());
+    process.exit(0);
+  }
+
+  validateOptions(options);
+
+  const projectIdCheck = validateProjectId(options.projectId);
+  if (!projectIdCheck.ok) {
+    throw new Error(`Invalid --project-id '${options.projectId}': ${projectIdCheck.reason}`);
+  }
+
+  const syncDir = path.resolve(options.syncDir);
+  const sourceDir = path.resolve(options.sourceDir);
+  const scrivPath = path.resolve(options.scrivPath);
+
+  if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) {
+    throw new Error(`--source-dir not found or not a directory: ${sourceDir}`);
+  }
+  if (!fs.existsSync(scrivPath) || !fs.statSync(scrivPath).isDirectory()) {
+    throw new Error(`--scriv-path not found or not a directory: ${scrivPath}`);
+  }
+
+  if (options.clean) {
+    if (!isSafeToDeleteSync(syncDir)) {
+      throw new Error(
+        `Safety check failed: --sync-dir must contain 'manual-realtest' or be in ./tmp or /tmp. Got: ${syncDir}`
+      );
+    }
+    fs.rmSync(syncDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(syncDir, { recursive: true });
+
+  const report = {
+    syncDir,
+    sourceDir,
+    scrivPath,
+    projectId: options.projectId,
+    cleanStart: options.clean,
+    tests: [],
+  };
+
+  report.tests.push(runStep("import_preflight", () => summarizeImport(importScrivenerSync({
+    scrivenerDir: sourceDir,
+    mcpSyncDir: syncDir,
+    projectId: options.projectId,
+    dryRun: true,
+    preflight: true,
+  }))));
+
+  report.tests.push(runStep("import_write", () => summarizeImport(importScrivenerSync({
+    scrivenerDir: sourceDir,
+    mcpSyncDir: syncDir,
+    projectId: options.projectId,
+    dryRun: false,
+    preflight: false,
+  }))));
+
+  report.tests.push(runStep("merge_dry_run", () => summarizeMerge(mergeScrivenerProjectMetadata({
+    scrivPath,
+    mcpSyncDir: syncDir,
+    projectId: options.projectId,
+    dryRun: true,
+  }))));
+
+  report.tests.push(runStep("merge_write", () => summarizeMerge(mergeScrivenerProjectMetadata({
+    scrivPath,
+    mcpSyncDir: syncDir,
+    projectId: options.projectId,
+    dryRun: false,
+  }))));
+
+  
+  // Use scenesDir from import_write result (the actual written path) instead of re-deriving
+  const importWriteResult = report.tests.find((test) => test.name === "import_write" && test.ok)?.result;
+  const scenesDir = importWriteResult?.scenesDir;
+  
+  const sidecars = scenesDir && fs.existsSync(scenesDir) ? walkSidecars(scenesDir) : [];
+  report.sidecarCount = sidecars.length;
+  report.sampleSidecars = sidecars
+    .slice(0, options.sampleCount)
+    .map((filePath) => path.relative(syncDir, filePath));
+
+  const failures = report.tests.filter((test) => !test.ok);
+  console.log(JSON.stringify(report, null, 2));
+  if (failures.length) process.exit(1);
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  console.error(usage());
+  process.exit(1);
+}