app/lib/cv/save.server.ts

Functions

Imports

It imports app/db/cv.ts, app/db/publications.ts, app/lib/cache-purge.server.ts, app/lib/carrel/errors.server.ts, app/lib/content-pages.mjs, app/lib/content/load-pipeline.server.ts, app/lib/cv/compile.mjs, app/lib/cv/parse.mjs, app/lib/cv/pdf.server.ts, app/lib/editor/converge.mjs, app/lib/editor/github.server.ts, app/lib/editor/publish-policy.mjs, app/lib/editor/write-path.server.ts, app/lib/search/records.mjs, app/lib/search/replace.server.ts. Imported by app/lib/carrel/cv-handler.server.ts, app/lib/operator/api.server.ts, app/lib/operator/sync-tools.server.ts, app/lib/publications/save.server.ts.

Source

1// The one CV save, called by the site-api adapter for Carrel (app/lib/carrel/cv-handler.server.ts), and the reads
2// the operator's list_cv and get_cv tools answer. The CV is edited through Carrel and nothing else: there is no
3// save tool and no admin editor. A save judges the file the way CI does (compile.mjs), joins it to the other
4// files D1 holds and to the publications, compiles the page its search records come from, refuses it with every
5// message if any of that fails, commits it to the repository (unless it is byte-identical, commitUnlessUnchanged),
6// then writes its D1 row and the CV's search records, so the page, its twin and its charts change on the next
7// request with no build or deploy. The commit is never reverted when the D1 write fails; the error
8// says the commit landed and how to repair the row. A save cannot create a file: the set of files is structure
9// and lives in CV_FILES.
10
11import matter from "gray-matter";
12
13import { listCvRows, readCv } from "~/db/cv";
14import { listPublishedPublications } from "~/db/publications";
15import { ContentInvalid } from "~/lib/carrel/errors.server";
16import { purgeCv, type PurgeOutcome } from "~/lib/cache-purge.server";
17import { loadPipeline } from "~/lib/content/load-pipeline.server";
18import { contentPageSearchUid } from "~/lib/content-pages.mjs";
19import { compileCv, compileCvFile, compileCvPage } from "~/lib/cv/compile.mjs";
20import { CV_FILES, cvFileFor, cvSourcePath } from "~/lib/cv/parse.mjs";
21import { regenerateCvPdfAfterSave, type CvPdfOutcome } from "~/lib/cv/pdf.server";
22import { convergeWithRetry } from "~/lib/editor/converge.mjs";
23import { blobGuard, commitFiles, readFile } from "~/lib/editor/github.server";
24import { commitUnlessUnchanged, UNCHANGED_NOTE } from "~/lib/editor/write-path.server";
25import { PolicyError, WRITE_CAPABILITIES, type Actor } from "~/lib/editor/publish-policy.mjs";
26import { recordsForPages } from "~/lib/search/records.mjs";
27import { replaceSearchRecords } from "~/lib/search/replace.server";
28
29type CvEnv = Env & { GITHUB_TOKEN?: string };
30
31/** A file the validator refused: 422, with every message, so the caller can fix its own edit. */
32export class CvInvalid extends ContentInvalid {
33  constructor(slug: string, errors: string[]) {
34    super(`The CV file "${slug}" was not saved: it fails ${errors.length} check(s). Nothing was committed.`, errors);
35    this.name = "CvInvalid";
36  }
37}
38
39/** The file a slug names. A slug outside CV_FILES is refused before any read or write: a save cannot create a file. */
40function registeredCvFile(slug: string) {
41  const clean = slug.trim();
42  const file = cvFileFor(clean);
43  if (!file) {
44    throw new CvInvalid(clean, [
45      `"${clean}" is not a CV file. A save cannot create a new one: the set of files is structure, so a new ` +
46        `section is added to CV_FILES (app/lib/cv/parse.mjs) in code first. The files are ${CV_FILES.map((f) => f.slug).join(", ")}.`,
47    ]);
48  }
49  return { slug: clean, file, path: cvSourcePath(clean) };
50}
51
52/** The one compile door for a file: the save and sync_cv both read a file through it (judged alone, against D1's papers). */
53export async function compile(env: CvEnv, slug: string, raw: string) {
54  return compileCvFile({ slug, raw, publications: await listPublishedPublications(env) });
55}
56
57/**
58 * Compile, then the rules that need the whole CV, then the page the search records come from: every message
59 * the file has now, which is what CI and a save both refuse. The whole is D1's other files with this one in place.
60 */
61async function judge(env: CvEnv, slug: string, raw: string) {
62  const publications = await listPublishedPublications(env);
63  const compiled = await compileCvFile({ slug, raw, publications });
64  if (!compiled.ok) return compiled;
65  const others = (await listCvRows(env)).filter((row) => row.slug !== slug).map((row) => row.record);
66  const whole = compileCv({ records: [...others, compiled.record], publications });
67  if (!whole.ok) return whole;
68  const { renderBody, findWideDashes } = await loadPipeline();
69  const page = await compileCvPage({ cv: whole.cv, pipeline: { renderBody, findWideDashes } });
70  return page.ok ? compiled : page;
71}
72
73/** The file, and its front matter as parsed, with what the validator says of it now. */
74export async function readCvFile(env: CvEnv, slug: string) {
75  const { path } = registeredCvFile(slug);
76  const existing = await readFile(env, path);
77  if (!existing) return null;
78  const judged = await judge(env, slug, existing.content);
79  return {
80    slug,
81    raw: existing.content,
82    record: matter(existing.content).data,
83    errors: judged.ok ? [] : judged.errors,
84  };
85}
86
87/** The CV's search records, compiled from D1's rows as they stand. */
88async function searchRecords(env: CvEnv) {
89  const { renderBody, findWideDashes } = await loadPipeline();
90  const page = await compileCvPage({ cv: await readCv(env), pipeline: { renderBody, findWideDashes } });
91  if (!page.ok) throw new Error(`The CV page does not compile: ${page.errors.join("; ")}`);
92  return recordsForPages([page.searchInput]);
93}
94
95/**
96 * Rewrites the CV's search records from D1's rows. They depend on every file and on the papers the CV cites,
97 * so the file save, sync_cv and a publication save all call it after they write.
98 */
99export async function refreshCvSearch(env: CvEnv) {
100  const records = await searchRecords(env);
101  await env.DB.batch(replaceSearchRecords(env.DB, contentPageSearchUid("/cv"), records));
102}
103
104export async function writeCvRow(env: CvEnv, compiled: Extract<Awaited<ReturnType<typeof compile>>, { ok: true }>) {
105  await env.DB.prepare(
106    `INSERT INTO cv (slug, type, record, source_path, source_blob_sha, synced_at)
107     VALUES (?1, ?2, ?3, ?4, ?5, unixepoch())
108     ON CONFLICT(slug) DO UPDATE SET type = excluded.type, record = excluded.record,
109       source_path = excluded.source_path, source_blob_sha = excluded.source_blob_sha,
110       synced_at = excluded.synced_at`,
111  )
112    .bind(compiled.record.slug, compiled.record.type, JSON.stringify(compiled.record), compiled.sourcePath, compiled.sourceBlobSha)
113    .run();
114}
115
116/** The row of a file that is gone: the one removal sync_cv makes. */
117export async function deleteCvRow(env: CvEnv, row: { slug: string }) {
118  await env.DB.prepare(`DELETE FROM cv WHERE slug = ?1`).bind(row.slug).run();
119}
120
121/** True when D1's row for the file was compiled from exactly this file (the git blob sha matches). */
122async function rowIsCurrent(env: CvEnv, slug: string, blobSha: string) {
123  const row = await env.DB.prepare("SELECT source_blob_sha FROM cv WHERE slug = ?1").bind(slug).first<{ source_blob_sha: string | null }>();
124  return row?.source_blob_sha === blobSha;
125}
126
127/** A credential that may not write is refused; the CV has no draft state, so there is no first-publication rule. */
128function decide(actor: Actor) {
129  if (!WRITE_CAPABILITIES[actor.kind].write) {
130    throw new PolicyError("Refused: this credential is READ ONLY and may not save a CV file.", "smoke-is-read-only");
131  }
132}
133
134/**
135 * What the save says of the PDF it starts. "scheduled": handed to `background` (ctx.waitUntil), so the save's
136 * answer does not wait for Browser Run and a failure is an alert plus the cv-pdf-drift check, never this answer.
137 * Without a `background` the render is awaited here and the outcome (or the failure) is in the result. Either way
138 * the commit and the D1 row stand.
139 */
140export type CvPdfReport = "scheduled" | "not-needed" | { rendered: CvPdfOutcome } | { failed: string };
141
142/** The CV save. */
143export async function saveCvFile(
144  env: CvEnv,
145  options: {
146    slug: string;
147    raw: string;
148    expectedHeadSha?: string | null;
149    /** The blob sha of this file as Carrel loaded it; undefined means no check. */
150    expectedBlobSha?: string | null;
151    actor: Actor;
152    /** ctx.waitUntil, from the caller that has one: the PDF render runs after the response. */
153    background?: (work: Promise<unknown>) => void;
154  },
155) {
156  const { raw, actor } = options;
157  const { slug, path } = registeredCvFile(options.slug);
158  const existing = await readFile(env, path);
159  if (!existing) throw new CvInvalid(slug, [`${path} is missing from the repository, so the CV file cannot be saved; restore it first`]);
160
161  const compiled = await judge(env, slug, raw);
162  if (!compiled.ok) throw new CvInvalid(slug, compiled.errors);
163  decide(actor);
164
165  const tag = actor.kind === "operator" ? ` [operator:${actor.id}]` : actor.kind === "carrel" ? ` [carrel:${actor.changeId}]` : "";
166  // After the gate, so a file that fails validation is still refused even when it is unchanged.
167  const written = await commitUnlessUnchanged(env, {
168    existing,
169    raw,
170    rowIsCurrent: () => rowIsCurrent(env, slug, compiled.sourceBlobSha),
171    commit: () =>
172      commitFiles(env, {
173        expectedHeadSha: options.expectedHeadSha,
174        expectedBlobs: blobGuard(path, options.expectedBlobSha),
175        message: `Update CV: ${slug}${tag}`,
176        changes: [{ path, content: raw }],
177      }),
178  });
179  if (written.action === "noop") {
180    return {
181      slug,
182      commitSha: written.commitSha,
183      sourceBlobSha: compiled.sourceBlobSha,
184      unchanged: true,
185      note: UNCHANGED_NOTE,
186      purged: null as PurgeOutcome,
187      pdf: "not-needed" as CvPdfReport,
188    };
189  }
190  const { commitSha, blobShas } = written;
191  if (blobShas[path] && blobShas[path] !== compiled.sourceBlobSha) {
192    throw new Error(
193      `The CV file "${slug}" WAS committed as ${commitSha}, but the committed bytes (${blobShas[path]}) are not ` +
194        `the bytes compiled (${compiled.sourceBlobSha}), so its row was not updated. Run the content sync to ` +
195        `rebuild the row from the repository.`,
196    );
197  }
198
199  let purged: PurgeOutcome = false;
200  await convergeWithRetry({
201    write: async () => {
202      await writeCvRow(env, compiled);
203      await refreshCvSearch(env);
204      purged = await purgeCv(`save CV ${slug}`);
205    },
206    // Nothing kept in KV for the CV: the thrown error names the commit and the repair (the content sync), and
207    // the next ship's sync converges the row from the repository anyway.
208    recordDivergence: async () => undefined,
209    slug,
210    commitSha,
211  });
212
213  // After the row, so the render reads the data the save just wrote. Never inside convergeWithRetry: a render
214  // failure must not retry or fail the D1 write, and the commit is not undone by it.
215  let pdf: CvPdfReport;
216  const render = regenerateCvPdfAfterSave(env, `save CV ${slug}`);
217  if (options.background) {
218    options.background(render);
219    pdf = "scheduled";
220  } else {
221    pdf = await render.then(
222      (rendered): CvPdfReport => ({ rendered }),
223      (error): CvPdfReport => ({ failed: error instanceof Error ? error.message : String(error) }),
224    );
225  }
226
227  return { slug, commitSha, sourceBlobSha: compiled.sourceBlobSha, unchanged: written.action !== "commit", purged, pdf };
228}