app/lib/colophon-sections.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/routes/colophon.tsx.

Source

1/*
2 * One list read by both the page and the search index: a record pointing at a
3 * fragment the page no longer has still looks like a hit and scrolls nowhere.
4 * Nothing here reads the clock, filesystem or git; records must be pure.
5 */
6
7export const COLOPHON_URL = "/colophon";
8
9/** Deliberately not the URL: `/colophon` is the IndieWeb convention, but the word is not widely known. */
10export const COLOPHON_TITLE = "How this site is built";
11
12export const COLOPHON_DESCRIPTION =
13  "The stack behind dustinedwards.info: every binding, migration and gate, " +
14  "generated from the repository's own configuration, with what was " +
15  "deliberately not adopted and why.";
16
17/**
18 * The site's versions. WordPress is named for version 2 because the WordPress export's earliest item is
19 * dated 2016-12-05; version 1's platform is not recorded anywhere this repo can read, so it is not named.
20 */
21export const COLOPHON_VERSIONS =
22  "This is the third version of dustinedwards.info. The first launched in 2006, the second, " +
23  "on WordPress, in 2016, and this one in 2026.";
24
25export const COLOPHON_INTRO =
26  "Everything below is generated from this repository's own configuration and " +
27  "checked against it in both directions on every build. If a binding is added " +
28  "and this page is not regenerated, the build fails. The one thing no " +
29  "generator can produce is why each piece is load-bearing, so those notes are " +
30  "written by hand and reconciled against the bindings they describe.";
31
32/**
33 * Order is load-bearing: record `ordinal` is derived from the index here.
34 *
35 * @type {ReadonlyArray<{ id: string, title: string, lead: string }>}
36 */
37export const COLOPHON_SECTIONS = /** @type {const} */ ([
38  {
39    id: "runtime",
40    title: "Runtime",
41    lead:
42      "The compatibility date, the flags the Worker runs under, and the Node " +
43      "version the build is pinned to.",
44  },
45  {
46    id: "bindings",
47    title: "Bindings",
48    lead:
49      "Every resource this Worker holds a handle to, with what it is for and " +
50      "the measurement that put it there rather than a logo wall.",
51  },
52  {
53    id: "schema",
54    title: "Schema",
55    lead:
56      "Hand-written migrations, applied in order. drizzle-kit is deliberately " +
57      "not a dependency, and because the database export command is broken on " +
58      "this schema, this directory is the only copy of the table definitions " +
59      "that exists anywhere.",
60  },
61  {
62    id: "gates",
63    title: "Gates",
64    lead:
65      "Checks that run before anything ships. The list is derived from the " +
66      "scripts themselves rather than maintained beside them, so a gate that " +
67      "is added and forgotten is not possible.",
68  },
69  {
70    id: "dependencies",
71    title: "Dependencies",
72    lead:
73      "The runtime dependencies. Build tooling is excluded: this is what " +
74      "serves the site, not what assembles it.",
75  },
76  {
77    id: "features",
78    title: "What it does",
79    lead:
80      "Nothing in this section can be generated from configuration, so each " +
81      "entry carries an anchor and a gate verifies that the thing the claim is " +
82      "about still exists. It does not verify that the sentence is true, which " +
83      "is the honest boundary of the technique.",
84  },
85  {
86    id: "security",
87    title: "A tradeoff in the security headers",
88    lead:
89      "The content security policy is enforced, not merely reported. One part " +
90      "of it is a compromise rather than a clean win, and the compromise is " +
91      "worth stating plainly.",
92  },
93  {
94    id: "ai",
95    title: "AI disclosure",
96    lead:
97      "This site is built with AI assistance and says so here rather than " +
98      "leaving you to guess, because a site about how it is built owes you " +
99      "that before it owes you anything else.",
100  },
101  {
102    id: "run",
103    title: "How the site is run",
104    lead:
105      "Three other systems of mine sit behind or beside this one. None is part " +
106      "of this repository.",
107  },
108  {
109    id: "not-adopted",
110    title: "What was not adopted",
111    lead:
112      "Anyone can list what they shipped. A refusal is a decision that was " +
113      "made and recorded: not a thing nobody got to, but a thing somebody " +
114      "ruled out, with the reason beside it.",
115  },
116]);
117
118/** @type {ReadonlyArray<string>} */
119export const SECURITY_TRADEOFF = Object.freeze([
120  "Every response carries a one-time number that scripts on the page must " +
121    "quote to be allowed to run. That number is generated per response.",
122  "Seven pages of this site are cached at Cloudflare's edge and served to " +
123    "everyone from the same stored copy for up to ten minutes. The number is " +
124    "part of that copy, so visitors served from one cache entry share it.",
125  "We took that trade deliberately. The alternative is to stop caching those " +
126    "pages, which would make every reader wait for the origin on every visit.",
127  "It is acceptable only because these pages carry no writing from anyone but " +
128    "me. There are no comments and no user submissions, so there is nowhere " +
129    "for a stranger's script to get in and use the shared number.",
130]);
131
132/**
133 * The last sentence is conditional on purpose: provider text marks do not survive
134 * hand editing, so the page must not claim a reader can check for one.
135 *
136 * @type {ReadonlyArray<string>}
137 */
138export const AI_DISCLOSURE = Object.freeze([
139  "The code and the prose here are written with AI assistance. The model is " +
140    "Anthropic's Claude, driven through Claude Code, and it reaches this site " +
141    "through exactly the same publishing API and the same gates a person does.",
142  "Nothing goes public on a model's say-so. Making a post public for the first " +
143    "time is reserved to me and the reservation is enforced in code, not asked " +
144    "for in a prompt: an agent that attempts it is refused by name.",
145  "Every published post has been read and edited by me before it went live, so " +
146    "what you are reading is human-reviewed writing I am answerable for rather " +
147    "than model output passed straight through.",
148  "Where a provider marks its model's output in a machine-readable way, that " +
149    "mark does not survive being edited, so it is not something you can check " +
150    "on this page. The review above is the guarantee instead, which is why it " +
151    "is stated as a practice and not as a badge.",
152]);
153
154/** @type {ReadonlyArray<string>} */
155export const SITE_OPERATION = Object.freeze([
156  "Capsid is the site's memory and job queue. It stores the project's " +
157    "decisions and current state, and it hands work from a conversation to a " +
158    "working session as a signed job that ends in a pull request.",
159]);
160
161/**
162 * Carrel's one sentence. Its name links to its page on this site (Dustin, 2026-09-28), never to the
163 * app, which is private; the footer's Workspace link is the separate sign-in.
164 */
165export const CARREL_PAGE_PATH = "/software/carrel";
166export const CARREL_NAME = "Carrel";
167const CARREL_SENTENCE =
168  "Carrel is my private writing hub, behind a login, where articles are " +
169  "written before they are published here. A finished article reaches this " +
170  "site through a small keyed API.";
171
172/** The sentence after its linked name, which is how the page renders it. */
173export const CARREL_SENTENCE_REST = CARREL_SENTENCE.slice(CARREL_NAME.length);
174
175export const CAPSID_REPO_URL = "https://github.com/DrDustinEdwards/capsid";
176
177/**
178 * Capsomer's one sentence. Its name links to its public site, which answers 200 (checked 2026-10-02).
179 * Capsid's public site, capsid.dustinedwards.info, did not answer then, so Capsid keeps its repository
180 * link until it does (job_a8f7cfc629de).
181 */
182export const CAPSOMER_NAME = "Capsomer";
183export const CAPSOMER_URL = "https://capsomer.dustinedwards.info";
184const CAPSOMER_SENTENCE = "Capsomer is the shared design system this site will adopt.";
185
186/** The sentence after its linked name, which is how the page renders it. */
187export const CAPSOMER_SENTENCE_REST = CAPSOMER_SENTENCE.slice(CAPSOMER_NAME.length);
188
189export const COLOPHON_ANCHORS = COLOPHON_SECTIONS.map((s) => s.id);
190
191/**
192 * `check:features` asserts both directions over this map, so a label no entry
193 * uses fails the gate; add a status here only together with its first entry.
194 *
195 * @type {Record<string, string>}
196 */
197export const STATUS_LABEL = {
198  refused: "Refused",
199};
200
201/**
202 * @param {string} status
203 * @returns {string}
204 */
205export function statusLabel(status) {
206  const label = STATUS_LABEL[status];
207  if (!label) {
208    throw new Error(
209      `no label for not-adopted status "${status}". Add one to STATUS_LABEL, ` +
210        `or the page and the search index would disagree about what it is called.`,
211    );
212  }
213  return label;
214}
215
216/**
217 * @param {any} stack   content/generated/stack.json
218 * @param {any} features content/features.json
219 */
220export function colophonPages(stack, features) {
221  return [colophonPageInput(stack, features)];
222}
223
224/**
225 * @param {any} stack   content/generated/stack.json
226 * @param {any} features content/features.json
227 */
228function colophonPageInput(stack, features) {
229  /** @param {string} id @returns {string} */
230  const contentFor = (id) => {
231    if (id === "runtime") {
232      return [
233        `Compatibility date ${stack.runtime.compatibilityDate}.`,
234        `Compatibility flags ${stack.runtime.compatibilityFlags.join(", ") || "none"}.`,
235        `Node ${stack.runtime.nodeVersion}.`,
236      ].join(" ");
237    }
238    if (id === "bindings") {
239      return stack.bindings
240        .map(
241          (/** @type {any} */ b) =>
242            `${b.name} (${b.kind}). ${b.what} ${b.whyLoadBearing}`,
243        )
244        .join(" ");
245    }
246    if (id === "schema") {
247      return stack.migrations.join(" ");
248    }
249    if (id === "gates") {
250      return stack.gates.join(" ");
251    }
252    if (id === "dependencies") {
253      return stack.dependencies
254        .map((/** @type {any} */ d) => `${d.name} ${d.range}`)
255        .join(" ");
256    }
257    if (id === "features") {
258      return features.features
259        .map((/** @type {any} */ f) => `${f.component}. ${f.name}. ${f.what}`)
260        .join(" ");
261    }
262    if (id === "security") {
263      return SECURITY_TRADEOFF.join(" ");
264    }
265    if (id === "ai") {
266      return AI_DISCLOSURE.join(" ");
267    }
268    if (id === "run") {
269      return `${SITE_OPERATION.join(" ")} ${CARREL_SENTENCE} Capsid's source is public at ${CAPSID_REPO_URL}. ${CAPSOMER_SENTENCE} Its site is ${CAPSOMER_URL}.`;
270    }
271    if (id === "not-adopted") {
272      // The label, never `n.status`: the page shows the label, so the index must.
273      return stack.notAdopted
274        .map(
275          (/** @type {any} */ n) =>
276            `${n.name} (${statusLabel(n.status)}). ${n.reason}`,
277        )
278        .join(" ");
279    }
280    // Fail closed: otherwise a new section is silently indexed as its lead alone.
281    throw new Error(
282      `colophonPageInput has no body rule for section "${id}". ` +
283        `Add one, or the section would be indexed without its content.`,
284    );
285  };
286
287  return {
288    url: COLOPHON_URL,
289    uid: "page:colophon",
290    title: COLOPHON_TITLE,
291    description: COLOPHON_DESCRIPTION,
292    intro: `${COLOPHON_VERSIONS} ${COLOPHON_INTRO}`,
293    sections: COLOPHON_SECTIONS.map((section) => ({
294      anchor: section.id,
295      title: section.title,
296      body: `${section.lead} ${contentFor(section.id)}`,
297    })),
298  };
299}