docugate 0.2.9 → 0.3.0

package/dist/select.js

@@ -0,0 +1,215 @@
+import { emitKeypressEvents } from 'node:readline';
+import { bold, colorOn, dim, gold, green } from './ui.js';
+const strip = (s) => s.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+/** How well `text` matches a search: lower is better, null is no match. */
+export function matchScore(text, query) {
+    const t = text.toLowerCase();
+    const q = query.toLowerCase().trim();
+    if (!q)
+        return 0;
+    const at = t.indexOf(q);
+    if (at >= 0)
+        return at === 0 ? 0 : t[at - 1] === ' ' ? 1 : 2;
+    // Letters in order, like "dsy" for "docs sync".
+    let i = 0;
+    for (const ch of t)
+        if (ch === q[i])
+            i++;
+    return i === q.length ? 5 : null;
+}
+export function filterChoices(choices, query) {
+    if (!query.trim())
+        return choices;
+    return choices
+        .map((c, order) => ({ c, order, score: matchScore(`${c.label} ${c.keywords ?? ''} ${c.status ?? ''}`, query) }))
+        .filter((x) => x.score !== null)
+        .sort((a, b) => a.score - b.score || a.order - b.order)
+        .map((x) => x.c);
+}
+/** The first choice Enter should land on: the recommended one, else the first that can be chosen. */
+export function initialCursor(choices) {
+    const rec = choices.findIndex((c) => c.recommended && !c.disabled);
+    if (rec >= 0)
+        return rec;
+    const first = choices.findIndex((c) => !c.disabled);
+    return Math.max(0, first);
+}
+const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+/**
+ * Moves to the next choice in a direction. A disabled one can be moved onto, so
+ * its description and the reason it is unavailable show; only Enter is refused.
+ */
+function step(list, from, dir) {
+    return clamp(from + dir, 0, Math.max(0, list.length - 1));
+}
+/** One key press, applied to the picker's state. */
+export function handleKey(choices, state, str, key, rows) {
+    const list = filterChoices(choices, state.query);
+    const move = (cursor) => {
+        const c = clamp(cursor, 0, Math.max(0, list.length - 1));
+        const top = c < state.top ? c : c >= state.top + rows ? c - rows + 1 : state.top;
+        return { state: { ...state, cursor: c, top } };
+    };
+    if (key.ctrl && (key.name === 'c' || key.name === 'd'))
+        return { done: 'cancelled' };
+    if (key.name === 'escape')
+        return state.query ? { state: { query: '', cursor: initialCursor(choices), top: 0 } } : { done: 'cancelled' };
+    if (key.name === 'return' || key.name === 'enter') {
+        const choice = list[state.cursor];
+        if (!choice)
+            return { state };
+        if (choice.disabled)
+            return { done: 'blocked', reason: choice.disabled, state };
+        return { done: 'chosen', choice };
+    }
+    if (key.name === 'up' || (key.ctrl && key.name === 'p'))
+        return move(step(list, state.cursor, -1));
+    if (key.name === 'down' || (key.ctrl && key.name === 'n'))
+        return move(step(list, state.cursor, 1));
+    if (key.name === 'pageup')
+        return move(state.cursor - rows);
+    if (key.name === 'pagedown')
+        return move(state.cursor + rows);
+    if (key.name === 'home')
+        return move(0);
+    if (key.name === 'end')
+        return move(list.length - 1);
+    if (key.name === 'backspace') {
+        const query = state.query.slice(0, -1);
+        return { state: { query, cursor: query ? 0 : initialCursor(choices), top: 0 } };
+    }
+    if (key.ctrl && key.name === 'u')
+        return { state: { query: '', cursor: initialCursor(choices), top: 0 } };
+    // Anything printable is part of the search.
+    if (str && !key.ctrl && !key.meta && /^[\x20-\x7e -￿]$/.test(str)) {
+        const query = state.query + str;
+        return { state: { query, cursor: 0, top: 0 } };
+    }
+    return { state };
+}
+const fit = (text, width) => {
+    const plain = strip(text);
+    if (plain.length <= width)
+        return text;
+    // Over width: cut the plain text. Color is not worth keeping on a line this long.
+    return `${plain.slice(0, Math.max(0, width - 1))}…`;
+};
+/** The picker as lines of text. */
+export function renderPicker(choices, state, o) {
+    const list = filterChoices(choices, state.query);
+    const rule = dim('─'.repeat(Math.max(10, Math.min(o.width - 4, 78))));
+    const lines = [];
+    const w = o.width - 2;
+    if (o.title)
+        lines.push(`  ${bold(o.title)}`);
+    lines.push(`  ${rule}`);
+    lines.push(`  ${dim('/')} ${state.query ? state.query : dim('Type to search')}${state.query ? gold('▌') : ''}`);
+    lines.push(`  ${rule}`);
+    if (list.length === 0) {
+        lines.push('', `  ${dim('Nothing matches')} "${state.query}"`, '');
+    }
+    else {
+        const visible = list.slice(state.top, state.top + o.rows);
+        const labelWidth = Math.min(46, Math.max(...list.map((c) => c.label.length)) + 2);
+        lines.push(`    ${state.top > 0 ? dim('↑ more above') : ' '}`.trimEnd());
+        visible.forEach((c, i) => {
+            const at = state.top + i === state.cursor;
+            const mark = c.recommended ? gold('●') : c.disabled ? dim('◌') : dim('·');
+            const pointer = at ? gold('❯') : ' ';
+            const label = c.label.padEnd(labelWidth);
+            const text = c.disabled ? dim(label) : at ? bold(gold(label)) : label;
+            const status = c.status ? (at ? c.status : dim(c.status)) : '';
+            lines.push(fit(`  ${pointer} ${mark} ${text}${status}`, w));
+        });
+        lines.push(`    ${state.top + o.rows < list.length ? dim('↓ more below') : ' '}`.trimEnd());
+        const focus = list[state.cursor];
+        const blurb = focus?.disabled ? `${focus.description ?? ''} ${dim(`(${focus.disabled})`)}`.trim() : focus?.description;
+        lines.push('', ...(blurb ? wrap(blurb, Math.min(w - 4, 76)).map((l) => `  ${dim('│')} ${l}`) : []));
+    }
+    if (o.note)
+        lines.push('', `  ${o.note}`);
+    if (o.legend !== false)
+        lines.push('', `  ${gold('●')} ${dim('Recommended')}   ${dim('◌ Needs something first')}`);
+    lines.push('', `  ${dim(o.footer ?? '↑↓ select · type to search · ↵ confirm · esc cancel')}`);
+    return lines.map((l) => fit(l, o.width - 1));
+}
+function wrap(text, width) {
+    const out = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        if ((line + ' ' + word).trim().length > width && line) {
+            out.push(line);
+            line = word;
+        }
+        else
+            line = `${line} ${word}`.trim();
+    }
+    if (line)
+        out.push(line);
+    return out;
+}
+/** Whether there is a real terminal to draw a picker in. */
+export const canPick = (io = { stdin: process.stdin, stdout: process.stdout }) => Boolean(io.stdin.isTTY && io.stdout.isTTY) && typeof io.stdin.setRawMode === 'function' && !process.env.CI;
+/**
+ * Draws the picker and resolves with the chosen value, or null if the person
+ * pressed escape or Ctrl+C. Draws in place and leaves one line behind.
+ */
+export function select(options, io = { stdin: process.stdin, stdout: process.stdout }) {
+    const { stdin, stdout } = io;
+    const rows = Math.max(3, Math.min(options.rows ?? 8, (stdout.rows ?? 24) - 14));
+    const color = colorOn();
+    let state = { query: '', cursor: initialCursor(options.choices), top: 0 };
+    state.top = Math.max(0, state.cursor - rows + 1);
+    let drawn = 0;
+    let note = options.note;
+    const hint = (s) => (color ? s : strip(s));
+    const draw = () => {
+        const lines = renderPicker(options.choices, state, {
+            title: options.title,
+            width: stdout.columns ?? 80,
+            rows,
+            footer: options.footer,
+            note,
+            legend: options.legend,
+        });
+        stdout.write(`${drawn ? `\x1b[${drawn}A\r` : ''}\x1b[0J${hint(lines.join('\n'))}\n`);
+        drawn = lines.length;
+    };
+    const erase = () => stdout.write(`${drawn ? `\x1b[${drawn}A\r` : ''}\x1b[0J`);
+    return new Promise((resolve) => {
+        emitKeypressEvents(stdin);
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdout.write('\x1b[?25l');
+        const finish = (value, summary) => {
+            stdin.off('keypress', onKey);
+            stdin.setRawMode(Boolean(wasRaw));
+            stdin.pause();
+            erase();
+            stdout.write('\x1b[?25h');
+            if (summary)
+                stdout.write(`  ${green('✓')} ${summary}\n`);
+            resolve(value);
+        };
+        const onKey = (str, key = {}) => {
+            const result = handleKey(options.choices, state, str, key, rows);
+            if ('done' in result) {
+                if (result.done === 'cancelled')
+                    return finish(null);
+                if (result.done === 'chosen')
+                    return finish(result.choice.value, result.choice.label);
+                note = `${gold('!')} ${result.reason}`;
+                state = result.state;
+                return draw();
+            }
+            note = options.note;
+            state = result.state;
+            draw();
+        };
+        stdin.on('keypress', onKey);
+        // A terminal closed mid-menu must still get its cursor back.
+        process.once('exit', () => stdout.write('\x1b[?25h'));
+        draw();
+    });
+}

package/dist/session.d.ts

@@ -0,0 +1,46 @@
+export type AccountState = {
+    state: 'signed-in';
+    login: string;
+} | {
+    state: 'signed-out';
+    reason?: string;
+}
+/** A token is saved but DocuGate could not be reached to confirm it. */
+ | {
+    state: 'offline';
+    detail: string;
+};
+export type SessionDeps = {
+    getSessionFn?: () => Promise<{
+        user: {
+            githubLogin: string;
+        } | null;
+    }>;
+    hasToken?: () => boolean;
+    env?: NodeJS.ProcessEnv;
+    /** How long to wait for DocuGate before calling it offline. */
+    timeoutMs?: number;
+};
+export declare function accountState(deps?: SessionDeps): Promise<AccountState>;
+export type EnsureOptions = SessionDeps & {
+    /** Whether anyone can be asked. False in CI, pipes and under --no-input. */
+    interactive: boolean;
+    ask?: (question: string) => Promise<boolean>;
+    loginFn?: (baseUrl: string) => Promise<unknown>;
+    say?: (line: string) => void;
+    /** What the account is needed for, to finish the sentence "…to ___". */
+    reason?: string;
+};
+export type Ensured = {
+    ok: true;
+    login: string;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * Makes sure there is a signed-in account before a command that needs one.
+ * Signed in: carry on. Not, and someone can answer: offer to connect, then do
+ * it. Not, and nobody can answer: say exactly what to do instead of hanging.
+ */
+export declare function ensureSignedIn(options: EnsureOptions): Promise<Ensured>;

package/dist/session.js

@@ -0,0 +1,54 @@
+import { BASE_URL, getSession } from './api.js';
+import { login, loadCredentials } from './auth.js';
+import { hint } from './ui.js';
+const withTimeout = (p, ms) => Promise.race([p, new Promise((_, reject) => setTimeout(() => reject(new Error('timed out')), ms).unref())]);
+export async function accountState(deps = {}) {
+    const env = deps.env ?? process.env;
+    const hasToken = deps.hasToken ?? (() => Boolean(env.DOCUGATE_TOKEN || loadCredentials()));
+    if (!hasToken())
+        return { state: 'signed-out' };
+    try {
+        const { user } = await withTimeout((deps.getSessionFn ?? getSession)(), deps.timeoutMs ?? 3000);
+        return user ? { state: 'signed-in', login: user.githubLogin } : { state: 'signed-out', reason: 'Your saved sign-in has expired.' };
+    }
+    catch (error) {
+        const message = error.message;
+        // A 401 surfaces as "Run docugate login": the token is no good, not the network.
+        if (/docugate login/i.test(message))
+            return { state: 'signed-out', reason: 'Your saved sign-in has expired.' };
+        return { state: 'offline', detail: message };
+    }
+}
+/**
+ * Makes sure there is a signed-in account before a command that needs one.
+ * Signed in: carry on. Not, and someone can answer: offer to connect, then do
+ * it. Not, and nobody can answer: say exactly what to do instead of hanging.
+ */
+export async function ensureSignedIn(options) {
+    const say = options.say ?? (() => { });
+    const first = await accountState(options);
+    if (first.state === 'signed-in')
+        return { ok: true, login: first.login };
+    if (first.state === 'offline') {
+        return { ok: false, why: `Could not reach DocuGate to confirm your sign-in (${first.detail}). Check your connection and try again.` };
+    }
+    const need = options.reason ? ` to ${options.reason}` : '';
+    if (!options.interactive || !options.ask) {
+        return { ok: false, why: `This needs a DocuGate account${need}. Run ${hint('login')}, or set DOCUGATE_TOKEN in CI.` };
+    }
+    if (first.reason)
+        say(first.reason);
+    if (!(await options.ask(`Connect your DocuGate account${need}?`))) {
+        return { ok: false, why: `This needs a DocuGate account${need}. Run ${hint('login')} when you are ready.` };
+    }
+    try {
+        await (options.loginFn ?? ((url) => login(url)))(BASE_URL);
+    }
+    catch (error) {
+        return { ok: false, why: `Sign-in did not finish: ${error.message}` };
+    }
+    const after = await accountState(options);
+    return after.state === 'signed-in'
+        ? { ok: true, login: after.login }
+        : { ok: false, why: 'Sign-in did not finish, so nothing was connected.' };
+}

package/dist/spinner.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A live "working on it" line for the waits in setup: a spinner, the elapsed
+ * time, and a status that changes every few seconds, so a minute of IBM Bob
+ * reading the code never looks like a frozen terminal.
+ *
+ * It runs in a small child process, so it keeps moving even while the main
+ * process is blocked waiting on Bob Shell. Only in a terminal; elsewhere it
+ * prints the first status once.
+ */
+export declare function startSpinner(statuses: string[]): (finalLine?: string) => void;
+/** Environment variables that look like an IBM Bob key under another name. */
+export declare function bobKeyCandidates(env?: NodeJS.ProcessEnv): string[];

package/dist/spinner.js

@@ -16,18 +16,18 @@ export function startSpinner(statuses) {
                 process.stderr.write(`${finalLine}\n`);
         };
     }
-    const script = `
-    const statuses = JSON.parse(process.argv[1]);
-    const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
-    const start = Date.now();
-    let i = 0;
-    const cols = () => process.stderr.columns || 80;
-    setInterval(() => {
-      const secs = Math.floor((Date.now() - start) / 1000);
-      const status = statuses[Math.min(Math.floor(secs / 6), statuses.length - 1)];
-      const line = '  ' + frames[i++ % frames.length] + ' ' + status + '... ' + secs + 's';
-      process.stderr.write('\\r' + line.slice(0, cols() - 1).padEnd(cols() - 1));
-    }, 90);
+    const script = `
+    const statuses = JSON.parse(process.argv[1]);
+    const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
+    const start = Date.now();
+    let i = 0;
+    const cols = () => process.stderr.columns || 80;
+    setInterval(() => {
+      const secs = Math.floor((Date.now() - start) / 1000);
+      const status = statuses[Math.min(Math.floor(secs / 6), statuses.length - 1)];
+      const line = '  ' + frames[i++ % frames.length] + ' ' + status + '... ' + secs + 's';
+      process.stderr.write('\\r' + line.slice(0, cols() - 1).padEnd(cols() - 1));
+    }, 90);
   `;
     const child = spawn(process.execPath, ['-e', script, JSON.stringify(statuses)], {
         stdio: ['ignore', 'ignore', 'inherit'],

package/dist/status.d.ts

@@ -0,0 +1,46 @@
+import type { AccountState, SessionDeps } from './session.js';
+import type { GitFn } from './sync/changes.js';
+export type Next = {
+    command: string;
+    why: string;
+    done?: boolean;
+};
+export type Status = {
+    account: AccountState;
+    project: {
+        git: boolean;
+        setUp: boolean;
+        docsDir: string;
+        pages: number;
+        role?: string;
+        space?: string;
+        freshness: string;
+    };
+    sync: {
+        workflow: boolean;
+        hook: boolean;
+        key: 'anthropic' | 'openai' | null;
+        lastRunAt?: string;
+        /** Commits since the last sync, or null when it could not be worked out. */
+        commits: number | null;
+        /** Pages the deterministic pass thinks those commits touched. */
+        affected: number;
+        uncovered: number;
+    };
+    tour: {
+        screens: number;
+        pill: boolean;
+    };
+    next: Next;
+};
+export type StatusDeps = SessionDeps & {
+    git?: GitFn;
+    now?: Date;
+};
+export declare function gatherStatus(root: string, deps?: StatusDeps): Promise<Status>;
+/** The one thing worth doing now, in the order a project grows. */
+export declare function nextStep(s: Omit<Status, 'next'>): Next;
+/** "3 days ago", for a time in the past. */
+export declare function ago(iso: string | undefined, now?: Date): string;
+/** The status as lines to print. */
+export declare function renderStatus(s: Status, now?: Date): string[];

package/dist/status.js

@@ -0,0 +1,166 @@
+import { loadConfig } from './config.js';
+import { accountState } from './session.js';
+import { collectChanges, defaultGit } from './sync/changes.js';
+import { hookInstalled } from './sync/hook.js';
+import { loadPages, scoreImpact } from './sync/impact.js';
+import { readSyncState } from './sync/state.js';
+import { workflowInstalled } from './sync/workflow.js';
+import { hasPillSnippet } from './tour-install.js';
+import { loadTours } from './tour.js';
+import { dim, gold, green, hint, plural, yellow } from './ui.js';
+export async function gatherStatus(root, deps = {}) {
+    const env = deps.env ?? process.env;
+    const git = deps.git ?? defaultGit;
+    const loaded = loadConfig(root);
+    const docsDir = loaded.docsDir;
+    let inGit = false;
+    try {
+        inGit = git(['rev-parse', '--is-inside-work-tree'], root).trim() === 'true';
+    }
+    catch {
+        /* not a repository */
+    }
+    const pages = (() => {
+        try {
+            return loadPages(root, docsDir);
+        }
+        catch {
+            return [];
+        }
+    })();
+    const state = readSyncState(root);
+    let commits = null;
+    let affected = 0;
+    let uncovered = 0;
+    if (inGit && loaded.found) {
+        try {
+            const changes = collectChanges(root, {
+                lastSha: state.lastSha,
+                freshness: loaded.config.freshness,
+                docsDir,
+                include: loaded.config.sync?.include,
+                exclude: loaded.config.sync?.exclude,
+                git,
+                now: deps.now,
+                budget: 20_000,
+            });
+            commits = changes.commits.length;
+            const impact = scoreImpact(pages, changes.files, loaded.config.sync?.map);
+            affected = impact.pages.length;
+            uncovered = impact.uncovered.length;
+        }
+        catch {
+            /* no commits yet, or history too short: nothing to report */
+        }
+    }
+    let screens = 0;
+    try {
+        screens = loadTours(root).length;
+    }
+    catch {
+        /* a broken tour file is `check`'s to report */
+    }
+    const account = await accountState({ ...deps, env });
+    const partial = {
+        account,
+        project: {
+            git: inGit,
+            setUp: loaded.found,
+            docsDir,
+            pages: pages.length,
+            role: loaded.config.role,
+            space: loaded.config.space,
+            freshness: loaded.config.freshness ?? 'off',
+        },
+        sync: {
+            workflow: workflowInstalled(root),
+            hook: inGit && hookInstalled(root, git),
+            key: env.ANTHROPIC_API_KEY ? 'anthropic' : env.OPENAI_API_KEY ? 'openai' : null,
+            lastRunAt: state.lastRunAt,
+            commits,
+            affected,
+            uncovered,
+        },
+        tour: { screens, pill: hasPillSnippet(root) },
+    };
+    return { ...partial, next: nextStep(partial) };
+}
+/** The one thing worth doing now, in the order a project grows. */
+export function nextStep(s) {
+    if (s.account.state === 'signed-out') {
+        return { command: 'login', why: 'Connect your DocuGate account so your docs can be published' };
+    }
+    if (!s.project.setUp)
+        return { command: 'init', why: 'Set this repository up for DocuGate' };
+    if (s.project.git && s.project.freshness !== 'off' && !s.sync.workflow) {
+        return { command: 'sync init', why: `Keep the docs current automatically (${s.project.freshness})` };
+    }
+    if (s.project.git && s.sync.commits && s.sync.commits > 0) {
+        return {
+            command: 'sync',
+            why: s.sync.affected
+                ? `${plural(s.sync.affected, 'page')} may be out of date after ${plural(s.sync.commits, 'commit')}`
+                : `${plural(s.sync.commits, 'commit')} since the last sync`,
+        };
+    }
+    const frontend = s.project.role === 'frontend' || s.project.role === 'both';
+    if (frontend && s.tour.screens === 0)
+        return { command: 'tour init', why: 'Write the first tour of your app' };
+    if (frontend && !s.tour.pill)
+        return { command: 'tour install', why: 'Add the Tour button to your app' };
+    return { command: 'check', why: 'Everything looks current', done: true };
+}
+/** "3 days ago", for a time in the past. */
+export function ago(iso, now = new Date()) {
+    if (!iso)
+        return 'never';
+    const ms = now.getTime() - new Date(iso).getTime();
+    if (!Number.isFinite(ms))
+        return 'never';
+    const h = Math.floor(ms / 3_600_000);
+    if (h < 1)
+        return 'just now';
+    if (h < 24)
+        return `${h}h ago`;
+    const d = Math.floor(h / 24);
+    return d === 1 ? 'yesterday' : d < 60 ? `${d} days ago` : `${Math.floor(d / 30)} months ago`;
+}
+const ok = green('✓');
+const off = dim('–');
+const warn = yellow('!');
+/** The status as lines to print. */
+export function renderStatus(s, now = new Date()) {
+    const row = (label, mark, text) => `  ${dim(label.padEnd(9))} ${mark} ${text}`;
+    const lines = [];
+    const a = s.account;
+    lines.push(a.state === 'signed-in'
+        ? row('Account', ok, `signed in as ${gold(`@${a.login}`)}`)
+        : a.state === 'offline'
+            ? row('Account', warn, `signed in, but DocuGate could not be reached ${dim(`(${a.detail})`)}`)
+            : row('Account', off, `not connected ${dim(`(${hint('login')})`)}`));
+    const p = s.project;
+    lines.push(!p.setUp
+        ? row('Docs', off, `not set up ${dim(`(${hint('init')})`)}`)
+        : row('Docs', p.pages ? ok : warn, `${plural(p.pages, 'page')} in ${p.docsDir}/${p.space ? ` ${dim('·')} space ${gold(p.space)}` : ` ${dim('· no space linked')}`}`));
+    const y = s.sync;
+    if (p.setUp) {
+        const bits = [
+            p.freshness === 'off' ? 'automatic sync off' : `checks ${p.freshness}`,
+            y.workflow ? 'workflow installed' : 'no workflow',
+            y.hook ? 'hook on' : null,
+            y.key ? `${y.key === 'anthropic' ? 'Anthropic' : 'OpenAI'} key found` : 'no AI key in this shell',
+        ].filter(Boolean);
+        lines.push(row('Sync', y.workflow ? ok : off, `${bits.join(dim(' · '))}`));
+        const behind = y.commits === null
+            ? dim('no history to compare yet')
+            : y.commits === 0
+                ? 'up to date with the code'
+                : `${plural(y.commits, 'commit')} since the last sync ${dim(`(${ago(y.lastRunAt, now)})`)}, ${y.affected ? `${plural(y.affected, 'page')} likely affected` : 'no page clearly affected'}`;
+        lines.push(row('', y.commits ? warn : ok, behind));
+    }
+    lines.push(s.tour.screens
+        ? row('Tour', s.tour.pill ? ok : warn, `${plural(s.tour.screens, 'screen')}${s.tour.pill ? ' · pill installed' : ` · pill not installed ${dim(`(${hint('tour install')})`)}`}`)
+        : row('Tour', off, dim('none yet')));
+    lines.push('', `  ${dim('Next'.padEnd(9))} ${gold(hint(s.next.command))} ${dim(`${s.next.done ? '' : '— '}${s.next.why}`)}`);
+    return lines;
+}

package/dist/sync/ai.d.ts

@@ -0,0 +1,44 @@
+import type { SyncConfig } from '../rules.js';
+import type { Changes } from './changes.js';
+import type { Impact, PageInfo } from './impact.js';
+export type DocEdit = {
+    path: string;
+    action: 'update' | 'create';
+    content: string;
+    reason: string;
+};
+export type AiPlan = {
+    summary: string;
+    edits: DocEdit[];
+};
+export type Provider = {
+    name: 'anthropic' | 'openai';
+    model: string;
+    key: string;
+    baseUrl: string;
+};
+export type AiRequest = {
+    system: string;
+    user: string;
+    maxTokens: number;
+};
+/** One model call. Tests pass their own, so none of them touches a network. */
+export type AiFn = (request: AiRequest) => Promise<string>;
+/** Which provider and key to use: the configured one, else whichever key is set. */
+export declare function resolveProvider(env: NodeJS.ProcessEnv, sync?: SyncConfig, modelOverride?: string): Provider | null;
+export declare const KEY_HELP: string;
+/** The call to a real provider. */
+export declare function providerAiFn(provider: Provider): AiFn;
+/** The words the model is given, with the untrusted diff fenced off. */
+export declare function buildPrompt(input: {
+    changes: Changes;
+    impact: Impact;
+    pages: PageInfo[];
+    docsDir: string;
+    maxFiles: number;
+    nonce?: string;
+}): string;
+/** The model's answer, as edits. Anything that does not fit the shape is an error. */
+export declare function parsePlan(text: string): AiPlan;
+/** One call: the model is asked once, and the answer is read, never trusted. */
+export declare function planEdits(aiFn: AiFn, input: Parameters<typeof buildPrompt>[0]): Promise<AiPlan>;