docugate 0.2.8 → 0.3.0

package/dist/developers.js

@@ -0,0 +1,439 @@
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { apiFetch, BASE_URL, createSpace, getSession, getSpaces } from './api.js';
+import { login } from './auth.js';
+import { loadConfig } from './config.js';
+import { choose, defaultGetRemote, makeDefaultIO, saveSetting } from './init.js';
+import { bold, dim, gold, green, plural, yellow } from './ui.js';
+// `docugate developers`: a developer space in one sitting. It finds the
+// OpenAPI file, writes the first pages where there are none, creates or links
+// a public space for them, and on Pro gives it an address, decides how the API
+// console sends requests, switches on API keys and hands over the verify
+// secret with the lines the backend needs. Every step says what it is about to
+// do, and nothing that already exists is overwritten.
+const SITE = 'https://www.trydocugate.site';
+/** Folders never worth walking for a spec. */
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', 'vendor', '.venv', 'venv', 'target']);
+/** File names that are, by convention, an API description. */
+const SPEC_FILE = /^(openapi|swagger)(\.[\w-]+)?\.(json|ya?ml)$/i;
+/**
+ * OpenAPI files in a repository, nearest the root first. Shallow on purpose: a
+ * spec lives near the top, and a walk through a large monorepo should not make
+ * the setup feel stuck.
+ */
+export function findSpecs(root, maxDepth = 4) {
+    const found = [];
+    const walk = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (depth < maxDepth && !SKIP.has(entry.name) && !entry.name.startsWith('.'))
+                    walk(join(dir, entry.name), depth + 1);
+            }
+            else if (SPEC_FILE.test(entry.name)) {
+                found.push(relative(root, join(dir, entry.name)).replace(/\\/g, '/'));
+            }
+        }
+    };
+    walk(root, 0);
+    return found.sort((a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b));
+}
+/** What a spec holds, enough to say so in a line. Null when it cannot be read. */
+export function readSpec(path) {
+    try {
+        const text = readFileSync(path, 'utf8');
+        const doc = (/\.json$/i.test(path) ? JSON.parse(text) : parseYaml(text));
+        if (!doc || typeof doc !== 'object')
+            return null;
+        const paths = (doc.paths ?? {});
+        const methods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+        let operations = 0;
+        const tags = new Set();
+        for (const item of Object.values(paths)) {
+            if (!item || typeof item !== 'object')
+                continue;
+            for (const [method, op] of Object.entries(item)) {
+                if (!methods.has(method))
+                    continue;
+                operations++;
+                const opTags = op?.tags;
+                if (Array.isArray(opTags))
+                    for (const t of opTags)
+                        if (typeof t === 'string')
+                            tags.add(t);
+            }
+        }
+        const info = doc.info;
+        return {
+            title: typeof info?.title === 'string' ? info.title : null,
+            operations,
+            tags: [...tags],
+            swagger2: typeof doc.swagger === 'string',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Where the server will find a spec without being told: openapi.json/.yaml/.yml at the root or in the docs folder. */
+export function specIsFoundByDefault(spec, docsDir) {
+    const name = /^openapi\.(json|ya?ml)$/i;
+    const dir = docsDir.replace(/^\/|\/$/g, '');
+    if (!spec.includes('/'))
+        return name.test(spec);
+    return spec.startsWith(`${dir}/`) && !spec.slice(dir.length + 1).includes('/') && name.test(spec.slice(dir.length + 1));
+}
+/** The web framework a Node backend uses, from its package.json. */
+export function detectFramework(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps.hono)
+            return 'hono';
+        if (deps.fastify)
+            return 'fastify';
+        if (deps.express)
+            return 'express';
+    }
+    catch {
+        /* not a Node project, or no package.json */
+    }
+    return null;
+}
+/** The lines that make a backend check keys, for the framework it uses. */
+export function middlewareSnippet(framework) {
+    if (framework === 'hono') {
+        return [
+            "import { requireKey } from 'docugate/hono'",
+            '',
+            "app.use('/api/*', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))",
+        ];
+    }
+    if (framework === 'fastify') {
+        return [
+            "import { requireKey } from 'docugate/fastify'",
+            '',
+            "app.addHook('onRequest', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))",
+        ];
+    }
+    if (framework === 'express') {
+        return [
+            "import { requireKey } from 'docugate/express'",
+            '',
+            "app.use('/api', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))",
+        ];
+    }
+    return [
+        "import { verifyKey } from 'docugate/keys'",
+        '',
+        'const verdict = await verifyKey(key, { secret: process.env.DOCUGATE_VERIFY_SECRET! })',
+        'if (!verdict.valid) /* answer 401 */',
+    ];
+}
+/** A scope name the server accepts, from an OpenAPI tag: `Shipments` → `shipments:read`. */
+export function scopeFromTag(tag) {
+    const base = tag
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 26);
+    return base ? `${base}:read` : null;
+}
+/** The first pages of a developer space. Only the ones missing are written. */
+export function starterPages(title, spec) {
+    const api = spec?.title ?? title;
+    return [
+        {
+            file: 'index.md',
+            body: `# ${api}\n\n` +
+                `Everything you need to build on the ${api}.\n\n` +
+                `- [Quickstart](quickstart.md): your first request, in a few minutes.\n` +
+                `- [Authentication](authentication.md): how to get a key and send it.\n` +
+                `- [Errors](errors.md): what each error means, and what to do about it.\n` +
+                (spec ? `\nThe full reference${spec.operations ? ` (${plural(spec.operations, 'endpoint')})` : ''} is in the sidebar, with a console to try each one.\n` : ''),
+        },
+        {
+            file: 'quickstart.md',
+            body: `# Quickstart\n\n` +
+                `1. Get an API key: see [Authentication](authentication.md).\n` +
+                `2. Send your first request:\n\n` +
+                '```bash\ncurl https://api.example.com/v1/... \\\n  -H "Authorization: Bearer $API_KEY"\n```\n\n' +
+                `3. Read the response, then try the same call from the API console in the sidebar.\n\n` +
+                `> Replace the example address and path with a real one from your API.\n`,
+        },
+        {
+            file: 'authentication.md',
+            body: `# Authentication\n\n` +
+                `Every request carries an API key in the \`Authorization\` header:\n\n` +
+                '```http\nAuthorization: Bearer <your key>\n```\n\n' +
+                `Generate a key from the **API keys** panel on these docs. A key is shown once, so copy it somewhere safe. ` +
+                `Keys can be revoked at any time, and a revoked key stops working on its next request.\n`,
+        },
+        {
+            file: 'errors.md',
+            body: `# Errors\n\n` +
+                `| Status | Meaning | What to do |\n| --- | --- | --- |\n` +
+                `| 400 | The request is malformed | Check the body against the reference |\n` +
+                `| 401 | The key is missing, unknown or revoked | Send a valid key; generate a new one if needed |\n` +
+                `| 403 | The key may not do this | Ask for the scope this call needs |\n` +
+                `| 404 | Nothing at that address | Check the path and the id |\n` +
+                `| 429 | Too many requests | Wait, then retry with backoff |\n` +
+                `| 5xx | Our side failed | Retry later; contact us if it persists |\n`,
+        },
+    ];
+}
+/** Whether a folder in the repository is on its remote branch yet, so a space can read it. */
+function isPushed(root, folder) {
+    try {
+        const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        const listed = execFileSync('git', ['ls-tree', '-r', '--name-only', `origin/${branch}`, '--', folder], {
+            cwd: root,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return listed.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function pushFolder(root, paths) {
+    const git = (...args) => execFileSync('git', args, { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+    git('add', '--', ...paths);
+    git('commit', '-m', 'docs: start the developer docs for DocuGate', '--', ...paths);
+    git('push');
+}
+async function yesNo(io, question, fallback = true) {
+    const answer = (await io.ask(`  ${question} ${dim(fallback ? '[Y/n]' : '[y/N]')}`, fallback ? 'y' : 'n')).trim().toLowerCase();
+    return answer.startsWith('y');
+}
+const step = (io, n, title) => {
+    io.print('');
+    io.print(`  ${gold(String(n))}  ${bold(title)}`);
+};
+export async function developersFlow(root, options = {}) {
+    const io = options.io ?? makeDefaultIO();
+    const yes = options.yes ?? false;
+    const ask = (q, d) => (yes ? Promise.resolve(d) : io.ask(`  ${q} ${dim(`[${d}]`)}`, d));
+    const confirm = (q, d = true) => (yes ? Promise.resolve(d) : yesNo(io, q, d));
+    io.print('');
+    io.print(`  ${bold('Set up a developer space')}`);
+    io.print(`  ${dim('API reference, guides and keys for the developers who build on your API.')}`);
+    // ── 1. Who ───────────────────────────────────────────────────────────────
+    step(io, 1, 'Your DocuGate account');
+    let user = (await getSession().catch(() => ({ user: null }))).user;
+    if (!user) {
+        io.print('  Not signed in. Opening your browser to sign in with GitHub…');
+        await login(BASE_URL);
+        user = (await getSession()).user;
+    }
+    if (!user)
+        throw new Error('Sign-in did not complete. Run docugate login, then try again.');
+    const paid = user.plan === 'pro' || user.plan === 'enterprise';
+    io.print(`  ${green('✓')} @${user.githubLogin} ${dim(`· ${paid ? 'Pro' : 'Free plan'}`)}`);
+    // ── 2. Where ─────────────────────────────────────────────────────────────
+    step(io, 2, 'The repository');
+    const repo = defaultGetRemote(root);
+    if (!repo) {
+        io.print(`  ${yellow('!')} This folder has no GitHub remote. A space reads its pages from GitHub,`);
+        io.print('    so push this repository to GitHub first, then run docugate developers again.');
+        return;
+    }
+    io.print(`  ${green('✓')} ${repo}`);
+    // ── 3. The API description ───────────────────────────────────────────────
+    step(io, 3, 'The OpenAPI file');
+    const specs = findSpecs(root);
+    let spec = null;
+    if (specs.length === 1)
+        spec = specs[0];
+    else if (specs.length > 1) {
+        const n = yes ? 1 : await choose(io, 'Which file describes the API?', [...specs, 'None of these']);
+        spec = n <= specs.length ? specs[n - 1] : null;
+    }
+    const summary = spec ? readSpec(join(root, spec)) : null;
+    if (spec && summary?.swagger2) {
+        io.print(`  ${yellow('!')} ${spec} is Swagger 2. DocuGate reads OpenAPI 3: convert it first, for example with`);
+        io.print('    https://converter.swagger.io, then run this again.');
+        spec = null;
+    }
+    else if (spec) {
+        io.print(`  ${green('✓')} ${spec}${summary ? dim(` · ${plural(summary.operations, 'endpoint')}${summary.title ? ` · ${summary.title}` : ''}`) : ''}`);
+    }
+    else {
+        io.print(`  ${yellow('!')} No OpenAPI file found. The space can still hold your guides.`);
+        io.print(`    To add the reference later: ${gold('docugate openapi --from <file or url>')}`);
+    }
+    // ── 4. The pages ─────────────────────────────────────────────────────────
+    step(io, 4, 'The pages');
+    const folder = (options.dir ?? (await ask('Folder for the developer docs', 'docs/developers'))).replace(/^\.?\/|\/$/g, '');
+    const base = join(root, folder);
+    mkdirSync(base, { recursive: true });
+    const written = [];
+    for (const page of starterPages(basename(root), summary)) {
+        const path = join(base, page.file);
+        if (existsSync(path))
+            continue;
+        writeFileSync(path, page.body);
+        written.push(`${folder}/${page.file}`);
+    }
+    if (written.length)
+        io.print(`  ${green('✓')} Wrote ${written.join(', ')} ${dim('(edit them freely)')}`);
+    else
+        io.print(`  ${green('✓')} ${folder}/ already has its pages; nothing was changed.`);
+    // The server finds openapi.json at the root or in the docs folder; anywhere
+    // else, docugate.json has to say where.
+    if (spec && !specIsFoundByDefault(spec, folder)) {
+        const api = (loadConfig(root).config.api ?? {});
+        saveSetting(root, 'api', { ...api, spec });
+        io.print(`  ${green('✓')} Saved api.spec = ${spec} in docugate.json`);
+        written.push('docugate.json');
+    }
+    // A space reads GitHub, not this folder: what was written has to be pushed.
+    if (!isPushed(root, folder) || written.length) {
+        const paths = [folder, ...(written.includes('docugate.json') ? ['docugate.json'] : [])];
+        if (await confirm(`Commit and push ${paths.join(' and ')} so DocuGate can read them?`)) {
+            try {
+                pushFolder(root, paths);
+                io.print(`  ${green('✓')} Pushed`);
+            }
+            catch (error) {
+                io.print(`  ${yellow('!')} Could not push: ${error.message.split('\n')[0]}`);
+                io.print(`    Push ${paths.join(' and ')} yourself; the space shows them from the next push.`);
+            }
+        }
+        else {
+            io.print(`    Push ${paths.join(' and ')} when ready; the space shows them from that push.`);
+        }
+    }
+    // ── 5. The space ─────────────────────────────────────────────────────────
+    step(io, 5, 'The space');
+    const { spaces } = await getSpaces();
+    const reads = (sp) => sp.sources?.some((s) => s.repo.toLowerCase() === repo.toLowerCase());
+    const existing = spaces.find(reads);
+    let space;
+    if (existing && (yes || (await confirm(`Use your space "${existing.name}" (/${existing.owner}/${existing.slug})?`)))) {
+        space = existing;
+    }
+    else {
+        const name = await ask('Name of the developer space', `${(summary?.title ?? repo.split('/')[1])} Developers`.replace(/\s+API Developers$/, ' API'));
+        space = await createSpace(repo, name, folder, 'public');
+        io.print(`  ${green('✓')} Created "${space.name}" ${dim('· public, so developers can read it before they sign up')}`);
+    }
+    saveSetting(root, 'space', `${space.owner}/${space.slug}`);
+    let address = `${SITE}/${space.owner}/${space.slug}`;
+    if (!paid) {
+        io.print('');
+        io.print(`  ${bold('Done.')} Your developer docs: ${gold(address)}`);
+        io.print('');
+        io.print(`  ${dim('On Pro, this same command also gives the space its own address, lets developers')}`);
+        io.print(`  ${dim('generate API keys on the page, and sends the API console through DocuGate.')}`);
+        io.print(`  ${dim(`Upgrade: ${SITE}/dashboard/upgrade, then run docugate developers again.`)}`);
+        return;
+    }
+    // ── 6. Address ───────────────────────────────────────────────────────────
+    step(io, 6, 'An address of its own');
+    const label = (await ask('Subdomain', repo.split('/')[0].toLowerCase().replace(/[^a-z0-9-]/g, '-'))).toLowerCase();
+    try {
+        const check = (await (await apiFetch(`/api/domains/${space.id}/subdomain/check?label=${encodeURIComponent(label)}`)).json());
+        if (!check.available) {
+            io.print(`  ${yellow('!')} ${label} is ${check.reason === 'label_taken' ? 'taken' : 'not a name we can use'}. Pick one in the space's settings later.`);
+        }
+        else {
+            const res = await apiFetch(`/api/domains/${space.id}/subdomain`, { method: 'PUT', body: JSON.stringify({ label }) });
+            const { subdomain } = (await res.json());
+            if (subdomain) {
+                address = `https://${subdomain.host}`;
+                io.print(`  ${green('✓')} ${address}`);
+            }
+        }
+    }
+    catch (error) {
+        io.print(`  ${yellow('!')} Skipped: ${error.message}`);
+    }
+    // ── 7. The API console ───────────────────────────────────────────────────
+    if (spec) {
+        step(io, 7, 'The API console');
+        const mode = yes
+            ? 1
+            : await choose(io, 'Where should "Try it" send requests from?', [
+                `The reader's browser ${dim('(your API must allow CORS from the docs address)')}`,
+                `Through DocuGate ${dim('(no CORS setup; readers must be signed in)')}`,
+            ]);
+        await apiFetch(`/api/proxy/spaces/${space.id}`, {
+            method: 'PUT',
+            body: JSON.stringify({ mode: mode === 2 ? 'proxy' : 'direct' }),
+        })
+            .then(() => io.print(`  ${green('✓')} ${mode === 2 ? 'Through DocuGate' : "From the reader's browser"}`))
+            .catch((error) => io.print(`  ${yellow('!')} Skipped: ${error.message}`));
+    }
+    // ── 8. API keys ──────────────────────────────────────────────────────────
+    step(io, 8, 'API keys');
+    if (!(await confirm('Let developers generate their own API keys on the docs?'))) {
+        io.print(`  ${dim('Skipped. Switch them on later in the space settings, under Developer.')}`);
+    }
+    else {
+        const suggested = (summary?.tags ?? []).map(scopeFromTag).filter((s) => Boolean(s)).slice(0, 8);
+        const scopes = (await ask('Scopes a new key gets (comma-separated)', suggested.length ? suggested.join(', ') : 'read'))
+            .split(',')
+            .map((s) => s.trim().toLowerCase())
+            .filter((s) => /^[a-z0-9:_-]{1,32}$/.test(s));
+        try {
+            await apiFetch(`/api/keys/spaces/${space.id}/config`, {
+                method: 'PUT',
+                body: JSON.stringify({
+                    enabled: true,
+                    header: 'authorization',
+                    scopes: scopes.map((name) => ({ name, description: `Granted to every new key: ${name}`, default: true })),
+                    allowlist: null,
+                    defaultLimit: 1000,
+                    defaultExpiryDays: 90,
+                    maxPerReader: 5,
+                }),
+            });
+            io.print(`  ${green('✓')} Keys on ${dim(`· ${scopes.join(', ') || 'no scopes'} · 1,000 calls and 90 days per key to start`)}`);
+            const { secret } = (await (await apiFetch(`/api/keys/spaces/${space.id}/verify-secret`, { method: 'POST' })).json());
+            io.print('');
+            io.print(`  Your backend checks each key with this secret. ${bold('It is shown once.')}`);
+            io.print(`    ${gold(`DOCUGATE_VERIFY_SECRET=${secret}`)}`);
+            const envFile = join(root, '.env');
+            const ignored = (() => {
+                try {
+                    execFileSync('git', ['check-ignore', '-q', '.env'], { cwd: root, stdio: 'ignore' });
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            })();
+            if (ignored && (await confirm('Add it to .env (git ignores that file)?'))) {
+                appendFileSync(envFile, `${existsSync(envFile) ? '\n' : ''}DOCUGATE_VERIFY_SECRET=${secret}\n`);
+                io.print(`  ${green('✓')} Added to .env`);
+            }
+            else if (!ignored) {
+                io.print(`  ${dim('.env is not git-ignored here, so it was not written. Put the secret in your host’s environment settings.')}`);
+            }
+            const framework = detectFramework(root);
+            io.print('');
+            io.print(`  Then, in your ${framework ?? 'backend'} app ${dim('(npm i docugate)')}:`);
+            for (const line of middlewareSnippet(framework))
+                io.print(`    ${line ? gold(line) : ''}`);
+        }
+        catch (error) {
+            io.print(`  ${yellow('!')} Keys were not switched on: ${error.message}`);
+        }
+    }
+    // ── Done ─────────────────────────────────────────────────────────────────
+    io.print('');
+    io.print(`  ${bold('Your developer space is ready.')}`);
+    io.print(`    Docs      ${gold(address)}`);
+    io.print(`    Settings  ${SITE}/dashboard/spaces/${space.id}`);
+    io.print(`  ${dim('Edit the pages in')} ${folder}/ ${dim('and push: the site updates on every push.')}`);
+}

package/dist/init.d.ts

@@ -0,0 +1,130 @@
+import type { RunBob } from './tour-init.js';
+import type { CreatedRepo } from './api.js';
+import type { TourInitResult } from './tour-init.js';
+import type { TourInstallResult } from './tour-install.js';
+import type { LoginOptions } from './auth.js';
+import type { Space } from './api.js';
+export type InitResult = {
+    created: string[];
+    kept: string[];
+    docsDir: string;
+};
+export { asCommand } from './ui.js';
+/**
+ * Sets a repository up for DocuGate: a docugate.json, and a first page if the
+ * docs folder has none. Never overwrites — running it twice is harmless, and
+ * running it in a repository that already has docs only adds what is missing.
+ */
+export declare function init(root: string, opts?: {
+    dir?: string;
+    title?: string;
+}): InitResult;
+export type Role = 'frontend' | 'backend' | 'both';
+/** Minimal I/O surface so the flow can be driven by tests without a terminal. */
+export interface IO {
+    isTTY: boolean;
+    ask(question: string, defaultAnswer: string): Promise<string>;
+    print(line: string): void;
+    /** Like ask, without echoing what is typed: for keys. */
+    askSecret?(question: string, defaultAnswer: string): Promise<string>;
+}
+/** Injectable for tests: replaces the real getSpaces call. */
+export type GetSpacesFn = () => Promise<{
+    spaces: Space[];
+}>;
+/** Injectable for tests: replaces the real connectRepo call. */
+export type ConnectRepoFn = (spaceId: string, repo: string, docsDir: string) => Promise<void>;
+/** Injectable for tests: replaces the real getSession call. */
+export type GetSessionFn = () => Promise<{
+    user: {
+        githubLogin: string;
+    } | null;
+}>;
+/** Injectable for tests: replaces the real login call. */
+export type LoginFn = (baseUrl: string, opts?: LoginOptions) => Promise<{
+    token: string;
+}>;
+/** Injectable for tests: replaces `git remote get-url origin`. Returns null if no remote. */
+export type GetRemoteFn = (root: string) => string | null;
+export interface InitFlowOptions {
+    dir?: string;
+    title?: string;
+    role?: Role;
+    yes?: boolean;
+    port?: number;
+    io?: IO;
+    runBob?: RunBob;
+    getSessionFn?: GetSessionFn;
+    getSpacesFn?: GetSpacesFn;
+    connectFn?: ConnectRepoFn;
+    loginFn?: LoginFn;
+    getRemoteFn?: GetRemoteFn;
+    /** Base URL for DocuGate (overrides DOCUGATE_URL env var). */
+    baseUrl?: string;
+    createSpaceFn?: (repo: string, name: string, docsDir: string) => Promise<{
+        name: string;
+        owner: string;
+        slug: string;
+    }>;
+    /** Creates the documentation repository for a new space; injectable for tests. */
+    createDocsRepoFn?: (name: string, isPrivate: boolean, title: string) => Promise<CreatedRepo>;
+    /** Creates the docs repository with the GitHub CLI when DocuGate cannot; injectable for tests. */
+    ghDocsRepoFn?: (name: string, isPrivate: boolean, title: string, io: IO) => CreatedRepo | null;
+    /** Opens a URL in the browser; injectable for tests. */
+    openUrl?: (url: string) => void;
+}
+export interface InitFlowResult {
+    created: string[];
+    kept: string[];
+    docsDir: string;
+    role: Role | undefined;
+    tourResult?: TourInitResult;
+    tourError?: string;
+    installResult?: TourInstallResult;
+    connectError?: string;
+    /** Set when a folder above already has the project's setup; nothing was written here. */
+    alreadySetUp?: string;
+}
+export declare function makeDefaultIO(): IO;
+/**
+ * The nearest folder above `root`, inside the same Git repository, that has
+ * DocuGate set up already (a docugate.json), if any.
+ */
+export declare function setUpAbove(root: string): string | undefined;
+/**
+ * Sets one key in docugate.json, keeping everything else as it was.
+ *
+ * A file that cannot be read is left alone and reported. It used to be started over with
+ * just this key, which threw away a hand-written `title` and `sidebar` over one stray comma.
+ */
+export declare function saveSetting(root: string, key: string, value: unknown): void;
+export declare const FRESHNESS: readonly [{
+    readonly value: "push";
+    readonly label: "On every push";
+}, {
+    readonly value: "daily";
+    readonly label: "Once a day (recommended: fewer AI runs)";
+}, {
+    readonly value: "weekly";
+    readonly label: "Once a week";
+}, {
+    readonly value: "off";
+    readonly label: "Never, I will ask for it";
+}];
+/**
+ * What the repository probably is, from its folders and files, so the question
+ * can suggest an answer. Only a suggestion: the person always confirms it.
+ */
+export declare function guessRole(root: string): Role | undefined;
+/**
+ * A numbered choice: prints the options, and takes only a number. Enter picks
+ * the default. Nobody types a word during setup.
+ */
+export declare function choose(io: IO, question: string, options: string[], fallback?: number): Promise<number>;
+export declare function defaultGetRemote(root: string): string | null;
+/**
+ * Runs the full interactive DocuGate setup wizard. Asks one short question,
+ * saves the result in docugate.json, conditionally runs tour init and tour
+ * install, and prints a summary.
+ */
+export declare function initFlow(root: string, options?: InitFlowOptions): Promise<InitFlowResult>;