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

Functions

Imports

It imports app/lib/carrel/content-kinds.server.ts, app/lib/carrel/errors.server.ts, app/lib/editor/github.server.ts, app/lib/llms/save.server.ts, app/lib/llms/validate.mjs. Imported by app/lib/carrel/site-adapter.server.ts.

Source

1// The "document" kind of Carrel's content group (docs/LLMS.md): today one record, `document.llms`, the
2// content/llms.txt file /llms.txt is served from. Every write is saveLlms, the one llms.txt save, so an edit
3// through Carrel is validated by the code CI runs, committed, written to D1 and live on the next request with
4// no deploy. A document has no draft state: it is always published, so saveDraft and publish are the same
5// save (a save to a live document edits it live, as a save to a live page does), and it cannot be
6// unpublished or created here. It has no preview: the page is plain text, and there is nothing rendered.
7
8import { RefusedError, VersionConflictError } from "@dustinedwards/site-api";
9import type { ContentSummary, WriteResult } from "@dustinedwards/site-api";
10
11import type { ContentKindHandler } from "~/lib/carrel/content-kinds.server";
12import { asSiteApiError } from "~/lib/carrel/errors.server";
13import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
14import { saveLlms } from "~/lib/llms/save.server";
15import { LLMS_PATH } from "~/lib/llms/validate.mjs";
16
17type DocumentEnv = Env & { GITHUB_TOKEN?: string };
18
19/** The one slug of the kind. `document.llms` is the id Carrel sees. */
20const LLMS_SLUG = "llms";
21
22const TITLE = "llms.txt";
23const PUBLIC_PATH = "/llms.txt";
24
25/** A revision's version is a commit sha; an item's own version is the blob sha of its file. */
26
27export function documentHandler(env: DocumentEnv): ContentKindHandler {
28  /** A write names the one document, or is refused with the reason. */
29  function target(slug: string) {
30    if (slug !== LLMS_SLUG) {
31      throw new RefusedError(`"${slug}" names no document. The only document is "${LLMS_SLUG}" (${LLMS_PATH}); a save cannot create another.`);
32    }
33  }
34
35  /** One write through saveLlms as the Carrel actor, answered in the package's terms. */
36  async function write(slug: string, changeId: string, raw: string, expectedVersion: string | null): Promise<WriteResult> {
37    try {
38      const saved = await saveLlms(env, { raw, expectedBlobSha: expectedVersion ?? undefined, actor: { kind: "carrel", changeId } });
39      return { id: slug, version: saved.sourceBlobSha, status: "published", changeId };
40    } catch (error) {
41      return asSiteApiError(env, error, LLMS_PATH);
42    }
43  }
44
45  /** The stored file; a write that names a version for a missing file is a conflict. */
46  async function existing() {
47    const file = await readFile(env, LLMS_PATH);
48    if (!file) throw new VersionConflictError(null);
49    return file.content;
50  }
51
52  /** A save, which is also the publish: the document has no state to change. */
53  async function save(slug: string, input: { changeId: string; source?: string; expectedVersion: string | null }) {
54    target(slug);
55    const stored = await readFile(env, LLMS_PATH);
56    // The file always exists, so a save that names no version is a conflict, as a page's is.
57    if (input.expectedVersion === null && stored) throw new VersionConflictError(stored.sha);
58    if (input.expectedVersion !== null && !stored) throw new VersionConflictError(null);
59    if (!stored) throw new RefusedError(`${LLMS_PATH} is missing from the repository, so it cannot be saved.`);
60    return write(slug, input.changeId, input.source ?? stored.content, input.expectedVersion);
61  }
62
63  return {
64    kind: "document",
65
66    async list(query) {
67      const needle = query.q?.toLowerCase();
68      const summary: ContentSummary = {
69        id: LLMS_SLUG,
70        kind: "document",
71        title: TITLE,
72        status: "published",
73        path: PUBLIC_PATH,
74        publishAt: null,
75        publishedAt: null,
76        // The settings row carries no timestamp, and the file's last change is the revision list.
77        updatedAt: null,
78      };
79      const matches = (!query.status || query.status === "published") && (!needle || TITLE.includes(needle) || LLMS_SLUG.includes(needle));
80      return matches ? [summary] : [];
81    },
82
83    async get(slug) {
84      if (slug !== LLMS_SLUG) return null;
85      const file = await readFile(env, LLMS_PATH);
86      if (!file) return null;
87      return {
88        id: LLMS_SLUG,
89        kind: "document",
90        title: TITLE,
91        status: "published",
92        path: PUBLIC_PATH,
93        publishAt: null,
94        publishedAt: null,
95        updatedAt: null,
96        format: "markdown",
97        source: file.content,
98        version: file.sha,
99      };
100    },
101
102    saveDraft: (slug, input) => save(slug, input),
103
104    async publish(slug, input) {
105      target(slug);
106      // Read even when source is sent: a version for a missing file is a conflict.
107      const stored = await existing();
108      return write(slug, input.changeId, input.source ?? stored, input.expectedVersion);
109    },
110
111    async unpublish() {
112      throw new RefusedError(`${TITLE} cannot be unpublished: it is the document agents read first, and it has no draft state.`);
113    },
114
115    revisions(slug) {
116      return fileRevisions(env, slug === LLMS_SLUG ? LLMS_PATH : null);
117    },
118
119    revisionSource(slug, version) {
120      return fileRevisionSource(env, slug === LLMS_SLUG ? LLMS_PATH : null, version);
121    },
122  };
123}