cowriter 0.1.0

package/scripts/cowriter-ai.mjs

@@ -0,0 +1,1126 @@
+#!/usr/bin/env node
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { createServer } from "node:net";
+import { homedir, platform, userInfo } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import YAML from "yaml";
+
+const require = createRequire(import.meta.url);
+const invokedPath = process.argv[1] ? pathToFileURL(realpathSync(process.argv[1])).href : "";
+const isCli = import.meta.url === invokedPath;
+const repoRoot = resolve(new URL("..", import.meta.url).pathname);
+const frontendRoot = join(repoRoot, "frontend");
+const initTemplateRoot = join(repoRoot, "templates", "init");
+const defaultPort = 47891;
+const projectStateDir = ".cowriter";
+const legacyProjectStateDir = ".ghostwriter";
+const projectSkillDir = ".codex/skills/cowriter";
+const starterSynopsis = "";
+const legacyStarterChapterText =
+  "Opening\n\nThe first page waits here. Write into the book, select a passage, then ask Codex to revise, expand, or test it against the story bible.";
+const legacyStarterSynopsis = "A rough promise for the book belongs here.";
+const coverContentTypes = {
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".avif": "image/avif",
+  ".gif": "image/gif",
+};
+const coverFilenamesByPreference = ["cover.png", "cover.webp", "cover.jpg", "cover.jpeg", "cover.avif", "cover.gif"];
+const fillerTerms = [
+  "delve",
+  "utilize",
+  "leverage",
+  "facilitate",
+  "elucidate",
+  "embark",
+  "endeavor",
+  "encompass",
+  "multifaceted",
+  "tapestry",
+  "testament",
+  "paradigm",
+  "synergy",
+  "holistic",
+  "catalyze",
+  "juxtapose",
+  "nuanced",
+  "realm",
+  "landscape",
+  "myriad",
+  "plethora",
+];
+const repeatedWordStopWords = new Set([
+  "about",
+  "after",
+  "again",
+  "also",
+  "because",
+  "before",
+  "between",
+  "could",
+  "from",
+  "have",
+  "into",
+  "only",
+  "over",
+  "said",
+  "some",
+  "than",
+  "that",
+  "their",
+  "there",
+  "they",
+  "this",
+  "through",
+  "what",
+  "when",
+  "where",
+  "which",
+  "with",
+  "would",
+]);
+
+function parseArgs(argv) {
+  if (argv[0] === "--") argv = argv.slice(1);
+  const [command, ...rest] = argv;
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < rest.length; index += 1) {
+    const item = rest[index];
+    if (!item.startsWith("--") && item !== "-o") {
+      positionals.push(item);
+      continue;
+    }
+    const key = item === "-o" ? "output" : item.slice(2);
+    const next = rest[index + 1];
+    if (!next || next.startsWith("-")) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    index += 1;
+  }
+  flags._ = positionals;
+  return { command, flags, positionals };
+}
+
+function output(value, flags) {
+  if (flags.output === "json" || flags.o === "json") {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    return;
+  }
+  if (typeof value.message === "string") {
+    process.stdout.write(`${value.message}\n`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function fail(error, flags) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (flags?.output === "json" || flags?.o === "json") {
+    process.stderr.write(`${JSON.stringify({ error: message }, null, 2)}\n`);
+  } else {
+    process.stderr.write(`${message}\n`);
+  }
+  process.exit(1);
+}
+
+function expandPath(path) {
+  if (!path || typeof path !== "string") throw new Error("A project path is required.");
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  return resolve(path);
+}
+
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true });
+}
+
+function readYaml(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  return YAML.parse(readFileSync(path, "utf8")) ?? fallback;
+}
+
+function writeYaml(path, value) {
+  ensureDir(dirname(path));
+  writeFileSync(path, YAML.stringify(value), "utf8");
+}
+
+function listTemplateFiles(root, prefix = "") {
+  return readdirSync(join(root, prefix), { withFileTypes: true }).flatMap((entry) => {
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) return listTemplateFiles(root, relativePath);
+    if (!entry.isFile()) return [];
+    return [safeRelativePath(relativePath)];
+  });
+}
+
+function renderTemplateValue(value, relativePath) {
+  const text = String(value ?? "");
+  return /\.ya?ml$/i.test(relativePath) ? JSON.stringify(text) : text;
+}
+
+function renderTemplate(content, context, relativePath) {
+  return content.replace(/\{\{([A-Za-z][A-Za-z0-9_]*)\}\}/g, (match, key) => {
+    if (!Object.hasOwn(context, key)) throw new Error(`Unknown template placeholder: ${key}`);
+    return renderTemplateValue(context[key], relativePath);
+  });
+}
+
+function writeRenderedTemplate(root, relativePath, context) {
+  const safePath = safeRelativePath(relativePath);
+  const source = join(initTemplateRoot, safePath);
+  if (!existsSync(source)) throw new Error(`Missing init template: ${safePath}`);
+  const rendered = renderTemplate(readFileSync(source, "utf8"), context, safePath);
+  const target = join(root, safePath);
+  ensureDir(dirname(target));
+  writeFileSync(target, rendered, "utf8");
+  return safePath;
+}
+
+function writeRenderedTemplates(root, relativePaths, context) {
+  return relativePaths.map((relativePath) => writeRenderedTemplate(root, relativePath, context));
+}
+
+function runGit(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function runGitStatus(cwd, args) {
+  return spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function ensureGitRepo(root) {
+  if (!existsSync(join(root, ".git"))) runGit(root, ["init"]);
+}
+
+function commitBookFiles(root, changedPaths, message) {
+  const paths = Array.from(new Set((changedPaths ?? []).filter((path) => typeof path === "string" && path.trim())));
+  ensureGitRepo(root);
+  runGit(root, ["add", ...(paths.length ? paths : ["."])]);
+
+  const diff = runGitStatus(root, ["diff", "--cached", "--quiet"]);
+  if (diff.status === 0) return false;
+  if (diff.status !== 1) throw new Error(diff.stderr?.trim() || "Unable to inspect staged book changes.");
+
+  runGit(root, ["-c", "user.name=Cowriter", "-c", "user.email=cowriter@localhost", "commit", "-m", message]);
+  return true;
+}
+
+function cleanAuthorName(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim();
+}
+
+function systemUsername() {
+  try {
+    return cleanAuthorName(userInfo().username);
+  } catch {
+    return cleanAuthorName(process.env.USER ?? process.env.USERNAME);
+  }
+}
+
+function fullNameFromOperatingSystem(username) {
+  if (platform() === "darwin") {
+    const result = spawnSync("id", ["-F"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return cleanAuthorName(result.stdout);
+  }
+
+  if (platform() !== "win32" && username) {
+    const result = spawnSync("getent", ["passwd", username], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const gecos = result.stdout.split(":")[4]?.split(",")[0];
+    return cleanAuthorName(gecos);
+  }
+
+  return "";
+}
+
+function defaultAuthorName() {
+  const username = systemUsername();
+  return fullNameFromOperatingSystem(username) || username || "Local Writer";
+}
+
+function starterProject(root, title = "Untitled Book", synopsis = "") {
+  const now = new Date().toISOString();
+  const cleanTitle = String(title ?? "").trim();
+  const metadataTitle = cleanTitle || "Untitled Book";
+  return {
+    path: root,
+    metadata: { title: metadataTitle, author: defaultAuthorName(), createdAt: now },
+    activeChapterId: "001-opening",
+    chapters: [
+      {
+        id: "001-opening",
+        title: "Opening",
+        path: "chapters/001-opening.md",
+        markdown: "",
+        updatedAt: now,
+      },
+    ],
+    story: {
+      title: cleanTitle,
+      synopsis: String(synopsis ?? "").trim(),
+      setting: "",
+      themes: "",
+      genre: "",
+      tone: "",
+      perspective: "",
+      continuity: "",
+    },
+    characters: [
+      {
+        id: "primary-character",
+        name: "",
+        role: "",
+        desire: "",
+        conflict: "",
+        notes: "",
+      },
+    ],
+    outline: [
+      {
+        id: "opening-beat",
+        title: "",
+        summary: "",
+      },
+    ],
+    cover: null,
+    git: { dirty: false, changedPaths: [] },
+  };
+}
+
+function initTemplateContext(project) {
+  return {
+    title: project.story.title,
+    metadataTitle: project.metadata.title,
+    synopsis: project.story.synopsis,
+    author: project.metadata.author,
+    createdAt: project.metadata.createdAt,
+  };
+}
+
+function titleFromId(id) {
+  return id
+    .replace(/^\d+-/, "")
+    .replace(/\.md$/, "")
+    .split("-")
+    .map((word) => word.slice(0, 1).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+function safeId(value, label) {
+  const id = String(value ?? "").trim();
+  if (!/^[A-Za-z0-9._-]+$/.test(id)) throw new Error(`Invalid ${label}.`);
+  return id;
+}
+
+function safeRelativePath(path) {
+  const clean = String(path ?? "").trim();
+  if (!clean || clean.startsWith("/") || clean.split(/[\\/]/).includes("..")) throw new Error("Unsafe book path.");
+  return clean;
+}
+
+function safeChapterPath(path) {
+  const clean = safeRelativePath(path);
+  if (clean.includes("\\") || !clean.startsWith("chapters/") || !clean.endsWith(".md")) throw new Error("Chapter path must be a Markdown file under chapters/.");
+  return clean;
+}
+
+function safeReportPath(path) {
+  const clean = safeRelativePath(path);
+  const reportPrefix = reportPathPrefix(clean);
+  if (clean.includes("\\") || !reportPrefix || !clean.endsWith(".md")) {
+    throw new Error("Report path must be a Markdown file under .cowriter/reports/.");
+  }
+  const name = clean.slice(reportPrefix.length);
+  if (!name || name.includes("/")) throw new Error("Report path must point directly under .cowriter/reports/.");
+  return clean;
+}
+
+function reportPathPrefix(path) {
+  for (const prefix of [".cowriter/reports/", ".ghostwriter/reports/"]) {
+    if (path.startsWith(prefix)) return prefix;
+  }
+  return null;
+}
+
+function projectMetadataPath(root) {
+  const current = join(root, projectStateDir, "project.yaml");
+  if (existsSync(current)) return current;
+  const legacy = join(root, legacyProjectStateDir, "project.yaml");
+  return existsSync(legacy) ? legacy : current;
+}
+
+function gitStatus(root) {
+  try {
+    const status = runGit(root, ["status", "--short"]);
+    const changedPaths = status.split("\n").map((line) => line.slice(3).trim()).filter(Boolean);
+    let lastCommit;
+    let lastCommitAt;
+    try {
+      lastCommit = runGit(root, ["log", "-1", "--pretty=%s"]);
+      lastCommitAt = runGit(root, ["log", "-1", "--pretty=%cI"]);
+    } catch {}
+    return { dirty: changedPaths.length > 0, changedPaths, lastCommit, lastCommitAt };
+  } catch {
+    return { dirty: true, changedPaths: [], lastCommit: "Git status unavailable" };
+  }
+}
+
+function materializeProject(project) {
+  const templatePaths = [
+    "chapters/001-opening.md",
+    "story.yaml",
+    "characters/primary-character.yaml",
+    "outline.yaml",
+    `${projectStateDir}/project.yaml`,
+    `${projectStateDir}/reports/.gitkeep`,
+  ];
+  writeRenderedTemplates(project.path, templatePaths, initTemplateContext(project));
+  commitBookFiles(project.path, ["chapters", "characters", "story.yaml", "outline.yaml", `${projectStateDir}/project.yaml`, `${projectStateDir}/reports/.gitkeep`], "Create Cowriter book");
+}
+
+function projectInstructionBlock() {
+  return `<!-- cowriter-instructions:start -->
+## Cowriter Runtime Instructions
+
+Codex should edit Cowriter book files directly:
+
+- \`chapters/*.md\` for manuscript chapters.
+- \`story.yaml\` for title, synopsis, setting, themes, genre, tone, perspective, and continuity.
+- \`characters/*.yaml\` for character records.
+- \`outline.yaml\` for outline beats.
+
+Save approved changes as you go. Do not wait until the end of the conversation to write accepted manuscript or story-material changes. The localhost Cowriter workspace watches these files and refreshes automatically.
+
+Ask one onboarding question at a time. Wait for the writer's answer before asking the next question; do not bundle premise, protagonist, setting, ending, and folder questions into one turn unless the writer explicitly asks for a checklist.
+
+If the localhost Cowriter workspace is not open in Codex Browser, or it is open on a different port, tell the writer to run \`npx cowriter serve --open\` from the book folder and open the reported localhost URL. Do not start the long-running serve process yourself unless the writer explicitly asks.
+
+The workspace publishes current manuscript selection context for the served book. If the writer asks about selected text and that text is not already available in chat or file context, use the selection API when it would materially improve the response:
+
+\`\`\`sh
+curl -sS "$COWRITER_URL/api/cowriter/selection"
+\`\`\`
+
+The response includes \`selection.selectedText\`, chapter metadata, range, surrounding text, and \`updatedAt\`, or \`selection: null\` when nothing useful is selected. Treat the endpoint as optional context, not a required step for every request.
+
+When discussing a specific manuscript passage with the writer, call the Cowriter highlight API so the web UI selects that passage. Derive \`COWRITER_URL\` from \`cowriter info -o json\` at \`app.url\`, then call:
+
+\`\`\`sh
+curl -sS -X POST "$COWRITER_URL/api/cowriter/codex" \\
+  -H 'content-type: application/json' \\
+  --data '{"command":"highlight","text":"exact passage text","chapterPath":"chapters/001-opening.md"}'
+\`\`\`
+
+Use \`occurrence\` when the same passage appears more than once. If the UI is not open or the passage is not found, continue the writing conversation normally.
+
+Commit at sensible creative checkpoints: after accepted onboarding material, a scene/chapter draft or revision pass, a stable continuity/story-bible update, before switching task types, and before pausing or ending a work session. Before committing, run \`git status --short\`, review the relevant diff, and stage only Cowriter book files for the completed writing unit.
+
+Serve the localhost workspace with:
+
+\`\`\`sh
+npx cowriter serve --open
+\`\`\`
+
+Refresh installed Cowriter skills with:
+
+\`\`\`sh
+npx cowriter upgrade
+\`\`\`
+<!-- cowriter-instructions:end -->`;
+}
+
+function installProjectSkill(root) {
+  const templatePrefix = projectSkillDir;
+  const templatePaths = listTemplateFiles(join(initTemplateRoot, templatePrefix)).map((path) => `${templatePrefix}/${path}`);
+  writeRenderedTemplates(root, templatePaths, {});
+}
+
+function writeProjectInstructions(root, { updateExisting = false } = {}) {
+  const agentsPath = join(root, "AGENTS.md");
+  if (!existsSync(agentsPath)) {
+    writeRenderedTemplate(root, "AGENTS.md", {});
+  } else if (updateExisting) {
+    const current = readFileSync(agentsPath, "utf8");
+    const block = projectInstructionBlock();
+    const start = "<!-- cowriter-instructions:start -->";
+    const end = "<!-- cowriter-instructions:end -->";
+    const legacyStart = "<!-- ghostwriter-instructions:start -->";
+    const legacyEnd = "<!-- ghostwriter-instructions:end -->";
+    const next = current.includes(start) && current.includes(end)
+      ? current.replace(new RegExp(`${start}[\\s\\S]*?${end}`), block)
+      : current.includes(legacyStart) && current.includes(legacyEnd)
+        ? current.replace(new RegExp(`${legacyStart}[\\s\\S]*?${legacyEnd}`), block)
+        : `${current.trimEnd()}\n\n${block}\n`;
+    writeFileSync(agentsPath, next, "utf8");
+  }
+  installProjectSkill(root);
+}
+
+function reportFallback(root, baseDir, name) {
+  const path = `${baseDir}/${name}`;
+  let createdAt = new Date().toISOString();
+  try {
+    createdAt = statSync(join(root, path)).mtime.toISOString();
+  } catch {}
+  return {
+    id: name.replace(/\.md$/, ""),
+    path,
+    type: "report",
+    title: titleFromId(name),
+    status: "unknown",
+    createdAt,
+  };
+}
+
+function parseReportFrontmatter(markdown) {
+  const text = String(markdown ?? "");
+  if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) return {};
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return {};
+  const parsed = YAML.parse(match[1]);
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+
+function listReports(root) {
+  return [
+    { absolute: join(root, projectStateDir, "reports"), relative: `${projectStateDir}/reports` },
+    { absolute: join(root, legacyProjectStateDir, "reports"), relative: `${legacyProjectStateDir}/reports` },
+  ].flatMap(({ absolute, relative }) => {
+    if (!existsSync(absolute)) return [];
+    return readdirSync(absolute, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".md") && !/[\\/]/.test(entry.name))
+      .flatMap((entry) => {
+        const fallback = reportFallback(root, relative, entry.name);
+        try {
+          const frontmatter = parseReportFrontmatter(readFileSync(join(absolute, entry.name), "utf8"));
+          return [{
+            ...fallback,
+            type: typeof frontmatter.type === "string" && frontmatter.type.trim() ? frontmatter.type : fallback.type,
+            title: typeof frontmatter.title === "string" && frontmatter.title.trim() ? frontmatter.title : fallback.title,
+            status: typeof frontmatter.status === "string" && frontmatter.status.trim() ? frontmatter.status : fallback.status,
+            createdAt: typeof frontmatter.createdAt === "string" && frontmatter.createdAt.trim() ? frontmatter.createdAt : fallback.createdAt,
+            ...(typeof frontmatter.chapter === "string" && frontmatter.chapter.trim() ? { chapter: frontmatter.chapter } : {}),
+          }];
+        } catch {
+          return [fallback];
+        }
+      });
+  })
+    .sort((left, right) => {
+      const dateDelta = (Date.parse(right.createdAt) || 0) - (Date.parse(left.createdAt) || 0);
+      return dateDelta || left.path.localeCompare(right.path);
+    });
+}
+
+function wordsFromText(text) {
+  return String(text ?? "").toLowerCase().match(/[a-z0-9]+(?:'[a-z0-9]+)?/g) ?? [];
+}
+
+function sentencesFromText(text) {
+  return String(text ?? "")
+    .replace(/\s+/g, " ")
+    .split(/(?<=[.!?])\s+/)
+    .map((sentence) => sentence.trim())
+    .filter((sentence) => wordsFromText(sentence).length > 0);
+}
+
+function paragraphsFromMarkdown(markdown) {
+  return String(markdown ?? "")
+    .split(/\n\s*\n/)
+    .map((paragraph) => plainTextFromMarkdown(paragraph))
+    .filter(Boolean);
+}
+
+function roundMetric(value) {
+  return Number.isFinite(value) ? Number(value.toFixed(2)) : 0;
+}
+
+function dialogueWordCount(text) {
+  const matches = String(text ?? "").match(/["“][^"”]+["”]/g) ?? [];
+  return matches.reduce((count, quote) => count + wordsFromText(quote).length, 0);
+}
+
+function addFinding(findings, severity, code, message, details = {}) {
+  findings.push({ severity, code, message, ...details });
+}
+
+function diagnoseProse(chapterPath, markdown) {
+  const plainText = plainTextFromMarkdown(markdown);
+  if (!plainText) {
+    return {
+      chapterPath,
+      metrics: {
+        wordCount: 0,
+        paragraphCount: 0,
+        sentenceCount: 0,
+        dialoguePercent: 0,
+        averageSentenceWords: 0,
+        emDashCount: 0,
+      },
+      findings: [],
+    };
+  }
+
+  const words = wordsFromText(plainText);
+  const paragraphs = paragraphsFromMarkdown(markdown);
+  const sentences = sentencesFromText(plainText);
+  const sentenceWordCounts = sentences.map((sentence) => wordsFromText(sentence).length).filter((count) => count > 0);
+  const wordCount = words.length;
+  const sentenceCount = sentenceWordCounts.length;
+  const averageSentenceWords = sentenceCount ? sentenceWordCounts.reduce((sum, count) => sum + count, 0) / sentenceCount : 0;
+  const emDashCount = (String(markdown ?? "").match(/—/g) ?? []).length;
+  const metrics = {
+    wordCount,
+    paragraphCount: paragraphs.length,
+    sentenceCount,
+    dialoguePercent: wordCount ? roundMetric((dialogueWordCount(markdown) / wordCount) * 100) : 0,
+    averageSentenceWords: roundMetric(averageSentenceWords),
+    emDashCount,
+  };
+  const findings = [];
+
+  paragraphs.forEach((paragraph, index) => {
+    const paragraphWordCount = wordsFromText(paragraph).length;
+    if (paragraphWordCount > 120) {
+      addFinding(findings, "warning", "long-paragraph", `Paragraph ${index + 1} is ${paragraphWordCount} words.`, { paragraph: index + 1, wordCount: paragraphWordCount });
+    }
+  });
+
+  const repeated = new Map();
+  for (let index = 0; index < words.length; index += 1) {
+    const word = words[index];
+    if (word.length < 4 || repeatedWordStopWords.has(word)) continue;
+    for (let lookback = Math.max(0, index - 8); lookback < index; lookback += 1) {
+      if (words[lookback] === word) {
+        repeated.set(word, (repeated.get(word) ?? 0) + 1);
+        break;
+      }
+    }
+  }
+  Array.from(repeated.entries())
+    .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+    .slice(0, 10)
+    .forEach(([word, count]) => addFinding(findings, "info", "repeated-word", `"${word}" repeats within nearby wording ${count} time${count === 1 ? "" : "s"}.`, { word, count }));
+
+  if (sentenceWordCounts.length >= 5) {
+    const variance = sentenceWordCounts.reduce((sum, count) => sum + ((count - averageSentenceWords) ** 2), 0) / sentenceWordCounts.length;
+    const coefficient = Math.sqrt(variance) / averageSentenceWords;
+    if (coefficient < 0.18) {
+      addFinding(findings, "info", "uniform-sentence-rhythm", "Sentence lengths are unusually uniform across this passage.", { variation: roundMetric(coefficient) });
+    }
+  }
+
+  if (wordCount >= 300 && metrics.dialoguePercent < 10) {
+    addFinding(findings, "info", "low-dialogue-ratio", `Dialogue is ${metrics.dialoguePercent}% of the chapter.`, { dialoguePercent: metrics.dialoguePercent });
+  }
+  if (wordCount >= 300 && metrics.dialoguePercent > 70) {
+    addFinding(findings, "warning", "high-dialogue-ratio", `Dialogue is ${metrics.dialoguePercent}% of the chapter.`, { dialoguePercent: metrics.dialoguePercent });
+  }
+
+  const lowerText = plainText.toLowerCase();
+  for (const term of fillerTerms) {
+    const matches = lowerText.match(new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g"));
+    if (matches?.length) addFinding(findings, "info", "filler-term", `"${term}" appears ${matches.length} time${matches.length === 1 ? "" : "s"}.`, { term, count: matches.length });
+  }
+
+  const hasStraightQuotes = /"/.test(markdown);
+  const hasCurlyQuotes = /[“”]/.test(markdown);
+  if (hasStraightQuotes && hasCurlyQuotes) {
+    addFinding(findings, "warning", "mixed-quotes", "Straight and curly double quotes are both present.");
+  }
+
+  if (wordCount > 0 && (emDashCount / wordCount) * 1000 > 4) {
+    addFinding(findings, "warning", "em-dash-density", `${emDashCount} em dashes appear in ${wordCount} words.`, { emDashCount, perThousandWords: roundMetric((emDashCount / wordCount) * 1000) });
+  }
+
+  return { chapterPath, metrics, findings };
+}
+
+function reportStatus(findings) {
+  if (findings.some((finding) => finding.severity === "issue")) return "issues";
+  if (findings.some((finding) => finding.severity === "warning")) return "warnings";
+  return "info";
+}
+
+function compactTimestamp(date) {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "").replace("T", "-");
+}
+
+function renderProseDiagnosticsReport(diagnostics, createdAt) {
+  const status = reportStatus(diagnostics.findings);
+  const title = `Prose diagnostics: ${titleFromId(diagnostics.chapterPath.split("/").at(-1) ?? "chapter")}`;
+  const lines = [
+    "---",
+    "type: prose-diagnostics",
+    `title: ${JSON.stringify(title)}`,
+    `status: ${status}`,
+    `createdAt: ${createdAt}`,
+    `chapter: ${diagnostics.chapterPath}`,
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    "## Metrics",
+    "",
+    `- Word count: ${diagnostics.metrics.wordCount}`,
+    `- Paragraph count: ${diagnostics.metrics.paragraphCount}`,
+    `- Sentence count: ${diagnostics.metrics.sentenceCount}`,
+    `- Dialogue: ${diagnostics.metrics.dialoguePercent}%`,
+    `- Average sentence length: ${diagnostics.metrics.averageSentenceWords} words`,
+    `- Em dashes: ${diagnostics.metrics.emDashCount}`,
+    "",
+    "## Findings",
+    "",
+    diagnostics.findings.length ? diagnostics.findings.map((finding) => `- **${finding.severity}** \`${finding.code}\`: ${finding.message}`).join("\n") : "- No findings.",
+    "",
+  ];
+  return lines.join("\n");
+}
+
+function writeProseDiagnosticsReport(root, diagnostics) {
+  const now = new Date();
+  const createdAt = now.toISOString();
+  const reportsRoot = join(root, projectStateDir, "reports");
+  ensureDir(reportsRoot);
+  const chapterId = diagnostics.chapterPath.split("/").at(-1).replace(/\.md$/, "");
+  const filename = `${compactTimestamp(now)}-prose-${chapterId}.md`;
+  const reportPath = `${projectStateDir}/reports/${filename}`;
+  writeFileSync(join(root, reportPath), renderProseDiagnosticsReport(diagnostics, createdAt), "utf8");
+  return reportPath;
+}
+
+function diagnoseProseChapter(root, flags) {
+  const chapterPath = safeChapterPath(flags.chapter);
+  const absoluteChapterPath = join(root, chapterPath);
+  if (!existsSync(absoluteChapterPath)) throw new Error(`Chapter does not exist: ${chapterPath}`);
+  const diagnostics = diagnoseProse(chapterPath, readFileSync(absoluteChapterPath, "utf8"));
+  const result = { diagnostics };
+  if (flags["write-report"] || flags.writeReport) result.reportPath = writeProseDiagnosticsReport(root, diagnostics);
+  return result;
+}
+
+function findCoverImage(root) {
+  if (!existsSync(root)) return null;
+  const names = new Map(readdirSync(root).map((name) => [name.toLowerCase(), name]));
+  for (const preferredName of coverFilenamesByPreference) {
+    const path = names.get(preferredName);
+    if (!path) continue;
+
+    const extension = extname(path).toLowerCase();
+    const contentType = coverContentTypes[extension];
+    if (!contentType) continue;
+
+    const stats = statSync(join(root, path));
+    if (!stats.isFile()) continue;
+
+    return {
+      path,
+      contentType,
+      updatedAt: new Date(stats.mtimeMs).toISOString(),
+    };
+  }
+  return null;
+}
+
+function loadProject(root) {
+  const metadata = readYaml(projectMetadataPath(root), {
+    title: "Untitled Book",
+    author: defaultAuthorName(),
+    createdAt: new Date().toISOString(),
+  });
+  const story = readYaml(join(root, "story.yaml"), starterProject(root, metadata.title).story);
+  const outlineYaml = readYaml(join(root, "outline.yaml"), { beats: starterProject(root, metadata.title).outline });
+  const chapterNames = existsSync(join(root, "chapters"))
+    ? readdirSync(join(root, "chapters")).filter((name) => name.endsWith(".md")).sort()
+    : [];
+  const chapters = chapterNames.map((name) => {
+    const id = name.replace(/\.md$/, "");
+    return {
+      id,
+      title: titleFromId(id),
+      path: `chapters/${name}`,
+      markdown: readFileSync(join(root, "chapters", name), "utf8"),
+      updatedAt: new Date().toISOString(),
+    };
+  });
+  const characterNames = existsSync(join(root, "characters"))
+    ? readdirSync(join(root, "characters")).filter((name) => name.endsWith(".yaml")).sort()
+    : [];
+  const characters = characterNames.map((name) => readYaml(join(root, "characters", name), {}));
+  return {
+    path: root,
+    metadata,
+    activeChapterId: chapters[0]?.id ?? "001-opening",
+    chapters: chapters.length ? chapters : starterProject(root, metadata.title).chapters,
+    story,
+    characters: characters.length ? characters : starterProject(root, metadata.title).characters,
+    outline: outlineYaml.beats ?? [],
+    cover: findCoverImage(root),
+    reports: listReports(root),
+    git: gitStatus(root),
+  };
+}
+
+function readReport(root, reportPath) {
+  const path = safeReportPath(reportPath);
+  const absolutePath = join(root, path);
+  if (!existsSync(absolutePath)) throw new Error(`Report does not exist: ${path}`);
+  return {
+    path,
+    markdown: readFileSync(absolutePath, "utf8"),
+  };
+}
+
+function writeChapter(root, chapter) {
+  const id = safeId(chapter.id, "chapter id");
+  const path = `chapters/${id}.md`;
+  ensureDir(join(root, "chapters"));
+  writeFileSync(join(root, path), String(chapter.markdown ?? ""), "utf8");
+  return path;
+}
+
+function writeStory(root, story) {
+  const project = loadProject(root);
+  writeYaml(join(root, "story.yaml"), { ...project.story, ...validateStoryFields(story) });
+  return "story.yaml";
+}
+
+function writeCharacters(root, characters) {
+  ensureDir(join(root, "characters"));
+  const paths = [];
+  for (const character of characters ?? []) {
+    const id = safeId(character.id, "character id");
+    writeYaml(join(root, "characters", `${id}.yaml`), {
+      id,
+      name: String(character.name ?? ""),
+      role: String(character.role ?? ""),
+      desire: String(character.desire ?? ""),
+      conflict: String(character.conflict ?? ""),
+      notes: String(character.notes ?? ""),
+    });
+    paths.push(`characters/${id}.yaml`);
+  }
+  return paths;
+}
+
+function writeOutline(root, outline) {
+  const beats = (outline ?? []).map((beat) => ({
+    id: safeId(beat.id, "outline beat id"),
+    title: String(beat.title ?? ""),
+    summary: String(beat.summary ?? ""),
+  }));
+  writeYaml(join(root, "outline.yaml"), { beats });
+  return "outline.yaml";
+}
+
+function plainTextFromMarkdown(markdown) {
+  return String(markdown ?? "")
+    .replace(/^[ \t]*\|?[ \t]*:?-{3,}:?[ \t]*(\|[ \t]*:?-{3,}:?[ \t]*)+\|?[ \t]*$(?:\r?\n)?/gm, "")
+    .replace(/^[ \t]*\|(.+)\|[ \t]*$/gm, (_row, cells) => cells.split("|").map((cell) => cell.trim()).filter(Boolean).join(" "))
+    .replace(/^#{1,6}\s+/gm, "")
+    .replace(/^>[ \t]?/gm, "")
+    .replace(/[*_`>#|-]/g, "")
+    .replace(/\[(.*?)\]\(.*?\)/g, "$1")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function isBookEmpty(project) {
+  const hasManuscript = project.chapters.some((chapter) => {
+    const text = plainTextFromMarkdown(chapter.markdown);
+    return text.length > 0 && text !== legacyStarterChapterText;
+  });
+  const synopsis = String(project.story.synopsis ?? "").trim();
+  const hasSynopsis = synopsis.length > 0 && synopsis !== starterSynopsis && synopsis !== legacyStarterSynopsis;
+  return !hasManuscript && !hasSynopsis;
+}
+
+function nextWritingTaskPrompt(project) {
+  if (isBookEmpty(project)) return "";
+  const synopsis = String(project.story.synopsis ?? "").trim();
+  if (!synopsis || synopsis === legacyStarterSynopsis) return "Write a rough synopsis so the manuscript has a clear dramatic promise.";
+  const hasManuscript = project.chapters.some((chapter) => plainTextFromMarkdown(chapter.markdown).length > 0);
+  if (!hasManuscript) return "Draft the opening page from the synopsis.";
+  return "Choose the next passage, scene beat, or story-bible note to develop.";
+}
+
+function summarizeProject(project) {
+  const activeChapter = project.chapters.find((chapter) => chapter.id === project.activeChapterId) ?? project.chapters[0];
+  return {
+    path: project.path,
+    title: project.metadata.title,
+    bookIsEmpty: isBookEmpty(project),
+    nextWritingTask: nextWritingTaskPrompt(project),
+    story: project.story,
+    cover: project.cover,
+    chapters: project.chapters.map((chapter) => ({
+      id: chapter.id,
+      title: chapter.title,
+      path: chapter.path,
+      wordCount: plainTextFromMarkdown(chapter.markdown).split(/\s+/).filter(Boolean).length,
+      updatedAt: chapter.updatedAt,
+    })),
+    activeChapter: activeChapter
+      ? {
+          id: activeChapter.id,
+          title: activeChapter.title,
+          path: activeChapter.path,
+          excerpt: plainTextFromMarkdown(activeChapter.markdown).slice(0, 1200),
+        }
+      : null,
+    characterCount: project.characters.length,
+    outlineBeatCount: project.outline.length,
+    reports: project.reports,
+    git: project.git,
+  };
+}
+
+function validateStoryFields(fields) {
+  const allowed = new Set(["title", "synopsis", "setting", "themes", "genre", "tone", "perspective", "continuity"]);
+  return Object.fromEntries(Object.entries(fields ?? {}).filter(([key, value]) => allowed.has(key) && typeof value === "string"));
+}
+
+function samePath(left, right) {
+  if (!left || !right) return false;
+  try {
+    return realpathSync(left) === realpathSync(right);
+  } catch {
+    return resolve(left) === resolve(right);
+  }
+}
+
+async function cowriterServerInfo(port) {
+  try {
+    const response = await fetch(`http://localhost:${port}/api/cowriter`, {
+      method: "GET",
+      signal: AbortSignal.timeout(500),
+    });
+    if (!response.ok) return null;
+    const json = await response.json();
+    return {
+      projectPath: typeof json?.activeProject?.path === "string" ? json.activeProject.path : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function portAvailable(port) {
+  return new Promise((resolvePromise) => {
+    const server = createServer();
+    server.unref();
+    server.on("error", () => resolvePromise(false));
+    server.listen({ port, host: "127.0.0.1" }, () => {
+      server.close(() => resolvePromise(true));
+    });
+  });
+}
+
+async function chooseServePort(preferredPort, projectPath) {
+  for (let offset = 0; offset < 100; offset += 1) {
+    const port = preferredPort + offset;
+    const runningServer = await cowriterServerInfo(port);
+    if (runningServer) {
+      if (samePath(runningServer.projectPath, projectPath)) return { port, alreadyRunning: true };
+      continue;
+    }
+    if (await portAvailable(port)) return { port, alreadyRunning: false };
+  }
+  throw new Error(`No available Cowriter port found starting at ${preferredPort}.`);
+}
+
+async function waitForServer(port, projectPath, timeoutMs = 12000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const runningServer = await cowriterServerInfo(port);
+    if (runningServer && samePath(runningServer.projectPath, projectPath)) return true;
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, 350));
+  }
+  return false;
+}
+
+async function findRunningProjectPort(preferredPort, projectPath) {
+  for (let offset = 0; offset < 100; offset += 1) {
+    const port = preferredPort + offset;
+    const runningServer = await cowriterServerInfo(port);
+    if (runningServer && samePath(runningServer.projectPath, projectPath)) return port;
+  }
+  return null;
+}
+
+function nextBinPath() {
+  if (process.env.COWRITER_NEXT_BIN) return process.env.COWRITER_NEXT_BIN;
+  if (process.env.GHOSTWRITER_NEXT_BIN) return process.env.GHOSTWRITER_NEXT_BIN;
+  return require.resolve("next/dist/bin/next");
+}
+
+function runForegroundServer(port, root) {
+  const child = spawn(process.execPath, [nextBinPath(), "dev", "--port", String(port)], {
+    cwd: frontendRoot,
+    detached: false,
+    env: { ...process.env, COWRITER_PROJECT_PATH: root, GHOSTWRITER_PROJECT_PATH: root },
+    stdio: "inherit",
+  });
+  return new Promise((resolvePromise, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (typeof code === "number") {
+        process.exitCode = code;
+      } else if (signal === "SIGINT") {
+        process.exitCode = 130;
+      } else if (signal) {
+        process.exitCode = 1;
+      }
+      resolvePromise();
+    });
+  });
+}
+
+function attachForegroundServer(result, port, root) {
+  Object.defineProperty(result, "runForegroundServer", {
+    enumerable: false,
+    value: () => runForegroundServer(port, root),
+  });
+  return result;
+}
+
+function preferredPort(flags) {
+  if (flags.port) return Number(flags.port);
+  return defaultPort;
+}
+
+function serveMessage(project) {
+  const base = "now open codex at this project: open -a Codex .";
+  return project.bookIsEmpty ? base : `${base} and tell it: how should we begin?`;
+}
+
+function openCodexProject(root) {
+  if (process.env.COWRITER_SKIP_CODEX_OPEN === "1" || process.env.GHOSTWRITER_SKIP_CODEX_OPEN === "1") return { requested: true, opened: false, skipped: true };
+  const result = spawnSync("open", ["-a", "Codex", "."], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.trim() || "Unable to open Codex.");
+  }
+  return { requested: true, opened: true, skipped: false };
+}
+
+async function handle(command, flags) {
+  const port = preferredPort(flags);
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    return {
+      message: "cowriter commands: info, serve, init, upgrade, inspect, diagnose",
+      commands: ["info", "serve", "init", "upgrade", "inspect", "diagnose"],
+    };
+  }
+
+  if (command === "info") {
+    const root = expandPath(flags.path ?? flags._?.[0] ?? process.cwd());
+    if (!existsSync(root)) throw new Error(`Project does not exist: ${root}`);
+    const runningPort = await findRunningProjectPort(port, root);
+    const appPort = runningPort ?? port;
+    return {
+      cli: { name: "cowriter", version: "0.1.0" },
+      app: { url: `http://localhost:${appPort}`, port: appPort, running: runningPort !== null },
+      activeProject: summarizeProject(loadProject(root)),
+    };
+  }
+
+  if (command === "serve") {
+    const root = expandPath(flags.path ?? flags._?.[0] ?? process.cwd());
+    if (root && !existsSync(root)) throw new Error(`Project does not exist: ${root}`);
+    const servePort = await chooseServePort(port, root);
+    const serveUrl = `http://localhost:${servePort.port}`;
+    const skipServer = process.env.COWRITER_SKIP_SERVER === "1" || process.env.GHOSTWRITER_SKIP_SERVER === "1";
+    const running = !skipServer && servePort.alreadyRunning;
+    const project = root ? summarizeProject(loadProject(root)) : null;
+    const codexOpen = root && flags.open ? openCodexProject(root) : { requested: false, opened: false, skipped: false };
+    const result = {
+      app: { url: serveUrl, port: servePort.port, running },
+      project,
+      codex: {
+        command: "open -a Codex .",
+        prompt: project && !project.bookIsEmpty ? "how should we begin?" : null,
+        ...codexOpen,
+      },
+      message: project ? serveMessage(project) : running ? `Cowriter is running at ${serveUrl}` : `Cowriter is starting at ${serveUrl}`,
+    };
+    return !skipServer && !servePort.alreadyRunning ? attachForegroundServer(result, servePort.port, root) : result;
+  }
+
+  if (command === "init") {
+    const root = expandPath(flags.path ?? flags._?.[0] ?? process.cwd());
+    const title = flags.title ?? titleFromId(root.split(/[\\/]/).filter(Boolean).at(-1) ?? "Untitled Book");
+    const project = starterProject(root, title, flags.synopsis);
+    materializeProject(project);
+    writeProjectInstructions(root);
+    commitBookFiles(root, ["AGENTS.md", ".codex"], "Install Cowriter Codex skills");
+    return {
+      project: summarizeProject(loadProject(root)),
+      skillPath: join(root, ".codex", "skills", "cowriter", "SKILL.md"),
+      message: `Initialized Cowriter book at ${root}`,
+    };
+  }
+
+  if (command === "upgrade") {
+    const root = expandPath(flags.path ?? flags._?.[0] ?? process.cwd());
+    if (!existsSync(root)) throw new Error(`Project does not exist: ${root}`);
+    writeProjectInstructions(root, { updateExisting: true });
+    const committed = commitBookFiles(root, ["AGENTS.md", ".codex"], "Upgrade Cowriter Codex skills");
+    return {
+      committed,
+      project: summarizeProject(loadProject(root)),
+      skillPath: join(root, ".codex", "skills", "cowriter", "SKILL.md"),
+      message: `Updated Cowriter skills at ${root}`,
+    };
+  }
+
+  if (command === "inspect") {
+    const root = expandPath(flags.path ?? flags._?.[0] ?? process.cwd());
+    if (!existsSync(root)) throw new Error(`Project does not exist: ${root}`);
+    return { project: summarizeProject(loadProject(root)) };
+  }
+
+  if (command === "diagnose") {
+    const [subcommand] = flags._ ?? [];
+    if (subcommand !== "prose") throw new Error("Unknown diagnose command. Expected: diagnose prose");
+    const root = expandPath(flags.path ?? process.cwd());
+    if (!existsSync(root)) throw new Error(`Project does not exist: ${root}`);
+    return diagnoseProseChapter(root, flags);
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+export {
+  findCoverImage,
+  gitStatus,
+  handle,
+  isBookEmpty,
+  loadProject,
+  materializeProject,
+  nextWritingTaskPrompt,
+  readReport,
+  starterProject,
+  summarizeProject,
+  writeCharacters,
+  writeChapter,
+  writeOutline,
+  writeStory,
+};
+
+if (isCli) {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  handle(command, flags)
+    .then(async (value) => {
+      output(value, flags);
+      if (typeof value?.runForegroundServer === "function") await value.runForegroundServer();
+    })
+    .catch((error) => fail(error, flags));
+}