app/kb/editor.server.ts

Functions

Imports

It imports app/kb/admin.mjs, app/kb/bases.mjs, app/kb/gap-labels.mjs, app/kb/procedures/parse.mjs, app/kb/procedures/save.server.ts, app/kb/registry/catalog.mjs, app/kb/registry/compile.mjs, app/kb/registry/kinds.mjs, app/kb/registry/save.server.ts, app/lib/carrel/errors.server.ts, app/lib/editor/github.server.ts, app/lib/editor/publish-policy.mjs. Imported by app/components/admin/kb-file-editor.tsx, app/components/admin/kb-form.tsx, app/kb/editor-route.server.ts, app/kb/form.server.ts.

Source

1// The admin's Knowledge Base editor (docs/KNOWLEDGE-BASE.md, step 3): one file at a time, an entry (a procedure) or a
2// lab registry item, read from the repository as it stands and saved back through the save the operator API and Carrel
3// already use (saveProcedure, saveRegistryItem). It adds no write path and no second validator: Check runs the save's
4// own checks and commits nothing, and Save is that save, refused when the file changed since it was opened.
5
6import matter from "gray-matter";
7
8import { ContentInvalid } from "~/lib/carrel/errors.server";
9import { GitHubError, readFile } from "~/lib/editor/github.server";
10import { PolicyError, type Actor } from "~/lib/editor/publish-policy.mjs";
11
12import { NEEDS_INFO, tabHref } from "./admin.mjs";
13import { BASES } from "./bases.mjs";
14import { labelGaps } from "./gap-labels.mjs";
15import { procedurePath } from "./procedures/parse.mjs";
16import { compile as compileProcedure, saveProcedure } from "./procedures/save.server";
17import { hasItemPage, itemPath, kindPath } from "./registry/catalog.mjs";
18import { registryPath } from "./registry/compile.mjs";
19import { KINDS } from "./registry/kinds.mjs";
20import { checkRegistryItem, saveRegistryItem } from "./registry/save.server";
21
22type EditorEnv = Env & { GITHUB_TOKEN?: string };
23
24/** What is being edited: an entry by its slug, or a registry item by its kind and id. */
25export type KbTarget = { type: "entry"; slug: string } | { type: "item"; kind: string; id: string };
26
27/** A recorded gap: its path in the file, its reason, and the same place in words with the id of the input it is filled in at. */
28export type KbGap = { field: string; reason: string; label: string; anchor: string };
29
30/** The file as the editor opens it, with what the save's checks say of it now. */
31export type KbFile = {
32  target: KbTarget;
33  /** The repository path, shown so the reader knows which file this is. */
34  file: string;
35  /** The entry's title or the item's name, else its address. */
36  title: string;
37  /** Which list it belongs to: a base's name, or the registry kind's plural. */
38  group: string;
39  /** The admin list it is reached from: its base's tab, or Needs info for a registry item (Inventory waits with step 4). */
40  listHref: string;
41  /** Where its public page or table is, when it has one. */
42  publicHref: string | null;
43  raw: string;
44  /** The git blob sha it was read at: Save is refused if the file has moved on since. */
45  sha: string;
46  errors: string[];
47  gaps: KbGap[];
48};
49
50export type CheckResult = { ok: boolean; errors: string[]; gaps: KbGap[] };
51
52export type SaveResult =
53  | { outcome: "saved"; commitSha: string; unchanged: boolean }
54  | { outcome: "refused"; errors: string[] }
55  | { outcome: "conflict"; message: string };
56
57const slugOf = (target: Extract<KbTarget, { type: "item" }>) => `${target.kind}/${target.id}`;
58
59/** The repository path a target names, or null when it names nothing the Knowledge Base holds. */
60function targetFile(target: KbTarget): string | null {
61  if (target.type === "entry") return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(target.slug) ? procedurePath(target.slug) : null;
62  return KINDS[target.kind] && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(target.id) ? registryPath(slugOf(target)) : null;
63}
64
65/** What Save's checks say of `raw`, without committing anything. */
66export async function checkFile(env: EditorEnv, target: KbTarget, raw: string): Promise<CheckResult> {
67  if (target.type === "entry") {
68    const compiled = await compileProcedure(env, target.slug, raw);
69    const profile = /^profile:\s*["']?([a-z]+)/m.exec(raw)?.[1] ?? "protocol";
70    return { ok: compiled.ok, errors: compiled.ok ? [] : compiled.errors, gaps: labelGaps(compiled.gaps ?? [], profile) };
71  }
72  const compiled = await checkRegistryItem(env, slugOf(target), raw);
73  return { ok: compiled.ok, errors: compiled.ok ? [] : compiled.errors, gaps: labelGaps(compiled.ok ? compiled.gaps : [], null) };
74}
75
76/** The file from the repository and its checks, or null when there is no such file. */
77export async function loadFile(env: EditorEnv, target: KbTarget): Promise<KbFile | null> {
78  const file = targetFile(target);
79  if (!file) return null;
80  const read = await readFile(env, file);
81  if (!read) return null;
82  const checked = await checkFile(env, target, read.content);
83  // The front matter as written, for the heading only: a file that fails its checks still opens, with its errors.
84  let data: Record<string, unknown> = {};
85  try {
86    data = matter(read.content, {}).data;
87  } catch {
88    data = {};
89  }
90  const text = (value: unknown) => (typeof value === "string" && value.trim() !== "" ? value : null);
91
92  if (target.type === "entry") {
93    const base = BASES.find((b) => b.profile === data.profile);
94    return {
95      target,
96      file,
97      title: text(data.title) ?? target.slug,
98      group: base?.name ?? "Entries",
99      listHref: tabHref(base?.id ?? NEEDS_INFO),
100      publicHref: text(data.path),
101      raw: read.content,
102      sha: read.sha,
103      ...checked,
104    };
105  }
106  const spec = KINDS[target.kind];
107  return {
108    target,
109    file,
110    title: text(data.name) ?? slugOf(target),
111    group: spec ? spec.plural.charAt(0).toUpperCase() + spec.plural.slice(1) : target.kind,
112    listHref: tabHref(NEEDS_INFO),
113    publicHref: hasItemPage(target.kind) ? itemPath(target.kind, target.id) : kindPath(target.kind),
114    raw: read.content,
115    sha: read.sha,
116    ...checked,
117  };
118}
119
120/** Save through the one save for the target's kind, refused if the file moved since `expectedBlobSha` was read. */
121export async function saveFile(env: EditorEnv, target: KbTarget, raw: string, expectedBlobSha: string, actor: Actor): Promise<SaveResult> {
122  try {
123    const saved =
124      target.type === "entry"
125        ? await saveProcedure(env, { slug: target.slug, raw, expectedBlobSha, isNew: false, actor })
126        : await saveRegistryItem(env, { slug: slugOf(target), raw, expectedBlobSha, isNew: false, actor });
127    return { outcome: "saved", commitSha: saved.commitSha, unchanged: saved.unchanged };
128  } catch (error) {
129    if (error instanceof ContentInvalid) return { outcome: "refused", errors: error.errors };
130    if (error instanceof PolicyError) return { outcome: "refused", errors: [error.message] };
131    if (error instanceof GitHubError && error.conflict) return { outcome: "conflict", message: error.message };
132    throw error;
133  }
134}