app/kb/procedures/save.server.ts

Functions

Imports

It imports app/db/procedure-versions.ts, app/kb/procedures/cite.mjs, app/kb/procedures/compile.mjs, app/kb/procedures/parse.mjs, app/kb/procedures/render.mjs, app/kb/registry/host.server.ts, app/lib/cache-purge.server.ts, app/lib/carrel/errors.server.ts, app/lib/content/load-pipeline.server.ts, app/lib/editor/converge.mjs, app/lib/editor/github.server.ts, app/lib/editor/publish-policy.mjs, app/lib/editor/publish.server.ts, app/lib/editor/write-path.server.ts, app/lib/search/records.mjs. Imported by app/kb/editor.server.ts, app/kb/form.server.ts, app/kb/procedures/primer-dependents.server.ts, app/lib/carrel/procedure-handler.server.ts, app/lib/operator/api.server.ts, app/lib/operator/sync-tools.server.ts, app/routes/admin.kb.preview.tsx.

Source

1// The operator API's procedure tools: read a procedure as its file and as structured data, and save an
2// edited file. A save compiles the file the way CI does (compile.mjs), refuses it with the validator's
3// own messages if it fails, commits it to the repository, then writes its D1 row and search records, so
4// the page changes on the next request with no build or deploy. The commit is never reverted when the
5// D1 write fails; the error says the commit landed and how to repair the row.
6
7import { ContentInvalid } from "~/lib/carrel/errors.server";
8import { purgeProcedures, type PurgeOutcome } from "~/lib/cache-purge.server";
9import { loadPipeline } from "~/lib/content/load-pipeline.server";
10import { convergeWithRetry } from "~/lib/editor/converge.mjs";
11import { blobGuard, commitFiles, readFile } from "~/lib/editor/github.server";
12import { makeResolveImage } from "~/lib/editor/publish.server";
13import { readEquipment, readPrimers, readReagents, readStrains } from "~/kb/registry/host.server";
14import { commitUnlessUnchanged, UNCHANGED_NOTE } from "~/lib/editor/write-path.server";
15import { decideFileWrite, type Actor } from "~/lib/editor/publish-policy.mjs";
16import { recordsForPages } from "~/lib/search/records.mjs";
17
18import { freezeStatement, frozenBlobSha } from "~/db/procedure-versions";
19
20import { needsFreeze, versionPath } from "./cite.mjs";
21import { compileProcedure } from "./compile.mjs";
22import { parseProcedure, procedurePath } from "./parse.mjs";
23import { procedureSearchUid } from "./render.mjs";
24
25type ProcedureEnv = Env & { GITHUB_TOKEN?: string };
26/** A file the validator refused: 422, with every message, so the caller can fix its own edit. */
27export class ProcedureInvalid extends ContentInvalid {
28  constructor(slug: string, errors: string[]) {
29    super(`The procedure "${slug}" was not saved: it fails ${errors.length} check(s). Nothing was committed.`, errors);
30    this.name = "ProcedureInvalid";
31  }
32}
33
34/**
35 * The one compile door: save_procedure, get_procedure and sync_procedures all read a file through it. A file that
36 * changes the words of a version already frozen does not compile here, so a save is refused before it commits, a
37 * sync names the file and converges the rest, and get_procedure shows the error; the frozen copy is never touched.
38 */
39export async function compile(env: ProcedureEnv, slug: string, raw: string) {
40  const { renderBody, findWideDashes } = await loadPipeline();
41  const compiled = await compileProcedure({
42    slug,
43    raw,
44    pipeline: { renderBody, findWideDashes },
45    resolveImage: makeResolveImage(env),
46    // The primers and host strains a protocol names are the lab registry's, read from the repository as CI reads them (docs/REGISTRY.md).
47    registry: { primers: (ids) => readPrimers(env, ids), strains: (ids) => readStrains(env, ids), reagents: (ids) => readReagents(env, ids), equipment: (ids) => readEquipment(env, ids) },
48  });
49  if (!compiled.ok) return compiled;
50  // A published variant points at words that are frozen (P3): the version of its parent it was copied at has its copy.
51  const from = compiled.record.forkedFrom;
52  if (from?.version && !compiled.record.draft && (await frozenBlobSha(env, from.slug, from.version)) === null) {
53    return {
54      ok: false as const,
55      errors: [`forked_from names version ${from.version} of ${from.slug}, which has no frozen copy: publish that version of ${from.slug} first, or keep this variant a draft`],
56      gaps: compiled.gaps,
57    };
58  }
59  if (!needsFreeze(compiled.record)) return compiled;
60  const frozen = await frozenBlobSha(env, slug, String(compiled.record.version));
61  if (frozen === null || frozen === compiled.sourceBlobSha) return compiled;
62  return { ok: false as const, errors: [frozenEditMessage(compiled.record)], gaps: compiled.gaps };
63}
64
65/** get_procedure: the file, its structure as parsed, and the gaps it records. */
66export async function readProcedure(env: ProcedureEnv, slug: string) {
67  const file = await readFile(env, procedurePath(slug));
68  if (!file) return null;
69  const parsed = parseProcedure({ file: procedurePath(slug), raw: file.content });
70  const compiled = await compile(env, slug, file.content);
71  return {
72    slug,
73    path: typeof parsed.data.path === "string" ? parsed.data.path : null,
74    raw: file.content,
75    draft: parsed.data.draft === true,
76    record: { data: parsed.data, intro: parsed.intro, sections: parsed.sections },
77    gaps: compiled.gaps,
78    errors: compiled.ok ? [] : compiled.errors,
79  };
80}
81
82/**
83 * An operator may edit, unpublish and republish a procedure, never publish one for the first time:
84 * the same rule as posts (the first-publish rule, `WRITE_CAPABILITIES` in `publish-policy.mjs`), read from the prior FILE, the only authority.
85 */
86function decideProcedure(actor: Actor, incomingDraft: boolean, prior: string | null) {
87  decideFileWrite({
88    actor,
89    noun: "procedure",
90    incomingDraft,
91    priorRaw: prior,
92    isDraft: (raw) => parseProcedure({ file: "", raw }).data.draft === true,
93  });
94}
95
96/**
97 * What a refused or flagged edit to a frozen version says: the words of a published version never change, so a
98 * correction is a new version with a history entry that says what changed.
99 */
100function frozenEditMessage(record: { version: string | null; path: string }) {
101  return (
102    `Version ${record.version} is already published and frozen at ${versionPath(record.path, String(record.version))}, so its words cannot change. ` +
103    `Set a new version in the file and add a history entry that says what changed.`
104  );
105}
106
107/**
108 * The one write door for a procedure's row and search records: a save and the sync both end here. A published
109 * procedure with a version is also frozen, in the same batch: the copy is written once and the database refuses to
110 * change it. `compile` has already refused a file that would change a frozen version, so the check after the batch
111 * is the last line of defence: it fails loudly if the sealed copy is not made from this file.
112 */
113export async function writeRow(env: ProcedureEnv, compiled: Extract<Awaited<ReturnType<typeof compile>>, { ok: true }>) {
114  const db = env.DB;
115  const r = compiled.record;
116  const uid = compiled.searchInput.uid;
117  const records = r.draft ? [] : recordsForPages([compiled.searchInput]);
118  await db.batch([
119    db
120      .prepare(
121        `INSERT INTO procedures (slug, path, profile, title, description, status, version, updated, record,
122           markdown, source_path, source_blob_sha, synced_at)
123         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, unixepoch())
124         ON CONFLICT(slug) DO UPDATE SET path = excluded.path, profile = excluded.profile,
125           title = excluded.title, description = excluded.description, status = excluded.status,
126           version = excluded.version, updated = excluded.updated, record = excluded.record,
127           markdown = excluded.markdown, source_path = excluded.source_path,
128           source_blob_sha = excluded.source_blob_sha, synced_at = excluded.synced_at`,
129      )
130      .bind(
131        r.slug,
132        r.path,
133        r.profile,
134        r.title,
135        r.description,
136        r.draft ? "draft" : "published",
137        r.version,
138        r.updated,
139        JSON.stringify(r),
140        compiled.markdown,
141        compiled.sourcePath,
142        compiled.sourceBlobSha,
143      ),
144    ...(needsFreeze(r)
145      ? [
146          freezeStatement(db, {
147            slug: r.slug,
148            version: String(r.version),
149            path: r.path,
150            profile: r.profile,
151            record: JSON.stringify(r),
152            markdown: compiled.markdown,
153            sourceBlobSha: compiled.sourceBlobSha,
154          }),
155        ]
156      : []),
157    db.prepare(`DELETE FROM search_docs WHERE doc_uid = ?1`).bind(uid),
158    ...records.map((s) =>
159      db
160        .prepare(
161          `INSERT INTO search_docs (uid, url, type, title, body, tags, doc_tags, doc_uid,
162             doc_title, doc_url, anchor, ordinal, status, publish_at)
163           VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14)`,
164        )
165        .bind(s.uid, s.url, s.type, s.title, s.body, s.tags, s.docTags, s.docUid, s.docTitle, s.docUrl, s.anchor, s.ordinal, s.status, null),
166    ),
167    db.prepare(`INSERT INTO search_identity (search_identity) VALUES ('rebuild')`),
168    db.prepare(`INSERT INTO search_prose (search_prose) VALUES ('rebuild')`),
169  ]);
170  if (needsFreeze(r)) {
171    const frozen = await frozenBlobSha(env, r.slug, String(r.version));
172    if (frozen !== compiled.sourceBlobSha) {
173      throw new Error(
174        `The frozen copy of version ${r.version} is not made from this file. ${frozenEditMessage(r)}`,
175      );
176    }
177  }
178}
179
180/**
181 * Removes a row whose file is gone, with its search records. The search uid is derived from the row's
182 * own path by the function the search input uses, so the two cannot disagree.
183 */
184export async function deleteProcedureRow(env: ProcedureEnv, row: { slug: string; path: string }) {
185  await env.DB.batch([
186    env.DB.prepare(`DELETE FROM procedures WHERE slug = ?1`).bind(row.slug),
187    env.DB.prepare(`DELETE FROM search_docs WHERE doc_uid = ?1`).bind(procedureSearchUid(row.path)),
188    env.DB.prepare(`INSERT INTO search_identity (search_identity) VALUES ('rebuild')`),
189    env.DB.prepare(`INSERT INTO search_prose (search_prose) VALUES ('rebuild')`),
190  ]);
191}
192
193/** True when D1's row for the procedure was compiled from exactly this file (the git blob sha matches). */
194async function rowIsCurrent(env: ProcedureEnv, slug: string, blobSha: string) {
195  const row = await env.DB.prepare("SELECT status, version, source_blob_sha FROM procedures WHERE slug = ?1")
196    .bind(slug)
197    .first<{ status: string; version: string | null; source_blob_sha: string | null }>();
198  if (row?.source_blob_sha !== blobSha) return false;
199  // A published version with no frozen copy yet is not current: the save that writes the row freezes it.
200  if (row.status === "published" && row.version) return (await frozenBlobSha(env, slug, row.version)) !== null;
201  return true;
202}
203
204/** save_procedure. */
205export async function saveProcedure(
206  env: ProcedureEnv,
207  options: { slug: string; raw: string; expectedHeadSha?: string | null;
208    /** The blob sha of this file as Carrel loaded it; undefined means no check. */
209    expectedBlobSha?: string | null; isNew: boolean; actor: Actor },
210) {
211  const { slug, raw, actor } = options;
212  const path = procedurePath(slug);
213  const existing = await readFile(env, path);
214  if (options.isNew && existing) throw new ProcedureInvalid(slug, [`a procedure named ${slug} already exists`]);
215  if (!options.isNew && !existing) throw new ProcedureInvalid(slug, [`no procedure named ${slug} exists; pass isNew to create it`]);
216
217  const compiled = await compile(env, slug, raw);
218  if (!compiled.ok) throw new ProcedureInvalid(slug, compiled.errors);
219  decideProcedure(actor, compiled.record.draft, existing?.content ?? null);
220
221  const tag = actor.kind === "operator" ? ` [operator:${actor.id}]` : actor.kind === "carrel" ? ` [carrel:${actor.changeId}]` : "";
222  // After the gate, so a file that fails validation is still refused even when it is unchanged.
223  const written = await commitUnlessUnchanged(env, {
224    existing,
225    raw,
226    rowIsCurrent: () => rowIsCurrent(env, slug, compiled.sourceBlobSha),
227    commit: () =>
228      commitFiles(env, {
229        expectedHeadSha: options.expectedHeadSha,
230        expectedBlobs: blobGuard(path, options.expectedBlobSha),
231        message: `${options.isNew ? "Add" : "Update"} procedure: ${compiled.record.title}${tag}`,
232        changes: [{ path, content: raw }],
233      }),
234  });
235  const unchanged = written.action !== "commit";
236  if (written.action === "noop") {
237    return {
238      slug,
239      path: compiled.record.path,
240      commitSha: written.commitSha,
241      sourceBlobSha: compiled.sourceBlobSha,
242      unchanged: true,
243      note: UNCHANGED_NOTE,
244      created: false,
245      draft: compiled.record.draft,
246      gaps: compiled.gaps,
247      purged: null as PurgeOutcome,
248    };
249  }
250  const { commitSha, blobShas } = written;
251  if (blobShas[path] && blobShas[path] !== compiled.sourceBlobSha) {
252    throw new Error(
253      `The procedure "${slug}" WAS committed as ${commitSha}, but the committed bytes (${blobShas[path]}) are not ` +
254        `the bytes compiled (${compiled.sourceBlobSha}), so its page was not updated. Run the content sync to ` +
255        `rebuild the row from the repository.`,
256    );
257  }
258
259  let purged: PurgeOutcome = false;
260  await convergeWithRetry({
261    write: async () => {
262      await writeRow(env, compiled);
263      purged = await purgeProcedures(`save_procedure ${slug}`);
264    },
265    // Nothing kept in KV for a procedure: the thrown error names the commit and the repair (the content
266    // sync), and the next ship's sync converges the row from the repository anyway.
267    recordDivergence: async () => undefined,
268    slug,
269    commitSha,
270  });
271
272  return {
273    slug,
274    path: compiled.record.path,
275    commitSha,
276    sourceBlobSha: compiled.sourceBlobSha,
277    unchanged,
278    created: options.isNew,
279    draft: compiled.record.draft,
280    gaps: compiled.gaps,
281    purged,
282  };
283}