src/write-modes.ts

Functions

Imports

It imports no other module of this repo. Imported by src/tools/docs-write.ts.

Source

1type WriteMode = "replace" | "append" | "patch" | "meta";
2
3export interface WriteRequest {
4  mode: WriteMode;
5  exists: boolean;
6  priorBody: string | null;
7  title?: string;
8  body?: string;
9  find?: string;
10  replace_with?: string;
11}
12
13// Wire type stays loose so a client sending a bad combination is refused rather
14// than silently ignored. The union is what assembly is allowed to see.
15export type AssembleInput =
16  | { mode: "replace"; exists: boolean; priorBody: string | null; title: string; body: string }
17  | { mode: "append"; exists: boolean; priorBody: string | null; body: string }
18  | { mode: "meta"; exists: boolean; priorBody: string | null }
19  | { mode: "patch"; exists: boolean; priorBody: string | null; find: string; replace_with: string };
20
21export type AssembleResult = { body: string } | { error: string };
22
23// Error precedence is load-bearing: replace is checked before the existence test.
24export function narrowWrite(req: WriteRequest): AssembleInput | { error: string } {
25  const { mode, exists, priorBody, title, body, find, replace_with } = req;
26
27  if (mode === "replace") {
28    if (title === undefined || body === undefined) {
29      return {
30        error:
31          "mode 'replace' needs both title and body. Use mode 'append' to add to a document, or 'patch' to change part of one.",
32      };
33    }
34    return { mode, exists, priorBody, title, body };
35  }
36
37  if (!exists) {
38    return { error: `cannot ${mode} a document that does not exist. Create it with mode 'replace' first.` };
39  }
40
41  // meta leaves the body byte-identical.
42  if (mode === "meta") {
43    if (body !== undefined) {
44      return { error: "mode 'meta' changes type, tags, status or title only, and does not take body." };
45    }
46    if (find !== undefined || replace_with !== undefined) {
47      return { error: "find and replace_with belong to mode 'patch', not 'meta'." };
48    }
49    return { mode, exists, priorBody };
50  }
51
52  if (mode === "append") {
53    if (body === undefined) {
54      return { error: "mode 'append' needs body: the text to add to the end of the document." };
55    }
56    if (find !== undefined || replace_with !== undefined) {
57      return { error: "find and replace_with belong to mode 'patch', not 'append'." };
58    }
59    return { mode, exists, priorBody, body };
60  }
61
62  if (find === undefined || replace_with === undefined) {
63    return { error: "mode 'patch' needs find and replace_with." };
64  }
65  if (body !== undefined) {
66    return { error: "mode 'patch' takes find and replace_with, not body." };
67  }
68  if (find === "") {
69    return { error: "mode 'patch' needs a non-empty find. An empty anchor matches everywhere." };
70  }
71  return { mode, exists, priorBody, find, replace_with };
72}
73
74function assemble(input: AssembleInput): AssembleResult {
75  if (input.mode === "replace") return { body: input.body };
76
77  const current = input.priorBody ?? "";
78
79  if (input.mode === "meta") return { body: current };
80
81  if (input.mode === "append") {
82    // Exactly one blank line between stored body and addition.
83    return { body: `${current.replace(/\s*$/, "")}\n\n${input.body.replace(/^\s*\n/, "")}` };
84  }
85
86  const { find, replace_with } = input;
87
88  const occurrences = current.split(find).length - 1;
89  if (occurrences === 0) {
90    return {
91      error:
92        "patch anchor not found. Nothing was written. The find text must match the stored body exactly, including whitespace and line endings. CRLF versus LF is the usual cause; it silently defeated two plants on 2026-08-11.",
93    };
94  }
95  if (occurrences > 1) {
96    return {
97      error: `patch anchor is ambiguous: it occurs ${occurrences} times. Nothing was written. Extend find until it is unique.`,
98    };
99  }
100
101  // Spliced by index, not String.replace: replace() still interprets $ in the
102  // replacement.
103  const at = current.indexOf(find);
104  return { body: current.slice(0, at) + replace_with + current.slice(at + find.length) };
105}
106
107export function assembleBody(req: WriteRequest): AssembleResult {
108  const input = narrowWrite(req);
109  if ("error" in input) return input;
110  return assemble(input);
111}