docugate 0.2.9 → 0.3.0

package/dist/sync/run.js

@@ -0,0 +1,124 @@
+import { checkTours } from '../check.js';
+import { loadConfig } from '../config.js';
+import { planEdits, providerAiFn, resolveProvider, KEY_HELP } from './ai.js';
+import { applyEdits, validateEdits } from './apply.js';
+import { collectChanges, defaultGit, SyncError } from './changes.js';
+import { shouldSkip } from './guard.js';
+import { loadPages, scoreImpact } from './impact.js';
+import { buildPrBody, defaultPr } from './pr.js';
+import { readSyncState, STATE_FILE, writeSyncState } from './state.js';
+const DEFAULT_MAX_FILES = 10;
+export async function runSync(root, options = {}, deps = {}) {
+    const env = deps.env ?? process.env;
+    const git = deps.git ?? defaultGit;
+    const log = deps.log ?? (() => { });
+    const result = { dryRun: Boolean(options.dryRun), staleTour: [], written: [], rejected: [] };
+    const loaded = loadConfig(root);
+    if (loaded.errors.length) {
+        throw new SyncError(`docugate.json has a problem: ${loaded.errors.map((e) => e.message).join(' ')}`);
+    }
+    const { docsDir } = loaded;
+    const sync = loaded.config.sync ?? {};
+    const tryGit = (args) => {
+        try {
+            return git(args, root).trim();
+        }
+        catch {
+            return '';
+        }
+    };
+    const branch = options.branch ?? env.GITHUB_REF_NAME ?? tryGit(['rev-parse', '--abbrev-ref', 'HEAD']);
+    const early = shouldSkip({ headMessage: tryGit(['log', '-1', '--format=%B']), branch, docsDir });
+    if (early)
+        return { ...result, skipped: `Skipped: ${early}` };
+    const state = readSyncState(root);
+    const changes = collectChanges(root, {
+        since: options.since,
+        lastSha: state.lastSha,
+        freshness: loaded.config.freshness,
+        docsDir,
+        include: sync.include,
+        exclude: sync.exclude,
+        git,
+        now: deps.now,
+    });
+    result.changes = changes;
+    const pages = loadPages(root, docsDir);
+    result.impact = scoreImpact(pages, changes.files, sync.map);
+    result.staleTour = checkTours(root);
+    if (changes.files.length === 0) {
+        const onlyDocs = changes.skipped.length > 0 && changes.skipped.every((s) => /documentation|DocuGate's own/.test(s.reason));
+        return {
+            ...result,
+            skipped: onlyDocs
+                ? 'Skipped: the changes only touch documentation.'
+                : `Nothing to document ${changes.range}: no code changed.`,
+        };
+    }
+    if (options.dryRun)
+        return result;
+    // From here the changes leave the machine, so the provider has to be known.
+    const provider = resolveProvider(env, sync, options.model);
+    const aiFn = deps.aiFn ?? (provider ? providerAiFn(provider) : undefined);
+    if (!aiFn)
+        throw new SyncError(`No AI key found. ${KEY_HELP}`);
+    result.provider = provider ? `${provider.name} (${provider.model})` : 'custom';
+    if (deps.confirm && !options.yes) {
+        const ok = await deps.confirm(`This sends the code changes (${changes.files.length} file${changes.files.length === 1 ? '' : 's'}) and the affected docs to ${result.provider}. Continue?`);
+        if (!ok)
+            return { ...result, skipped: 'Stopped before anything was sent.' };
+    }
+    const maxFiles = options.maxFiles ?? sync.maxFiles ?? DEFAULT_MAX_FILES;
+    log('Asking the model what the docs need…');
+    const plan = await planEdits(aiFn, { changes, impact: result.impact, pages, docsDir, maxFiles });
+    result.summary = plan.summary;
+    const checked = validateEdits(root, docsDir, plan.edits, { maxFiles, pageCount: pages.length });
+    result.rejected.push(...checked.rejected);
+    const applied = applyEdits(root, checked.accepted);
+    result.rejected.push(...applied.reverted);
+    result.written = applied.written;
+    if (sync.digest && applied.written.length) {
+        const date = (deps.now ?? new Date()).toISOString().slice(0, 10);
+        const digest = digestPage(changes, applied.written, plan.summary, date);
+        const path = `${docsDir === '.' ? '' : `${docsDir}/`}changes/${date}.md`;
+        const done = applyEdits(root, [{ path, action: 'create', content: digest, reason: 'what changed this run' }]);
+        result.written.push(...done.written);
+    }
+    if (result.written.length === 0)
+        return result;
+    // The sync moves forward only when there is something to review.
+    writeSyncState(root, { lastSha: changes.to, lastRunAt: (deps.now ?? new Date()).toISOString() });
+    if (options.pr) {
+        const prFn = deps.prFn ?? defaultPr({ git, env });
+        const siteUrl = env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
+        result.pr = await prFn({
+            root,
+            title: `docs: sync with code changes (${changes.commits.length} commit${changes.commits.length === 1 ? '' : 's'})`,
+            body: buildPrBody({
+                summary: plan.summary,
+                written: result.written,
+                rejected: result.rejected,
+                changes,
+                docsDir,
+                space: loaded.config.space,
+                siteUrl,
+                staleTour: result.staleTour.map((t) => `${t.file ? `${t.file}: ` : ''}${t.message}`),
+            }),
+            files: [...result.written.map((e) => e.path), STATE_FILE],
+        });
+    }
+    return result;
+}
+/** A short, plain page of what changed, made without the model. */
+function digestPage(changes, written, summary, date) {
+    const lines = [`# Changes on ${date}`, ''];
+    if (summary)
+        lines.push(summary, '');
+    lines.push('## Commits', '');
+    for (const c of changes.commits.slice(0, 50))
+        lines.push(`- ${c.subject} (${c.author})`);
+    lines.push('', '## Pages updated', '');
+    for (const e of written)
+        lines.push(`- \`${e.path}\`${e.reason ? `: ${e.reason}` : ''}`);
+    return lines.join('\n');
+}

package/dist/sync/state.d.ts

@@ -0,0 +1,8 @@
+/** Where the last sync ended. It is committed in the sync's own pull request. */
+export declare const STATE_FILE = ".docugate/sync.json";
+export type SyncState = {
+    lastSha?: string;
+    lastRunAt?: string;
+};
+export declare function readSyncState(root: string): SyncState;
+export declare function writeSyncState(root: string, state: SyncState): void;

package/dist/sync/state.js

@@ -0,0 +1,22 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Where the last sync ended. It is committed in the sync's own pull request. */
+export const STATE_FILE = '.docugate/sync.json';
+export function readSyncState(root) {
+    const path = join(root, STATE_FILE);
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        // A damaged file is the same as none: the next run looks back a default window.
+        return {};
+    }
+}
+export function writeSyncState(root, state) {
+    const path = join(root, STATE_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`);
+}

package/dist/sync/workflow.d.ts

@@ -0,0 +1,20 @@
+import type { DocugateConfig } from '../rules.js';
+export declare const WORKFLOW_FILE = ".github/workflows/docugate-sync.yml";
+export type WorkflowOptions = {
+    freshness: NonNullable<DocugateConfig['freshness']>;
+    docsDir: string;
+    /** The branch pushes are watched on. */
+    branch: string;
+    /** The version to run, so a new release never changes what CI does by surprise. */
+    version: string;
+    provider?: 'anthropic' | 'openai';
+};
+/** The workflow file, or null when `freshness` is "off". */
+export declare function buildWorkflow(o: WorkflowOptions): string | null;
+export type WorkflowResult = {
+    path: string;
+    status: 'created' | 'updated' | 'kept' | 'off';
+};
+/** Write the workflow. An existing one that differs is left alone unless `force`. */
+export declare function writeWorkflow(root: string, o: WorkflowOptions, force?: boolean): WorkflowResult;
+export declare function workflowInstalled(root: string): boolean;

package/dist/sync/workflow.js

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { SYNC_BRANCH_PREFIX, SYNC_TAG } from './guard.js';
+// The GitHub Action that runs `docugate sync` for you. How often is the
+// `freshness` setting in docugate.json: on every push, daily or weekly.
+export const WORKFLOW_FILE = '.github/workflows/docugate-sync.yml';
+const CRON = {
+    // Off the hour, where GitHub's schedules are busiest.
+    daily: '17 6 * * *',
+    weekly: '17 6 * * 1',
+};
+/** The workflow file, or null when `freshness` is "off". */
+export function buildWorkflow(o) {
+    if (o.freshness === 'off')
+        return null;
+    const secret = o.provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+    const docs = o.docsDir === '.' ? null : o.docsDir.replace(/^\/|\/$/g, '');
+    const on = o.freshness === 'push'
+        ? [
+            '  push:',
+            `    branches: [${o.branch}]`,
+            '    paths-ignore:',
+            ...(docs ? [`      - '${docs}/**'`] : []),
+            `      - '.docugate/**'`,
+        ]
+        : ['  schedule:', `    - cron: '${CRON[o.freshness]}'`];
+    return `# Written by \`docugate sync init\`. It keeps your docs in step with your code.
+# ${o.freshness === 'push' ? 'Runs on every push' : o.freshness === 'daily' ? 'Runs every day' : 'Runs every Monday'}, reads what changed, and opens a pull request with the docs
+# edits. Nothing is merged for you. Change how often in docugate.json ("freshness"),
+# then run \`docugate sync init --force\`.
+name: DocuGate sync
+
+on:
+${on.join('\n')}
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# One sync at a time, so two runs never fight over the same branch.
+concurrency:
+  group: docugate-sync
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    # A sync's own commits and branch never start another sync.
+    if: \${{ !contains(github.event.head_commit.message, '${SYNC_TAG}') && !startsWith(github.ref_name, '${SYNC_BRANCH_PREFIX}') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx --yes docugate@${o.version} sync --pr --yes
+        env:
+          ${secret}: \${{ secrets.${secret} }}
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+`;
+}
+/** Write the workflow. An existing one that differs is left alone unless `force`. */
+export function writeWorkflow(root, o, force = false) {
+    const text = buildWorkflow(o);
+    if (text === null)
+        return { path: WORKFLOW_FILE, status: 'off' };
+    const path = join(root, WORKFLOW_FILE);
+    if (existsSync(path)) {
+        if (readFileSync(path, 'utf8') === text)
+            return { path: WORKFLOW_FILE, status: 'kept' };
+        if (!force)
+            return { path: WORKFLOW_FILE, status: 'kept' };
+        writeFileSync(path, text);
+        return { path: WORKFLOW_FILE, status: 'updated' };
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+    return { path: WORKFLOW_FILE, status: 'created' };
+}
+export function workflowInstalled(root) {
+    return existsSync(join(root, WORKFLOW_FILE));
+}

package/dist/text.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reads a file somebody wrote by hand, as DocuGate's server will read it.
+ *
+ * Windows PowerShell and Notepad save UTF-8 files with a byte-order mark. The server
+ * decodes what GitHub sends with `Response.text()`, which drops the mark, so such a file
+ * works there. `readFileSync` keeps it as a stray U+FEFF at the front, which breaks
+ * `JSON.parse` and hides a leading `# Title`, so the CLI would report a problem the
+ * published space does not have. Stripping it here keeps `docugate check` honest.
+ */
+export declare function readText(path: string): string;
+export declare function stripBom(text: string): string;

package/dist/text.js

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+/**
+ * Reads a file somebody wrote by hand, as DocuGate's server will read it.
+ *
+ * Windows PowerShell and Notepad save UTF-8 files with a byte-order mark. The server
+ * decodes what GitHub sends with `Response.text()`, which drops the mark, so such a file
+ * works there. `readFileSync` keeps it as a stray U+FEFF at the front, which breaks
+ * `JSON.parse` and hides a leading `# Title`, so the CLI would report a problem the
+ * published space does not have. Stripping it here keeps `docugate check` honest.
+ */
+export function readText(path) {
+    return stripBom(readFileSync(path, 'utf8'));
+}
+export function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}

package/dist/tour-init.d.ts

@@ -0,0 +1,61 @@
+export declare const TOUR_DIR = ".docugate/tour";
+export declare const MODE_SLUG = "tour-writer";
+export declare const TOUR_RULES = "# DocuGate tour format\n\nA tour explains the screens of an app to a developer who is new to its code.\nIt lives in `.docugate/tour/`, one markdown file per screen.\n\n## File\n\n- Name the file after the screen's route: `/invoices/:id` becomes\n  `invoices-id.md`, `/` becomes `home.md`.\n- Front matter holds `route` (the URL pattern, with `:param` segments) and\n  `title` (the screen's name).\n- Then one `##` section per stop, in the order a person reads the screen.\n\n## Stop\n\n```md\n## Total\ntarget: [data-tour=\"invoice-total\"]\ndata: GET /api/invoices/:id \u2192 total\ncode: frontend/src/screens/InvoiceDetail.tsx\nsource: backend/src/billing.ts\ndocs: https://example.com/docs/billing\n\nThe amount due: the subtotal plus tax, computed by `totals()` in the backend.\n```\n\n- `target`: a CSS selector for the element. Prefer `[data-tour=\"...\"]`\n  when the element has one. Otherwise use the most stable selector you can\n  see, and add a line `suggest: add data-tour=\"name\" in <file>`.\n- `data`: the request the value comes from and the field in the response,\n  as `METHOD /path \u2192 field`. Leave it out for elements that show no data.\n- `code`: the file that renders the element, relative to the repository root.\n- `source`: optional. The file where the value is computed or stored, when\n  that is somewhere else, such as a backend service.\n- `docs`: optional. A link that explains the concept.\n- Then one or two sentences of plain prose: what the element is and why its\n  value is what it is.\n\n## Rules\n\n- Only claim what the code shows. Every path must exist and every endpoint\n  must appear in the code. If you are not sure where a value comes from,\n  leave `data` and `source` out rather than guess.\n- Pick the elements a new developer would ask about: numbers, statuses,\n  actions and anything whose meaning is not obvious. Not every element.\n- Never edit, rename or delete a tour file that already exists. Only add\n  files for screens that have none.\n- Change nothing outside `.docugate/tour/`.\n";
+export declare const MODE: {
+    slug: string;
+    name: string;
+    description: string;
+    roleDefinition: string;
+    whenToUse: string;
+    customInstructions: string;
+    groups: (string | (string | {
+        fileRegex: string;
+        description: string;
+    })[])[];
+};
+export interface BobRun {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type RunBob = (args: string[], cwd: string) => BobRun;
+export interface TourInitOptions {
+    maxCost?: string;
+    teamId?: string;
+    runBob?: RunBob;
+}
+export interface TourInitResult {
+    setup: string[];
+    added: string[];
+    restored: string[];
+    mode: string;
+    stats?: {
+        durationMs?: number;
+        cost?: number;
+        taskId?: string;
+    };
+    lastMessage?: string;
+}
+export declare class BobMissingError extends Error {
+}
+/** Bob Shell's headless mode signs in with an API key, not the IDE's IBMid session. */
+export declare class BobKeyMissingError extends Error {
+}
+/**
+ * The Bob API key comes from the environment only: BOB_API_KEY. DocuGate never
+ * writes it anywhere. A key pasted during setup is put in this process's
+ * environment for that one run, and is gone when the command ends.
+ */
+export declare function readBobKey(): string | undefined;
+export declare function useBobKeyForThisRun(key: string): void;
+/**
+ * On Windows, `bob` is an npm .cmd shim, and a .cmd only runs through cmd.exe,
+ * which splits a path at its spaces ("C:\Users\GUSENGA Thierry") and cannot
+ * carry the prompt's line breaks. The shim only starts Node on Bob Shell's
+ * script, so run that script with Node directly: no shell, nothing mangled.
+ */
+export declare function bobScript(pathEnv?: string): string | undefined;
+/** Adds the Tour Writer mode and its rules to the project, keeping whatever is there. */
+export declare function ensureTourWriter(root: string): string[];
+export declare function buildPrompt(existing: string[], inlineRules: boolean): string;
+export declare function tourInit(root: string, options?: TourInitOptions): TourInitResult;

package/dist/tour-install.d.ts

@@ -0,0 +1,38 @@
+export declare const DEFAULT_PORT = 4178;
+/** Candidate paths checked in order. The first one that exists wins. */
+export declare const CANDIDATES: readonly ["app/layout.tsx", "app/layout.jsx", "src/app/layout.tsx", "src/app/layout.jsx", "pages/_document.tsx", "pages/_document.jsx", "index.html", "frontend/index.html", "client/index.html", "web/index.html", "app/index.html", "public/index.html"];
+export type TourInstallOptions = {
+    port?: number;
+    remove?: boolean;
+};
+export type TourInstallResult = {
+    /** The file that was (or would be) modified; null when nothing was found. */
+    target: string | null;
+    action: 'inserted' | 'removed' | 'already' | 'none';
+    /** The npm script that now starts the tour server with the app, e.g. predev. */
+    hook?: string;
+    hookAction?: 'inserted' | 'removed' | 'already' | 'none';
+};
+/** What the app's own start script runs first, so the tour server comes up with it. */
+export declare const SERVE_HOOK = "docugate tour serve --background";
+/**
+ * Adds `docugate tour serve --background` as the `predev` script (or
+ * `prestart`, for apps started with npm start), so running the project the
+ * usual way also starts the tour server. npm runs pre-scripts by itself, on
+ * every platform. An existing pre-script keeps running first. Only this
+ * repository's package.json, and only its scripts, are touched.
+ */
+export declare function installStartHook(root: string, options?: TourInstallOptions): {
+    hook?: string;
+    action: TourInstallResult['action'];
+};
+/** Returns true if any candidate file already contains the pill snippet. */
+export declare function hasPillSnippet(root: string): boolean;
+/**
+ * Installs (or removes) the dev-only pill loader snippet in the app's entry
+ * point. Safe to run multiple times — running it again when the snippet is
+ * already present is a no-op.
+ */
+export declare function tourInstall(root: string, options?: TourInstallOptions): TourInstallResult;
+/** The one-line snippet to paste manually when no entry point was found. */
+export declare function pillSnippetLine(port: number): string;

package/dist/tour-server.d.ts

@@ -0,0 +1,21 @@
+/** Where this project's docs are published, from the space docugate init saved. */
+export declare function publishedDocsUrl(root: string): string | undefined;
+/**
+ * The repository file that renders an element with this data-tour value, so
+ * the pill fills in "the file that shows it" instead of asking. A file with
+ * data-tour="value" wins over one that only passes the value along as a prop.
+ */
+export declare function findTourFile(root: string, value: string): string | undefined;
+/**
+ * The editor `docugate tour serve` was started from, as the command that opens
+ * a file at a line. DOCUGATE_EDITOR wins; otherwise the integrated terminal's
+ * environment says which VS Code family editor it is.
+ */
+export declare function editorCommand(env?: NodeJS.ProcessEnv): string;
+/** The 1-based line of the first occurrence of `find` in `text`, or 1. */
+export declare function lineOf(text: string, find?: string): number;
+export interface TourServer {
+    port: number;
+    close(): void;
+}
+export declare function startTourServer(root: string, port: number): Promise<TourServer>;

package/dist/tour.d.ts

@@ -0,0 +1,60 @@
+export type TourStop = {
+    /** Heading text for this stop (the ## heading). */
+    heading: string;
+    /** CSS selector for the element, e.g. `[data-tour="invoice-total"]`. */
+    target: string;
+    /** Request and field, e.g. `GET /api/invoices/:id → total`. Optional. */
+    data?: string;
+    /** Repo-relative path to the file that renders the element. */
+    code: string;
+    /** Repo-relative path to the file where the value is computed. Optional. */
+    source?: string;
+    /** URL linking to relevant docs. Optional. */
+    docs?: string;
+    /** Prose paragraph(s) after the fields. */
+    prose: string;
+};
+export type Tour = {
+    /** URL pattern for the screen, e.g. `/invoices/:id`. */
+    route: string;
+    /** Human-readable title for the screen. */
+    title: string;
+    /** Stops, in order. */
+    stops: TourStop[];
+    /** Source file path, set by loadTours. */
+    file?: string;
+};
+/**
+ * Parse a tour markdown file into a Tour object.
+ * `text` is the file contents, `file` is the path (used for error messages).
+ */
+export declare function parseTourFile(text: string, file: string): Tour;
+/**
+ * Serialize a Tour back to the markdown format parseTourFile reads.
+ */
+export declare function serializeTourFile(tour: Tour): string;
+/**
+ * Read every .md file under `<root>/.docugate/tour/` and return an array of
+ * Tour objects. Returns [] when the directory does not exist.
+ */
+export declare function loadTours(root: string): Tour[];
+/**
+ * Match a tour route pattern (with `:param` segments) against a pathname.
+ * Returns true when they match.
+ *
+ * Examples:
+ *   matchRoute('/invoices/:id', '/invoices/INV-001') → true
+ *   matchRoute('/invoices/:id', '/invoices')         → false
+ */
+export declare function matchRoute(route: string, pathname: string): boolean;
+/**
+ * Derive the tour filename from a route.
+ * Strips the leading `/`, replaces `/` and `:` with `-`, lower-cases the result,
+ * and appends `.md`. The root route `/` becomes `home.md`.
+ *
+ * Examples:
+ *   routeToFilename('/')                      → 'home.md'
+ *   routeToFilename('/invoices/:id')           → 'invoices-id.md'
+ *   routeToFilename('/orgs/:org/repos/:repo')  → 'orgs-org-repos-repo.md'
+ */
+export declare function routeToFilename(route: string): string;

package/dist/ui.d.ts

@@ -0,0 +1,29 @@
+/** Color only in a real terminal, and never when NO_COLOR is set, so logs and CI stay plain. */
+/**
+ * Git Bash's mintty window draws color, but Node sees its console as a pipe,
+ * so it is recognised by the name it puts in TERM_PROGRAM.
+ */
+export declare const isMintty: () => boolean;
+export declare const colorOn: () => boolean;
+export declare const bold: (text: string) => string;
+export declare const dim: (text: string) => string;
+export declare const red: (text: string) => string;
+export declare const green: (text: string) => string;
+export declare const yellow: (text: string) => string;
+export declare const gold: (text: string) => string;
+export declare const cream: (text: string) => string;
+export declare const plural: (n: number, word: string) => string;
+/** `a`, `a and b`, `a, b and c`. */
+export declare function list(items: string[]): string;
+/**
+ * How to write a docugate command for the person reading it: installed in the
+ * project (npm i docugate) it runs through npx; installed on the computer it
+ * is plain `docugate`. Judged from where this copy of the CLI lives.
+ */
+export declare function asCommand(line: string, script?: string): string;
+/** A command to run next, written the way this person would type it. */
+export declare const hint: (command: string) => string;
+/** Edit distance where swapping two neighbours counts once, so "chekc" is one slip from "check". */
+export declare function distance(a: string, b: string): number;
+/** The closest of `candidates` to `input`, if any is close enough to be a typo. */
+export declare function suggest(input: string, candidates: string[]): string | undefined;

package/dist/ui.js

@@ -0,0 +1,63 @@
+// What every command prints with: color that turns itself off, and the small
+// helpers that keep the wording the same everywhere.
+/** Color only in a real terminal, and never when NO_COLOR is set, so logs and CI stay plain. */
+/**
+ * Git Bash's mintty window draws color, but Node sees its console as a pipe,
+ * so it is recognised by the name it puts in TERM_PROGRAM.
+ */
+export const isMintty = () => process.platform === 'win32' && process.env.TERM_PROGRAM === 'mintty';
+export const colorOn = () => (Boolean(process.stdout.isTTY) || isMintty()) && !process.env.NO_COLOR;
+const paint = (code) => (text) => (colorOn() ? `\x1b[${code}m${text}\x1b[0m` : text);
+export const bold = paint('1');
+export const dim = paint('2');
+export const red = paint('31');
+export const green = paint('32');
+export const yellow = paint('33');
+export const gold = paint('38;2;244;196;63');
+export const cream = paint('38;2;245;240;227');
+export const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+/** `a`, `a and b`, `a, b and c`. */
+export function list(items) {
+    if (items.length < 2)
+        return items.join('');
+    return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+/**
+ * How to write a docugate command for the person reading it: installed in the
+ * project (npm i docugate) it runs through npx; installed on the computer it
+ * is plain `docugate`. Judged from where this copy of the CLI lives.
+ */
+export function asCommand(line, script = process.argv[1] ?? '') {
+    if (!/[\\/]node_modules[\\/]/.test(script) || /[\\/]npm[\\/]node_modules[\\/]|[\\/]lib[\\/]node_modules[\\/]/.test(script))
+        return line;
+    return line.replace(/(^|[\s(`"'])docugate (init|login|logout|whoami|check|openapi|tour|sync|status|help|completion)\b/g, '$1npx docugate $2');
+}
+/** A command to run next, written the way this person would type it. */
+export const hint = (command) => asCommand(`docugate ${command}`);
+/** Edit distance where swapping two neighbours counts once, so "chekc" is one slip from "check". */
+export function distance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+        }
+    }
+    return d[a.length][b.length];
+}
+/** The closest of `candidates` to `input`, if any is close enough to be a typo. */
+export function suggest(input, candidates) {
+    const lower = input.toLowerCase();
+    let best;
+    for (const name of candidates) {
+        const d = name.startsWith(lower) && lower.length >= 2 ? 1 : distance(lower, name.toLowerCase());
+        if (!best || d < best.d)
+            best = { name, d };
+    }
+    const limit = Math.max(1, Math.min(3, Math.floor(lower.length / 3)));
+    return best && best.d <= limit ? best.name : undefined;
+}