cowriter 0.1.0

package/README.md

@@ -0,0 +1,283 @@
+![Cowriter header](assets/cowriter-header.png)
+
+# `cowriter`
+
+A local Codex.app workspace for writing long-form stories in Markdown, YAML, and git.
+
+> [!NOTE]
+> Codex.app owns the conversation. Cowriter serves the book: manuscript pages,
+> story materials, selection context, and local files Codex can edit directly.
+
+## Quickstart
+
+```sh
+$ mkdir my-book
+$ cd my-book
+$ npx cowriter@latest init
+Initialized Cowriter book at /Users/you/my-book
+
+$ npx cowriter@latest serve --open
+now open codex at this project: open -a Codex .
+▲ Next.js ...
+- Local:         http://localhost:47891
+```
+
+`serve --open` hosts the current book folder and runs `open -a Codex .` from
+that folder. In Codex, ask for the next writing move, a synopsis pass, a
+selected-text rewrite, a continuity check, or whatever the book actually needs.
+
+> [!IMPORTANT]
+> `--open` is intentionally macOS/Codex.app shaped. Without Codex.app, you still
+> have a local book folder and localhost UI, but not the intended collaborator.
+
+## Start With a Synopsis
+
+Cowriter does not make you fill out a giant story bible before you can write.
+Give it a rough promise for the book and start from there.
+
+```sh
+$ npx cowriter init \
+  --path /Users/you/the-local-draft \
+  --title "The Local Draft" \
+  --synopsis "A cartographer returns to a city that has erased her street." \
+  -o json
+{
+  "project": {
+    "title": "The Local Draft",
+    "bookIsEmpty": false,
+    "nextWritingTask": "Draft the opening page from the synopsis."
+  },
+  "message": "Initialized Cowriter book at /Users/you/the-local-draft"
+}
+```
+
+The first useful thing is usually a one-paragraph synopsis. Characters,
+continuity, outline beats, tone, setting, and perspective can grow from the
+draft instead of blocking it.
+
+## The Book Folder Is the API
+
+`cowriter init` creates a normal local project:
+
+```txt
+my-book/
+  AGENTS.md
+  chapters/
+    001-opening.md
+  characters/
+    primary-character.yaml
+  story.yaml
+  outline.yaml
+  .cowriter/
+    project.yaml
+    reports/
+      .gitkeep
+  .codex/
+    skills/
+      cowriter/
+        SKILL.md
+```
+
+The durable writing state is plain files:
+
+- `chapters/*.md` is the manuscript.
+- `story.yaml` is title, synopsis, setting, themes, genre, tone, perspective,
+  and continuity.
+- `characters/*.yaml` is character role, desire, conflict, and notes.
+- `outline.yaml` is scene and structure planning.
+- `.cowriter/project.yaml` is project metadata.
+- `.cowriter/reports/*.md` is optional review output, not manuscript source.
+
+Codex edits those files. The web workspace watches them and refreshes. This is
+the whole trick, and it is a good trick.
+
+## Serve One Book
+
+```sh
+$ npx cowriter serve --path /Users/you/Writing/my-book --open -o json
+{
+  "app": {
+    "url": "http://localhost:47891",
+    "port": 47891,
+    "running": false
+  },
+  "codex": {
+    "command": "open -a Codex .",
+    "prompt": "how should we begin?"
+  },
+  "message": "now open codex at this project: open -a Codex . and tell it: how should we begin?"
+}
+```
+
+Each `serve` process is bound to one book folder. It chooses an available port
+starting at `47891`; if another Cowriter project is already there, it moves
+to the next port.
+
+Run one server per book. No global daemon. No hidden cloud state.
+
+## Ask Codex From the Book
+
+Every initialized book includes project-local Codex instructions and the
+Cowriter skill under `.codex/skills/cowriter`.
+
+Useful prompts look like this:
+
+```text
+$cowriter inspect this book and suggest the next writing task
+$cowriter help me turn this synopsis into a sharper story bible
+$cowriter rewrite the selected passage with stronger rhythm
+$cowriter review continuity for the current chapter
+$cowriter plan the next scene beat
+```
+
+The skill prefers direct file edits once you approve a change. If you select
+manuscript text in the web workspace, Codex can read the selection context from
+localhost and highlight discussed passages back in the UI.
+
+## Inspect the Project
+
+Use JSON when scripting or when Codex needs exact context.
+
+```sh
+$ npx cowriter inspect --path /Users/you/Writing/my-book -o json
+{
+  "project": {
+    "title": "The Local Draft",
+    "bookIsEmpty": false,
+    "nextWritingTask": "Draft the opening page from the synopsis.",
+    "chapters": [
+      {
+        "title": "Opening",
+        "path": "chapters/001-opening.md",
+        "wordCount": 0
+      }
+    ],
+    "characterCount": 1,
+    "outlineBeatCount": 1,
+    "reports": []
+  }
+}
+```
+
+`info` is similar, but also tells you which localhost URL should represent the
+book:
+
+```sh
+$ npx cowriter info -o json
+{
+  "cli": { "name": "cowriter", "version": "0.1.0" },
+  "app": { "url": "http://localhost:47891", "running": false }
+}
+```
+
+## Local Prose Diagnostics
+
+Diagnostics are deterministic and chapter-level. They do not rewrite your prose.
+
+```sh
+$ npx cowriter diagnose prose \
+  --path /Users/you/Writing/my-book \
+  --chapter chapters/001-opening.md \
+  -o json
+{
+  "diagnostics": {
+    "metrics": {
+      "wordCount": 0,
+      "paragraphCount": 0,
+      "sentenceCount": 0,
+      "dialoguePercent": 0,
+      "averageSentenceWords": 0,
+      "emDashCount": 0
+    },
+    "findings": []
+  }
+}
+```
+
+It checks repetition, long paragraphs, sentence rhythm, dialogue percentage,
+filler or AI-ish terms, mixed quote styles, and em dash density.
+
+Save a report only when you want an artifact:
+
+```sh
+$ npx cowriter diagnose prose \
+  --path /Users/you/Writing/my-book \
+  --chapter chapters/001-opening.md \
+  --write-report \
+  -o json
+{
+  "reportPath": ".cowriter/reports/20260518-092627-prose-001-opening.md"
+}
+```
+
+## Commands
+
+```sh
+$ npx cowriter help -o json
+{
+  "message": "cowriter commands: info, serve, init, upgrade, inspect, diagnose",
+  "commands": ["info", "serve", "init", "upgrade", "inspect", "diagnose"]
+}
+```
+
+The common forms:
+
+```sh
+npx cowriter init
+npx cowriter init --path /absolute/path/to/book --title "Working Title"
+npx cowriter --help
+npx cowriter serve --path /absolute/path/to/book --open
+npx cowriter info --path /absolute/path/to/book -o json
+npx cowriter inspect --path /absolute/path/to/book -o json
+npx cowriter upgrade --path /absolute/path/to/book -o json
+npx cowriter diagnose prose --path /absolute/path/to/book --chapter chapters/001-opening.md -o json
+```
+
+## Package Shape
+
+The npm package ships the CLI, the bundled Next.js frontend, and the init
+templates. The intended public path is:
+
+```sh
+npx cowriter init
+npx cowriter serve --open
+```
+
+For repo development:
+
+```sh
+$ pnpm install
+$ pnpm test
+$ pnpm build
+$ pnpm pack:dry
+```
+
+Before changing publish-facing behavior, test the packed package, not just the
+checkout:
+
+```sh
+$ npm pack
+$ tmp=$(mktemp -d)
+$ cd "$tmp"
+$ npm exec --yes --package=/absolute/path/to/cowriter-0.1.0.tgz -- cowriter init
+$ npm exec --yes --package=/absolute/path/to/cowriter-0.1.0.tgz -- cowriter serve
+```
+
+Remove generated `cowriter-*.tgz` files after smoke tests. They are not a
+souvenir.
+
+## Caveats
+
+> [!WARNING]
+> This is local writing-workspace software. Keep the book in git, review diffs,
+> and do not treat generated prose or story changes as automatically correct.
+
+- Cowriter serves one book folder per process.
+- The localhost app is not a chat sidebar. Codex.app is the chat surface.
+- Book data is Markdown and YAML on disk. If Codex changes it, git can show it.
+- `serve` is a foreground dev server. Stop it with `Ctrl-C`.
+- Real Codex-backed workflows require Codex.app with localhost access.
+
+## License
+
+MIT

package/frontend/app/api/cowriter/codex/route.ts

@@ -0,0 +1,65 @@
+import { randomUUID } from "node:crypto";
+import { NextRequest, NextResponse } from "next/server";
+import { publishCodexCommand, type CodexHighlightCommand } from "../events/hub";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const commandDescriptions = [
+  {
+    command: "highlight",
+    description: "Highlight a manuscript passage in the Cowriter workspace UI.",
+    request: {
+      command: "highlight",
+      text: "exact passage text",
+      chapterPath: "chapters/001-opening.md",
+      occurrence: 1,
+    },
+    required: ["command", "text"],
+    optional: ["chapterPath", "occurrence"],
+  },
+];
+
+function parseHighlightCommand(body: unknown): CodexHighlightCommand {
+  if (!body || typeof body !== "object") throw new Error("Request body must be a JSON object.");
+  const value = body as Record<string, unknown>;
+  if (value.command !== "highlight") throw new Error(`Unsupported command: ${String(value.command)}`);
+  if (typeof value.text !== "string" || !value.text.trim()) throw new Error("Highlight command requires non-empty text.");
+  if (value.chapterPath !== undefined && typeof value.chapterPath !== "string") throw new Error("chapterPath must be a string when provided.");
+  const occurrence = value.occurrence;
+  if (occurrence !== undefined && (typeof occurrence !== "number" || !Number.isInteger(occurrence) || occurrence < 1)) {
+    throw new Error("occurrence must be a positive integer when provided.");
+  }
+
+  return {
+    id: randomUUID(),
+    command: "highlight",
+    text: value.text,
+    chapterPath: value.chapterPath,
+    occurrence: typeof occurrence === "number" ? occurrence : 1,
+    createdAt: Date.now(),
+  };
+}
+
+export async function GET() {
+  return NextResponse.json({
+    commands: commandDescriptions,
+    context: [
+      {
+        endpoint: "/api/cowriter/selection",
+        method: "GET",
+        description: "Returns the current manuscript selection context published by the Cowriter workspace, or null when nothing is selected.",
+      },
+    ],
+  });
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const command = parseHighlightCommand(await request.json());
+    const deliveredTo = publishCodexCommand(command);
+    return NextResponse.json({ queued: true, deliveredTo, command });
+  } catch (error) {
+    return NextResponse.json({ error: error instanceof Error ? error.message : "Codex command failed" }, { status: 400 });
+  }
+}

package/frontend/app/api/cowriter/cover/route.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { NextResponse } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const cliPath = join(process.cwd(), "../scripts/cowriter-ai.mjs");
+
+type CowriterModule = {
+  findCoverImage(path: string): { path: string; contentType: string; updatedAt: string } | null;
+};
+
+type CowriterImporter = (specifier: string) => Promise<CowriterModule>;
+const testImporter = (globalThis as { __cowriterImport?: CowriterImporter }).__cowriterImport;
+const nativeImporter = new Function("specifier", "return import(specifier)") as CowriterImporter;
+
+async function cowriter() {
+  return (testImporter ?? nativeImporter)(pathToFileURL(cliPath).href);
+}
+
+function projectPath() {
+  return process.env.COWRITER_PROJECT_PATH ?? process.env.GHOSTWRITER_PROJECT_PATH;
+}
+
+export async function GET() {
+  try {
+    const path = projectPath();
+    if (!path) return NextResponse.json({ error: "Cowriter was not started with a project path." }, { status: 404 });
+
+    const cowriterModule = await cowriter();
+    const cover = cowriterModule.findCoverImage(path);
+    if (!cover) return NextResponse.json({ error: "No root cover image found." }, { status: 404 });
+
+    return new NextResponse(new Uint8Array(readFileSync(join(path, cover.path))), {
+      headers: {
+        "cache-control": "no-store",
+        "content-type": cover.contentType,
+      },
+    });
+  } catch (error) {
+    return NextResponse.json({ error: error instanceof Error ? error.message : "Unable to read cover image" }, { status: 500 });
+  }
+}

package/frontend/app/api/cowriter/events/hub.ts

@@ -0,0 +1,24 @@
+export type CodexHighlightCommand = {
+  id: string;
+  command: "highlight";
+  text: string;
+  chapterPath?: string;
+  occurrence: number;
+  createdAt: number;
+};
+
+export type CodexUiCommand = CodexHighlightCommand;
+
+type Listener = (command: CodexUiCommand) => void;
+
+const listeners = new Set<Listener>();
+
+export function subscribeToCodexCommands(listener: Listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function publishCodexCommand(command: CodexUiCommand) {
+  for (const listener of listeners) listener(command);
+  return listeners.size;
+}

package/frontend/app/api/cowriter/events/route.ts

@@ -0,0 +1,77 @@
+import { existsSync, watch, type FSWatcher } from "node:fs";
+import { subscribeToCodexCommands } from "./hub";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function serverProjectPath() {
+  const projectPath = process.env.COWRITER_PROJECT_PATH ?? process.env.GHOSTWRITER_PROJECT_PATH;
+  return typeof projectPath === "string" && existsSync(projectPath) ? projectPath : null;
+}
+
+function shouldIgnore(filename: string | null) {
+  if (!filename) return false;
+  return filename.includes(".git/") || filename.startsWith(".git") || filename.includes("node_modules/");
+}
+
+export async function GET(request: Request) {
+  const encoder = new TextEncoder();
+  const projectPath = serverProjectPath();
+  let watcher: FSWatcher | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+  let unsubscribeFromCodexCommands: (() => void) | null = null;
+  let isClosed = false;
+  const cleanup = () => {
+    if (isClosed) return;
+    isClosed = true;
+    watcher?.close();
+    unsubscribeFromCodexCommands?.();
+    if (heartbeat) clearInterval(heartbeat);
+  };
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const send = (payload: unknown) => {
+        if (isClosed) return;
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(payload)}\n\n`));
+      };
+
+      send({ type: "connected", projectPath });
+      unsubscribeFromCodexCommands = subscribeToCodexCommands((command) => {
+        send({ type: "codex-command", command });
+      });
+
+      if (projectPath) {
+        try {
+          watcher = watch(projectPath, { recursive: true }, (_event, filename) => {
+            const changedPath = filename?.toString() ?? null;
+            if (shouldIgnore(changedPath)) return;
+            send({ type: "change", path: changedPath, at: Date.now() });
+          });
+        } catch (error) {
+          send({ type: "error", message: error instanceof Error ? error.message : "Unable to watch project files" });
+        }
+      }
+
+      heartbeat = setInterval(() => send({ type: "heartbeat", at: Date.now() }), 25000);
+
+      request.signal.addEventListener("abort", () => {
+        cleanup();
+        try {
+          controller.close();
+        } catch {}
+      });
+    },
+    cancel() {
+      cleanup();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+    },
+  });
+}

package/frontend/app/api/cowriter/route.ts

@@ -0,0 +1,83 @@
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { NextRequest, NextResponse } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const cliPath = join(process.cwd(), "../scripts/cowriter-ai.mjs");
+
+type CowriterModule = {
+  findCoverImage(path: string): { path: string; contentType: string; updatedAt: string } | null;
+  loadProject(path: string): unknown;
+  readReport(path: string, reportPath: string): unknown;
+  writeChapter(path: string, chapter: unknown): unknown;
+  writeCharacters(path: string, characters: unknown[]): unknown;
+  writeOutline(path: string, outline: unknown[]): unknown;
+  writeStory(path: string, story: unknown): unknown;
+};
+
+type CowriterImporter = (specifier: string) => Promise<CowriterModule>;
+const testImporter = (globalThis as { __cowriterImport?: CowriterImporter }).__cowriterImport;
+const nativeImporter = new Function("specifier", "return import(specifier)") as CowriterImporter;
+
+async function cowriter() {
+  return (testImporter ?? nativeImporter)(pathToFileURL(cliPath).href);
+}
+
+function projectPath() {
+  return process.env.COWRITER_PROJECT_PATH ?? process.env.GHOSTWRITER_PROJECT_PATH;
+}
+
+export async function GET() {
+  try {
+    const path = projectPath();
+    if (!path) return NextResponse.json({ activeProject: null, error: "Cowriter was not started with a project path." }, { status: 200 });
+    const cowriterModule = await cowriter();
+    return NextResponse.json({ activeProject: cowriterModule.loadProject(path) });
+  } catch (error) {
+    return NextResponse.json({ activeProject: null, error: error instanceof Error ? error.message : "Unable to read Cowriter project" }, { status: 200 });
+  }
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const command = body.command;
+    const path = projectPath();
+    if (!path) return NextResponse.json({ error: "Cowriter was not started with a project path." }, { status: 400 });
+    const cowriterModule = await cowriter();
+
+    if (command === "write-chapter") {
+      cowriterModule.writeChapter(path, body.chapter);
+      return NextResponse.json({ project: cowriterModule.loadProject(path) });
+    }
+
+    if (command === "write-story") {
+      cowriterModule.writeStory(path, body.story);
+      return NextResponse.json({ project: cowriterModule.loadProject(path) });
+    }
+
+    if (command === "write-characters") {
+      cowriterModule.writeCharacters(path, Array.isArray(body.characters) ? body.characters : []);
+      return NextResponse.json({ project: cowriterModule.loadProject(path) });
+    }
+
+    if (command === "write-outline") {
+      cowriterModule.writeOutline(path, Array.isArray(body.outline) ? body.outline : []);
+      return NextResponse.json({ project: cowriterModule.loadProject(path) });
+    }
+
+    if (command === "read-report") {
+      try {
+        return NextResponse.json({ report: cowriterModule.readReport(path, body.path) });
+      } catch (error) {
+        return NextResponse.json({ error: error instanceof Error ? error.message : "Unable to read report" }, { status: 400 });
+      }
+    }
+
+    return NextResponse.json({ error: `Unsupported command: ${command}` }, { status: 400 });
+  } catch (error) {
+    return NextResponse.json({ error: error instanceof Error ? error.message : "Cowriter command failed" }, { status: 500 });
+  }
+}

package/frontend/app/api/cowriter/selection/route.ts

@@ -0,0 +1,69 @@
+import { NextRequest, NextResponse } from "next/server";
+import { readSelectionContext, writeSelectionContext, type CowriterSelectionContext } from "./store";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type SelectionBody = {
+  selection?: unknown;
+};
+
+function projectPath() {
+  return process.env.COWRITER_PROJECT_PATH ?? process.env.GHOSTWRITER_PROJECT_PATH ?? null;
+}
+
+function parseSelection(body: SelectionBody, boundProjectPath: string): CowriterSelectionContext | null {
+  if (body.selection === null) return null;
+  if (!body.selection || typeof body.selection !== "object") throw new Error("selection must be an object or null.");
+
+  const value = body.selection as Record<string, unknown>;
+  if (value.source !== "manuscript") throw new Error("selection.source must be manuscript.");
+  if (typeof value.selectedText !== "string" || !value.selectedText.trim()) return null;
+  if (typeof value.chapterId !== "string" || !value.chapterId.trim()) throw new Error("selection.chapterId must be a string.");
+  if (typeof value.chapterPath !== "string" || !value.chapterPath.trim()) throw new Error("selection.chapterPath must be a string.");
+  if (typeof value.chapterTitle !== "string") throw new Error("selection.chapterTitle must be a string.");
+  if (typeof value.surroundingText !== "string") throw new Error("selection.surroundingText must be a string.");
+  if (typeof value.activePage !== "number" || !Number.isInteger(value.activePage) || value.activePage < 0) {
+    throw new Error("selection.activePage must be a non-negative integer.");
+  }
+
+  const range = value.range;
+  if (!range || typeof range !== "object") throw new Error("selection.range must be an object.");
+  const from = (range as Record<string, unknown>).from;
+  const to = (range as Record<string, unknown>).to;
+  if (typeof from !== "number" || typeof to !== "number" || !Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to <= from) {
+    throw new Error("selection.range must contain valid from and to offsets.");
+  }
+
+  return {
+    projectPath: boundProjectPath,
+    source: "manuscript",
+    selectedText: value.selectedText,
+    chapterId: value.chapterId,
+    chapterPath: value.chapterPath,
+    chapterTitle: value.chapterTitle,
+    range: { from, to },
+    activePage: value.activePage,
+    surroundingText: value.surroundingText,
+    updatedAt: Date.now(),
+  };
+}
+
+export async function GET() {
+  const boundProjectPath = projectPath();
+  return NextResponse.json({
+    activeProjectPath: boundProjectPath,
+    selection: readSelectionContext(boundProjectPath),
+  });
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const boundProjectPath = projectPath();
+    if (!boundProjectPath) return NextResponse.json({ error: "Cowriter was not started with a project path." }, { status: 400 });
+    const selection = parseSelection(await request.json(), boundProjectPath);
+    return NextResponse.json({ selection: writeSelectionContext(selection) });
+  } catch (error) {
+    return NextResponse.json({ error: error instanceof Error ? error.message : "Unable to update selection context" }, { status: 400 });
+  }
+}

package/frontend/app/api/cowriter/selection/store.ts

@@ -0,0 +1,27 @@
+export type CowriterSelectionContext = {
+  projectPath: string;
+  source: "manuscript";
+  selectedText: string;
+  chapterId: string;
+  chapterPath: string;
+  chapterTitle: string;
+  range: {
+    from: number;
+    to: number;
+  };
+  activePage: number;
+  surroundingText: string;
+  updatedAt: number;
+};
+
+let latestSelection: CowriterSelectionContext | null = null;
+
+export function readSelectionContext(projectPath: string | null) {
+  if (!projectPath || latestSelection?.projectPath !== projectPath) return null;
+  return latestSelection;
+}
+
+export function writeSelectionContext(selection: CowriterSelectionContext | null) {
+  latestSelection = selection;
+  return latestSelection;
+}