app/lib/novels/layout.ts

Functions

Imports

It imports app/lib/novels/frontmatter.ts. Imported by app/lib/books.server.ts, app/lib/mcp/tools.ts, app/lib/novels/checks.ts, app/lib/writing/binder.ts, app/routes/book.chapter.tsx, app/routes/book.corkboard.tsx, app/routes/book.file.tsx, app/routes/book.history.tsx, app/routes/book.outliner.tsx, app/routes/book.tsx.

Source

1// The writing repository's layout, from the design job: shared/ for voice passages, checks, assembly
2// and templates; one folder per book with bible/, outline/, chapters/NN-name/NN-scene.md, and build/
3// ignored. Paths here are relative to the book's folder unless a name says otherwise.
4
5import { flag, list, parseFile, text, type HeaderValue } from "./frontmatter";
6
7export type FileKind = "scene" | "character" | "place" | "rule" | "outline" | "book" | "note";
8
9const SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
10const NUMBERED = /^(\d{2,3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
11
12/** A book folder name: lower case, digits and single hyphens, as every segment is. */
13export function isBookFolder(value: string): boolean {
14  return SEGMENT.test(value) && value !== "shared" && value.length <= 80;
15}
16
17/**
18 * A Markdown file Carrel may open and save inside a book: known folders only, plain segments, no
19 * `..`, nothing under build/. Anything else is refused before Git is asked.
20 */
21export function isBookPath(path: string): boolean {
22  if (!path.endsWith(".md") || path.length > 200) return false;
23  const parts = path.slice(0, -3).split("/");
24  if (!parts.every((p) => SEGMENT.test(p))) return false;
25  if (parts.length === 1) return parts[0] === "book";
26  const [top] = parts;
27  if (top === "chapters") return parts.length === 3 && NUMBERED.test(parts[1]!) && NUMBERED.test(parts[2]!);
28  if (top === "bible") return parts.length === 2 || (parts.length === 3 && ["characters", "places", "rules"].includes(parts[1]!));
29  // Notes (design 4.1): flat like the outline, read by no check and never exported.
30  if (top === "outline" || top === "notes") return parts.length === 2;
31  return false;
32}
33
34export function kindOf(path: string): FileKind {
35  if (path === "book.md") return "book";
36  if (path.startsWith("chapters/")) return "scene";
37  if (path.startsWith("bible/characters/")) return "character";
38  if (path.startsWith("bible/places/")) return "place";
39  if (path.startsWith("bible/rules/")) return "rule";
40  if (path.startsWith("outline/")) return "outline";
41  return "note";
42}
43
44/** "03-the-long-road" to "The long road". */
45export function titleFromSegment(segment: string): string {
46  const name = NUMBERED.exec(segment)?.[2] ?? segment;
47  const words = name.replace(/-/g, " ");
48  return words.charAt(0).toUpperCase() + words.slice(1);
49}
50
51export function slugify(title: string): string {
52  return title
53    .toLowerCase()
54    .normalize("NFKD")
55    .replace(/[\u0300-\u036f]/g, "")
56    .replace(/[^a-z0-9]+/g, "-")
57    .replace(/^-+|-+$/g, "")
58    .slice(0, 60)
59    .replace(/-+$/g, "");
60}
61
62/** The next NN- prefix after the ones present, two digits until a hundred. */
63export function nextNumbered(existing: string[], name: string): string {
64  const numbers = existing.map((s) => Number(NUMBERED.exec(s)?.[1] ?? 0));
65  const next = Math.max(0, ...numbers) + 1;
66  return `${String(next).padStart(2, "0")}-${name}`;
67}
68
69export type SceneHeader = {
70  pov: string;
71  date: string;
72  location: string;
73  characters: string[];
74  goal: string;
75  conflict: string;
76  outcome: string;
77  flashback: boolean;
78  /** Writing-desk keys (ruling 8): a label from the project's status list, a line for the outliner, a word goal. */
79  status: string;
80  summary: string;
81  target: number | null;
82  /** A ceiling, not a goal: a journal section's word limit. */
83  limit: number | null;
84};
85
86export type CharacterEntry = { name: string; aliases: string[]; born: string; died: string };
87export type PlaceEntry = { name: string; aliases: string[] };
88export type RuleEntry = { name: string; forbidden: string[] };
89type BookEntry = { title: string; author: string; language: string; target: number | null; deadline: string };
90
91export type Meta =
92  | { kind: "scene"; header: SceneHeader; hasHeader: boolean }
93  | { kind: "character"; entry: CharacterEntry }
94  | { kind: "place"; entry: PlaceEntry }
95  | { kind: "rule"; entry: RuleEntry }
96  | { kind: "book"; entry: BookEntry }
97  | { kind: "outline" | "note" };
98
99/** The name a bible file stands for when its header gives none: its file name. */
100function fallbackName(path: string): string {
101  const file = path.split("/").pop()!.replace(/\.md$/, "");
102  return titleFromSegment(file);
103}
104
105const DAY = /^\d{4}-\d{2}-\d{2}$/;
106
107/** A whole number of words, written as 2000, 2,000 or 2_000. Anything else is no target, not a guess. */
108function wordCount(data: Record<string, HeaderValue>, key: string): number | null {
109  const raw = text(data, key).replace(/[,_]/g, "");
110  if (!/^\d{1,7}$/.test(raw)) return null;
111  const n = Number(raw);
112  return n > 0 ? n : null;
113}
114
115export function readMeta(path: string, data: Record<string, HeaderValue>, hasHeader: boolean): Meta {
116  const kind = kindOf(path);
117  switch (kind) {
118    case "scene":
119      return {
120        kind,
121        hasHeader,
122        header: {
123          pov: text(data, "pov"),
124          date: text(data, "date"),
125          location: text(data, "location"),
126          characters: list(data, "characters"),
127          goal: text(data, "goal"),
128          conflict: text(data, "conflict"),
129          outcome: text(data, "outcome"),
130          flashback: flag(data, "flashback"),
131          status: text(data, "status"),
132          summary: text(data, "summary"),
133          target: wordCount(data, "target"),
134          limit: wordCount(data, "limit"),
135        },
136      };
137    case "character":
138      return {
139        kind,
140        entry: { name: text(data, "name") || fallbackName(path), aliases: list(data, "aliases"), born: text(data, "born"), died: text(data, "died") },
141      };
142    case "place":
143      return { kind, entry: { name: text(data, "name") || fallbackName(path), aliases: list(data, "aliases") } };
144    case "rule":
145      return { kind, entry: { name: text(data, "name") || fallbackName(path), forbidden: list(data, "forbidden") } };
146    case "book":
147      return {
148        kind,
149        entry: {
150          title: text(data, "title"),
151          author: text(data, "author"),
152          language: text(data, "language") || "en",
153          target: wordCount(data, "target"),
154          deadline: DAY.test(text(data, "deadline")) ? text(data, "deadline") : "",
155        },
156      };
157    default:
158      return { kind };
159  }
160}
161
162export function describe(path: string, source: string): { meta: Meta; words: number } {
163  const parsed = parseFile(source);
164  return { meta: readMeta(path, parsed.data, Object.keys(parsed.data).length > 0), words: countProseWords(parsed.body) };
165}
166
167export function countProseWords(body: string): number {
168  return body.match(/[\p{L}\p{N}]+(?:['\u2019][\p{L}]+)*/gu)?.length ?? 0;
169}
170
171export const TEMPLATES: Record<"scene" | "character" | "place" | "rule", (name: string) => string> = {
172  scene: () =>
173    ["---", "status:", "summary:", "target:", "pov:", "date:", "location:", "characters: []", "goal:", "conflict:", "outcome:", "---", "", ""].join("\n"),
174  character: (name) => ["---", `name: ${name}`, "aliases: []", "born:", "died:", "---", "", ""].join("\n"),
175  place: (name) => ["---", `name: ${name}`, "aliases: []", "---", "", ""].join("\n"),
176  rule: (name) =>
177    [
178      "---",
179      `name: ${name}`,
180      "# Each pattern is matched against every scene, ignoring case. A match is flagged, never refused.",
181      "forbidden: []",
182      "---",
183      "",
184      "",
185    ].join("\n"),
186};
187
188function orderKey(path: string): number[] {
189  return path.split("/").slice(1).map((segment) => Number(NUMBERED.exec(segment.replace(/\.md$/, ""))?.[1] ?? 0));
190}
191
192/** Scenes in reading order: chapters by their number, then scenes by theirs (so 100 follows 99). */
193export function readingOrder<T extends { path: string }>(files: T[]): T[] {
194  return files
195    .filter((f) => kindOf(f.path) === "scene")
196    .sort((a, b) => {
197      const [ka, kb] = [orderKey(a.path), orderKey(b.path)];
198      return ka[0]! - kb[0]! || ka[1]! - kb[1]! || (a.path < b.path ? -1 : 1);
199    });
200}
201
202export function chapterOf(path: string): string | null {
203  const parts = path.split("/");
204  return parts[0] === "chapters" && parts.length === 3 ? parts[1]! : null;
205}