docugate 0.2.9 → 0.3.1

package/dist/logo-pixels.d.ts

@@ -0,0 +1,4 @@
+export declare const LOGO_PALETTE: Record<string, [number, number, number]>;
+export declare const LOGO_ROWS: string[];
+/** The same owl as a small PNG, for terminals that can show real images. */
+export declare const LOGO_PNG_BASE64 = "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";

package/dist/logo-pixels.js

@@ -0,0 +1,35 @@
+// Generated from DocuGate's owl glyph by a script; the grid the terminal banner draws.
+// Each character is one pixel: . transparent, c cream, g gold, d deep gold.
+export const LOGO_PALETTE = {
+    c: [245, 240, 227],
+    g: [244, 196, 63],
+    d: [217, 154, 30],
+};
+export const LOGO_ROWS = [
+    '.....ccccccc..........cccccc......',
+    '....ccccccccc........ccccccccc....',
+    '...cccccccccccc....cccccccccccc...',
+    '..ccccc...ccccc....ccccc...ccccc..',
+    '.cccc....c..cccc..cccc....c..cccc.',
+    '.ccc...ccccc.ccc..ccc...ccccc.ccc.',
+    'cccc...cccccccccccccc..ccccccccccc',
+    'ccc...ccccccc.cccccc...ccccccc.ccc',
+    'ccc...ccccccc.cccccc...ccccccc.ccc',
+    'ccc....ccccc..cccccc....ccccc..ccc',
+    'ccc.....cccc..cccccc.....cccc..ccc',
+    'cccc.........cccccccc.........cccc',
+    '.ccc.........ccc..ccc.........ccc.',
+    '.cccc.......ccc.gd.ccc.......cccc.',
+    '..cccccc.ccccc.ggdd.ccccc.cccccc..',
+    '...cccccccccc.gggddd.cccccccccc...',
+    '....cccccccc.ggggdddd.cccccccc....',
+    '......ccccc.gggggddddd.ccccc......',
+    '.............ggggdddd.............',
+    '..............gggddd..............',
+    '..............gggddd..............',
+    '...............ggdd...............',
+    '................gd................',
+    '................g.................',
+];
+/** The same owl as a small PNG, for terminals that can show real images. */
+export const LOGO_PNG_BASE64 = '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';

package/dist/logo.d.ts

@@ -0,0 +1,19 @@
+export type Rgb = [number, number, number];
+/** How much color this terminal shows, from what it says about itself. */
+export declare function colorDepth(env?: NodeJS.ProcessEnv): 'truecolor' | '256';
+/** Whether the terminal draws inline images (the iTerm2 image protocol). */
+export declare function showsImages(env?: NodeJS.ProcessEnv): boolean;
+export declare function fg(rgb: Rgb, depth: 'truecolor' | '256'): string;
+/**
+ * The owl as lines of colored half blocks: each character is the pixel above
+ * (its color) and the pixel below (its background). Transparent pixels show
+ * the terminal's own background, so it sits well on dark and light themes.
+ */
+export declare function logoCells(depth?: 'truecolor' | '256'): string[];
+/** The owl as a real image, for terminals that draw them: one escape sequence. */
+export declare function logoImage(rows?: number): string;
+/**
+ * The banner: the owl on the left and `text` beside it, vertically centered.
+ * `text` lines may carry their own color codes.
+ */
+export declare function logoBanner(text: string[], env?: NodeJS.ProcessEnv): string[];

package/dist/logo.js

@@ -0,0 +1,68 @@
+import { LOGO_PALETTE, LOGO_PNG_BASE64, LOGO_ROWS } from './logo-pixels.js';
+/** How much color this terminal shows, from what it says about itself. */
+export function colorDepth(env = process.env) {
+    const term = `${env.COLORTERM ?? ''} ${env.TERM ?? ''}`.toLowerCase();
+    if (/truecolor|24bit|direct/.test(term))
+        return 'truecolor';
+    if (env.WT_SESSION || env.TERM_PROGRAM === 'vscode' || env.TERM_PROGRAM === 'iTerm.app' || env.TERM_PROGRAM === 'WezTerm') {
+        return 'truecolor';
+    }
+    return '256';
+}
+/** Whether the terminal draws inline images (the iTerm2 image protocol). */
+export function showsImages(env = process.env) {
+    return env.TERM_PROGRAM === 'iTerm.app' || env.TERM_PROGRAM === 'WezTerm';
+}
+/** The nearest color of the xterm 256-color cube. */
+function to256([r, g, b]) {
+    const step = (v) => (v < 48 ? 0 : v < 115 ? 1 : Math.min(5, Math.floor((v - 35) / 40)));
+    return 16 + 36 * step(r) + 6 * step(g) + step(b);
+}
+export function fg(rgb, depth) {
+    return depth === 'truecolor' ? `\x1b[38;2;${rgb.join(';')}m` : `\x1b[38;5;${to256(rgb)}m`;
+}
+function bg(rgb, depth) {
+    return depth === 'truecolor' ? `\x1b[48;2;${rgb.join(';')}m` : `\x1b[48;5;${to256(rgb)}m`;
+}
+/**
+ * The owl as lines of colored half blocks: each character is the pixel above
+ * (its color) and the pixel below (its background). Transparent pixels show
+ * the terminal's own background, so it sits well on dark and light themes.
+ */
+export function logoCells(depth = colorDepth()) {
+    const lines = [];
+    for (let y = 0; y < LOGO_ROWS.length; y += 2) {
+        const top = LOGO_ROWS[y];
+        const bottom = LOGO_ROWS[y + 1] ?? '';
+        let line = '';
+        for (let x = 0; x < top.length; x++) {
+            const up = LOGO_PALETTE[top[x]];
+            const down = LOGO_PALETTE[bottom[x] ?? '.'];
+            if (up && down)
+                line += `${fg(up, depth)}${bg(down, depth)}▀\x1b[0m`;
+            else if (up)
+                line += `${fg(up, depth)}▀\x1b[0m`;
+            else if (down)
+                line += `${fg(down, depth)}▄\x1b[0m`;
+            else
+                line += ' ';
+        }
+        lines.push(line);
+    }
+    return lines;
+}
+/** The owl as a real image, for terminals that draw them: one escape sequence. */
+export function logoImage(rows = 5) {
+    return `\x1b]1337;File=inline=1;height=${rows};preserveAspectRatio=1:${LOGO_PNG_BASE64}\x07`;
+}
+/**
+ * The banner: the owl on the left and `text` beside it, vertically centered.
+ * `text` lines may carry their own color codes.
+ */
+export function logoBanner(text, env = process.env) {
+    if (showsImages(env))
+        return ['', `  ${logoImage()}`, ...text.map((t) => `  ${t}`)];
+    const cells = logoCells(colorDepth(env));
+    const start = Math.max(0, Math.floor((cells.length - text.length) / 2));
+    return ['', ...cells.map((cell, i) => `  ${cell}   ${text[i - start] ?? ''}`.trimEnd()), ''];
+}

package/dist/menu.d.ts

@@ -0,0 +1,29 @@
+import { select } from './select.js';
+import type { Choice } from './select.js';
+import type { Status } from './status.js';
+/** The words of a command to run, like ['sync', '--dry-run']. */
+export type Action = string[];
+/** The menu's choices, from the project's state. Pure, so it is tested without a terminal. */
+export declare function buildChoices(s: Status, now?: Date): Choice<Action>[];
+/** The line under the list: who you are, and the one thing worth doing. */
+export declare function menuNote(s: Status, now?: Date): string;
+/** Who is signed in: the one line the launch screen keeps above the list. */
+export declare function whoNote(s: Status): string;
+export type Section = 'main' | 'tours' | 'more';
+/**
+ * The launch menu, short enough to see at once: the few things people come
+ * for on the first screen, the rest one step away under Tours and More. A step
+ * that cannot run yet is left out rather than shown greyed, so every line is
+ * something to do. Labels and rules come from buildChoices, written once.
+ */
+export declare function buildMenu(s: Status, section: Section): Choice<Action>[];
+export type MenuDeps = {
+    pick?: typeof select<Action>;
+    /** For terminals that cannot do arrow keys: a numbered list instead. */
+    numbered?: boolean;
+};
+/**
+ * Shows the menu and returns the command chosen, or null to quit. Tours and
+ * More open their own short list, with Back to return.
+ */
+export declare function runMenu(status: Status, deps?: MenuDeps): Promise<Action | null>;

package/dist/menu.js

@@ -0,0 +1,213 @@
+import { createInterface } from 'node:readline/promises';
+import { select } from './select.js';
+import { ago } from './status.js';
+import { bold, dim, gold, plural } from './ui.js';
+/** The menu's choices, from the project's state. Pure, so it is tested without a terminal. */
+export function buildChoices(s, now = new Date()) {
+    const p = s.project;
+    const y = s.sync;
+    const needsSetup = p.setUp ? undefined : 'Set the repository up first';
+    const needsGit = p.git ? undefined : 'This is not a git repository';
+    const needsDocs = needsSetup ?? needsGit;
+    const signedIn = s.account.state === 'signed-in';
+    const choices = [];
+    if (!signedIn) {
+        choices.push({
+            value: ['login'],
+            label: 'Connect your DocuGate account',
+            status: s.account.state === 'offline' ? 'cannot reach DocuGate' : 'not connected',
+            description: 'Sign in with GitHub in your browser. It lets DocuGate publish your docs and link this repository to a space.',
+            keywords: 'login sign in account github',
+        });
+    }
+    choices.push({
+        value: ['developers'],
+        label: 'Set up a developer space',
+        status: '',
+        description: 'API reference from your OpenAPI file, first guides, and a public space for them. On Pro: a subdomain, the API console and API keys, with the code your backend needs.',
+        keywords: 'developers api openapi keys reference space portal',
+    }, {
+        value: ['init'],
+        label: p.setUp ? 'Set up again or change settings' : 'Set up this repository',
+        status: p.setUp ? 'set up' : 'not set up',
+        description: 'A short guided setup: where the docs live, the kind of repository, and linking a DocuGate space. It never overwrites your files.',
+        keywords: 'init setup configure',
+    }, {
+        value: ['sync'],
+        label: 'Update the docs from the code',
+        status: y.commits === null ? '' : y.commits === 0 ? 'up to date' : `${plural(y.commits, 'commit')} behind`,
+        description: 'Reads what changed in the code, asks your AI model for the docs edits, and writes them. Add --pr from the command line to open a pull request instead.',
+        keywords: 'sync update docs changes ai',
+        disabled: needsDocs,
+    }, {
+        value: ['sync', '--dry-run'],
+        label: 'Preview which pages are out of date',
+        status: y.affected ? `${plural(y.affected, 'page')} likely` : '',
+        description: 'Free and instant: lists the pages the latest changes probably touch. Nothing is sent and nothing is written.',
+        keywords: 'sync dry run preview impact',
+        disabled: needsDocs,
+    }, {
+        value: ['sync', 'init'],
+        label: 'Keep the docs current automatically',
+        status: y.workflow ? `on · ${p.freshness}` : 'not set up',
+        description: `Adds a GitHub Action that runs sync ${p.freshness === 'push' ? 'on every push' : p.freshness === 'daily' ? 'every day' : 'every week'} and opens a pull request with the edits. You review and merge.`,
+        keywords: 'sync init github action workflow schedule freshness',
+        disabled: needsDocs,
+    }, {
+        value: y.hook ? ['sync', 'hook', 'remove'] : ['sync', 'hook', 'install'],
+        label: y.hook ? 'Turn off the after-commit heads-up' : 'Get a heads-up after each commit',
+        status: y.hook ? 'on' : 'off',
+        description: 'A git hook that tells you which pages your commit may have left out of date. It sends nothing and changes nothing.',
+        keywords: 'sync hook git commit',
+        disabled: needsGit,
+    }, {
+        value: ['status'],
+        label: 'Where things stand',
+        status: '',
+        description: 'Your account, docs, sync and tour at a glance, and what to do next.',
+        keywords: 'status overview',
+    }, {
+        value: ['check'],
+        label: 'Check the docs',
+        status: p.setUp ? `${plural(p.pages, 'page')}` : '',
+        description: 'Checks the docs the way DocuGate will read them: broken links, a missing landing page, tours that no longer match the code.',
+        keywords: 'check lint validate',
+    }, {
+        value: ['tour', 'init'],
+        label: 'Write the first tour of the app',
+        status: s.tour.screens ? `${plural(s.tour.screens, 'screen')}` : 'none yet',
+        description: 'IBM Bob reads your code and writes a guided tour of each screen. The tour files are yours to edit.',
+        keywords: 'tour bob walkthrough pill',
+    }, {
+        value: ['tour', 'install'],
+        label: 'Add the Tour button to the app',
+        status: s.tour.pill ? 'installed' : 'not installed',
+        description: 'Adds a one-line loader to your app so the Tour button shows while you develop.',
+        keywords: 'tour install pill',
+    }, {
+        value: ['tour', 'serve'],
+        label: 'Start the tour server',
+        status: '',
+        description: 'Serves your tour to the Tour button on localhost until you press Ctrl+C.',
+        keywords: 'tour serve server',
+    }, {
+        value: ['openapi'],
+        label: 'Prepare an OpenAPI spec',
+        status: '',
+        description: "Cleans up an OpenAPI file for DocuGate's API reference. Needs --from or api.generate in docugate.json.",
+        keywords: 'openapi api spec',
+    });
+    if (signedIn) {
+        choices.push({
+            value: ['logout'],
+            label: 'Sign out',
+            status: s.account.state === 'signed-in' ? `@${s.account.login}` : '',
+            description: 'Deletes the saved sign-in from this computer.',
+            keywords: 'logout sign out',
+        });
+    }
+    choices.push({
+        value: ['help'],
+        label: 'Help: every command',
+        status: '',
+        description: 'The full list of commands. Run `docugate help <command>` for one command in detail.',
+        keywords: 'help commands',
+    });
+    const recommended = s.next.command;
+    const match = choices.find((c) => c.value.join(' ') === recommended);
+    if (match && !match.disabled)
+        match.recommended = true;
+    return choices;
+}
+/** The line under the list: who you are, and the one thing worth doing. */
+export function menuNote(s, now = new Date()) {
+    const who = s.account.state === 'signed-in' ? `signed in as ${gold(`@${s.account.login}`)}` : s.account.state === 'offline' ? 'offline' : 'not connected';
+    const bits = [who];
+    if (s.project.setUp)
+        bits.push(`${plural(s.project.pages, 'page')} in ${s.project.docsDir}/`);
+    if (s.project.setUp && s.project.git) {
+        bits.push(s.sync.commits ? `last sync ${ago(s.sync.lastRunAt, now)}` : 'docs match the code');
+    }
+    return dim(bits.join(' · '));
+}
+/** Who is signed in: the one line the launch screen keeps above the list. */
+export function whoNote(s) {
+    if (s.account.state === 'signed-in')
+        return `signed in as ${gold(`@${s.account.login}`)}`;
+    return dim(s.account.state === 'offline' ? 'offline' : 'not signed in');
+}
+/** Values that move around the menu rather than run a command. */
+const GO = { tours: ['@tours'], more: ['@more'], back: ['@back'], quit: ['@quit'] };
+/**
+ * The launch menu, short enough to see at once: the few things people come
+ * for on the first screen, the rest one step away under Tours and More. A step
+ * that cannot run yet is left out rather than shown greyed, so every line is
+ * something to do. Labels and rules come from buildChoices, written once.
+ */
+export function buildMenu(s, section) {
+    const all = buildChoices(s);
+    const pick = (...commands) => commands
+        .map((command) => all.find((c) => c.value.join(' ') === command))
+        .filter((c) => Boolean(c && !c.disabled))
+        .map((c) => ({ ...c, status: undefined, recommended: c.recommended }));
+    if (section === 'tours') {
+        return [...pick('tour init', 'tour install', 'tour serve'), { value: [...GO.back], label: 'Back' }];
+    }
+    if (section === 'more') {
+        const hook = all.find((c) => c.value[0] === 'sync' && c.value[1] === 'hook');
+        return [
+            ...pick('sync --dry-run', 'sync init', ...(hook ? [hook.value.join(' ')] : []), 'status', 'openapi', 'help'),
+            { value: [...GO.back], label: 'Back' },
+        ];
+    }
+    const signedIn = s.account.state === 'signed-in';
+    return [
+        ...pick('developers', 'init', 'sync', 'check'),
+        { value: [...GO.tours], label: 'Tours' },
+        { value: [...GO.more], label: 'More' },
+        ...pick(signedIn ? 'logout' : 'login'),
+        { value: [...GO.quit], label: 'Quit' },
+    ];
+}
+/**
+ * Shows the menu and returns the command chosen, or null to quit. Tours and
+ * More open their own short list, with Back to return.
+ */
+export async function runMenu(status, deps = {}) {
+    const pick = deps.pick ?? select;
+    let section = 'main';
+    for (;;) {
+        const choices = buildMenu(status, section);
+        const note = section === 'main' ? whoNote(status) : dim(section === 'tours' ? 'Tours' : 'More');
+        const chosen = deps.numbered ? await numbered(choices, note) : await pick({ choices, note, minimal: true });
+        if (!chosen || chosen[0] === GO.quit[0])
+            return null;
+        if (chosen[0] === GO.back[0])
+            section = 'main';
+        else if (chosen[0] === GO.tours[0])
+            section = 'tours';
+        else if (chosen[0] === GO.more[0])
+            section = 'more';
+        else
+            return chosen;
+    }
+}
+async function numbered(choices, note) {
+    console.log(`
+  ${note}
+`);
+    choices.forEach((c, i) => console.log(`  ${dim(String(i + 1).padStart(2))}  ${c.label}`));
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const def = Math.max(0, choices.findIndex((c) => c.recommended)) + 1;
+        const answer = (await rl.question(`
+  ${dim(`Choose 1-${choices.length} [${def}]`)}: `)).trim().toLowerCase();
+        if (answer === 'q')
+            return null;
+        const n = answer === '' ? def : Number(answer);
+        return Number.isInteger(n) && choices[n - 1] ? choices[n - 1].value : null;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/openapi.d.ts

@@ -0,0 +1,38 @@
+export type OpenApiOptions = {
+    /** A spec file (.json, .yaml, .yml) or an http(s) URL serving one. */
+    from: string;
+    /** Where to write the result, relative to the repository root. */
+    output: string;
+    /** Path globs to keep. Empty keeps every path. */
+    include: string[];
+    /** Path globs to drop, applied after `include`. */
+    exclude: string[];
+    /** Property names removed from every schema and example. */
+    redact: string[];
+};
+export type OpenApiResult = {
+    spec: Record<string, unknown>;
+    text: string;
+    operations: number;
+    droppedPaths: string[];
+    redacted: number;
+};
+/**
+ * `*` matches within one path segment and `**` across them, so
+ * `/internal/**` drops everything under /internal and `/v1/*` keeps only
+ * direct children of /v1.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+/**
+ * Turns an existing OpenAPI 3 spec into the file DocuGate will read from the
+ * repository: only the paths meant to be public, without redacted fields, in
+ * a stable order so it diffs cleanly in review.
+ *
+ * It does not infer a spec from code. Frameworks that know their own schemas
+ * (NestJS, Fastify, FastAPI, Hono with zod-openapi) already emit one; point
+ * `from` at that file or at the URL the running server serves it on.
+ */
+export declare function buildOpenApi(root: string, opts: OpenApiOptions): Promise<OpenApiResult>;
+/** Whether the committed file already matches what would be written. */
+export declare function isCurrent(root: string, output: string, text: string): boolean;
+export declare function writeOpenApi(root: string, output: string, text: string): void;

package/dist/openapi.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { readText } from './text.js';
 const METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
 /**
  * `*` matches within one path segment and `**` across them, so
@@ -35,7 +36,7 @@ async function readSource(root, from) {
     const path = resolve(root, from);
     if (!existsSync(path))
         throw new Error(`${from} does not exist.`);
-    return { text: readFileSync(path, 'utf8'), yaml: /\.ya?ml$/i.test(from) };
+    return { text: readText(path), yaml: /\.ya?ml$/i.test(from) };
 }
 /** Every `$ref` in the document, so external ones can be refused. */
 function refsIn(value, out = []) {

package/dist/rules.d.ts

@@ -0,0 +1,69 @@
+/**
+ * How DocuGate reads a repository, restated for the command line.
+ *
+ * These mirror src/lib/docs.ts and server/github.ts in the DocuGate app. They
+ * are copied rather than imported because this package is published on its
+ * own; if the app changes how it reads a repository, change them here too, or
+ * `docugate check` will pass docs the server then renders differently.
+ */
+/** The server refuses a docs folder with more markdown files than this. */
+export declare const MAX_FILES = 300;
+/** Turn `guides/deploying.md` into `guides/deploying`, and `index.md` into ''. */
+export declare function pathToSlug(path: string): string;
+/**
+ * Resolve a relative markdown link, as authored inside `fromPath`, to the slug
+ * DocuGate routes it under. Null for links this does not apply to: external
+ * URLs, in-page anchors and anything that is not a markdown file.
+ */
+export declare function resolveRelativeLink(href: string, fromPath: string): string | null;
+/**
+ * Where a docs folder has no index.md, its top-level README becomes the
+ * landing page — the same file GitHub shows first.
+ */
+export declare function landingPath(paths: string[]): string | null;
+/** The page title DocuGate shows: the first `# heading`, if there is one. */
+export declare function firstHeading(content: string): string | null;
+/**
+ * How `docugate sync` keeps the docs in step with the code. The server never
+ * reads this: it is only for the command line and the workflow it writes.
+ */
+export type SyncConfig = {
+    /** Which AI provider writes the edits. Defaults to whichever key is set. */
+    provider?: 'anthropic' | 'openai';
+    model?: string;
+    /** Path globs of code worth documenting. Empty means every changed file. */
+    include?: string[];
+    /** Path globs to leave out, on top of what is always left out. */
+    exclude?: string[];
+    /** Pin a page to the code it documents: `{"docs/api.md": ["server/routes/**"]}`. */
+    map?: Record<string, string[]>;
+    /** Most pages one run may change. */
+    maxFiles?: number;
+    /** Also write a short "what changed" page for each run. */
+    digest?: boolean;
+};
+export declare const FRESHNESS_VALUES: readonly ["push", "daily", "weekly", "off"];
+/** The fields docugate.json may carry, and what each must be. */
+export type DocugateConfig = {
+    docsDir?: string;
+    title?: string;
+    role?: 'frontend' | 'backend' | 'both';
+    /** How often DocuGate checks the docs still match the code. */
+    freshness?: 'push' | 'daily' | 'weekly' | 'off';
+    /** The DocuGate space the docs publish to, as owner/slug. */
+    space?: string;
+    sidebar?: string[];
+    sync?: SyncConfig;
+    api?: {
+        /** Where the OpenAPI file is, when it is not openapi.json/.yaml at the root or in the docs folder. */
+        spec?: string;
+        generate?: {
+            from?: string;
+            output?: string;
+            include?: string[];
+            exclude?: string[];
+            redact?: string[];
+        };
+    };
+};
+export declare const KNOWN_KEYS: Set<string>;

package/dist/rules.js

@@ -58,4 +58,5 @@ export function firstHeading(content) {
     const heading = content.match(/^#\s+(.+)$/m);
     return heading ? heading[1].trim() : null;
 }
-export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'space', 'sidebar', 'api']);
+export const FRESHNESS_VALUES = ['push', 'daily', 'weekly', 'off'];
+export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'space', 'sidebar', 'sync', 'api']);

package/dist/select.d.ts

@@ -0,0 +1,81 @@
+export type Choice<T> = {
+    value: T;
+    label: string;
+    /** A short dim column to the right: a status, a group, a time. */
+    status?: string;
+    /** Shown under the list while this choice is highlighted. */
+    description?: string;
+    /** Words that also match a search, like a command's name. */
+    keywords?: string;
+    /** The suggested choice: marked, and the one Enter lands on to begin with. */
+    recommended?: boolean;
+    /** Why it cannot be chosen right now, if so. */
+    disabled?: string;
+};
+export type PickerState = {
+    query: string;
+    cursor: number;
+    top: number;
+};
+export type Key = {
+    name?: string;
+    ctrl?: boolean;
+    meta?: boolean;
+    sequence?: string;
+};
+/** How well `text` matches a search: lower is better, null is no match. */
+export declare function matchScore(text: string, query: string): number | null;
+export declare function filterChoices<T>(choices: Choice<T>[], query: string): Choice<T>[];
+/** The first choice Enter should land on: the recommended one, else the first that can be chosen. */
+export declare function initialCursor<T>(choices: Choice<T>[]): number;
+export type KeyResult<T> = {
+    state: PickerState;
+} | {
+    done: 'chosen';
+    choice: Choice<T>;
+} | {
+    done: 'cancelled';
+} | {
+    done: 'blocked';
+    reason: string;
+    state: PickerState;
+};
+/** One key press, applied to the picker's state. */
+export declare function handleKey<T>(choices: Choice<T>[], state: PickerState, str: string | undefined, key: Key, rows: number, 
+/** False for a short menu: letters do not search, a number picks, q quits. */
+search?: boolean): KeyResult<T>;
+export type RenderOptions = {
+    title?: string;
+    width: number;
+    rows: number;
+    footer?: string;
+    note?: string;
+    legend?: boolean;
+    /** Just the note and a numbered list: no search, rules, description, legend or key hints. */
+    minimal?: boolean;
+};
+/** The picker as lines of text. */
+export declare function renderPicker<T>(choices: Choice<T>[], state: PickerState, o: RenderOptions): string[];
+export type PickerIO = {
+    stdin: NodeJS.ReadStream;
+    stdout: NodeJS.WriteStream;
+};
+export type SelectOptions<T> = {
+    title?: string;
+    choices: Choice<T>[];
+    footer?: string;
+    /** A line shown under the list, like "signed in as @you". */
+    note?: string;
+    /** How many choices show at once. */
+    rows?: number;
+    legend?: boolean;
+    /** The short form: see renderPicker. Every choice shows; a number picks one. */
+    minimal?: boolean;
+};
+/** Whether there is a real terminal to draw a picker in. */
+export declare const canPick: (io?: PickerIO) => boolean;
+/**
+ * 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 declare function select<T>(options: SelectOptions<T>, io?: PickerIO): Promise<T | null>;