@hanna84/mcp-writing 1.4.8 → 1.5.0

package/CHANGELOG.md

@@ -4,11 +4,21 @@ 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.5.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.4.8...v1.5.0)
+
+- feat: add MCP tool for first-time Scrivener import [`#42`](https://github.com/hannasdev/mcp-writing.git
+/pull/42)
+
 #### [v1.4.8](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.4.7...v1.4.8)
 
+> 19 April 2026
+
 - docs: move release automation out of README [`#41`](https://github.com/hannasdev/mcp-writing.git
 /pull/41)
+- Release 1.4.8 [`cebc920`](https://github.com/hannasdev/mcp-writing.git
+/commit/cebc920da6b2ce86a8758d17a9a089d06b5b3615)
 
 #### [v1.4.7](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.4.6...v1.4.7)

package/README.md

@@ -36,14 +36,15 @@ git --version     # should be installed
 
 ## First-time setup path (recommended)
 
-If this is your first time, use this path and skip the advanced/reference sections for now:
+If this is your first time, follow these steps in order:
 
-1. Follow either **Quick start with Scrivener** or **Running with Docker**.
-2. Start the server with `npm start`.
-3. Run **Verify your setup** (`/healthz` and `/sse`).
-4. Use the MCP `sync` tool once to build the index.
+1. Start with **Quick start with Scrivener** (or use **Running with Docker** if that is your preferred setup).
+2. Start the server.
+3. Verify the server (`/healthz` and `/sse`).
+4. Run `import_scrivener_sync` with `dry_run: true` first to preview what will happen.
+5. Run it again with `dry_run: false` to write files. Keep `auto_sync: true` (default) so your scenes are indexed immediately.
 
-After that, come back to:
+Once this is working, you can come back to:
 
 - **Advanced: Native sync format** for custom project layouts
 - **Reference: Available tools** for the full tool catalog
@@ -51,50 +52,83 @@ After that, come back to:
 
 ## Quick start with Scrivener
 
-If you write in [Scrivener](https://www.literatureandlatte.com/scrivener), you can seed `mcp-writing` from a Scrivener external-sync export for scene prose, then curate non-draft content directly into the target folder structure.
+If you write in [Scrivener](https://www.literatureandlatte.com/scrivener), this gives you the smoothest path to get started.
 
 ### 1. Export from Scrivener
 
-In Scrivener: **File → Sync → With External Folder**. Set the format to **plain text** (`.txt`) and pick an output folder, for example `~/my-novel-txt/`. `mcp-writing` imports the `Draft/` folder automatically.
+In Scrivener, go to **File → Sync → With External Folder**. Set the format to **plain text** (`.txt`) and choose an output folder, for example `~/my-novel-txt/`.
 
-### 2. Import into mcp-writing
+Only `Draft/` is imported automatically.
+
+### 2. Start mcp-writing
 
 ```sh
-node scripts/import.js ~/my-novel-txt /path/to/sync-dir --project my-novel
+WRITING_SYNC_DIR=/path/to/sync-dir DB_PATH=./writing.db npm start
 ```
 
-The importer:
+You should see:
 
-- Converts `Draft/` files to scene sidecars (`.meta.yaml`) with auto-generated `scene_id`, `title`, `part`, `chapter`, and `save_the_cat_beat` fields derived from the filename/structure.
-- Skips beat-marker files (`-Setup-`, `-Catalyst-`, etc.), chapter-intro files, epigraphs, and trashed files.
+```sh
+Listening on port 3000
+Sync dir: /path/to/sync-dir
+Database: ./writing.db
+```
 
-Important: `sync` does not run this import step for you. If your source is a raw Scrivener `Draft/` export, run `scripts/import.js` first so scene files get `scene_id` metadata before indexing.
+### 3. Verify the server
 
-Non-draft content is not inferred from `Notes/`. Put it directly into the target sync dir using the `world/` folder conventions described below.
+- Open `http://localhost:3000/healthz` and confirm it returns OK.
+- Open `http://localhost:3000/sse` and confirm it opens an SSE stream.
 
-### 3. Start the server
+### 4. Import Draft scenes through MCP (recommended)
 
-```sh
-WRITING_SYNC_DIR=/path/to/sync-dir DB_PATH=./writing.db npm start
+From your MCP client, call `import_scrivener_sync` with:
+
+```json
+{
+  "source_dir": "/Users/yourname/my-novel-txt",
+  "project_id": "my-novel",
+  "dry_run": true
+}
 ```
 
-You should see:
+> **Note:** use a full absolute path for `source_dir`. Shell shortcuts like `~` are not expanded by Node.js.
+
+If the preview looks right, run it again with writes enabled:
+
+```json
+{
+  "source_dir": "/Users/yourname/my-novel-txt",
+  "project_id": "my-novel",
+  "dry_run": false,
+  "auto_sync": true
+}
+```
+
+The importer:
+
+- Converts `Draft/` files to scene sidecars (`.meta.yaml`) with generated `scene_id`, `title`, `timeline_position`, `external_source`, `external_id`, and carried `save_the_cat_beat` where applicable.
+- Skips beat-marker files (`-Setup-`, `-Catalyst-`, etc.), chapter-intro files, epigraphs, and trashed files.
+- Reconciles updates by stable Scrivener binder ID (`[123]` in filenames) so reorder/move operations map to existing scenes.
+
+Non-draft content is not inferred from `Notes/`. Put it directly into the target sync dir using the `world/` folder conventions described below.
+
+### 5. Optional: CLI fallback import
+
+If you prefer to run the import from the command line, use:
 
 ```sh
-Listening on port 3000
-Sync dir: /path/to/sync-dir
-Database: ./writing.db
+node scripts/import.js ~/my-novel-txt /path/to/sync-dir --project my-novel
 ```
 
-Then call the `sync` tool once to index everything.
+Then call `sync` once.
 
-### 4. Lint your metadata (optional)
+### 6. Lint your metadata (optional)
 
 ```sh
 node scripts/lint-metadata.mjs --sync-dir /path/to/sync-dir
 ```
 
-Exits non-zero if any errors are found. Warnings (e.g. `UNKNOWN_KEY`) are informational only.
+This exits with a non-zero code if it finds errors. Warnings (for example `UNKNOWN_KEY`) are informational.
 
 ---
 
@@ -251,6 +285,7 @@ Outcome: you get AI speed with explicit approval and recoverable history for eve
 | Tool | Description |
 | --- | --- |
 | `sync` | Re-scan the sync folder and update the index |
+| `import_scrivener_sync` | Import Scrivener Draft export into sidecars and optionally auto-run sync |
 | `find_scenes` | Filter scenes by character, beat, tag, part, chapter, or POV |
 | `get_scene_prose` | Load the full prose for a specific scene |
 | `get_chapter_prose` | Load all prose for a chapter |

package/importer.js

@@ -0,0 +1,299 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+
+export function validateProjectId(projectId) {
+  if (typeof projectId !== "string" || projectId.trim().length === 0) {
+    return { ok: false, reason: "project_id must be a non-empty string." };
+  }
+
+  if (path.isAbsolute(projectId)) {
+    return { ok: false, reason: "project_id must not be an absolute path." };
+  }
+
+  if (projectId.includes("\\")) {
+    return { ok: false, reason: "project_id must not contain backslashes." };
+  }
+
+  const segments = projectId.split("/");
+  if (segments.length < 1 || segments.length > 2) {
+    return { ok: false, reason: "project_id must be '<project>' or '<universe>/<project>'." };
+  }
+
+  for (const segment of segments) {
+    if (!segment || segment === "." || segment === "..") {
+      return { ok: false, reason: "project_id must not contain '.' or '..' path segments." };
+    }
+    if (!/^[a-z0-9-]+$/.test(segment)) {
+      return { ok: false, reason: "project_id segments may contain only lowercase letters, numbers, and '-'." };
+    }
+  }
+
+  return { ok: true };
+}
+
+// Parse "NNN Title [binder_id].txt" -> { seq, rawTitle, binderId, ext } or null
+function parseFilename(filename) {
+  const m = filename.match(/^(\d+)\s+(.+?)\s*\[(\d+)\]\.(txt|md)$/);
+  if (!m) return null;
+  return {
+    seq: parseInt(m[1], 10),
+    rawTitle: m[2].trim(),
+    binderId: m[3],
+    ext: m[4],
+  };
+}
+
+function isBeatMarker(rawTitle) {
+  return /^-[^-].+-$/.test(rawTitle.trim());
+}
+
+function parseBeat(rawTitle) {
+  return rawTitle.trim().replace(/^-/, "").replace(/-$/, "").trim();
+}
+
+function isEpigraph(rawTitle) {
+  return /^epigraph$/i.test(rawTitle.trim());
+}
+
+function cleanTitle(rawTitle) {
+  return rawTitle.replace(/^Scene\s+/i, "").trim();
+}
+
+function slugify(str) {
+  return str
+    .toLowerCase()
+    .replace(/[\u{1F000}-\u{1FFFF}\u{2600}-\u{27FF}]/gu, "") // strip emoji
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 50);
+}
+
+function makeSceneId(binderId, title) {
+  return `sc-${String(binderId).padStart(3, "0")}-${slugify(title).slice(0, 40)}`;
+}
+
+function walkSorted(dir) {
+  const files = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isFile() && (entry.name.endsWith(".txt") || entry.name.endsWith(".md"))) {
+      files.push(full);
+    }
+  }
+  return files.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+}
+
+function loadYamlFile(filePath) {
+  try {
+    return yaml.load(fs.readFileSync(filePath, "utf8")) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function buildExistingSceneIndex(dir) {
+  const byBinderId = new Map();
+  if (!fs.existsSync(dir)) return byBinderId;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".meta.yaml")) continue;
+
+    const sidecarPath = path.join(dir, entry.name);
+    const proseCandidates = [
+      sidecarPath.replace(/\.meta\.yaml$/, ".txt"),
+      sidecarPath.replace(/\.meta\.yaml$/, ".md"),
+    ];
+    const prosePath = proseCandidates.find(candidate => fs.existsSync(candidate)) ?? null;
+    const proseName = prosePath ? path.basename(prosePath) : entry.name.replace(/\.meta\.yaml$/, ".txt");
+    const parsedName = parseFilename(proseName);
+    const meta = loadYamlFile(sidecarPath);
+    const binderId = meta.external_source === "scrivener" && meta.external_id
+      ? String(meta.external_id)
+      : parsedName?.binderId ?? null;
+
+    if (!binderId) continue;
+
+    byBinderId.set(String(binderId), {
+      binderId: String(binderId),
+      prosePath,
+      sidecarPath,
+      meta,
+    });
+  }
+
+  return byBinderId;
+}
+
+function removeIfExists(filePath) {
+  if (filePath && fs.existsSync(filePath)) fs.unlinkSync(filePath);
+}
+
+export function importScrivenerSync({
+  scrivenerDir,
+  mcpSyncDir,
+  projectId,
+  dryRun = false,
+  logger = () => {},
+}) {
+  const scrivenerDirAbs = path.resolve(scrivenerDir);
+  const mcpSyncDirAbs = path.resolve(mcpSyncDir);
+  const resolvedProjectId = projectId
+    ? projectId
+    : path.basename(mcpSyncDirAbs).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+  const projectIdCheck = validateProjectId(resolvedProjectId);
+  if (!projectIdCheck.ok) {
+    throw new Error(`Invalid project_id '${resolvedProjectId}': ${projectIdCheck.reason}`);
+  }
+
+  if (!fs.existsSync(scrivenerDirAbs)) {
+    throw new Error(`Scrivener sync dir not found: ${scrivenerDirAbs}`);
+  }
+
+  // Route universe/project IDs to universes/<universe>/<project>/scenes,
+  // matching the convention used by inferProjectAndUniverse in sync.js.
+  const segments = resolvedProjectId.split("/");
+  let scenesDir;
+  let scenesBoundaryRoot;
+  if (segments.length === 2) {
+    const [universeId, projectSlug] = segments;
+    scenesBoundaryRoot = path.join(mcpSyncDirAbs, "universes");
+    scenesDir = path.resolve(scenesBoundaryRoot, universeId, projectSlug, "scenes");
+  } else {
+    scenesBoundaryRoot = path.join(mcpSyncDirAbs, "projects");
+    scenesDir = path.resolve(scenesBoundaryRoot, resolvedProjectId, "scenes");
+  }
+
+  const relFromBoundary = path.relative(scenesBoundaryRoot, scenesDir);
+  if (relFromBoundary.startsWith("..") || path.isAbsolute(relFromBoundary)) {
+    throw new Error(`Invalid project_id '${resolvedProjectId}': resolved path escapes expected sync root.`);
+  }
+  const draftDir = path.join(scrivenerDirAbs, "Draft");
+  const hasDraft = fs.existsSync(draftDir);
+  const draftRoot = hasDraft ? draftDir : scrivenerDirAbs;
+
+  const files = walkSorted(draftRoot);
+  const existingScenes = buildExistingSceneIndex(scenesDir);
+
+  let created = 0;
+  let skipped = 0;
+  let existing = 0;
+  let beatMarkersSeen = 0;
+  let beatCarry = null;
+
+  if (!dryRun) {
+    fs.mkdirSync(scenesDir, { recursive: true });
+  }
+
+  logger(`Project:   ${resolvedProjectId}`);
+  logger(`Scenes to: ${scenesDir}`);
+  logger(`Files:     ${files.length}`);
+  logger("");
+
+  for (const file of files) {
+    const filename = path.basename(file);
+    const parsed = parseFilename(filename);
+
+    if (!parsed) {
+      logger(`  SKIP  (unrecognised pattern) ${filename}`);
+      skipped++;
+      continue;
+    }
+
+    const { seq, rawTitle, binderId, ext } = parsed;
+    const isEmpty = fs.statSync(file).size === 0;
+
+    if (isBeatMarker(rawTitle)) {
+      beatCarry = parseBeat(rawTitle);
+      beatMarkersSeen++;
+      logger(`  BEAT  "${beatCarry}"`);
+      continue;
+    }
+
+    if (isEmpty) {
+      logger(`  SKIP  (empty) ${filename}`);
+      skipped++;
+      continue;
+    }
+
+    if (isEpigraph(rawTitle)) {
+      logger(`  SKIP  (epigraph) ${filename}`);
+      skipped++;
+      continue;
+    }
+
+    const title = cleanTitle(rawTitle);
+    const existingScene = existingScenes.get(String(binderId)) ?? null;
+    const sceneId = existingScene?.meta?.scene_id ?? makeSceneId(binderId, title);
+    const destFile = path.join(scenesDir, `${seq.toString().padStart(3, "0")} ${rawTitle} [${binderId}].${ext}`);
+    const sidecar = destFile.replace(/\.(txt|md)$/, ".meta.yaml");
+
+    const meta = {
+      ...(existingScene?.meta ?? {}),
+      scene_id: sceneId,
+      external_source: "scrivener",
+      external_id: String(binderId),
+      title,
+      timeline_position: seq,
+      ...(beatCarry ? { save_the_cat_beat: beatCarry } : {}),
+    };
+
+    if (!beatCarry && existingScene?.meta && Object.hasOwn(existingScene.meta, "save_the_cat_beat")) {
+      delete meta.save_the_cat_beat;
+    }
+
+    if (dryRun) {
+      logger(`  DRY   ${path.basename(sidecar)}`);
+      if (existingScene) {
+        logger(`        reconcile: binder ${binderId} -> existing scene_id ${sceneId}`);
+      }
+      logger(`        scene_id: ${sceneId}, beat: ${beatCarry ?? "(none)"}`);
+    } else {
+      fs.copyFileSync(file, destFile);
+      fs.writeFileSync(sidecar, yaml.dump(meta, { lineWidth: 120 }), "utf8");
+
+      if (existingScene) {
+        if (existingScene.prosePath && existingScene.prosePath !== destFile) removeIfExists(existingScene.prosePath);
+        if (existingScene.sidecarPath && existingScene.sidecarPath !== sidecar) removeIfExists(existingScene.sidecarPath);
+        logger(`  OK    ${path.basename(sidecar)}  [reconciled binder ${binderId}, beat: ${beatCarry ?? "-"}]`);
+      } else {
+        logger(`  OK    ${path.basename(sidecar)}  [beat: ${beatCarry ?? "-"}]`);
+      }
+
+      existingScenes.set(String(binderId), {
+        binderId: String(binderId),
+        prosePath: destFile,
+        sidecarPath: sidecar,
+        meta,
+      });
+    }
+
+    beatCarry = null;
+    if (existingScene) existing++;
+    else created++;
+  }
+
+  logger("");
+  logger(`${"-".repeat(50)}`);
+  logger(`Created:  ${created} sidecars${dryRun ? " (dry run)" : ""}`);
+  logger(`Skipped:  ${skipped} (empty / epigraph / pattern)`);
+  if (existing) logger(`Existing: ${existing} already had sidecars`);
+  logger(`Beat markers seen: ${beatMarkersSeen}`);
+
+  logger(`Non-draft content: manual`);
+  logger(`  Place character/place/reference files directly in the target sync dir using the world/ folder conventions.`);
+
+  return {
+    projectId: resolvedProjectId,
+    scrivenerDir: scrivenerDirAbs,
+    mcpSyncDir: mcpSyncDirAbs,
+    scenesDir,
+    sourceFiles: files.length,
+    created,
+    skipped,
+    existing,
+    beatMarkersSeen,
+    dryRun,
+  };
+}

package/index.js

@@ -10,6 +10,7 @@ import { openDb } from "./db.js";
 import { syncAll, isSyncDirWritable, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, sidecarPath } from "./sync.js";
 import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit } from "./git.js";
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
+import { importScrivenerSync, validateProjectId } from "./importer.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
@@ -309,6 +310,89 @@ function createMcpServer() {
     return { content: [{ type: "text", text: parts.join(" ") }] };
   });
 
+  // ---- import_scrivener_sync ----------------------------------------------
+  s.tool(
+    "import_scrivener_sync",
+    "Import Scrivener External Folder Sync Draft files into this server's WRITING_SYNC_DIR by generating scene sidecars and reconciling by Scrivener binder ID. Use this for first-time setup before sync().",
+    {
+      source_dir: z.string().describe("Path to Scrivener external sync folder (the folder that contains Draft/, or Draft/ itself)."),
+      project_id: z.string().optional().describe("Project ID override (e.g. 'the-lamb'). Defaults to a slug derived from WRITING_SYNC_DIR."),
+      dry_run: z.boolean().optional().describe("If true, reports planned writes without changing files."),
+      auto_sync: z.boolean().optional().describe("If true (default), runs sync() after import when not dry-run."),
+    },
+    async ({ source_dir, project_id, dry_run = false, auto_sync = true }) => {
+      if (project_id !== undefined) {
+        const projectIdCheck = validateProjectId(project_id);
+        if (!projectIdCheck.ok) {
+          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+        }
+      }
+
+      if (!dry_run && !SYNC_DIR_WRITABLE) {
+        return errorResponse(
+          "SYNC_DIR_NOT_WRITABLE",
+          "Cannot import because WRITING_SYNC_DIR is not writable in this runtime.",
+          { sync_dir: SYNC_DIR_ABS }
+        );
+      }
+
+      let importResult;
+      try {
+        importResult = importScrivenerSync({
+          scrivenerDir: source_dir,
+          mcpSyncDir: SYNC_DIR,
+          projectId: project_id,
+          dryRun: Boolean(dry_run),
+        });
+      } catch (error) {
+        return errorResponse(
+          "IMPORT_FAILED",
+          error instanceof Error ? error.message : "Import failed.",
+          {
+            source_dir,
+            sync_dir: SYNC_DIR_ABS,
+            project_id: project_id ?? null,
+          }
+        );
+      }
+
+      let syncResult = null;
+      if (!dry_run && auto_sync) {
+        syncResult = syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
+      }
+
+      return jsonResponse({
+        ok: true,
+        import: {
+          source_dir: importResult.scrivenerDir,
+          sync_dir: importResult.mcpSyncDir,
+          scenes_dir: importResult.scenesDir,
+          project_id: importResult.projectId,
+          source_files: importResult.sourceFiles,
+          created: importResult.created,
+          existing: importResult.existing,
+          skipped: importResult.skipped,
+          beat_markers_seen: importResult.beatMarkersSeen,
+          dry_run: importResult.dryRun,
+        },
+        sync: syncResult
+          ? {
+            indexed: syncResult.indexed,
+            stale_marked: syncResult.staleMarked,
+            sidecars_migrated: syncResult.sidecarsMigrated,
+            skipped: syncResult.skipped,
+            warnings: syncResult.warnings,
+          }
+          : null,
+        next_step: dry_run
+          ? "Dry run complete. Re-run with dry_run=false to write files."
+          : auto_sync
+            ? "Import and sync complete."
+            : "Import complete. Run sync() to index imported scenes.",
+      });
+    }
+  );
+
   // ---- get_runtime_config --------------------------------------------------
   s.tool(
     "get_runtime_config",

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.4.8",
+  "version": "1.5.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
   "files": [
     "index.js",
+    "importer.js",
     "db.js",
     "sync.js",
     "git.js",
@@ -21,7 +22,7 @@
     "start": "node --experimental-sqlite index.js",
     "new:entity": "node scripts/new-world-entity.js",
     "release": "release-it",
-    "lint": "eslint index.js db.js sync.js metadata-lint.js scripts/",
+    "lint": "eslint index.js importer.js db.js sync.js metadata-lint.js scripts/",
     "lint:metadata": "node scripts/lint-metadata.mjs",
     "test:unit": "node --experimental-sqlite --test test/unit.test.mjs",
     "test:integration": "node --experimental-sqlite --test test/integration.test.mjs",

package/scripts/import.js

@@ -3,287 +3,60 @@
  * Import a Scrivener External Folder Sync output into mcp-writing sidecar format.
  *
  * Usage:
- *   node scripts/import.js <scrivener-sync-dir> <mcp-sync-dir> [options]
- *
- *   <scrivener-sync-dir>  The folder Scrivener syncs into (e.g. ./txt)
- *                         Only Draft/ is imported automatically.
- *   <mcp-sync-dir>        The WRITING_SYNC_DIR root (e.g. ./my-project-sync)
- *
- * Options:
- *   --project <id>    Project ID to assign (default: derived from mcp-sync-dir name)
- *   --dry-run         Show what would be created without writing anything
- *
- * What it does (Draft folder):
- *   - Walks the Draft dir in filename order (NNN prefix = current binder sequence)
- *   - Skips empty files (non-compilation title cards) and Epigraphs
- *   - Detects Save the Cat beat markers ("-Beat Name-" empty files) and carries
- *     the beat name forward to the next prose scene's sidecar
- *   - Creates mcp-sync-dir/projects/<project>/scenes/ structure
- *   - Reconciles existing imports by stable Scrivener binder ID (`[123]` in the filename)
- *   - Writes a .meta.yaml sidecar for each scene while preserving existing editorial metadata
- *
- * What it does not do:
- *   - It does not infer structure from Scrivener Notes/
- *   - Non-draft content should be placed manually into the target sync dir
- *     using the world/characters, world/places, and world/reference conventions
+ *   node scripts/import.js <scrivener-sync-dir> <mcp-sync-dir> [--project <id>] [--dry-run]
  */
 
-import fs from "node:fs";
 import path from "node:path";
-import yaml from "js-yaml";
+import { importScrivenerSync, validateProjectId } from "../importer.js";
+
+function printUsage() {
+  console.log("Usage: node scripts/import.js <scrivener-sync-dir> <mcp-sync-dir> [--project <id>] [--dry-run]");
+}
 
-// ---------------------------------------------------------------------------
-// Args
-// ---------------------------------------------------------------------------
 const args = process.argv.slice(2);
 if (args.length < 2 || args[0] === "--help") {
-  console.log("Usage: node scripts/import.js <scrivener-sync-dir> <mcp-sync-dir> [--project <id>] [--dry-run]");
+  printUsage();
   process.exit(args[0] === "--help" ? 0 : 1);
 }
 
 const scrivenerDir = path.resolve(args[0]);
-const mcpSyncDir   = path.resolve(args[1]);
-const dryRun       = args.includes("--dry-run");
-const projectIdx   = args.indexOf("--project");
-const projectId    = projectIdx !== -1
-  ? args[projectIdx + 1]
-  : path.basename(mcpSyncDir).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
-
-if (!fs.existsSync(scrivenerDir)) {
-  console.error(`Scrivener sync dir not found: ${scrivenerDir}`);
+const mcpSyncDir = path.resolve(args[1]);
+const dryRun = args.includes("--dry-run");
+const projectIdx = args.indexOf("--project");
+let projectId;
+if (projectIdx !== -1) {
+  const candidate = args[projectIdx + 1];
+  if (!candidate || candidate.startsWith("--")) {
+    console.error("Invalid --project value: expected a project id after --project.");
+    printUsage();
+    process.exit(1);
+  }
+  const projectIdCheck = validateProjectId(candidate);
+  if (!projectIdCheck.ok) {
+    console.error(`Invalid --project value '${candidate}': ${projectIdCheck.reason}`);
+    printUsage();
+    process.exit(1);
+  }
+  projectId = candidate;
+}
+
+try {
+  const result = importScrivenerSync({
+    scrivenerDir,
+    mcpSyncDir,
+    projectId,
+    dryRun,
+    logger: line => console.log(line),
+  });
+
+  if (!dryRun) {
+    console.log("\nNext steps:");
+    console.log("  1. Start the service:");
+    console.log(`       WRITING_SYNC_DIR=${result.mcpSyncDir} DB_PATH=./writing.db npm start`);
+    console.log("  2. Call the sync tool to index everything");
+    console.log("  3. Review part/chapter/pov fields in sidecars as needed");
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
   process.exit(1);
 }
-
-const scenesDir = path.join(mcpSyncDir, "projects", projectId, "scenes");
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-// Parse "NNN Title [binder_id].txt" → { seq, rawTitle, binderId, ext } or null
-function parseFilename(filename) {
-  const m = filename.match(/^(\d+)\s+(.+?)\s*\[(\d+)\]\.(txt|md)$/);
-  if (!m) return null;
-  return {
-    seq: parseInt(m[1], 10),
-    rawTitle: m[2].trim(),
-    binderId: m[3],
-    ext: m[4],
-  };
-}
-
-function isBeatMarker(rawTitle) {
-  return /^-[^-].+-$/.test(rawTitle.trim());
-}
-
-function parseBeat(rawTitle) {
-  return rawTitle.trim().replace(/^-/, "").replace(/-$/, "").trim();
-}
-
-function isEpigraph(rawTitle) {
-  return /^epigraph$/i.test(rawTitle.trim());
-}
-
-function cleanTitle(rawTitle) {
-  return rawTitle.replace(/^Scene\s+/i, "").trim();
-}
-
-function slugify(str) {
-  return str
-    .toLowerCase()
-    .replace(/[\u{1F000}-\u{1FFFF}\u{2600}-\u{27FF}]/gu, "") // strip emoji
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 50);
-}
-
-function makeSceneId(binderId, title) {
-  return `sc-${String(binderId).padStart(3, "0")}-${slugify(title).slice(0, 40)}`;
-}
-
-// ---------------------------------------------------------------------------
-// Walk a directory (sorted by filename = binder order, non-recursive)
-// ---------------------------------------------------------------------------
-function walkSorted(dir) {
-  const files = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isFile() && (entry.name.endsWith(".txt") || entry.name.endsWith(".md"))) {
-      files.push(full);
-    }
-  }
-  return files.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
-}
-
-function loadYamlFile(filePath) {
-  try {
-    return yaml.load(fs.readFileSync(filePath, "utf8")) ?? {};
-  } catch {
-    return {};
-  }
-}
-
-function buildExistingSceneIndex(dir) {
-  const byBinderId = new Map();
-  if (!fs.existsSync(dir)) return byBinderId;
-
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.endsWith(".meta.yaml")) continue;
-
-    const sidecarPath = path.join(dir, entry.name);
-    const proseCandidates = [
-      sidecarPath.replace(/\.meta\.yaml$/, ".txt"),
-      sidecarPath.replace(/\.meta\.yaml$/, ".md"),
-    ];
-    const prosePath = proseCandidates.find(candidate => fs.existsSync(candidate)) ?? null;
-    const proseName = prosePath ? path.basename(prosePath) : entry.name.replace(/\.meta\.yaml$/, ".txt");
-    const parsedName = parseFilename(proseName);
-    const meta = loadYamlFile(sidecarPath);
-    const binderId = meta.external_source === "scrivener" && meta.external_id
-      ? String(meta.external_id)
-      : parsedName?.binderId ?? null;
-
-    if (!binderId) continue;
-
-    byBinderId.set(String(binderId), {
-      binderId: String(binderId),
-      prosePath,
-      sidecarPath,
-      meta,
-    });
-  }
-
-  return byBinderId;
-}
-
-function removeIfExists(filePath) {
-  if (filePath && fs.existsSync(filePath)) fs.unlinkSync(filePath);
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-const draftDir = path.join(scrivenerDir, "Draft");
-const hasDraft = fs.existsSync(draftDir);
-
-// If there's a Draft/ subdir use that; otherwise treat scrivenerDir as Draft directly
-const draftRoot = hasDraft ? draftDir : scrivenerDir;
-
-const files = walkSorted(draftRoot);
-const existingScenes = buildExistingSceneIndex(scenesDir);
-let created = 0;
-let skipped = 0;
-let alreadyDone = 0;
-let beatCarry = null; // last seen beat marker
-
-if (!dryRun) {
-  fs.mkdirSync(scenesDir, { recursive: true });
-}
-
-console.log(`Project:   ${projectId}`);
-console.log(`Scenes to: ${scenesDir}`);
-console.log(`Files:     ${files.length}\n`);
-
-for (const file of files) {
-  const filename = path.basename(file);
-  const parsed = parseFilename(filename);
-
-  if (!parsed) {
-    console.log(`  SKIP  (unrecognised pattern) ${filename}`);
-    skipped++;
-    continue;
-  }
-
-  const { seq, rawTitle, binderId, ext } = parsed;
-  const isEmpty = fs.statSync(file).size === 0;
-
-  // Beat markers: always empty, carry beat name forward
-  if (isBeatMarker(rawTitle)) {
-    beatCarry = parseBeat(rawTitle);
-    console.log(`  BEAT  "${beatCarry}"`);
-    continue;
-  }
-
-  // Empty non-beat files: title cards, chapter headers excluded from compilation
-  if (isEmpty) {
-    console.log(`  SKIP  (empty) ${filename}`);
-    skipped++;
-    continue;
-  }
-
-  // Epigraphs: have content but aren't scenes
-  if (isEpigraph(rawTitle)) {
-    console.log(`  SKIP  (epigraph) ${filename}`);
-    skipped++;
-    continue;
-  }
-
-  // Scene file — create sidecar
-  const title = cleanTitle(rawTitle);
-  const existing = existingScenes.get(String(binderId)) ?? null;
-  const sceneId = existing?.meta?.scene_id ?? makeSceneId(binderId, title);
-  const destFile = path.join(scenesDir, `${seq.toString().padStart(3, "0")} ${rawTitle} [${binderId}].${ext}`);
-  const sidecar = destFile.replace(/\.(txt|md)$/, ".meta.yaml");
-
-  const meta = {
-    ...(existing?.meta ?? {}),
-    scene_id: sceneId,
-    external_source: "scrivener",
-    external_id: String(binderId),
-    title,
-    timeline_position: seq,
-    ...(beatCarry ? { save_the_cat_beat: beatCarry } : {}),
-    // Placeholders — fill in after reviewing
-    // part: null,
-    // chapter: null,
-    // pov: null,
-    // logline: null,
-    // characters: [],
-    // places: [],
-    // tags: [],
-  };
-
-  if (!beatCarry && existing?.meta && Object.hasOwn(existing.meta, "save_the_cat_beat")) {
-    delete meta.save_the_cat_beat;
-  }
-
-  if (dryRun) {
-    console.log(`  DRY   ${path.basename(sidecar)}`);
-    if (existing) {
-      console.log(`        reconcile: binder ${binderId} -> existing scene_id ${sceneId}`);
-    }
-    console.log(`        scene_id: ${sceneId}, beat: ${beatCarry ?? "(none)"}`);
-  } else {
-    // Copy/update prose file in mcp-sync-dir scenes folder
-    fs.copyFileSync(file, destFile);
-    fs.writeFileSync(sidecar, yaml.dump(meta, { lineWidth: 120 }), "utf8");
-
-    if (existing) {
-      if (existing.prosePath && existing.prosePath !== destFile) removeIfExists(existing.prosePath);
-      if (existing.sidecarPath && existing.sidecarPath !== sidecar) removeIfExists(existing.sidecarPath);
-      console.log(`  OK    ${path.basename(sidecar)}  [reconciled binder ${binderId}, beat: ${beatCarry ?? "—"}]`);
-    } else {
-      console.log(`  OK    ${path.basename(sidecar)}  [beat: ${beatCarry ?? "—"}]`);
-    }
-    existingScenes.set(String(binderId), { binderId: String(binderId), prosePath: destFile, sidecarPath: sidecar, meta });
-  }
-
-  beatCarry = null; // consumed
-  if (existing) alreadyDone++;
-  else created++;
-}
-
-console.log(`\n${"─".repeat(50)}`);
-console.log(`Created:  ${created} sidecars${dryRun ? " (dry run)" : ""}`);
-console.log(`Skipped:  ${skipped} (empty / epigraph / pattern)`);
-if (alreadyDone) console.log(`Existing: ${alreadyDone} already had sidecars`);
-
-console.log(`Non-draft content: manual`);
-console.log(`  Place character/place/reference files directly in the target sync dir using the world/ folder conventions.`);
-
-if (!dryRun && created > 0) {
-  console.log(`\nNext steps:`);
-  console.log(`  1. Start the service:`);
-  console.log(`       WRITING_SYNC_DIR=${mcpSyncDir} DB_PATH=./writing.db npm start`);
-  console.log(`  2. Call the sync tool to index everything`);
-  console.log(`  3. Review part/chapter/pov fields in sidecars as needed`);
-}