@anja.codes/vitakit 0.1.0 → 0.3.0

package/README.md

@@ -1,159 +1,80 @@
 # @anja.codes/vitakit
 
-Structured CV data in, academic website and LaTeX CV out.
+Your academic website and CV, from one set of files. Write your CV once, as
+YAML, Markdown and BibTeX; vitakit makes a static website from it and a typeset
+LaTeX CV — kept in sync, validated, and yours to change.
 
 ```bash
 pnpm create @anja.codes/vitakit my-site
 cd my-site && pnpm install
-pnpm dev            # the website
-pnpm build:cv       # cv-tex/cv.pdf, from the same data
+pnpm dev                # the website, at http://localhost:3000
+pnpm pdf                # cv-tex/cv.pdf, from the same data
+pnpm vitakit status     # what is in the project, and where it appears
 ```
 
-To add it to an existing Nuxt project instead:
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@anja.codes/vitakit/nuxt'],
-})
-```
-
-## Documentation
-
-[Getting started](./docs/getting-started.md) ·
-[Content reference](./docs/content-reference.md) ·
-[Commands](./docs/cli.md) ·
-[Customising](./docs/customising.md) ·
-[CV documents](./docs/cv-documents.md) ·
-[Privacy](./docs/privacy.md) ·
-[Troubleshooting](./docs/troubleshooting.md)
+**Documentation: [vitakit.anja.codes](https://vitakit.anja.codes)** — a
+[tutorial](https://vitakit.anja.codes/guide/tutorial/) from an empty directory to a
+published site, [concepts](https://vitakit.anja.codes/guide/concepts),
+[how do I …?](https://vitakit.anja.codes/guide/how-do-i), and references for the
+[command](https://vitakit.anja.codes/cli/),
+[content](https://vitakit.anja.codes/content/),
+[website](https://vitakit.anja.codes/website/) and
+[PDF](https://vitakit.anja.codes/pdf/). The source is in [`docs/`](./docs).
 
 ## What it does
 
-`content/` is compiled at build time into a typed module. Markdown and TeX are
-rendered with remark and KaTeX, BibTeX with citation-js, and every file is
-validated with Zod. Nothing content-related reaches the browser: no Markdown
-parser, no content database, no KaTeX runtime.
-
 ```
 content/
-  profile.yml           name, affiliation, links, navigation, footer
+  profile.yml           name, affiliation, links, menu, footer
   <section>.yml         education, employment, teaching, talks, …
-  publications.bib      grouped, linked reference list
-  publications.csl      optional: its citation style on the website
-  pages/*.md            prose pages, math and images included
-schemas/<section>.ts    optional: change a built-in schema, or add your own
-schemas/publications.ts optional: publication groups, badges, fields
+  publications.bib      your publications, formatted and linked
+  publication-lists.yml which of them each list shows: recent, preprints, by year, …
+  pages/*.md            prose pages, mathematics and images included
+schemas/<section>.ts    optional: what a section of your own may contain
+app/pages/*.vue         which sections and lists each website page shows
+cv-tex/<document>.tex   which sections and lists each PDF shows; cv-tex/<document>.yml selects entries
 ```
 
-## Composables
-
-| | |
-|---|---|
-| `useSection(id)` | validated, sorted, visibility-filtered entries |
-| `usePublications()` | reference groups; each entry has its formatted `html` and its `badges` as data |
-| `usePage(route)`, `usePages()` | compiled Markdown pages |
-| `useProfile()` | everything in `profile.yml`, including `nav` |
-| `useVitakit()` | everything, including `issues` |
-
-## Components
-
-`VitaSection`, `VitaEntry`, `VitaDate`, `VitaLinks`, `VitaPublications`,
-`VitaPublication`, `VitaMarkdown`, `VitaIssues`. All are thin: they take props and emit markup, so
-ejecting one into your own repo leaves nothing behind that can silently break.
-
-## Sections
-
-A file `content/<name>.yml` is a section. Its schema is found by convention:
-`schemas/<name>.ts` in your repo wins, otherwise the built-in schema for
-`<name>` is used, otherwise the build fails with a starter snippet.
+- **Validated content.** Every file is checked against its schema. A broken
+  file fails the build, naming the file, the entry and the field; during
+  `nuxt dev` it is reported in place, and fixing it recovers without a restart.
+- **Nothing content-related in the browser.** Markdown, mathematics (KaTeX) and
+  citations (citation-js) are rendered at build time into static HTML.
+- **Private stays private.** Entries marked `cv` or `private` never reach the
+  website, and `pnpm check` verifies that none did.
+- **The PDF** is LaTeX you own: `cv-tex/cv.tex` orders sections, Eta templates
+  write entries, `latexmk` typesets — no `-shell-escape`, no Python.
+- **The `vitakit` command** shows what is where (`status`, `explain`), checks
+  everything without building (`validate`), and sets up sections, fields and
+  pages (`add`, `customize`), showing every change before it makes it.
+
+To use it in an existing Nuxt project:
 
 ```ts
-// schemas/outreach.ts
-import { section, dateRange, richText, institution } from '@anja.codes/vitakit'
-
-export default section({
-  date: dateRange,
-  title: richText,          // Markdown and $math$ allowed
-  venue: institution.optional(),
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@anja.codes/vitakit/nuxt'],
 })
 ```
 
-Every entry gets `visibility: public | cv | private`. The website loader is
-hard-wired to `public`, so a phone number, an address or a referee marked `cv`
-cannot reach the site; the other levels exist for the LaTeX side. Assume the
-repository itself is private, and let `vitakit-check` verify the build output.
-
-PDFs are never part of the website build: `build:cv` writes to `cv-tex/`, and
-the website renders CV information directly from the same data.
-
-## Strict builds, forgiving development
-
-A broken file fails `nuxt generate`, naming the file, the entry and the field.
-The same problem during `nuxt dev` is reported instead of thrown: the page shows
-its error, `VitaIssues` lists all of them, and saving a fix recovers in place —
-a typo never takes down the dev server.
-
-## Status
-
-Early but complete in both halves: website and PDF are produced from the same
-content, with strict builds, forgiving development, output assertions and a
-scaffolder whose output is regenerated and tested in CI.
-
-Not yet implemented: cover-letter helpers (`\vitacount`, `\vitafirst`), a
-`schema` command to draft a schema from existing YAML, a second theme, and a
-Typst target.
-
-MIT
-
-## LaTeX CV
+## Development
 
 ```bash
-pnpm build:cv          # every document in cv-tex/
-pnpm build:cv cv       # one document
-pnpm build:cv --no-pdf # only generate .tex
-```
-
-A **document** is a `.tex` file you own. vitakit renders `content/` into
-`cv-tex/generated/<document>/`, one file per section, and `latexmk` typesets it.
-No `-shell-escape`, no Python.
-
-```tex
-\documentclass{vitakit-cv}
-\vitadocument{cv}
-\addbibresource{../content/publications.bib}
-\input{preamble.tex}
-\input{generated/cv/profile.tex}
-
-\begin{document}
-\vitaheader
-\vitasection{employment}     % order lives here: move a line, move a section
-\vitasection{education}
-\section{Publications}\vitainput{publications}
-\end{document}
-```
-
-An optional `cv-tex/<name>.yml` decides *what* goes in:
-
-```yaml
-visibility: cv        # include public and cv entries, not private
-sections:
-  talks:
-    where: { kind: invited }
-    limit: 10
+pnpm install
+pnpm check          # typecheck, build, tests, and the scaffolded example
+pnpm docs:dev       # the documentation site
 ```
 
-Copy `cv.tex` to make a variant; a document is just a file. Generated files use
-only the macros in `vitakit-cv.cls` (`\vitaentry`, `\vitanote`, `\vitasection`),
-so redefining those in `preamble.tex` restyles everything. Any template can be
-overridden by putting a file of the same name in `cv-tex/templates/`.
+To release, set one version everywhere it must match, commit, and push a tag:
+`node scripts/release.mjs set 0.2.0`, then `git tag v0.2.0 && git push --tags`.
+The `Release` workflow checks the versions, runs `pnpm check`, and publishes
+both packages to npm with trusted publishing.
 
-## Starting a project
+The creator lives in [`create/`](./create); its output is kept in
+[`examples/scaffolded`](./examples/scaffolded), regenerated by `pnpm example`
+and verified in CI, so it cannot drift from the package.
 
-```bash
-pnpm create @anja.codes/vitakit my-site
-```
+Not yet implemented: cover-letter helpers (`\vitacount`, `\vitafirst`), a
+second theme, and a Typst target.
 
-See [`@anja.codes/create-vitakit`](./create). The scaffolded output is kept in
-[`examples/scaffolded`](./examples/scaffolded), regenerated by
-`pnpm example` and verified in CI, so it cannot drift from the package.
+MIT

package/dist/check.mjs

@@ -1,25 +1,33 @@
 import { readFile, stat, readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-import { l as loadContent } from './shared/vitakit.CypCF-4Q.mjs';
-import { M as MARKER_KEY, k as atMost } from './shared/vitakit.BxcnlFGP.mjs';
-import { r as richSource, a as richHtml } from './shared/vitakit.BlU-p01e.mjs';
+import { l as loadContent } from './shared/vitakit.DteA9vLy.mjs';
+import { M as MARKER_KEY } from './shared/vitakit.DvABWuUc.mjs';
+import { a as richSource, r as richHtml } from './shared/vitakit.CtChKO0I.mjs';
+import { a as atMost } from './shared/vitakit.TSMTC5Jl.mjs';
 import 'gray-matter';
 import 'yaml';
+import './chunks/bibliography.mjs';
+import 'node:fs';
+import './shared/vitakit.DQ6PmGoL.mjs';
+import 'node:url';
+import '@behackl/citation-js-extras';
 import 'unified';
+import 'rehype-parse';
+import 'rehype-sanitize';
+import 'rehype-stringify';
 import 'remark-parse';
 import 'remark-gfm';
 import 'remark-math';
 import 'remark-rehype';
 import 'rehype-katex';
 import 'rehype-raw';
-import 'rehype-stringify';
 import 'unist-util-visit';
-import 'node:fs';
-import '@behackl/citation-js-extras';
-import 'rehype-parse';
-import 'rehype-sanitize';
+import './shared/vitakit.DCK90zq4.mjs';
 import 'zod';
-import 'node:url';
+import './chunks/publication-lists.mjs';
+import './shared/vitakit.D10HyDhF.mjs';
+import './chunks/sections.mjs';
+import './chunks/schemas.mjs';
 
 async function exists(path) {
   return stat(path).then(() => true, () => false);
@@ -139,7 +147,8 @@ async function checkStatic(options) {
     let hidden = 0;
     let leaked = 0;
     for (const [id, entries] of Object.entries(content.sections)) {
-      for (const [index, entry] of entries.entries()) {
+      for (const entry of entries) {
+        const index = Number(entry.id.slice(id.length + 1));
         if (atMost(entry.visibility, "public")) continue;
         hidden += 1;
         const fragments = identifyingText(entry);
@@ -183,7 +192,7 @@ async function checkStatic(options) {
     }
     checked.push("links into the site lead somewhere");
   }
-  if (content.publications.length) {
+  if (Object.values(content.publications).some((list) => list.count)) {
     const bibPages = [...pages].filter(([, html]) => html.includes("vita-bib"));
     for (const [file, html] of bibPages) {
       if (/bibmathplaceholderx*\d+end/i.test(html)) fail(`${relative(outDir, file)}: a formula in the bibliography was not rendered`);

package/dist/chunks/authoring.mjs

@@ -0,0 +1,372 @@
+import { parse } from 'yaml';
+import { p as propertyKey, a as addSchemaField, e as ensurePackageImports } from '../shared/vitakit.CCTDg7pz.mjs';
+import { c as findPdfPublicationPlacements, f as findPdfPlacements } from '../shared/vitakit.DvvUYUTS.mjs';
+import { a as escapeTex } from '../shared/vitakit.DcQOdM4I.mjs';
+import { b as insertLinesAfter, i as indentationAt, c as insertLinesBefore } from '../shared/vitakit.UfoXdL7U.mjs';
+import { addPublicationsToPage, publicationsElementSource, addSectionToPage, sectionElementSource } from './vue.mjs';
+import { addNavItem, yamlScalar } from './yaml.mjs';
+import { C as CommandError } from '../shared/vitakit.zwr1ssO5.mjs';
+import '@babel/parser';
+import 'node:fs/promises';
+import 'node:path';
+import '@vue/compiler-sfc';
+import 'node:fs';
+import '../shared/vitakit.DQ6PmGoL.mjs';
+import 'node:url';
+import 'node:process';
+import 'node:util';
+import 'node:readline/promises';
+
+function vitasectionLine(id, heading) {
+  return `\\vitasection${heading ? `[${escapeTex(heading)}]` : ""}{${id}}`;
+}
+function vitapublicationsLine(list, heading) {
+  return `\\vitapublications${heading ? `[${escapeTex(heading)}]` : ""}{${list}}`;
+}
+function anchors(source) {
+  return [
+    ...findPdfPlacements("", "", source).map((placement) => ({ id: placement.section, line: placement.line })),
+    ...findPdfPublicationPlacements("", "", source).map((placement) => ({ id: placement.list, line: placement.line }))
+  ].sort((a, b) => a.line - b.line);
+}
+function insertLine(source, text, after) {
+  const found = anchors(source);
+  const lines = source.split("\n");
+  const offsetOf = (lineNumber) => lines.slice(0, lineNumber - 1).reduce((sum, line) => sum + line.length + 1, 0);
+  const anchor = (after && found.find((existing) => existing.id === after)) ?? found[found.length - 1];
+  if (anchor) {
+    const offset = offsetOf(anchor.line);
+    return {
+      ok: true,
+      value: { source: insertLinesAfter(source, offset, [`${indentationAt(source, offset)}${text}`]), line: anchor.line + 1, afterSection: anchor.id }
+    };
+  }
+  const end = lines.findIndex((line) => /^\s*\\end\{document\}/.test(line));
+  if (end === -1) return { ok: false, reason: "it has no \\end{document} line" };
+  return { ok: true, value: { source: insertLinesBefore(source, offsetOf(end + 1), [text, ""]), line: end + 1 } };
+}
+function addSectionToDocument(source, placement) {
+  if (findPdfPlacements("", "", source).some((existing) => existing.section === placement.id && existing.macro === "vitasection")) {
+    return { ok: false, reason: `it already includes ${placement.id}` };
+  }
+  return insertLine(source, vitasectionLine(placement.id, placement.heading), placement.after);
+}
+function addPublicationsToDocument(source, placement) {
+  if (findPdfPublicationPlacements("", "", source).some((existing) => existing.list === placement.id)) {
+    return { ok: false, reason: `it already includes the list ${placement.id}` };
+  }
+  return insertLine(source, vitapublicationsLine(placement.id, placement.heading), placement.after);
+}
+
+function dataStarter(id) {
+  return [
+    `# ${id}: one entry per item. vitakit sorts them by date, newest first.`,
+    `# Which fields an entry may have is decided in schemas/${id}.ts.`,
+    `- date: 2025-03-14`,
+    `  title: An example entry`,
+    `  note: Replace this with something real.`,
+    ""
+  ].join("\n");
+}
+const STARTER_ENTRIES = [{ date: "2025-03-14", title: "An example entry", note: "Replace this with something real." }];
+const EXAMPLES = {
+  "text": "Some text",
+  "formatted-text": "Text with *emphasis* and $k$-ary trees",
+  "number": "4.5",
+  "yes-no": "true",
+  "date": "2025-03",
+  "web-address": "https://example.org",
+  "link": "{ name: University of Graz, url: https://uni-graz.at }",
+  "choice": "",
+  "group": "",
+  "custom": ""
+};
+function exampleValue(field) {
+  const single = field.type === "choice" ? field.choices?.[0] ?? "\u2026" : EXAMPLES[field.type] || "\u2026";
+  return field.several ? `[${single}]` : single;
+}
+function dataExample(id, fields) {
+  const required = fields.filter((field) => !field.optional);
+  const optional = fields.filter((field) => field.optional).map((field) => field.path);
+  const lines = required.map((field, index) => `#${index === 0 ? " -" : "  "} ${field.path}: ${exampleValue(field)}`);
+  return [
+    `# ${id}: one entry per item; vitakit sorts them by date, newest first.`,
+    `# An entry looks like this (remove the # to use it):`,
+    `#`,
+    ...lines,
+    ...optional.length ? [`#`, `# Optional: ${optional.join(", ")}.`] : [],
+    ""
+  ].join("\n");
+}
+function rawEntries(source) {
+  const data = parse(source);
+  if (data === null || data === void 0) return [];
+  if (!Array.isArray(data)) throw new CommandError('expected a list of entries (lines starting with "- ")');
+  return data;
+}
+async function schemaOwner(inv, id) {
+  const section = inv.sections.find((candidate) => candidate.id === id);
+  if (section) return section.schema.origin === "none" ? void 0 : section;
+  const { schemas } = await import('./schemas.mjs');
+  const { describeSection } = await import('./fields.mjs');
+  if (!Object.hasOwn(schemas, id)) return void 0;
+  return { id, where: `content/${id}.yml`, schema: { origin: "built-in" }, fields: describeSection(schemas[id]) ?? [], problems: [] };
+}
+async function matchingSchemas(rootDir, inv, id, entries) {
+  if (!entries.length) return [];
+  const { findSectionFiles, resolveSectionSchema } = await import('./sections.mjs');
+  const { files } = await findSectionFiles(rootDir).catch(() => ({ files: [] }));
+  const { schemas } = await import('./schemas.mjs');
+  const keys = new Set(entries.flatMap((entry) => typeof entry === "object" && entry ? Object.keys(entry) : []));
+  const matches = [];
+  const builtIns = Object.keys(schemas).filter((name) => !inv.sections.some((section) => section.id === name));
+  const candidates = [...inv.sections, ...(await Promise.all(builtIns.map((name) => schemaOwner(inv, name)))).filter((section) => section !== void 0)];
+  for (const section of candidates) {
+    if (section.id === id || section.schema.origin === "none" || section.schema.sharedWith) continue;
+    const file = files.find((candidate) => candidate.id === section.id);
+    let schema;
+    try {
+      schema = file ? (await resolveSectionSchema(rootDir, file)).schema : schemas[section.id];
+    } catch {
+      continue;
+    }
+    const fields = new Set(section.fields?.map((field) => field.path) ?? []);
+    if ([...keys].every((key) => key === "visibility" || fields.has(key)) && schema.safeParse(entries).success) matches.push(section.id);
+  }
+  return matches;
+}
+function sharedSchemaModule(id, other) {
+  const body = other.schema.origin === "built-in" ? [`import { schemas } from '@anja.codes/vitakit'`, "", `export default schemas.${other.id.replace(/-(\w)/g, (_match, char) => char.toUpperCase())}`] : [`export { default } from './${other.id}.ts'`];
+  return [
+    "/**",
+    ` * content/${id}.yml has the same fields as content/${other.id}.yml. A field`,
+    ` * added to ${other.id} is accepted here too; to give ${id} fields of its own,`,
+    ` * replace this file with its own schema.`,
+    " */",
+    ...body,
+    ""
+  ].join("\n");
+}
+const FIELD_TYPES = [
+  { type: "text", label: "text" },
+  { type: "formatted-text", label: "formatted text (Markdown, $math$)" },
+  { type: "number", label: "number" },
+  { type: "yes-no", label: "yes/no" },
+  { type: "date", label: "date" },
+  { type: "web-address", label: "web address" },
+  { type: "link", label: "link (a name, optionally with a web address)" },
+  { type: "choice", label: "one of a fixed list" }
+];
+const CODE = {
+  "text": { code: "text", imports: ["text"] },
+  "formatted-text": { code: "richText", imports: ["richText"] },
+  "number": { code: "z.number()", imports: ["z"] },
+  "yes-no": { code: "z.boolean()", imports: ["z"] },
+  "date": { code: "dateRange", imports: ["dateRange"] },
+  "web-address": { code: "url", imports: ["url"] },
+  "link": { code: "linked", imports: ["linked"] }
+};
+function fieldCode(spec) {
+  let base = CODE[spec.type];
+  if (spec.type === "choice") {
+    if (!spec.choices.length) throw new CommandError("a field of type choice needs its values: --choice <value>, once per value");
+    base = { code: `z.enum([${spec.choices.map((choice) => `'${choice.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`).join(", ")}])`, imports: ["z"] };
+  }
+  if (!base) throw new CommandError(`unknown type ${spec.type}`);
+  const code = spec.several ? `z.array(${base.code})` : base.code;
+  return {
+    code: `${code}${spec.required ? "" : ".optional()"}`,
+    imports: [.../* @__PURE__ */ new Set([...base.imports, ...spec.several ? ["z"] : []])]
+  };
+}
+function extensionModule(id, fields, imports) {
+  const names = [.../* @__PURE__ */ new Set(["extendSection", "schemas", ...imports])].sort();
+  const builtin = id.replace(/-(\w)/g, (_match, char) => char.toUpperCase());
+  return [
+    "/**",
+    ` * The ${id} section: vitakit's built-in fields, and yours below. A field`,
+    ` * here is accepted in content/${id}.yml; showing it on the website or in`,
+    ` * the PDF is a separate step (\`vitakit customize ${id}\`). A built-in field`,
+    ` * listed here replaces vitakit's rule for it.`,
+    " */",
+    `import { ${names.join(", ")} } from '@anja.codes/vitakit'`,
+    "",
+    `export default extendSection(schemas.${builtin}, {`,
+    ...fields.length ? fields.flatMap((field) => [...(field.notes ?? []).map((note) => `  // ${note}`), `  ${propertyKey(field.name)}: ${field.code},`]) : ["  // Your fields, e.g.", "  //   evaluation: z.number().optional(),"],
+    "})",
+    ""
+  ].join("\n");
+}
+async function planAddField(ws, section, name, spec) {
+  const { code, imports } = fieldCode(spec);
+  const path = `schemas/${section.id}.ts`;
+  if (section.schema.origin === "built-in") {
+    ws.create(path, extensionModule(section.id, [{ name, code }], imports), `keeps vitakit's ${section.id} fields, adds ${name}`, { show: true });
+    return "created";
+  }
+  const source = await ws.read(path);
+  if (source === void 0) throw new CommandError(`${section.id} has no schema yet; \`vitakit add section ${section.id}\` drafts one`);
+  const added = addSchemaField(source, name, code);
+  const imported = added.ok ? ensurePackageImports(added.value, imports) : added;
+  if (imported.ok) {
+    await ws.edit(path, imported.value, `adds ${name}`);
+    return "edited";
+  }
+  ws.paste(path, `${propertyKey(name)}: ${code},`, `cannot be changed safely (${imported.reason}); add this line among the fields, and import ${imports.join(", ")} from '@anja.codes/vitakit'`);
+  return "pasted";
+}
+async function planPlaceOnPage(ws, inv, path, placement) {
+  const source = await ws.read(path);
+  if (source === void 0) throw new CommandError(`${path} does not exist`);
+  const result = addSectionToPage(source, placement, inv.web.components.keys());
+  if (result.ok) {
+    await ws.edit(path, result.value.source, `shows ${placement.id}${result.value.afterSection ? ` after ${result.value.afterSection}` : ""}`);
+    return path;
+  }
+  if (result.reason.startsWith("it already shows")) {
+    ws.keep(path, `already shows ${placement.id}`);
+    return path;
+  }
+  ws.paste(path, sectionElementSource(placement), `cannot be changed safely (${result.reason}); add this line where the section should appear`);
+  return path;
+}
+async function planPlaceInDocument(ws, document, placement) {
+  const path = `cv-tex/${document}.tex`;
+  const source = await ws.read(path);
+  if (source === void 0) throw new CommandError(`${path} does not exist`);
+  const result = addSectionToDocument(source, { id: placement.id, ...placement.title ? { heading: placement.title } : {}, ...placement.after ? { after: placement.after } : {} });
+  if (result.ok) {
+    await ws.edit(path, result.value.source, `includes ${placement.id}${result.value.afterSection ? ` after ${result.value.afterSection}` : ""}`);
+  } else if (result.reason.startsWith("it already includes")) {
+    ws.keep(path, `already includes ${placement.id}`);
+  } else {
+    ws.paste(path, vitasectionLine(placement.id, placement.title), `cannot be changed safely (${result.reason}); add this line where the section should appear`);
+  }
+}
+async function planListOnPage(ws, inv, path, placement) {
+  const source = await ws.read(path);
+  if (source === void 0) throw new CommandError(`${path} does not exist`);
+  const result = addPublicationsToPage(source, placement, inv.web.components.keys());
+  if (result.ok) await ws.edit(path, result.value.source, `shows the list ${placement.list}${result.value.afterSection ? ` after ${result.value.afterSection}` : ""}`);
+  else if (result.reason.startsWith("it already shows")) ws.keep(path, `already shows the list ${placement.list}`);
+  else ws.paste(path, publicationsElementSource(placement.list, placement.title), `cannot be changed safely (${result.reason}); add this line where the list should appear`);
+}
+async function planListInDocument(ws, document, placement) {
+  const path = `cv-tex/${document}.tex`;
+  const source = await ws.read(path);
+  if (source === void 0) throw new CommandError(`${path} does not exist`);
+  const result = addPublicationsToDocument(source, { id: placement.id, ...placement.title ? { heading: placement.title } : {}, ...placement.after ? { after: placement.after } : {} });
+  if (result.ok) await ws.edit(path, result.value.source, `includes the list ${placement.id}${result.value.afterSection ? ` after ${result.value.afterSection}` : ""}`);
+  else if (result.reason.startsWith("it already includes")) ws.keep(path, `already includes the list ${placement.id}`);
+  else ws.paste(path, vitapublicationsLine(placement.id, placement.title), `cannot be changed safely (${result.reason}); add this line where the list should appear`);
+}
+function pageModule(route, name, title) {
+  return `<script setup lang="ts">
+/**
+ * The ${title} page: the text from content/pages/${name}.md, then sections.
+ *
+ * One line per section, in the order they appear; \`vitakit add section\`
+ * adds more. A section without entries is not shown, heading included.
+ */
+const profile = useProfile()
+const page = usePage('${route}')
+
+if (!page) {
+  throw createError({ statusCode: 404, statusMessage: 'No page for ${route} (expected content/pages/${name}.md)', fatal: true })
+}
+
+useHead({
+  title: \`\${page.title} \u2013 \${profile.name}\`,
+  meta: [{ name: 'description', content: page.description ?? profile.summary }],
+})
+<\/script>
+
+<template>
+  <article>
+    <h1 class="text-3xl font-semibold" v-html="page.titleHtml" />
+    <VitaMarkdown class="mt-6" :html="page.bodyHtml" />
+  </article>
+</template>
+`;
+}
+function pageText(name, title) {
+  return `---
+title: ${yamlScalar(title)}
+---
+
+An introduction to this page, in Markdown. The sections below it are listed
+in app/pages/${name}.vue.
+`;
+}
+async function planCreatePage(ws, inv, name, { title, menu }) {
+  const { sectionNameProblem } = await import('./sections.mjs');
+  const problem = sectionNameProblem(name);
+  if (problem && !problem.includes("reserved")) throw new CommandError(problem.replace("research-stays", "research-interests"));
+  const route = `/${name}/`;
+  const existing = inv.pages.find((page) => page.route === route);
+  if (existing?.vue) throw new CommandError(`${route} exists already (${[existing.markdown, existing.vue].filter(Boolean).join(", ")})`);
+  const vue = `app/pages/${name}.vue`;
+  if (existing?.markdown) {
+    if (existing.markdown !== `content/pages/${name}.md`) {
+      throw new CommandError(`${route} is ${existing.markdown}; its Vue page would have to read it by route, which this command does not write`);
+    }
+    ws.keep(existing.markdown, "the page's title and text, as they are");
+  } else {
+    ws.create(`content/pages/${name}.md`, pageText(name, title), "the page's title and text");
+  }
+  ws.create(vue, pageModule(route, name, existing?.title ?? title), "the page, with its sections");
+  if (menu && !existing?.inMenu) {
+    const profile = await ws.read("content/profile.yml");
+    const result = profile === void 0 ? { ok: false, reason: "it does not exist" } : addNavItem(profile, { label: title, to: route });
+    if (result.ok) await ws.edit("content/profile.yml", result.value, `adds ${title} to the menu`);
+    else ws.paste("content/profile.yml", `- { label: ${yamlScalar(title)}, to: ${route} }`, `cannot be changed safely (${result.reason}); add this to nav`);
+  }
+  return vue;
+}
+function fieldsNotShown(fields) {
+  const shown = /* @__PURE__ */ new Set(["date", "title", "position", "degree", "role", "student", "event", "term", "institution", "issuer", "organisation", "location", "note", "url", "slides", "ongoing"]);
+  return (fields ?? []).map((field) => field.path).filter((path) => !shown.has(path));
+}
+async function planMissingFields(rootDir, ws, section, entries) {
+  const { draftExtension } = await import('./draft.mjs');
+  const { findSectionFiles, resolveSectionSchema } = await import('./sections.mjs');
+  const { schemas } = await import('./schemas.mjs');
+  const builtIn = section.schema.origin === "built-in";
+  let base = builtIn ? schemas[section.id] : void 0;
+  if (!base) {
+    const { files } = await findSectionFiles(rootDir).catch(() => ({ files: [] }));
+    const file = files.find((candidate) => candidate.id === section.id);
+    if (!file) return { fields: [], changes: [] };
+    try {
+      base = (await resolveSectionSchema(rootDir, file)).schema;
+    } catch {
+      return { fields: [], changes: [] };
+    }
+  }
+  const extension = draftExtension(base, entries);
+  if (!extension?.fields.length) return { fields: [], changes: [] };
+  const names = extension.fields.map((field) => field.name);
+  const path = `schemas/${section.id}.ts`;
+  if (builtIn) {
+    ws.create(path, extensionModule(section.id, extension.fields, extension.imports), `keeps vitakit's ${section.id} fields, adds ${names.join(", ")} from your entries`, { show: true });
+    return { fields: names, changes: extension.changes };
+  }
+  if (section.schema.sharedWith) {
+    return { fields: [], changes: [], note: `Entries of ${section.id} have fields its shared schema (${section.schema.sharedWith}) does not: ${names.join(", ")}.` };
+  }
+  let source = await ws.read(path) ?? "";
+  for (const field of extension.fields) {
+    const added = addSchemaField(source, field.name, field.code);
+    if (!added.ok) {
+      ws.paste(path, extension.fields.map((item) => `${propertyKey(item.name)}: ${item.code},`).join("\n"), `cannot be changed safely (${added.reason}); add these fields`);
+      return { fields: [], changes: extension.changes };
+    }
+    source = added.value;
+  }
+  const imported = ensurePackageImports(source, extension.imports);
+  if (!imported.ok) return { fields: [], changes: [] };
+  await ws.edit(path, imported.value, `adds ${names.join(", ")} from your entries`);
+  return { fields: names, changes: extension.changes };
+}
+
+export { FIELD_TYPES, STARTER_ENTRIES, dataExample, dataStarter, exampleValue, extensionModule, fieldCode, fieldsNotShown, matchingSchemas, planAddField, planCreatePage, planListInDocument, planListOnPage, planMissingFields, planPlaceInDocument, planPlaceOnPage, rawEntries, schemaOwner, sharedSchemaModule };