@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/cli/mcp/appMap.js

@@ -0,0 +1,128 @@
+// @ts-check
+'use strict';
+
+const path = require('node:path');
+const { createProgram, readCommandScreens } = require('../codegen/read');
+const { readLinking } = require('../links/prefixes');
+const { findConfig, keysOf } = require('../typescript');
+const { openWorkspace } = require('../workspace');
+
+/** @typedef {import('../codegen/read').Model} Model */
+/** @typedef {import('../codegen/read').CommandScreenModel} CommandScreenModel */
+
+/**
+ * The map of the app's navigation, from its code, for an agent that is about to change it: the screens with their
+ * props as TypeScript writes them, the roots, the links, and how the screens render.
+ * @typedef {{
+ *   navigation: string;
+ *   mode: 'one-tree' | 'root-per-screen';
+ *   screens: {
+ *     name: string;
+ *     kind: 'react' | 'native';
+ *     props: { name: string; type: string; optional: boolean }[];
+ *     note?: string;
+ *   }[];
+ *   root?: string;
+ *   roots?: Record<string, string>;
+ *   initialRoot?: string;
+ *   linking?: { prefixes: string[]; routes: string[] } | { error: string };
+ * }} AppMap
+ */
+
+/**
+ * The map of the app, or why the CLI can't read its code.
+ * @param {string} root
+ * @param {import('../exec').Exec} run
+ * @returns {AppMap | { error: string }}
+ */
+function appMap(root, run) {
+  const workspace = openWorkspace(root, run);
+  if ('code' in workspace) return { error: workspace.message };
+  const { ts, navigation } = workspace;
+  const { screens, skipped } = readCommandScreens(
+    ts,
+    createProgram(ts, root, navigation),
+    navigation
+  );
+  const text = (/** @type {string} */ key) => {
+    const value = findConfig(ts, navigation, key);
+    return value ? value.node.getText(value.source) : undefined;
+  };
+  const roots = findConfig(ts, navigation, 'roots');
+  const linking = readLinking(ts, navigation);
+  return {
+    navigation: path.relative(root, navigation),
+    mode: findConfig(ts, navigation, 'appProvider') ? 'one-tree' : 'root-per-screen',
+    screens: [
+      ...screens.map((screen) => ({
+        name: screen.name,
+        kind: screen.native ? /** @type {const} */ ('native') : /** @type {const} */ ('react'),
+        props: [
+          ...screen.fields.map((field) => ({
+            name: field.name,
+            type: typeText(field.type, screen),
+            optional: field.optional,
+          })),
+          ...screen.functions.map((name) => ({ name, type: 'function', optional: true })),
+        ],
+      })),
+      ...skipped.map(({ name, native, reason }) => ({
+        name,
+        kind: native ? /** @type {const} */ ('native') : /** @type {const} */ ('react'),
+        props: [],
+        note: `props not read: ${reason}`,
+      })),
+    ],
+    ...(text('root') && { root: text('root') }),
+    ...(roots && {
+      roots: Object.fromEntries(
+        keysOf(ts, roots).map((name) => {
+          const value =
+            ts.isObjectLiteralExpression(roots.node) &&
+            roots.node.properties.find((property) => property.name?.getText(roots.source) === name);
+          return [name, value ? value.getText(roots.source).replace(/^[^:]+:\s*/, '') : ''];
+        })
+      ),
+    }),
+    ...(text('initialRoot') && { initialRoot: text('initialRoot') }),
+    ...('code' in linking
+      ? linking.code === 'no-linking'
+        ? {}
+        : { linking: { error: linking.message } }
+      : {
+          linking: {
+            prefixes: linking.prefixes.map(({ text: prefix }) => prefix),
+            routes: linking.routes,
+          },
+        }),
+  };
+}
+
+/**
+ * A prop's type as TypeScript writes it.
+ * @param {Model} model
+ * @param {CommandScreenModel} screen
+ * @returns {string}
+ */
+function typeText(model, screen) {
+  switch (model.kind) {
+    case 'enum': {
+      const values = screen.enums.find(({ name }) => name === model.name)?.values ?? [];
+      return values.map((value) => JSON.stringify(value)).join(' | ') || 'string';
+    }
+    case 'object': {
+      const object = screen.objects.find(({ name }) => name === model.name);
+      return object
+        ? `{ ${object.fields.map((field) => `${field.name}${field.optional ? '?' : ''}: ${typeText(field.type, screen)}`).join('; ')} }`
+        : 'object';
+    }
+    case 'array':
+      return `${typeText(model.element, screen)}[]`;
+    case 'function':
+      return 'function';
+    default:
+      return model.kind;
+  }
+}
+
+module.exports = { appMap };

package/cli/mcp/docs.js

@@ -0,0 +1,175 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { sectionsOf, toMarkdown } = require('./markdown');
+
+/** @typedef {import('./markdown').DocPage} DocPage */
+
+// The package: docs-md/ is in it once published; in its repository the pages are read from docs/content.
+const PACKAGE_ROOT = path.join(__dirname, '..', '..');
+// At most this many characters of a page in one answer: an agent reads a section of a longer page.
+const MAX_PAGE = 40_000;
+
+/** @type {DocPage[] | undefined} */
+let pages;
+
+/**
+ * The pages of the docs, in the order of the site: the Markdown the package ships (`docs-md/<group>/<section>.md` with
+ * `docs-md/index.json`, made by `scripts/docs-md.mjs`), or, in the repository of the navigation, its pages made on the spot.
+ * @param {string} [root] the package
+ * @returns {DocPage[]}
+ */
+function loadDocs(root = PACKAGE_ROOT) {
+  if (pages && root === PACKAGE_ROOT) return pages;
+  const built = path.join(root, 'docs-md', 'index.json');
+  /** @type {DocPage[]} */
+  let found = [];
+  if (fs.existsSync(built)) {
+    /** @type {Omit<DocPage, 'markdown' | 'sections'>[]} */
+    const index = JSON.parse(fs.readFileSync(built, 'utf8'));
+    found = index.map((entry) => {
+      const markdown = fs.readFileSync(path.join(root, 'docs-md', `${entry.id}.md`), 'utf8');
+      return { ...entry, markdown, sections: sectionsOf(markdown, entry.anchors) };
+    });
+  } else {
+    const content = path.join(root, 'docs', 'content');
+    const sections = path.join(root, 'docs', 'sections.json');
+    if (fs.existsSync(sections)) {
+      found = readSite(content, JSON.parse(fs.readFileSync(sections, 'utf8')));
+    }
+  }
+  if (root === PACKAGE_ROOT) pages = found;
+  return found;
+}
+
+/**
+ * The pages of the site from its sources, in the order of sections.json; pages it doesn't list come after.
+ * @param {string} content docs/content
+ * @param {{ groups: { id: string; sections: { id: string }[] }[] }} registry
+ * @returns {DocPage[]}
+ */
+function readSite(content, registry) {
+  const ids = registry.groups.flatMap((group) =>
+    group.sections.map((section) => `${group.id}/${section.id}`)
+  );
+  const all = fs
+    .readdirSync(content, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .flatMap((group) =>
+      fs
+        .readdirSync(path.join(content, group.name))
+        .filter((name) => name.endsWith('.mdx'))
+        .map((name) => `${group.name}/${name.replace(/\.mdx$/, '')}`)
+    );
+  const ordered = [
+    ...ids.filter((id) => all.includes(id)),
+    ...all.filter((id) => !ids.includes(id)),
+  ];
+  return ordered.map((id) =>
+    toMarkdown(id, fs.readFileSync(path.join(content, `${id}.mdx`), 'utf8'))
+  );
+}
+
+/**
+ * The sections of the docs that answer a query best: each word of it counts where it is, a heading most, then the
+ * page's title, then the text. A line with a word of the query comes with each.
+ * @param {DocPage[]} docs
+ * @param {string} query
+ * @param {number} [limit]
+ * @returns {{ page: string; title: string; section: string; anchor: string; line: string }[]}
+ */
+function searchDocs(docs, query, limit = 8) {
+  const words = query
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}_.-]+/u)
+    .filter((word) => word.length > 1);
+  if (words.length === 0) return [];
+  const moving = /migrat|moving|react-navigation|react-native-navigation|expo|\bfrom\b/.test(
+    query.toLowerCase()
+  );
+  const count = (/** @type {string} */ text, /** @type {string} */ word) =>
+    text.split(word).length - 1;
+  const results = [];
+  for (const page of docs) {
+    const title = page.title.toLowerCase();
+    for (const section of page.sections) {
+      const heading = section.heading.toLowerCase();
+      const text = section.text.toLowerCase();
+      let score = 0;
+      for (const word of words) {
+        score += count(heading, word) * 6 + count(title, word) * 8 + Math.min(count(text, word), 5);
+      }
+      // Every word of the query in the section counts more than one word many times.
+      if (words.every((word) => heading.includes(word) || text.includes(word))) score *= 2;
+      // The pages of moving from another library repeat every topic: they come first only when the query is about it.
+      if (page.id.startsWith('migration/') && !moving) score /= 2;
+      if (score === 0) continue;
+      const line =
+        section.text
+          .split('\n')
+          .find((candidate) => words.some((word) => candidate.toLowerCase().includes(word)))
+          ?.trim()
+          .slice(0, 200) ?? '';
+      results.push({
+        score,
+        page: page.id,
+        title: page.title,
+        section: section.heading,
+        anchor: section.anchor,
+        line,
+      });
+    }
+  }
+  return results
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ page, title, section, anchor, line }) => ({ page, title, section, anchor, line }));
+}
+
+/**
+ * A page of the docs, or one of its sections, as Markdown: by its id (`start/installation`), the id of its section
+ * of the site (`installation`), or its title. A section by its anchor or heading takes what is under it, up to the next
+ * heading of its level. Undefined when there is no such page or section.
+ * @param {DocPage[]} docs
+ * @param {string} page
+ * @param {string} [section]
+ * @returns {{ page: string; title: string; markdown: string; sections: string[] } | undefined}
+ */
+function readDoc(docs, page, section) {
+  const wanted = page.toLowerCase().replace(/^\/|\.mdx?$/g, '');
+  const found =
+    docs.find(({ id }) => id === wanted) ??
+    docs.find(({ id }) => id.split('/')[1] === wanted) ??
+    docs.find(({ title }) => title.toLowerCase() === wanted);
+  if (!found) return undefined;
+  const anchors = found.sections.map(({ anchor, heading }) => `${anchor}: ${heading}`);
+  if (!section) {
+    const markdown =
+      found.markdown.length > MAX_PAGE
+        ? `${found.markdown.slice(0, MAX_PAGE)}\n\n[The page goes on: read one of its sections.]\n`
+        : found.markdown;
+    return { page: found.id, title: found.title, markdown, sections: anchors };
+  }
+  const key = section.toLowerCase().replace(/^#/, '');
+  const index = found.sections.findIndex(
+    ({ anchor, heading }) => anchor === key || heading.toLowerCase() === key
+  );
+  if (index < 0) return undefined;
+  const { heading, level, text } = found.sections[index];
+  // The subsections under it belong to it.
+  const nested = [];
+  for (const next of found.sections.slice(index + 1)) {
+    if (next.level <= level) break;
+    nested.push(`${'#'.repeat(next.level)} ${next.heading}\n\n${next.text}`);
+  }
+  return {
+    page: found.id,
+    title: found.title,
+    markdown: [`${'#'.repeat(level)} ${heading}`, text, ...nested].join('\n\n') + '\n',
+    sections: anchors,
+  };
+}
+
+module.exports = { loadDocs, searchDocs, readDoc, readSite };

package/cli/mcp/index.js

@@ -0,0 +1,153 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createRun } = require('../changes');
+const { createUI } = require('../ui');
+const { serve } = require('./protocol');
+const { createTools } = require('./tools');
+
+const NAME = 'apex-navigation';
+const ENTRY = { command: 'npx', args: [NAME, 'mcp'] };
+
+const INSTRUCTIONS = `apex-navigation is the CLI of @apexnative/navigation: native navigation for React Native. The platform's own stacks, tabs, modals and bars, owned by the native side and driven from JavaScript; the commands come from the package (navigation.push('Details', { props })), the screens are registered by name in createNavigation.
+
+- app_map first, before changing the navigation: the screens with their props, the roots, the links.
+- docs_search and docs_read for the API, the options and the guides: the docs of the version installed here.
+- doctor when the app doesn't build or start; info for an issue.
+- setup, screen, codegen, links, icons, splash and migrate change files: they return the plan with every diff, and write with apply: true. A screen added in JavaScript needs no native build; a change of native files needs one.
+- init (a new app) and upgrade aren't tools: they take minutes and the network. Run npx apex-navigation init or upgrade in a shell.`;
+
+/**
+ * The MCP server of the CLI on stdio, for AI coding agents, on the app in `root` (the folder the client starts it in).
+ * It takes the stdout the protocol writes to before any tool runs: the commands' output is caught under the tools.
+ * @param {{ root: string; input?: NodeJS.ReadableStream; send?: (line: string) => void }} options
+ * @returns {Promise<number>} the exit code, when the client closes the input
+ */
+async function mcp({ root, input, send = process.stdout.write.bind(process.stdout) }) {
+  const version = JSON.parse(
+    fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8')
+  ).version;
+  await serve({
+    info: { name: NAME, version },
+    instructions: INSTRUCTIONS,
+    tools: createTools(root),
+    input,
+    send,
+  });
+  return 0;
+}
+
+/**
+ * The config of a client with the server in it, in the project: Claude Code `.mcp.json`, Cursor `.cursor/mcp.json`,
+ * VS Code `.vscode/mcp.json`; for Codex, whose config is the user's, the line that adds it. Merged into what is there.
+ * @param {{
+ *   root: string;
+ *   client: string | undefined;
+ *   yes: boolean;
+ *   dryRun: boolean;
+ *   json?: boolean;
+ *   ui?: ReturnType<typeof createUI>;
+ *   write?: (text: string) => void;
+ * }} options
+ * @returns {Promise<number>} the exit code
+ */
+async function mcpInstall({
+  root,
+  client,
+  yes,
+  dryRun,
+  json = false,
+  ui = createUI(),
+  write = (text) => process.stdout.write(text),
+}) {
+  const command = createRun({ command: 'mcp install', root, json, ui });
+  if (!json) ui.banner({ command: 'mcp install', facts: [{ text: client ?? 'no client' }] });
+  if (client === 'codex') {
+    const line = `codex mcp add ${NAME} -- ${ENTRY.command} ${ENTRY.args.join(' ')}`;
+    if (json) {
+      write(JSON.stringify({ command: 'mcp install', ok: true, next: [line] }, null, 2) + '\n');
+    } else {
+      ui.line('  Codex keeps its servers in ~/.codex/config.toml. Add this one with:');
+      ui.next([line]);
+    }
+    return 0;
+  }
+  /** @type {Record<string, { file: string; key: string; entry: Record<string, unknown> }>} */
+  const clients = {
+    claude: { file: '.mcp.json', key: 'mcpServers', entry: ENTRY },
+    cursor: { file: path.join('.cursor', 'mcp.json'), key: 'mcpServers', entry: ENTRY },
+    vscode: {
+      file: path.join('.vscode', 'mcp.json'),
+      key: 'servers',
+      entry: { type: 'stdio', ...ENTRY },
+    },
+  };
+  const target = client && clients[client];
+  if (!target) {
+    return command.fail(
+      'client-unknown',
+      `The client is claude, cursor, vscode or codex: npx ${NAME} mcp install claude`
+    );
+  }
+  const file = path.join(root, target.file);
+  const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : undefined;
+  /** @type {any} */
+  let config = {};
+  if (before !== undefined) {
+    try {
+      config = JSON.parse(before);
+    } catch {
+      return command.apply(
+        [
+          {
+            name: target.file,
+            platform: 'js',
+            file,
+            status: 'manual',
+            note: "isn't plain JSON, see below",
+            howTo: `Add under "${target.key}":\n\n  "${NAME}": ${JSON.stringify(target.entry)}`,
+          },
+        ],
+        { yes, dryRun }
+      );
+    }
+  }
+  const servers = { ...config[target.key] };
+  const same = JSON.stringify(servers[NAME]) === JSON.stringify(target.entry);
+  servers[NAME] = target.entry;
+  const next = JSON.stringify({ ...config, [target.key]: servers }, null, 2) + '\n';
+  return command.apply(
+    [
+      same
+        ? { name: target.file, platform: 'js', file, status: 'done', note: 'the server is there' }
+        : before === undefined
+          ? {
+              name: target.file,
+              platform: 'js',
+              file,
+              status: 'create',
+              next,
+              note: `${NAME} for ${client}`,
+            }
+          : {
+              name: target.file,
+              platform: 'js',
+              file,
+              status: 'change',
+              before,
+              next,
+              note: `${NAME} for ${client}`,
+            },
+    ],
+    {
+      yes,
+      dryRun,
+      nothingToDo: 'The server is there already.',
+      next: ['Restart the client, or reload its servers, and allow apex-navigation when it asks.'],
+    }
+  );
+}
+
+module.exports = { mcp, mcpInstall, INSTRUCTIONS };

package/cli/mcp/markdown.js

@@ -0,0 +1,210 @@
+// @ts-check
+'use strict';
+
+/**
+ * A page of the docs as plain Markdown, for an agent: its title, description, text, and its sections by anchor.
+ * @typedef {{
+ *   id: string;
+ *   title: string;
+ *   description: string;
+ *   markdown: string;
+ *   anchors: { heading: string; anchor: string }[];
+ *   sections: { heading: string; anchor: string; level: number; text: string }[];
+ * }} DocPage
+ */
+
+/**
+ * A page of the site (MDX) as plain Markdown: the components of the site go, keeping what they say (the steps of
+ * `Steps`, the label of a tab, a marked phrase in bold, the platform of `Os`), the notes become quotes, and the code
+ * stays as it is.
+ * @param {string} id the page, `group/section`
+ * @param {string} mdx
+ * @returns {DocPage}
+ */
+function toMarkdown(id, mdx) {
+  const front = /^---\n([\s\S]*?)\n---\n/.exec(mdx);
+  const meta = front?.[1] ?? '';
+  const title = unquote(/^title:\s*(.+)$/m.exec(meta)?.[1] ?? id);
+  const description = unquote(/^description:\s*(.+)$/m.exec(meta)?.[1] ?? '');
+  const lines = mdx.slice(front ? front[0].length : 0).split('\n');
+
+  /** @type {string[]} */
+  const out = [`# ${title}`, '', ...(description ? [description, ''] : [])];
+  let fence = '';
+  let note = false;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    // Code stays as it is: its JSX is the app's, not the site's.
+    const fenceMark = /^\s*(```+|~~~+)/.exec(line)?.[1];
+    if (fence) {
+      out.push(line);
+      if (fenceMark && fenceMark.startsWith(fence)) fence = '';
+      continue;
+    }
+    if (fenceMark) {
+      fence = fenceMark;
+      out.push(line.replace(/\s+title="[^"]*"/, ''));
+      continue;
+    }
+    if (/^import\s/.test(line)) {
+      while (index < lines.length && !/from\s+['"][^'"]+['"];?\s*$/.test(lines[index])) index++;
+      continue;
+    }
+    const admonition = /^:::(\w+)?/.exec(line.trim());
+    if (admonition) {
+      note = Boolean(admonition[1]);
+      if (note) out.push(`> **${capitalize(admonition[1])}**`, '>');
+      continue;
+    }
+    // A component of the site on lines of its own: what it says, or nothing. One followed by text on its line, such as
+    // `<Os name="iOS" /> 16+ …`, is part of the prose.
+    const end = /^\s*<\/?[A-Z]/.test(line) ? tagEnd(line) : -2;
+    if (end === -1 || (end >= 0 && line.slice(end).trim() === '')) {
+      let tag = line;
+      while (tagEnd(tag) === -1 && index + 1 < lines.length) tag += '\n' + lines[++index];
+      out.push(...component(tag));
+      continue;
+    }
+    const text = inline(line);
+    out.push(note ? `> ${text}`.trimEnd() : text);
+  }
+  const markdown =
+    out
+      .join('\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim() + '\n';
+  const anchors = [...mdx.matchAll(/^#{2,4}\s+(.+?)\s*\{#([\w-]+)\}\s*$/gm)].map((found) => ({
+    heading: inline(found[1]).trim(),
+    anchor: found[2],
+  }));
+  return { id, title, description, markdown, anchors, sections: sectionsOf(markdown, anchors) };
+}
+
+/**
+ * The sections of a page by its headings, each with the anchor the site gives it (`{#anchor}`, else from its words).
+ * @param {string} markdown
+ * @param {{ heading: string; anchor: string }[]} anchors
+ * @returns {DocPage['sections']}
+ */
+function sectionsOf(markdown, anchors) {
+  const headings = [...markdown.matchAll(/^(#{2,4})\s+(.+)$/gm)];
+  return headings.map((found, index) => {
+    const heading = found[2].trim();
+    const start = /** @type {number} */ (found.index) + found[0].length;
+    const end = headings[index + 1]?.index ?? markdown.length;
+    return {
+      heading,
+      anchor:
+        anchors.find((item) => item.heading === heading)?.anchor ??
+        heading
+          .toLowerCase()
+          .replace(/[^\w]+/g, '-')
+          .replace(/^-|-$/g, ''),
+      level: found[1].length,
+      text: markdown.slice(start, end).trim(),
+    };
+  });
+}
+
+/**
+ * What a component of the site says, as Markdown lines: its items in order (a `title` or an `eyebrow` starts one,
+ * `text`, `lines` and `description` go on with it, `code` in backticks), numbered for `Steps`.
+ * @param {string} tag
+ * @returns {string[]}
+ */
+function component(tag) {
+  const name = /^\s*<\/?([A-Za-z]+)/.exec(tag)?.[1] ?? '';
+  if (tag.trim().startsWith('</')) return [];
+  if (name === 'TabItem') {
+    const label = /label="([^"]+)"/.exec(tag)?.[1];
+    return label ? ['', `**${label}**`, ''] : [];
+  }
+  if (name === 'PackageInstall') {
+    const packages = /packages?=["{]['"]?([^"'}]+)/.exec(tag)?.[1];
+    return packages ? ['```bash', `npm install ${packages.trim()}`, '```'] : [];
+  }
+  /** @type {string[]} */
+  const items = [];
+  let key = '';
+  let fresh = false;
+  const token = /(\w+)\s*:|(['"`])((?:\\.|(?!\2).)*)\2|<>([\s\S]*?)<\/>/g;
+  for (const found of tag.matchAll(token)) {
+    if (found[1]) {
+      key = found[1];
+      fresh = true;
+      continue;
+    }
+    const value = (found[3] ?? inline(found[4] ?? '').trim()).replace(/\\(.)/g, '$1');
+    if (key === 'title' || key === 'eyebrow') {
+      const last = items.length - 1;
+      // An eyebrow and then its title make one item.
+      if (key === 'title' && last >= 0 && items[last].endsWith(' —'))
+        items[last] += ` **${value}**`;
+      else items.push(key === 'title' ? `**${value}**` : `${value} —`);
+    } else if (key === 'code') {
+      if (items.length > 0) items[items.length - 1] += ` \`${value}\``;
+    } else if (key === 'text' || key === 'lines' || key === 'description') {
+      const last = items.length - 1;
+      if (last < 0 || (key === 'text' && fresh && !/\*\*$|—$/.test(items[last]))) items.push(value);
+      else items[last] += /\*\*$/.test(items[last]) ? `: ${value}` : ` ${value}`;
+    }
+    fresh = false;
+  }
+  if (items.length === 0) return [];
+  return [
+    '',
+    ...items.map((item, index) => (name === 'Steps' ? `${index + 1}. ${item}` : `- ${item}`)),
+    '',
+  ];
+}
+
+/**
+ * Where the first tag of a line ends, just after its `>`; -1 when it doesn't end there, as a component written over
+ * several lines. Braces and quotes inside it are skipped.
+ * @param {string} text
+ */
+function tagEnd(text) {
+  let depth = 0;
+  /** @type {string | undefined} */
+  let quote;
+  const start = text.indexOf('<');
+  for (let index = start + 1; index < text.length; index++) {
+    const character = text[index];
+    if (quote) {
+      if (character === '\\') index++;
+      else if (character === quote) quote = undefined;
+      continue;
+    }
+    if (character === '"' || character === "'" || character === '`') quote = character;
+    else if (character === '{' || character === '[' || character === '(') depth++;
+    else if (character === '}' || character === ']' || character === ')') depth--;
+    else if (character === '>' && depth === 0 && text[index - 1] !== '=') return index + 1;
+  }
+  return -1;
+}
+
+/**
+ * A line of prose with the inline components of the site as text, and the heading anchors gone.
+ * @param {string} line
+ */
+function inline(line) {
+  return line
+    .replace(/\s*\{#[\w-]+\}\s*$/, '')
+    .replace(/<Mark>([\s\S]*?)<\/Mark>/g, '**$1**')
+    .replace(/<Os\s+name="([^"]+)"\s*\/>/g, '($1)')
+    .replace(/<[A-Z][A-Za-z]*\b[^>]*\/>/g, '')
+    .replace(/<\/?[A-Z][A-Za-z]*\b[^>]*>/g, '');
+}
+
+/** @param {string} text */
+function unquote(text) {
+  const trimmed = text.trim();
+  return /^(['"]).*\1$/.test(trimmed) ? trimmed.slice(1, -1).replace(/''/g, "'") : trimmed;
+}
+
+/** @param {string} text */
+function capitalize(text) {
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+module.exports = { toMarkdown, sectionsOf };