@hanna84/mcp-writing 2.12.4 → 2.12.6

package/scene-character-batch.js

@@ -1,246 +1 @@
-import fs from "node:fs";
-import matter from "gray-matter";
-import { buildCharacterNormalizationContext, escapeRegex, resolveCharacterReference } from "./scene-character-normalization.js";
-import { normalizeSceneMetaForPath, readMeta, writeMeta } from "./sync.js";
-
-function normalizeCharacterRows(rows) {
-  return buildCharacterNormalizationContext(rows);
-}
-
-function inferCharactersFromProse(prose, characterRows) {
-  const { clean, tokenMap } = characterRows;
-  const inferred = new Set();
-  const full_name_matches = new Set();
-  const ambiguous_tokens = [];
-
-  for (const row of clean) {
-    if (row.full_name_regex?.test(prose)) {
-      inferred.add(row.character_id);
-      full_name_matches.add(row.character_id);
-      continue;
-    }
-
-    // Precision-first v1 policy: multi-token names require a full phrase match.
-    if (row.phrase_tokens.length !== 1) {
-      continue;
-    }
-
-    for (const token of row.informative_tokens) {
-      const tokenRegex = new RegExp(`\\b${escapeRegex(token)}\\b`, "i");
-      if (!tokenRegex.test(prose)) continue;
-
-      const tokenIds = tokenMap.get(token) ?? [];
-      if (tokenIds.length === 1) {
-        inferred.add(row.character_id);
-      } else if (!ambiguous_tokens.includes(token)) {
-        ambiguous_tokens.push(token);
-      }
-    }
-  }
-
-  for (const [token, tokenIds] of tokenMap.entries()) {
-    if (tokenIds.length < 2) continue;
-    const tokenRegex = new RegExp(`\\b${escapeRegex(token)}\\b`, "i");
-    if (tokenRegex.test(prose) && !ambiguous_tokens.includes(token)) {
-      ambiguous_tokens.push(token);
-    }
-  }
-
-  return {
-    inferred_characters: [...inferred],
-    full_name_matches: [...full_name_matches],
-    ambiguous_tokens,
-  };
-}
-
-function resolveCharacterEntry(entry, characterRows) {
-  return resolveCharacterReference(entry, characterRows);
-}
-
-function pruneLessSpecificCharacters(characterIds, fullNameMatches, characterRows) {
-  const kept = new Set(characterIds);
-
-  for (const candidateId of [...kept]) {
-    const candidate = characterRows.byId.get(candidateId);
-    if (!candidate || candidate.informative_tokens.length < 2) continue;
-
-    for (const dominantId of fullNameMatches) {
-      if (candidateId === dominantId) continue;
-      const dominant = characterRows.byId.get(dominantId);
-      if (!dominant) continue;
-      if (candidate.informative_tokens.length >= dominant.informative_tokens.length) continue;
-
-      if (candidate.informative_tokens.every(token => dominant.informative_tokens.includes(token))) {
-        kept.delete(candidateId);
-        break;
-      }
-    }
-  }
-
-  return [...kept];
-}
-
-function nextTurn() {
-  return new Promise(resolve => setImmediate(resolve));
-}
-
-function getInterSceneDelayMs() {
-  const raw = Number(process.env.MCP_WRITING_SCENE_CHARACTER_BATCH_DELAY_MS ?? 0);
-  return Number.isFinite(raw) && raw > 0 ? raw : 0;
-}
-
-function delay(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-export async function runSceneCharacterBatch({ syncDir, args, onProgress, shouldCancel }) {
-  const {
-    project_id,
-    dry_run = true,
-    replace_mode = "merge",
-    include_match_details = false,
-    project_exists = true,
-    target_scenes = [],
-    character_rows = [],
-  } = args;
-
-  const targetScenes = Array.isArray(target_scenes) ? target_scenes : [];
-  const characterRows = Array.isArray(character_rows) ? character_rows : [];
-  const normalizedCharacterRows = normalizeCharacterRows(characterRows);
-
-  const results = [];
-  let processed_scenes = 0;
-  let scenes_changed = 0;
-  let failed_scenes = 0;
-  let links_added = 0;
-  let links_removed = 0;
-  const interSceneDelayMs = getInterSceneDelayMs();
-
-  const emitProgress = () => {
-    if (typeof onProgress !== "function") return;
-    onProgress({
-      total_scenes: targetScenes.length,
-      processed_scenes,
-      scenes_changed,
-      failed_scenes,
-    });
-  };
-
-  emitProgress();
-
-  for (const scene of targetScenes) {
-    await nextTurn();
-
-    if (typeof shouldCancel === "function" && shouldCancel()) {
-      break;
-    }
-
-    try {
-      const raw = fs.readFileSync(scene.file_path, "utf8");
-      const { content: prose } = matter(raw);
-      const { meta } = readMeta(scene.file_path, syncDir, { writable: !dry_run });
-
-      const before_characters = [...new Set((meta.characters ?? []).map(String).filter(Boolean))];
-      const normalized_before_characters = [...new Set(
-        before_characters
-          .map(character => resolveCharacterEntry(character, normalizedCharacterRows))
-          .filter(Boolean)
-      )];
-      const inference = inferCharactersFromProse(prose, normalizedCharacterRows);
-      const inferred_characters = inference.inferred_characters;
-
-      const afterSet = new Set(normalized_before_characters);
-      if (replace_mode === "replace") {
-        afterSet.clear();
-      }
-      for (const characterId of inferred_characters) {
-        afterSet.add(characterId);
-      }
-
-      const after_characters = pruneLessSpecificCharacters(
-        [...afterSet],
-        inference.full_name_matches,
-        normalizedCharacterRows
-      );
-      const beforeSet = new Set(before_characters);
-      const added = after_characters.filter(id => !beforeSet.has(id));
-      const afterSetLookup = new Set(after_characters);
-      const removed = before_characters.filter(id => !afterSetLookup.has(id));
-      const changed = added.length > 0 || removed.length > 0;
-
-      if (!dry_run && changed) {
-        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
-          ...meta,
-          characters: after_characters,
-        }).meta;
-
-        writeMeta(scene.file_path, updatedMeta);
-      }
-
-      scenes_changed += changed ? 1 : 0;
-      links_added += added.length;
-      links_removed += removed.length;
-
-      const hasInferredMatches = inferred_characters.length > 0;
-      const sceneStatus = changed
-        ? "changed"
-        : (!hasInferredMatches && inference.ambiguous_tokens.length > 0 ? "skipped_ambiguous" : "unchanged");
-
-      results.push({
-        scene_id: scene.scene_id,
-        file_path: scene.file_path,
-        before_characters,
-        inferred_characters,
-        after_characters,
-        added,
-        removed,
-        changed,
-        status: sceneStatus,
-        ...(include_match_details ? { match_details: { ambiguous_tokens: inference.ambiguous_tokens } } : {}),
-      });
-    } catch (error) {
-      failed_scenes += 1;
-      results.push({
-        scene_id: scene.scene_id,
-        file_path: scene.file_path,
-        before_characters: [],
-        inferred_characters: [],
-        after_characters: [],
-        added: [],
-        removed: [],
-        changed: false,
-        status: "failed",
-        error: error instanceof Error ? error.message : String(error),
-      });
-    } finally {
-      processed_scenes += 1;
-      emitProgress();
-      if (interSceneDelayMs > 0) {
-        await delay(interSceneDelayMs);
-      }
-    }
-  }
-
-  const warnings = [];
-  if (failed_scenes > 0) {
-    warnings.push("PARTIAL_SUCCESS: one or more scenes failed to process.");
-  }
-  if (!project_exists && targetScenes.length === 0) {
-    warnings.push(`PROJECT_NOT_FOUND_WARNING: project '${project_id}' was not found; nothing to process.`);
-  }
-
-  return {
-    ok: true,
-    cancelled: Boolean(typeof shouldCancel === "function" && shouldCancel() && processed_scenes < targetScenes.length),
-    project_id,
-    dry_run: Boolean(dry_run),
-    total_scenes: targetScenes.length,
-    processed_scenes,
-    scenes_changed,
-    failed_scenes,
-    links_added,
-    links_removed,
-    results,
-    ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}),
-  };
-}
+export * from "./src/sync/scene-character-batch.js";

package/scene-character-normalization.js

@@ -1,199 +1 @@
-export const NON_DISTINCTIVE_TOKENS = new Set([
-  "the",
-  "and",
-  "for",
-  "with",
-  "from",
-  "into",
-  "onto",
-  "over",
-  "under",
-  "after",
-  "before",
-  "about",
-  "around",
-]);
-
-export function escapeRegex(text) {
-  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-export function isDistinctiveToken(token) {
-  const normalized = String(token ?? "").trim().toLowerCase();
-  return Boolean(normalized) && normalized.length >= 3 && !NON_DISTINCTIVE_TOKENS.has(normalized);
-}
-
-function normalizeRawCharacterValues(values) {
-  const raw = Array.isArray(values) ? values : [];
-  const seen = new Set();
-  const normalized = [];
-
-  for (const value of raw) {
-    const text = String(value ?? "").trim();
-    if (!text || seen.has(text)) continue;
-    seen.add(text);
-    normalized.push(text);
-  }
-
-  return normalized;
-}
-
-function tokenizeValue(value) {
-  return [...new Set(String(value ?? "").toLowerCase().split(/\s+/).filter(isDistinctiveToken))];
-}
-
-export function buildCharacterNormalizationContext(rows) {
-  const clean = (Array.isArray(rows) ? rows : [])
-    .filter(row => row?.character_id && row?.name)
-    .map(row => {
-      const character_id = String(row.character_id).trim();
-      const name = String(row.name).trim();
-      const phrase_tokens = name.toLowerCase().split(/\s+/).filter(Boolean);
-      const tokens = [...new Set(phrase_tokens)];
-      return {
-        character_id,
-        name,
-        phrase_tokens,
-        tokens,
-        informative_tokens: tokens.filter(isDistinctiveToken),
-        full_name_regex: phrase_tokens.length > 1
-          ? new RegExp(`\\b${phrase_tokens.map(escapeRegex).join("\\s+")}\\b`, "i")
-          : null,
-      };
-    })
-    .filter(row => row.character_id.length > 0 && row.name.length > 0);
-
-  const byId = new Map();
-  const nameMap = new Map();
-  const tokenMap = new Map();
-  for (const row of clean) {
-    byId.set(row.character_id, row);
-    const normalizedName = row.name.toLowerCase();
-    const ids = nameMap.get(normalizedName) ?? [];
-    ids.push(row.character_id);
-    nameMap.set(normalizedName, ids);
-
-    for (const token of row.informative_tokens) {
-      const tokenIds = tokenMap.get(token) ?? [];
-      tokenIds.push(row.character_id);
-      tokenMap.set(token, tokenIds);
-    }
-  }
-
-  return { clean, byId, nameMap, tokenMap };
-}
-
-export function resolveCharacterReference(value, context) {
-  const text = String(value ?? "").trim();
-  if (!text) return null;
-
-  if (context.byId.has(text)) {
-    return text;
-  }
-
-  const exactNameIds = context.nameMap.get(text.toLowerCase());
-  if (exactNameIds?.length === 1) {
-    return exactNameIds[0];
-  }
-
-  const words = text.toLowerCase().split(/\s+/).filter(isDistinctiveToken);
-  if (words.length === 0) {
-    return text;
-  }
-
-  const matches = context.clean.filter(row =>
-    words.every(word => row.informative_tokens.includes(word))
-  );
-
-  if (matches.length === 1) {
-    return matches[0].character_id;
-  }
-
-  return text;
-}
-
-function isProperSubset(subsetTokens, supersetTokens) {
-  if (subsetTokens.length < 2 || subsetTokens.length >= supersetTokens.length) {
-    return false;
-  }
-  return subsetTokens.every(token => supersetTokens.includes(token));
-}
-
-function hasMoreSpecificNonCanonicalSource(candidate, sourceInfo) {
-  if (!sourceInfo || sourceInfo.hadCanonicalSource || sourceInfo.nonCanonicalTokens.length === 0) {
-    return false;
-  }
-
-  return sourceInfo.nonCanonicalTokens.some(tokens => isProperSubset(candidate.informative_tokens, tokens));
-}
-
-function pruneLessSpecificCanonicalIds(values, context, sourceMap) {
-  return values.filter((value, idx) => {
-    const row = context.byId.get(value);
-    if (!row || row.informative_tokens.length === 0) {
-      return true;
-    }
-
-    const rowSource = sourceMap.get(value);
-    if (!rowSource?.hadCanonicalSource) {
-      return true;
-    }
-
-    for (let i = 0; i < values.length; i++) {
-      if (i === idx) continue;
-
-      const otherId = values[i];
-      const other = context.byId.get(otherId);
-      if (!other || other.informative_tokens.length === 0) continue;
-
-      if (
-        isProperSubset(row.informative_tokens, other.informative_tokens)
-        && hasMoreSpecificNonCanonicalSource(row, sourceMap.get(otherId))
-      ) {
-        return false;
-      }
-    }
-
-    return true;
-  });
-}
-
-export function normalizeSceneCharacters(values, context) {
-  const before = normalizeRawCharacterValues(values);
-  const resolved = [];
-  const seen = new Set();
-  const sourceMap = new Map();
-
-  for (const value of before) {
-    const normalized = resolveCharacterReference(value, context);
-    if (!normalized) continue;
-
-    const source = sourceMap.get(normalized) ?? {
-      hadCanonicalSource: false,
-      nonCanonicalTokens: [],
-    };
-
-    if (context.byId.has(value)) {
-      source.hadCanonicalSource = true;
-    } else {
-      source.nonCanonicalTokens.push(tokenizeValue(value));
-    }
-    sourceMap.set(normalized, source);
-
-    if (seen.has(normalized)) continue;
-    seen.add(normalized);
-    resolved.push(normalized);
-  }
-
-  const after = pruneLessSpecificCanonicalIds(resolved, context, sourceMap);
-  const beforeSet = new Set(before);
-  const afterSet = new Set(after);
-
-  return {
-    before,
-    after,
-    changed: before.length !== after.length || before.some((value, idx) => after[idx] !== value),
-    added: after.filter(value => !beforeSet.has(value)),
-    removed: before.filter(value => !afterSet.has(value)),
-  };
-}
+export * from "./src/sync/scene-character-normalization.js";

package/scripts/async-job-runner.mjs

@@ -1,8 +1,8 @@
 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 { importScrivenerSync } from "../src/sync/importer.js";
+import { mergeScrivenerProjectMetadata } from "../src/sync/scrivener-direct.js";
+import { runSceneCharacterBatch } from "../src/sync/scene-character-batch.js";
 import { ASYNC_PROGRESS_PREFIX } from "../async-progress.js";
 
 const PROGRESS_PREFIX = ASYNC_PROGRESS_PREFIX;

package/scripts/generate-tool-docs.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /**
- * Generates docs/tools.md from tool definitions in index.js and tools/*.js.
+ * Generates docs/tools.md from tool definitions in the runtime entrypoint
+ * (src/index.js when present, otherwise index.js) and tools/*.js.
  *
  * Run:  node scripts/generate-tool-docs.mjs
  *   or: npm run docs
@@ -29,7 +30,17 @@ try {
 
 // Inline each register*Tools(s, ...) call with the module source so that
 // s.tool() blocks appear in registration order (matching createMcpServer()).
-let source = readFileSync(path.join(ROOT, 'index.js'), 'utf8');
+const ENTRYPOINT_PATH = path.join(ROOT, 'src', 'index.js');
+const LEGACY_ENTRYPOINT_PATH = path.join(ROOT, 'index.js');
+const sourcePath = (() => {
+  try {
+    readFileSync(ENTRYPOINT_PATH, 'utf8');
+    return ENTRYPOINT_PATH;
+  } catch {
+    return LEGACY_ENTRYPOINT_PATH;
+  }
+})();
+let source = readFileSync(sourcePath, 'utf8');
 for (const [fnName, content] of toolModuleMap) {
   source = source.replace(new RegExp(`[ \\t]*${fnName}\\s*\\([\\s\\S]*?\\);`), content);
 }
@@ -129,6 +140,12 @@ function extractConstantValues(src) {
     values.set(match[1], Number.parseInt(match[2], 10));
   }
 
+  for (const match of src.matchAll(/const\s+(\w+)\s*=\s*parsePositiveIntEnv\(\s*process\.env\.\w+\s*,\s*(\d+)\s*\);/g)) {
+    if (!values.has(match[1])) {
+      values.set(match[1], Number.parseInt(match[2], 10));
+    }
+  }
+
   for (const match of src.matchAll(/const\s+(\w+)\s*=\s*process\.env\.\w+\s*\?\?\s*(["'`])([\s\S]*?)\2;/g)) {
     if (!values.has(match[1])) {
       values.set(match[1], match[3]);
@@ -416,10 +433,11 @@ function anchor(name) {
 }
 
 function generateMarkdown(tools) {
+  const sourceLabel = path.relative(ROOT, sourcePath).replace(/\\/g, '/');
   const lines = [
     '# Tool Reference',
     '',
-    '> Auto-generated from `index.js`.',
+    `> Auto-generated from \`${sourceLabel}\`.`,
     '> Do not edit manually — run `npm run docs` to regenerate.',
     '',
     '## Tools',

package/scripts/import.js

@@ -7,7 +7,7 @@
  */
 
 import path from "node:path";
-import { importScrivenerSync, validateProjectId } from "../importer.js";
+import { importScrivenerSync, validateProjectId } from "../src/sync/importer.js";
 
 function printUsage() {
   console.log("Usage: node scripts/import.js <scrivener-sync-dir> <mcp-sync-dir> [--project <id>] [--dry-run]");

package/scripts/lint-metadata.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import path from "node:path";
-import { lintMetadataInSyncDir } from "../metadata-lint.js";
+import { lintMetadataInSyncDir } from "../src/sync/metadata-lint.js";
 
 function parseArgs(argv) {
   const args = { syncDir: process.env.WRITING_SYNC_DIR ?? "./sync" };

package/scripts/manual-scrivener-realtest.mjs

@@ -1,8 +1,8 @@
 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";
+import { importScrivenerSync, validateProjectId } from "../src/sync/importer.js";
+import { mergeScrivenerProjectMetadata } from "../src/sync/scrivener-direct.js";
 
 function usage() {
   return [
@@ -259,4 +259,4 @@ try {
   console.error(err instanceof Error ? err.message : String(err));
   console.error(usage());
   process.exit(1);
-}
+}

package/scripts/merge-scrivx.js

@@ -27,8 +27,8 @@
  */
 
 import path from "node:path";
-import { validateProjectId } from "../importer.js";
-import { mergeScrivenerProjectMetadata } from "../scrivener-direct.js";
+import { validateProjectId } from "../src/sync/importer.js";
+import { mergeScrivenerProjectMetadata } from "../src/sync/scrivener-direct.js";
 
 // ---------------------------------------------------------------------------
 // Args

package/scripts/new-world-entity.js

@@ -6,7 +6,7 @@ import {
   renderCharacterSheetTemplate,
   renderPlaceSheetTemplate,
   slugifyEntityName,
-} from "../world-entity-templates.js";
+} from "../src/world/world-entity-templates.js";
 
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -157,4 +157,4 @@ function main() {
   }
 }
 
-main();
+main();

package/scripts/normalize-scene-characters.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import path from "node:path";
 import { openDb } from "../db.js";
-import { buildCharacterNormalizationContext, normalizeSceneCharacters } from "../scene-character-normalization.js";
-import { normalizeSceneMetaForPath, readMeta, syncAll, writeMeta } from "../sync.js";
+import { buildCharacterNormalizationContext, normalizeSceneCharacters } from "../src/sync/scene-character-normalization.js";
+import { normalizeSceneMetaForPath, readMeta, syncAll, writeMeta } from "../src/sync/sync.js";
 
 function readRequiredValue(argv, index, option) {
   const value = argv[index + 1];
@@ -222,4 +222,4 @@ function main() {
   }
 }
 
-main();
+main();

package/scripts/profile-review-bundles.mjs

@@ -9,7 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { openDb } from "../db.js";
-import { syncAll } from "../sync.js";
+import { syncAll } from "../src/sync/sync.js";
 import { isGitRepository, getHeadCommitHash } from "../git.js";
 import {
   buildReviewBundlePlan,