@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/assets/walkthrough.js

@@ -0,0 +1,233 @@
+// Walkthroughs are complete without scripts: every step shows its explanation and code in order.
+// On wide screens this adds a code pane beside the steps; tokens that stay the same between steps move
+// to their new place. The scroll layout keeps the whole walkthrough in view while its steps scroll.
+// The spotlight layout turns step titles into buttons and shows one step's explanation at a time.
+const reduced = matchMedia('(prefers-reduced-motion: reduce)');
+const SPLIT_WIDTH = 720;
+
+for (const root of document.querySelectorAll('.walkthrough[data-walkthrough]')) {
+  const unified = root.dataset.mode === 'unified';
+  const spotlight = root.dataset.layout === 'spotlight';
+  const list = root.querySelector(':scope > .walkthrough-steps');
+  const steps = [...list.children];
+  const shared = root.querySelector(':scope > .walkthrough-code');
+  const sources = unified ? [] : steps.map(step => step.querySelector(':scope > .walkthrough-code pre'));
+
+  // The pane shows copies of each step's code. The originals stay in their steps, out of sight, so screen
+  // readers still meet code beside its explanation. The pane's code is a labelled region that keyboard users
+  // can scroll, and one Copy button copies the code on show.
+  const pane = document.createElement('div');
+  pane.className = 'walkthrough-pane';
+  const bar = document.createElement('div');
+  bar.className = 'walkthrough-bar';
+  const status = document.createElement('span');
+  status.className = 'walkthrough-status';
+  const copy = document.createElement('button');
+  copy.type = 'button';
+  copy.className = 'code-copy';
+  copy.textContent = 'Copy';
+  // Copy results are announced here; the button's own label names the step it copies.
+  const announce = document.createElement('span');
+  announce.className = 'copy-status';
+  announce.setAttribute('role', 'status');
+  bar.append(status, copy, announce);
+  const stage = document.createElement('div');
+  stage.className = 'walkthrough-stage';
+  pane.append(bar, stage);
+
+  const originals = unified ? [shared.querySelector('pre')] : sources;
+  const views = originals.map(pre => pre?.cloneNode(true));
+  // The pane's toolbar repeats each code block's title or file name.
+  const names = originals.map(pre => [...(pre?.closest('.code-block')?.querySelectorAll(':scope > .code-toolbar .code-block-meta > span') ?? [])].map(item => item.textContent).join(' — '));
+  for (const view of views) {
+    if (!view) continue;
+    view.tabIndex = 0;
+    view.setAttribute('role', 'region');
+    view.hidden = true;
+    stage.append(view);
+  }
+  // A step without code keeps showing the code before it.
+  const viewFor = index => { for (let at = index; at >= 0; at--) if (views[unified ? 0 : at]) return views[unified ? 0 : at]; return views.find(Boolean); };
+
+  let active = -1;
+  let buttons = [];
+  let shown;
+  const show = (index, animate, trigger) => {
+    if (index === active) return;
+    active = index;
+    if (trigger) globalThis.shoalrunAnalytics?.track('walkthrough_step_change', { stepIndex: index, stepCount: steps.length, layout: spotlight ? 'spotlight' : 'scroll', trigger }, root);
+    steps.forEach((step, at) => step.classList.toggle('is-active', at === index));
+    const name = names[unified ? 0 : views.indexOf(viewFor(index))];
+    status.textContent = `${name ? `${name} · ` : ''}Step ${index + 1} of ${steps.length}`;
+    copy.setAttribute('aria-label', `Copy code for step ${index + 1}`);
+    buttons.forEach((button, at) => button.setAttribute('aria-expanded', String(at === index)));
+    const next = viewFor(index);
+    next.setAttribute('aria-label', `Code for step ${index + 1}; the step also includes it`);
+    if (unified) highlight(next, steps[index].dataset.highlight);
+    if (next !== shown) {
+      const previous = shown;
+      shown = next;
+      if (animate && previous && !reduced.matches) morph(previous, next);
+      else { if (previous) previous.hidden = true; next.hidden = false; }
+    }
+    focusLines(next, animate);
+  };
+
+  copy.addEventListener('click', async () => {
+    try {
+      await navigator.clipboard.writeText(shown?.querySelector('code')?.textContent ?? '');
+      globalThis.shoalrunAnalytics?.track('code_copy', { stepIndex: active, language: shown?.querySelector('code')?.className.match(/language-([\w-]+)/)?.[1] ?? '' }, root);
+      copy.textContent = 'Copied';
+      announce.textContent = `Copied code for step ${active + 1}`;
+    } catch {
+      copy.textContent = 'Copy failed';
+      announce.textContent = 'Copy failed';
+    }
+    setTimeout(() => { copy.textContent = 'Copy'; announce.textContent = ''; }, 1600);
+  });
+
+  // The active step is the last one whose top has passed a reading line in the step scroller.
+  // At the end, show the final step even when it cannot reach that line.
+  let frame = 0;
+  const track = (interaction = false) => {
+    frame = 0;
+    const line = list.getBoundingClientRect().top + Math.min(96, list.clientHeight / 3);
+    let index = 0;
+    steps.forEach((step, at) => { if (step.getBoundingClientRect().top <= line) index = at; });
+    if (list.scrollHeight > list.clientHeight + 2 && list.scrollTop + list.clientHeight >= list.scrollHeight - 2) index = steps.length - 1;
+    show(index, true, interaction ? 'scroll' : undefined);
+  };
+  const onScroll = () => { frame ||= requestAnimationFrame(() => track(true)); };
+  // Wheel input over either column advances the steps. When they reach an edge, let the page scroll.
+  const onWheel = event => {
+    if (!split || spotlight || event.ctrlKey || event.shiftKey || Math.abs(event.deltaX) > Math.abs(event.deltaY)) return;
+    const unit = event.deltaMode === WheelEvent.DOM_DELTA_LINE ? 16 : event.deltaMode === WheelEvent.DOM_DELTA_PAGE ? list.clientHeight : 1;
+    const amount = event.deltaY * unit;
+    const next = Math.max(0, Math.min(list.scrollHeight - list.clientHeight, list.scrollTop + amount));
+    if (Math.abs(next - list.scrollTop) < 1) return;
+    event.preventDefault();
+    list.scrollTop = next;
+  };
+  // Clicking a step shows it at once; links inside it still work.
+  steps.forEach((step, index) => step.addEventListener('click', event => {
+    if (!split || event.target.closest('a, button') || getSelection()?.toString()) return;
+    show(index, true, 'click');
+  }));
+
+  // Spotlight titles become buttons while the pane shows; Up and Down move between them.
+  const titles = steps.map(step => step.querySelector(':scope > .walkthrough-step-title'));
+  const addButtons = () => {
+    buttons = titles.map((title, index) => {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'walkthrough-step-button';
+      button.append(...title.childNodes);
+      title.append(button);
+      button.addEventListener('click', () => show(index, true, 'click'));
+      button.addEventListener('keydown', event => {
+        const next = { ArrowDown: index + 1, ArrowUp: index - 1, Home: 0, End: steps.length - 1 }[event.key];
+        if (next === undefined || next < 0 || next >= steps.length) return;
+        event.preventDefault();
+        buttons[next].focus();
+        show(next, true, 'keyboard');
+      });
+      return button;
+    });
+  };
+  const removeButtons = () => {
+    buttons.forEach((button, index) => {
+      const focused = button === document.activeElement;
+      titles[index].append(...button.childNodes);
+      button.remove();
+      // Keep a keyboard user's place when the layout narrows under them.
+      if (focused) { titles[index].tabIndex = -1; titles[index].focus({ preventScroll: true }); }
+    });
+    buttons = [];
+  };
+
+  let split = false;
+  const layout = () => {
+    // The split style adds a border. Measure the stable outer box so that
+    // crossing the threshold cannot undo itself after that border is applied.
+    const wide = root.getBoundingClientRect().width >= SPLIT_WIDTH;
+    if (wide === split) return;
+    split = wide;
+    root.classList.toggle('is-split', wide);
+    // Hidden originals leave the tab order so focus never lands on something invisible.
+    for (const element of root.querySelectorAll('.walkthrough-code :is(pre, button)')) {
+      if (wide) { element.dataset.tabindex = element.getAttribute('tabindex') ?? ''; element.tabIndex = -1; }
+      else if (element.dataset.tabindex !== undefined) { element.dataset.tabindex ? element.setAttribute('tabindex', element.dataset.tabindex) : element.removeAttribute('tabindex'); delete element.dataset.tabindex; }
+    }
+    if (wide) {
+      list.after(pane);
+      if (spotlight) addButtons();
+      else {
+        list.tabIndex = 0;
+        list.setAttribute('aria-label', `Steps for ${root.getAttribute('aria-label')}`);
+        list.addEventListener('scroll', onScroll, { passive: true });
+        root.addEventListener('wheel', onWheel, { passive: false });
+      }
+      const current = Math.max(active, 0);
+      active = -1;
+      show(current, false);
+      if (!spotlight) track();
+    } else {
+      list.removeEventListener('scroll', onScroll);
+      root.removeEventListener('wheel', onWheel);
+      list.removeAttribute('tabindex');
+      list.removeAttribute('aria-label');
+      removeButtons();
+      pane.remove();
+    }
+  };
+  if (views.some(Boolean)) {
+    new ResizeObserver(layout).observe(root);
+    layout();
+  }
+}
+
+function highlight(view, value) {
+  const lines = new Set((value ?? '').split(' ').filter(Boolean).map(Number));
+  view.querySelectorAll(':scope > code > .line').forEach((line, index) => line.classList.toggle('is-highlighted', lines.has(index + 1)));
+  view.toggleAttribute('data-focus', lines.size > 0);
+}
+
+// Keep the first highlighted line in view inside the pane.
+function focusLines(view, animate) {
+  const first = view.querySelector('.line.is-highlighted');
+  const top = first ? Math.max(0, first.offsetTop - view.clientHeight / 3) : 0;
+  view.scrollTo({ top, behavior: animate && !reduced.matches ? 'smooth' : 'auto' });
+}
+
+// FLIP: measure tokens in the old code, swap, then play each kept token from its old position to its new one.
+// Removed tokens fade out on a snapshot of the old code; new tokens fade in after the movement starts.
+function morph(from, to) {
+  const before = new Map();
+  for (const token of from.querySelectorAll('[data-k]')) before.set(token.dataset.k, token.getBoundingClientRect());
+  const ghost = from.cloneNode(true);
+  ghost.classList.add('walkthrough-ghost');
+  ghost.inert = true;
+  ghost.setAttribute('aria-hidden', 'true');
+  ghost.style.top = `${from.offsetTop}px`;
+  ghost.style.height = `${from.offsetHeight}px`;
+  const scrollTop = from.scrollTop;
+  const scrollLeft = from.scrollLeft;
+  from.hidden = true;
+  to.hidden = false;
+  from.after(ghost);
+  ghost.scrollTop = scrollTop;
+  ghost.scrollLeft = scrollLeft;
+  const kept = new Set();
+  const timing = { duration: 480, easing: 'cubic-bezier(.2,.7,.2,1)' };
+  for (const token of to.querySelectorAll('[data-k]')) {
+    const old = before.get(token.dataset.k);
+    if (!old) { token.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 260, delay: 220, fill: 'backwards' }); continue; }
+    kept.add(token.dataset.k);
+    const now = token.getBoundingClientRect();
+    const dx = old.left - now.left;
+    const dy = old.top - now.top;
+    if (dx || dy) token.animate([{ transform: `translate(${dx}px, ${dy}px)` }, { transform: 'none' }], timing);
+  }
+  for (const token of ghost.querySelectorAll('[data-k]')) if (kept.has(token.dataset.k)) token.style.visibility = 'hidden';
+  ghost.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 200, fill: 'forwards' }).finished.then(() => ghost.remove(), () => ghost.remove());
+}

package/dist/agent-discovery.d.ts

@@ -0,0 +1,11 @@
+export type AgentDiscovery = {
+    mode: 'focus' | 'visible' | 'disclosure' | 'off';
+    label: string;
+    message?: string;
+    links: {
+        article: string;
+        index: string;
+        markdown: string;
+    };
+};
+export declare function resolveAgentDiscovery(value: unknown): AgentDiscovery;

package/dist/agent-discovery.js

@@ -0,0 +1,37 @@
+export function resolveAgentDiscovery(value) {
+    const mapping = (value, where) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(`${where} must be a mapping`);
+        return value;
+    };
+    const config = value === undefined ? {} : mapping(value, 'site.agentDiscovery');
+    for (const key of Object.keys(config))
+        if (!['mode', 'label', 'message', 'links'].includes(key))
+            throw new Error(`site.agentDiscovery does not accept ${key}`);
+    const mode = config.mode === undefined ? 'focus' : config.mode;
+    if (typeof mode !== 'string' || !['focus', 'visible', 'disclosure', 'off'].includes(mode))
+        throw new Error('site.agentDiscovery.mode must be focus, visible, disclosure, or off');
+    const label = (value, fallback, where) => {
+        if (value === undefined)
+            return fallback;
+        if (typeof value !== 'string' || !value.trim())
+            throw new Error(`${where} must be nonempty text`);
+        return value.trim();
+    };
+    if (config.message !== undefined && typeof config.message !== 'string')
+        throw new Error('site.agentDiscovery.message must be text');
+    const links = config.links === undefined ? {} : mapping(config.links, 'site.agentDiscovery.links');
+    for (const key of Object.keys(links))
+        if (!['article', 'index', 'markdown'].includes(key))
+            throw new Error(`site.agentDiscovery.links does not accept ${key}`);
+    return {
+        mode: mode,
+        label: label(config.label, 'For agents', 'site.agentDiscovery.label'),
+        message: config.message?.trim() || undefined,
+        links: {
+            article: label(links.article, 'Skip to article', 'site.agentDiscovery.links.article'),
+            index: label(links.index, 'Documentation index', 'site.agentDiscovery.links.index'),
+            markdown: label(links.markdown, 'Read this page as Markdown', 'site.agentDiscovery.links.markdown'),
+        },
+    };
+}

package/dist/analytics.d.ts

@@ -0,0 +1,2 @@
+/** Browser-only adapter: resolve its source without importing customer code. */
+export declare function resolveAnalytics(value: unknown, configFile: string): string | undefined;

package/dist/analytics.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { configMappingAt } from './compiler-config.js';
+/** Browser-only adapter: resolve its source without importing customer code. */
+export function resolveAnalytics(value, configFile) {
+    if (value === undefined || value === false)
+        return undefined;
+    const config = configMappingAt(value, 'analytics');
+    if (Object.keys(config).some(key => key !== 'module'))
+        throw new Error('analytics accepts only module');
+    if (typeof config.module !== 'string' || !config.module.trim() || !/\.m?js$/i.test(config.module) || /^[a-z][a-z0-9+.-]*:/i.test(config.module))
+        throw new Error('analytics.module must name a local .js or .mjs browser module');
+    return path.resolve(path.dirname(configFile), config.module);
+}

package/dist/answer-cache.d.ts

@@ -0,0 +1,24 @@
+import type { AskResult } from './ask.js';
+export type CacheOptions = {
+    maxEntries?: number;
+    ttlMs?: number;
+    now?: () => number;
+};
+export declare const normalizeQuestion: (question: string) => string;
+export declare function cacheable(result: AskResult): boolean;
+export declare class AnswerCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private readonly now;
+    hits: number;
+    misses: number;
+    constructor(options?: CacheOptions);
+    key(question: string, scope: {
+        variant?: string;
+        readerSelection?: Record<string, string[]>;
+    }): string;
+    get(key: string, digestOf: (id: string) => string | undefined): AskResult | undefined;
+    set(key: string, result: AskResult, digestOf: (id: string) => string | undefined): void;
+    get size(): number;
+}

package/dist/answer-cache.js

@@ -0,0 +1,55 @@
+// Case, spacing, and closing punctuation do not change a question.
+export const normalizeQuestion = (question) => question.toLocaleLowerCase().replace(/\s+/g, ' ').replace(/[\s?.!]+$/g, '').trim();
+// Only an answer that passed every check is worth reusing. A hedged answer, a flagged one, or one that was declined is not stored. Any note
+// means a layer did not run as planned, such as Jev being down, so the answer is not stored either. The exception is the note that
+// records a successful escalation, because the answer that is shown has already passed every check.
+export function cacheable(result) {
+    const notes = result.notes.filter(note => !/^The answer was flagged \(.*\), so .* answered too\. Its answer has fewer flags and is shown\.$/.test(note));
+    return (result.decision === 'answered' || result.decision === 'excerpt') && !result.uncited && !result.unsupportedClaims.length && !result.unsupportedCode.length && !result.invalidCitations.length && !notes.length;
+}
+export class AnswerCache {
+    entries = new Map();
+    maxEntries;
+    ttlMs;
+    now;
+    hits = 0;
+    misses = 0;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 500;
+        this.ttlMs = options.ttlMs ?? 24 * 60 * 60 * 1000;
+        this.now = options.now ?? Date.now;
+    }
+    key(question, scope) {
+        return JSON.stringify([normalizeQuestion(question), scope.variant ?? '', Object.entries(scope.readerSelection ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([facet, choices]) => [facet, [...choices].sort()])]);
+    }
+    get(key, digestOf) {
+        const entry = this.entries.get(key);
+        if (!entry || this.now() - entry.storedAt > this.ttlMs || [...entry.digests].some(([id, digest]) => digestOf(id) !== digest)) {
+            if (entry)
+                this.entries.delete(key);
+            this.misses++;
+            return undefined;
+        }
+        // Reading an entry makes it the most recent, so the least recently used one is evicted first.
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        this.hits++;
+        return entry.result;
+    }
+    set(key, result, digestOf) {
+        if (!cacheable(result))
+            return;
+        const digests = new Map();
+        for (const source of result.considered) {
+            const digest = digestOf(source.id);
+            if (digest === undefined)
+                return;
+            digests.set(source.id, digest);
+        }
+        this.entries.delete(key);
+        this.entries.set(key, { result, storedAt: this.now(), digests });
+        while (this.entries.size > this.maxEntries)
+            this.entries.delete(this.entries.keys().next().value);
+    }
+    get size() { return this.entries.size; }
+}

package/dist/answer-cards.d.ts

@@ -0,0 +1,71 @@
+import type { AskResult, Source } from './ask.js';
+export type ReaderSelection = Record<string, string[]>;
+export type CardQuestion = {
+    question: string;
+    aliases?: string[];
+};
+export type Card = {
+    id: string;
+    question: string;
+    aliases: string[];
+    answer: string;
+    sources: Source[];
+    digests: Record<string, string>;
+    model: string;
+    generatedAt: string;
+    variant: string;
+    readerSelection?: ReaderSelection;
+    decision: 'answered' | 'excerpt';
+};
+export type CardFile = {
+    schemaVersion: 1;
+    embedding: {
+        provider: string;
+        model: string;
+        space: string;
+        dimension: number;
+    };
+    cards: Array<Card & {
+        vectors: string[];
+    }>;
+};
+export declare const encodeVector: (vector: Float32Array) => string;
+export declare function decodeVector(value: string): Float32Array;
+export type BuildInput = {
+    questions: CardQuestion[];
+    ask: (question: string) => Promise<AskResult>;
+    embed: (texts: string[]) => Promise<Float32Array[]>;
+    digestOf: (id: string) => string | undefined;
+    embedding: CardFile['embedding'];
+    variant: string;
+    readerSelection?: ReaderSelection;
+    now?: () => Date;
+    progress?: (message: string) => void;
+};
+export declare function rejection(result: AskResult): string | undefined;
+export declare function buildCards(input: BuildInput): Promise<{
+    file: CardFile;
+    rejected: Array<{
+        question: string;
+        reason: string;
+    }>;
+}>;
+export declare function writeCards(directory: string, file: CardFile): Promise<string>;
+export declare function readCards(directory: string): Promise<CardFile | undefined>;
+export type CardMatch = {
+    card: Card;
+    similarity: number;
+};
+export declare class CardIndex {
+    private readonly rows;
+    readonly embedding: CardFile['embedding'];
+    constructor(file: CardFile);
+    get size(): number;
+    match(query: Float32Array, options: {
+        threshold: number;
+        variant: string;
+        readerSelection?: ReaderSelection;
+    }): CardMatch | undefined;
+}
+export declare const cardIsCurrent: (card: Card, digestOf: (id: string) => string | undefined) => boolean;
+export declare function parseCardQuestions(text: string): CardQuestion[];

package/dist/answer-cards.js

@@ -0,0 +1,148 @@
+import { readFile, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { cacheable, normalizeQuestion } from './answer-cache.js';
+import { aiDirectory } from './index-build.js';
+export const encodeVector = (vector) => Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength).toString('base64');
+export function decodeVector(value) {
+    const bytes = Buffer.from(value, 'base64');
+    return new Float32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+}
+const slug = (question) => normalizeQuestion(question).replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '').slice(0, 60);
+const scopeKey = (variant, selection) => JSON.stringify([variant, Object.entries(selection ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([facet, choices]) => [facet, [...choices].sort()])]);
+// Why an answer is not good enough to keep, or undefined when it is.
+export function rejection(result) {
+    if (cacheable(result))
+        return undefined;
+    if (result.decision === 'declined')
+        return 'the docs do not cover it';
+    if (result.decision === 'hedged')
+        return 'the answer was hedged';
+    if (result.decision === 'search')
+        return 'the scorer was down, so no answer was written';
+    if (result.uncited)
+        return 'the answer cites nothing';
+    if (result.unsupportedClaims.length)
+        return `${result.unsupportedClaims.length} unsupported sentence(s)`;
+    if (result.unsupportedCode.length)
+        return 'code that is not in the docs';
+    if (result.invalidCitations.length)
+        return 'an invented citation';
+    return `the answer carried a note: ${result.notes[0] ?? 'unknown'}`;
+}
+export async function buildCards(input) {
+    const kept = [];
+    const rejected = [];
+    const seen = new Set();
+    for (const item of input.questions) {
+        const question = item.question.trim();
+        const id = slug(question);
+        if (!question || seen.has(id)) {
+            rejected.push({ question, reason: question ? 'a card for this question already exists' : 'the question is empty' });
+            continue;
+        }
+        seen.add(id);
+        let result;
+        try {
+            result = await input.ask(question);
+        }
+        catch (error) {
+            rejected.push({ question, reason: `asking failed: ${error.message}` });
+            continue;
+        }
+        const reason = rejection(result);
+        if (reason) {
+            rejected.push({ question, reason });
+            input.progress?.(`skipped: ${question} (${reason})`);
+            continue;
+        }
+        const digests = {};
+        for (const source of result.considered) {
+            const digest = input.digestOf(source.id);
+            if (digest !== undefined)
+                digests[source.id] = digest;
+        }
+        if (Object.keys(digests).length !== result.considered.length) {
+            rejected.push({ question, reason: 'a passage behind the answer is unknown' });
+            continue;
+        }
+        const aliases = [...new Set((item.aliases ?? []).map(alias => alias.trim()).filter(Boolean))];
+        input.progress?.(`kept: ${question}`);
+        kept.push({ card: { id, question, aliases, answer: result.answer, sources: result.sources, digests, model: result.routing?.answeredBy ?? 'excerpt', generatedAt: (input.now ?? (() => new Date()))().toISOString(), variant: input.variant, ...(input.readerSelection && Object.keys(input.readerSelection).length ? { readerSelection: input.readerSelection } : {}), decision: result.decision }, phrases: [question, ...aliases] });
+    }
+    const vectors = kept.length ? await input.embed(kept.flatMap(item => item.phrases)) : [];
+    let at = 0;
+    const cards = kept.map(item => ({ ...item.card, vectors: item.phrases.map(() => encodeVector(vectors[at++])) }));
+    return { file: { schemaVersion: 1, embedding: input.embedding, cards }, rejected };
+}
+export async function writeCards(directory, file) {
+    const target = path.join(await aiDirectory(directory), 'answers.json');
+    await writeFile(target, JSON.stringify(file) + '\n');
+    return target;
+}
+export async function readCards(directory) {
+    const root = path.resolve(directory);
+    const target = path.join(root, 'ai', 'answers.json');
+    let file;
+    try {
+        const real = await realpath(path.join(root, 'ai'));
+        const realRoot = await realpath(root);
+        if (real !== realRoot && !real.startsWith(realRoot + path.sep))
+            throw new Error('The ai directory leaves the site directory');
+        file = JSON.parse(await readFile(target, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    if (file?.schemaVersion !== 1 || !Array.isArray(file.cards) || !file.embedding || file.cards.some(card => !card || typeof card.id !== 'string' || typeof card.answer !== 'string' || !Array.isArray(card.vectors) || typeof card.digests !== 'object'))
+        throw new Error('Unsupported or invalid answers.json');
+    return file;
+}
+export class CardIndex {
+    rows = [];
+    embedding;
+    constructor(file) {
+        this.embedding = file.embedding;
+        for (const { vectors, ...card } of file.cards)
+            for (const vector of vectors)
+                this.rows.push({ card, vector: decodeVector(vector) });
+    }
+    get size() { return new Set(this.rows.map(row => row.card.id)).size; }
+    // The closest card for the same publication and reader view, when it is close enough. Vectors are unit length, so a dot product is the cosine.
+    match(query, options) {
+        const scope = scopeKey(options.variant, options.readerSelection);
+        let best;
+        for (const row of this.rows) {
+            if (row.vector.length !== query.length || scopeKey(row.card.variant, row.card.readerSelection) !== scope)
+                continue;
+            let similarity = 0;
+            for (let at = 0; at < query.length; at++)
+                similarity += query[at] * row.vector[at];
+            if (!best || similarity > best.similarity)
+                best = { card: row.card, similarity };
+        }
+        return best && best.similarity >= options.threshold ? best : undefined;
+    }
+}
+// A card is current only while every passage behind it has the digest it had when the card was made.
+export const cardIsCurrent = (card, digestOf) => Object.entries(card.digests).every(([id, digest]) => digestOf(id) === digest);
+// A list of questions, as JSON or YAML: plain strings, or mappings with `question` and optional `aliases`.
+export function parseCardQuestions(text) {
+    const value = parse(text);
+    const list = Array.isArray(value) ? value : value && typeof value === 'object' && Array.isArray(value.questions) ? value.questions : undefined;
+    if (!list)
+        throw new Error('The questions file must be a list, or a mapping with a questions list');
+    return list.map((item, at) => {
+        if (typeof item === 'string')
+            return { question: item };
+        if (item && typeof item === 'object' && typeof item.question === 'string') {
+            const aliases = item.aliases;
+            if (aliases !== undefined && (!Array.isArray(aliases) || aliases.some(alias => typeof alias !== 'string')))
+                throw new Error(`Question ${at + 1}: aliases must be a list of strings`);
+            return { question: item.question, ...(aliases ? { aliases: aliases } : {}) };
+        }
+        throw new Error(`Question ${at + 1} must be a string or a mapping with a question`);
+    });
+}

package/dist/api-embeds.d.ts

@@ -0,0 +1,22 @@
+import type { ApiReader } from './api.js';
+export type ApiEmbedRequest = {
+    component: 'ApiExample' | 'ApiSchema';
+    operation?: string;
+    api?: string;
+    kind?: 'request' | 'response';
+    mediaType?: string;
+    status?: string;
+    example?: string;
+    schema?: string;
+};
+export type ApiEmbedUse = ApiEmbedRequest & {
+    sourceFile: string;
+    documentKey: string;
+};
+export declare function apiEmbedComponent(node: any, file: string): any;
+export declare function resolveApiEmbedTree(tree: any, reader: ApiReader, sourceFor: (operation: string) => {
+    file: string;
+    sourceOperationId: string;
+}, sourceForApi: (api: string) => {
+    file: string;
+}, documentKey: string, uses: ApiEmbedUse[]): Promise<any>;