app/lib/carrel/procedure-handler.server.ts

Functions

Imports

It imports app/db/procedures.ts, app/kb/procedures/parse.mjs, app/kb/procedures/save.server.ts, app/lib/carrel/content-kinds.server.ts, app/lib/carrel/errors.server.ts, app/lib/carrel/front-matter-lines.ts, app/lib/editor/github.server.ts. Imported by app/lib/carrel/site-adapter.server.ts.

Source

1// The "procedure" kind of Carrel's content group (docs/PROCEDURES.md): the lab protocols under
2// content/procedures. The id is `procedure.<slug>`. Every read is the operator API's (listProceduresForOperator,
3// the file itself) and every write is saveProcedure, the one procedure save, so a procedure saved through
4// Carrel is compiled by the code CI runs, committed, written to D1 and live on the next request with no deploy.
5// A procedure has no publish time and no preview route, so it is neither scheduled nor previewed.
6
7import { VersionConflictError } from "@dustinedwards/site-api";
8import type { ContentStatus, ContentSummary, WriteResult } from "@dustinedwards/site-api";
9
10import { listProceduresForOperator } from "~/db/procedures";
11import type { ContentKindHandler } from "~/lib/carrel/content-kinds.server";
12import { asSiteApiError } from "~/lib/carrel/errors.server";
13import { withPublication } from "~/lib/carrel/front-matter-lines";
14import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
15import { parseProcedure, procedurePath } from "~/kb/procedures/parse.mjs";
16import { saveProcedure } from "~/kb/procedures/save.server";
17
18type ProcedureEnv = Env & { GITHUB_TOKEN?: string };
19
20/** A revision's version is a commit sha; an item's own version is the blob sha of its file. */
21
22/** Whether a stored file is a draft, read from the file itself, the only authority. */
23const fileIsDraft = (raw: string) => parseProcedure({ file: "", raw }).data.draft === true;
24
25/** The source with its draft flag set to `draft`, touching no line when it already says so. */
26const withDraft = (raw: string, draft: boolean) => (fileIsDraft(raw) === draft ? raw : withPublication(raw, { draft }));
27
28/** A date the file wrote, as the ISO instant a summary carries; null when the file wrote none. */
29function isoDay(value: unknown): string | null {
30  if (typeof value !== "string") return null;
31  const at = Date.parse(value);
32  return Number.isNaN(at) ? null : new Date(at).toISOString();
33}
34
35export function procedureHandler(env: ProcedureEnv): ContentKindHandler {
36  /** One write through saveProcedure as the Carrel actor, answered in the package's terms. */
37  async function write(slug: string, changeId: string, raw: string, expectedVersion: string | null): Promise<WriteResult> {
38    try {
39      const saved = await saveProcedure(env, {
40        slug,
41        raw,
42        expectedBlobSha: expectedVersion ?? undefined,
43        isNew: expectedVersion === null,
44        actor: { kind: "carrel", changeId },
45      });
46      return { id: slug, version: saved.sourceBlobSha, status: saved.draft ? "draft" : "published", changeId };
47    } catch (error) {
48      // A ProcedureInvalid carries every message the validator gave; asSiteApiError passes them on.
49      return asSiteApiError(env, error, procedurePath(slug));
50    }
51  }
52
53  /** The stored file for a write that names a version; a version for a missing id is a conflict. */
54  async function existing(slug: string): Promise<string> {
55    const file = await readFile(env, procedurePath(slug));
56    if (!file) throw new VersionConflictError(null);
57    return file.content;
58  }
59
60  return {
61    kind: "procedure",
62
63    async list(query) {
64      const needle = query.q?.toLowerCase();
65      const summaries: ContentSummary[] = (await listProceduresForOperator(env)).map((row) => {
66        const status: ContentStatus = row.draft ? "draft" : "published";
67        return {
68          id: row.slug,
69          kind: "procedure",
70          title: row.title,
71          status,
72          path: row.draft ? null : row.path,
73          publishAt: null,
74          publishedAt: null,
75          updatedAt: isoDay(row.updated),
76        };
77      });
78      return summaries
79        .filter((s) => !query.status || s.status === query.status)
80        .filter((s) => !needle || s.title.toLowerCase().includes(needle) || s.id.includes(needle));
81    },
82
83    async get(slug) {
84      const file = await readFile(env, procedurePath(slug));
85      if (!file) return null;
86      const { data } = parseProcedure({ file: procedurePath(slug), raw: file.content });
87      const draft = data.draft === true;
88      return {
89        id: slug,
90        kind: "procedure",
91        title: typeof data.title === "string" ? data.title : slug,
92        status: draft ? "draft" : "published",
93        path: draft || typeof data.path !== "string" ? null : data.path,
94        publishAt: null,
95        publishedAt: null,
96        updatedAt: isoDay(data.updated),
97        format: "markdown",
98        source: file.content,
99        version: file.sha,
100      };
101    },
102
103    // Keeps the stored status, as a post does: a save to a live procedure edits it live, and a new one starts
104    // as a draft. First publication is a separate call, which Carrel's key may make.
105    async saveDraft(slug, input) {
106      const file = await readFile(env, procedurePath(slug));
107      if (input.expectedVersion === null && file) throw new VersionConflictError(file.sha);
108      if (input.expectedVersion !== null && !file) throw new VersionConflictError(null);
109      const raw = withDraft(input.source, file ? fileIsDraft(file.content) : true);
110      return write(slug, input.changeId, raw, input.expectedVersion);
111    },
112
113    async publish(slug, input) {
114      // Read even when source is sent: a version for an id that does not exist is a conflict.
115      const stored = await existing(slug);
116      return write(slug, input.changeId, withDraft(input.source ?? stored, false), input.expectedVersion);
117    },
118
119    async unpublish(slug, input) {
120      const source = await existing(slug);
121      return write(slug, input.changeId, withDraft(source, true), input.expectedVersion);
122    },
123
124    revisions(slug) {
125      return fileRevisions(env, procedurePath(slug));
126    },
127
128    revisionSource(slug, version) {
129      return fileRevisionSource(env, procedurePath(slug), version);
130    },
131  };
132}