app/kb/form.server.ts

Functions

Imports

It imports app/db/registry.ts, app/kb/bases.mjs, app/kb/editor.server.ts, app/kb/form-fields.mjs, app/kb/form.mjs, app/kb/procedures/save.server.ts, app/kb/registry/kinds.mjs, app/lib/editor/publish-policy.mjs, app/lib/phage-tools.mjs. Imported by app/components/admin/kb-form-fields.tsx, app/components/admin/kb-form-steps.tsx, app/components/admin/kb-form.tsx, app/kb/editor-route.server.ts, app/routes/admin.kb.preview.tsx.

Source

1// The Knowledge Base form editor's server half (docs/KNOWLEDGE-BASE.md): the form a file opens as, with the lists its
2// pickers choose from; the file a submitted form describes, which then goes through the same Check and Save as the raw
3// editor (editor.server.ts); and Duplicate, a new draft copied from an entry that records where it came from.
4
5import matter from "gray-matter";
6
7import { listRegistry } from "~/db/registry";
8import type { Actor } from "~/lib/editor/publish-policy.mjs";
9import { TOOLS } from "~/lib/phage-tools.mjs";
10
11import { BASES } from "./bases.mjs";
12import type { KbFile } from "./editor.server";
13import { entryFields, gapReason, itemFields, type FieldSpec } from "./form-fields.mjs";
14import { fileToForm, formToFile, STEP_FLAGS, type FormModel } from "./form.mjs";
15import { compile as compileProcedure, saveProcedure } from "./procedures/save.server";
16import { KINDS } from "./registry/kinds.mjs";
17
18
19type FormEnv = Env & { GITHUB_TOKEN?: string };
20
21export type Choice = { value: string; label: string };
22
23/** A field as the page draws it: its spec, and for a YAML field the text it opens with. */
24export type FormField = FieldSpec & { yaml?: string; gap?: string | null };
25
26export type KbForm = {
27  model: FormModel;
28  fields: FormField[];
29  /** The registry's items, by kind, for the pickers. */
30  registry: Record<"reagent" | "equipment" | "primer" | "strain", Choice[]>;
31  flags: readonly string[];
32  /** What a step note or a reagent can point at, by name: the troubleshooting table's rows, the calculators, the solutions. */
33  references: Record<"troubleshooting" | "calculators" | "solutions", Choice[]>;
34};
35
36/** A value as YAML text, for a field the form edits as YAML. */
37function yamlText(value: unknown): string {
38  if (value === undefined || value === null) return "";
39  return matter
40    .stringify("", { v: value })
41    .replace(/^---\n/, "")
42    .replace(/\n---\n*$/, "")
43    .replace(/^v:\s?/, "")
44    .replace(/^ {2}/gm, "")
45    .trim();
46}
47
48/** YAML text back into a value; the text is what a person typed, so a mistake is said, not thrown. */
49function readYaml(key: string, text: string): { value: unknown } | { error: string } {
50  if (text.trim() === "") return { value: undefined };
51  try {
52    const indented = text.split("\n").map((line) => `  ${line}`).join("\n");
53    return { value: (matter(`---\nv:\n${indented}\n---\n`).data as { v: unknown }).v };
54  } catch (error) {
55    return { error: `${key} is not valid YAML: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}` };
56  }
57}
58
59/** The form a file opens as. */
60export async function formFor(env: FormEnv, file: KbFile): Promise<KbForm> {
61  const items = await listRegistry(env);
62  const of = (kind: string) => items.filter((i) => i.kind === kind).map((i) => ({ value: i.id, label: i.status === "draft" ? `${i.name} (draft)` : i.name }));
63  const registry = { reagent: of("reagent"), equipment: of("equipment"), primer: of("primer"), strain: of("strain") };
64  const model = fileToForm(file.raw, { body: file.target.type === "entry" });
65  const specs =
66    file.target.type === "entry"
67      ? entryFields(String(model.data.profile ?? "protocol"), model.data, registry.strain)
68      : itemFields(Object.keys(KINDS[file.target.kind]?.fields ?? {}), model.data);
69  const fields = specs.map((spec) => ({
70    ...spec,
71    gap: gapReason(model.data[spec.key]),
72    // A gap opens empty, its reason beside it, like any other input; left empty, it keeps the gap (rawFromForm).
73    ...(spec.kind === "yaml" || spec.kind === "readonly" ? { yaml: gapReason(model.data[spec.key]) ? "" : yamlText(model.data[spec.key]) } : {}),
74  }));
75  return { model, fields, registry, flags: STEP_FLAGS, references: referencesOf(model.data) };
76}
77
78/** The rows of a list field that have an id. */
79function rowsOf(rows: unknown): Array<Record<string, unknown>> {
80  return Array.isArray(rows) ? rows.filter((r): r is Record<string, unknown> => Boolean(r) && typeof r === "object" && typeof (r as { id?: unknown }).id === "string") : [];
81}
82
83/** What a step note or a reagent row can name, each by its words: a row's step and problem, a calculator's title, a solution's name. */
84function referencesOf(data: Record<string, unknown>): KbForm["references"] {
85  return {
86    troubleshooting: rowsOf(data.troubleshooting).map((row) => ({ value: String(row.id), label: `Step ${String(row.step ?? "?")}: ${String(row.problem ?? row.id)}` })),
87    calculators: Object.entries(TOOLS).map(([value, tool]) => ({ value, label: tool.title })),
88    solutions: rowsOf(data.solutions).map((row) => ({ value: String(row.id), label: String(row.name ?? row.id) })),
89  };
90}
91
92/**
93 * The file a submitted form describes, written over the file it was opened from. A field the form sent as YAML text
94 * ({ "$yaml": text }) is read here; text that is not YAML is a refusal with its reason, and nothing is written.
95 */
96export function rawFromForm(original: string, posted: string): { raw: string } | { errors: string[] } {
97  let model: FormModel;
98  try {
99    model = JSON.parse(posted) as FormModel;
100  } catch {
101    return { errors: ["The form could not be read. Reload the page and make the edit again."] };
102  }
103  const errors: string[] = [];
104  const data: Record<string, unknown> = {};
105  let before: Record<string, unknown> | null = null;
106  for (const [key, value] of Object.entries(model.data ?? {})) {
107    if (value && typeof value === "object" && !Array.isArray(value) && "$yaml" in value) {
108      const read = readYaml(key, String((value as { $yaml: unknown }).$yaml ?? ""));
109      before ??= fileToForm(original, { body: false }).data;
110      if ("error" in read) errors.push(read.error);
111      // Left empty, a field that held a gap keeps it: an empty box is not an answer.
112      else data[key] = read.value === undefined && gapReason(before[key]) ? before[key] : read.value;
113    } else data[key] = value;
114  }
115  if (errors.length > 0) return { errors };
116  try {
117    return { raw: formToFile(original, { ...model, data }) };
118  } catch (error) {
119    return { errors: [error instanceof Error ? error.message : String(error)] };
120  }
121}
122
123const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
124
125/** A slug from a title: lower-case words joined by hyphens. */
126function slugFor(title: string): string {
127  return title
128    .normalize("NFKD")
129    .replace(/[\u0300-\u036f]/g, "")
130    .toLowerCase()
131    .replace(/[^a-z0-9]+/g, "-")
132    .replace(/^-+|-+$/g, "")
133    .slice(0, 60)
134    .replace(/-+$/, "");
135}
136
137export type DuplicateResult = { outcome: "created"; slug: string } | { outcome: "refused"; errors: string[] };
138
139/**
140 * A new draft entry copied from `from`: the same profile and steps, a new title and address, and `forked_from` naming the
141 * entry and version it was copied at. What belongs to the original alone is left behind: its versions and their history,
142 * its place in the Start here list, and the papers and phages that prove it, since the variant has none of them yet.
143 */
144export async function duplicateEntry(
145  env: FormEnv,
146  from: { slug: string; raw: string },
147  wanted: { title: string; slug: string },
148  actor: Actor,
149): Promise<DuplicateResult> {
150  const title = wanted.title.trim();
151  const slug = (wanted.slug.trim() || slugFor(title)).toLowerCase();
152  const errors: string[] = [];
153  if (!title) errors.push("The copy needs a title.");
154  if (!SLUG.test(slug)) errors.push(`"${slug}" is not a file name: use lower-case letters, digits and hyphens.`);
155  if (slug === from.slug) errors.push("The copy needs a file name of its own.");
156  if (errors.length > 0) return { outcome: "refused", errors };
157
158  const model = fileToForm(from.raw);
159  const profile = String(model.data.profile ?? "protocol");
160  const base = BASES.find((b) => b.profile === profile);
161  const version = typeof model.data.version === "string" && !gapReason(model.data.version) ? model.data.version : null;
162  const data: Record<string, unknown> = {
163    ...model.data,
164    title,
165    seo_title: title,
166    path: `${base?.entryRoot ?? "/research/protocols/"}${slug}`,
167    draft: true,
168    version: "MISSING: A new variant; no version has been assigned yet.",
169    forked_from: version ? { slug: from.slug, version } : { slug: from.slug },
170    history: undefined,
171    start_here: undefined,
172    proof_of_use: undefined,
173  };
174  const raw = formToFile(from.raw, { ...model, data });
175  const checked = await compileProcedure(env, slug, raw);
176  if (!checked.ok) return { outcome: "refused", errors: checked.errors };
177  try {
178    await saveProcedure(env, { slug, raw, isNew: true, actor });
179  } catch (error) {
180    const listed = (error as { errors?: string[] }).errors;
181    if (Array.isArray(listed)) return { outcome: "refused", errors: listed };
182    throw error;
183  }
184  return { outcome: "created", slug };
185}