docugate 0.2.8 → 0.3.0

package/dist/commands.d.ts

@@ -0,0 +1,35 @@
+export type Flag = {
+    name: string;
+    /** Present when the flag takes a value; the text is the placeholder shown. */
+    value?: string;
+    description: string;
+};
+export type Group = 'Docs sync' | 'Setup' | 'Checks' | 'Walkthrough' | 'Account' | 'Help';
+export type Command = {
+    /** One to three words: `check`, `sync init`, `sync hook install`. */
+    name: string;
+    group: Group;
+    summary: string;
+    description?: string;
+    /** A trailing positional argument, like `<file>`. */
+    positional?: string;
+    flags: Flag[];
+    examples: string[];
+    /** Whether the command works with the DocuGate account: not at all, if you have one, or only with one. */
+    account: 'none' | 'optional' | 'required';
+};
+export declare const COMMANDS: Command[];
+export declare const GLOBAL_FLAGS: Flag[];
+export declare const GROUP_ORDER: Group[];
+export declare const findCommand: (name: string) => Command | undefined;
+/** Every flag that takes a value, anywhere: needed to read the line before the command is known. */
+export declare const VALUE_FLAG_NAMES: Set<string>;
+/** The flags a command accepts, with the ones every command accepts. */
+export declare const flagsOf: (c: Command) => Flag[];
+/** The page `docugate --help` prints. */
+export declare function renderHelp(site: string): string;
+/** The page `docugate help <command>` and `docugate <command> --help` print. */
+export declare function renderCommandHelp(c: Command, command?: string): string;
+/** What `docugate tour` and `docugate sync hook` list when given no sub-command. */
+export declare function renderGroupHelp(prefix: string, command?: string): string;
+export declare function renderCompletion(shell: string): string | null;

package/dist/commands.js

@@ -0,0 +1,293 @@
+import { bold, dim, gold } from './ui.js';
+const YES = { name: 'yes', description: 'Accept every default without asking' };
+export const COMMANDS = [
+    {
+        name: 'sync',
+        group: 'Docs sync',
+        summary: 'Update the docs from what changed in the code',
+        description: 'Reads the git changes since the last sync (or a time you give), finds the docs pages they affect, asks an AI model for the edits, and writes them. ' +
+            'With --pr it opens a pull request instead, so nothing changes without a review. It uses your own AI key and never sends anything through DocuGate.',
+        flags: [
+            { name: 'since', value: 'when', description: 'Look back to a commit, branch, or a time like 7d (default: the last sync)' },
+            { name: 'dry-run', description: 'Only say which pages are affected: no AI, nothing written' },
+            { name: 'pr', description: 'Push the edits and open a pull request' },
+            { name: 'max-files', value: 'n', description: 'Most pages one run may change (default: 10)' },
+            { name: 'model', value: 'name', description: 'Model to use (default: sync.model in docugate.json)' },
+            { name: 'quiet', description: 'Print one line only when pages are out of date (for the git hook)' },
+            YES,
+        ],
+        examples: ['docugate sync --dry-run', 'docugate sync --since 7d', 'docugate sync --pr --yes'],
+        account: 'none',
+    },
+    {
+        name: 'sync init',
+        group: 'Docs sync',
+        summary: 'Add the GitHub Action that runs sync on a schedule or on every push',
+        description: 'How often comes from "freshness" in docugate.json: push, daily, weekly or off.',
+        flags: [
+            { name: 'freshness', value: 'when', description: 'push, daily, weekly or off (default: weekly)' },
+            { name: 'force', description: 'Rewrite the workflow if it already exists' },
+        ],
+        examples: ['docugate sync init', 'docugate sync init --freshness daily'],
+        account: 'none',
+    },
+    {
+        name: 'sync hook install',
+        group: 'Docs sync',
+        summary: 'Tell me after each commit which pages the code left behind',
+        description: 'A git hook that runs `sync --dry-run` after every commit. It sends nothing and changes nothing.',
+        flags: [],
+        examples: ['docugate sync hook install'],
+        account: 'none',
+    },
+    {
+        name: 'sync hook remove',
+        group: 'Docs sync',
+        summary: 'Remove the post-commit hook',
+        flags: [],
+        examples: ['docugate sync hook remove'],
+        account: 'none',
+    },
+    {
+        name: 'status',
+        group: 'Docs sync',
+        summary: 'Where things stand: account, docs, sync and tour, and what to do next',
+        flags: [{ name: 'json', description: 'Print it as JSON, for scripts' }],
+        examples: ['docugate status', 'docugate status --json'],
+        account: 'optional',
+    },
+    {
+        name: 'init',
+        group: 'Setup',
+        summary: 'Set up this repository for DocuGate (interactive)',
+        flags: [
+            { name: 'dir', value: 'folder', description: 'Docs folder (default: docs)' },
+            { name: 'title', value: 'text', description: "Space title (default: this folder's name)" },
+            { name: 'role', value: 'role', description: 'Repository role: frontend, backend, or both' },
+            { name: 'no-serve', description: 'Do not start the tour server at the end' },
+            YES,
+        ],
+        examples: ['docugate init', 'docugate init --dir documentation --yes'],
+        account: 'optional',
+    },
+    {
+        name: 'developers',
+        group: 'Setup',
+        summary: 'Set up a developer space: API reference, guides and keys (interactive)',
+        description: 'Finds the OpenAPI file, writes the first developer pages where there are none, and creates or links a public space for them. On Pro it also claims a subdomain, sets how the API console sends requests, switches on API keys and prints the verify secret with the lines your backend needs.',
+        flags: [{ name: 'dir', value: 'folder', description: 'Folder for the developer docs (default: docs/developers)' }, YES],
+        examples: ['docugate developers', 'docugate developers --dir docs/api'],
+        account: 'required',
+    },
+    {
+        name: 'check',
+        group: 'Checks',
+        summary: 'Check the docs the way DocuGate will read them',
+        flags: [
+            { name: 'dir', value: 'folder', description: "Check this folder instead of docugate.json's docsDir" },
+            { name: 'strict', description: 'Treat warnings as errors' },
+        ],
+        examples: ['docugate check', 'docugate check --strict'],
+        account: 'none',
+    },
+    {
+        name: 'openapi',
+        group: 'Checks',
+        summary: "Prepare an OpenAPI spec for DocuGate's API reference",
+        flags: [
+            { name: 'from', value: 'file|url', description: 'The spec to read (or api.generate.from in docugate.json)' },
+            { name: 'out', value: 'file', description: 'Where to write it (default: openapi.json)' },
+            { name: 'include', value: 'glob', description: 'Keep only paths that match; repeatable' },
+            { name: 'exclude', value: 'glob', description: 'Drop paths that match; repeatable' },
+            { name: 'redact', value: 'name', description: 'Remove a property from every schema and example; repeatable' },
+            { name: 'check', description: 'Fail if the file is out of date, instead of writing it' },
+        ],
+        examples: ['docugate openapi --from http://localhost:3000/openapi.json'],
+        account: 'none',
+    },
+    {
+        name: 'tour init',
+        group: 'Walkthrough',
+        summary: 'Write the first tour of this app with IBM Bob',
+        flags: [
+            { name: 'max-cost', value: 'n', description: 'Most Bobcoins the run may spend (default: 3)' },
+            { name: 'team-id', value: 'id', description: 'Bob team to run under, for API keys that need one' },
+        ],
+        examples: ['docugate tour init'],
+        account: 'none',
+    },
+    {
+        name: 'tour install',
+        group: 'Walkthrough',
+        summary: 'Add the pill loader to your app',
+        flags: [
+            { name: 'port', value: 'n', description: 'Port the pill server listens on (default: 4178)' },
+            { name: 'remove', description: 'Remove the pill snippet instead of adding it' },
+        ],
+        examples: ['docugate tour install', 'docugate tour install --remove'],
+        account: 'none',
+    },
+    {
+        name: 'tour serve',
+        group: 'Walkthrough',
+        summary: 'Start a local server that serves tour data for the pill',
+        flags: [
+            { name: 'port', value: 'n', description: 'Port to listen on (default: 4178)' },
+            { name: 'background', description: 'Start it detached and return at once (used by `npm run dev`)' },
+        ],
+        examples: ['docugate tour serve'],
+        account: 'none',
+    },
+    {
+        name: 'tour export',
+        group: 'Walkthrough',
+        summary: 'Write every tour screen to a single JSON file',
+        positional: '<file>',
+        flags: [],
+        examples: ['docugate tour export tours.json'],
+        account: 'none',
+    },
+    {
+        name: 'login',
+        group: 'Account',
+        summary: 'Sign in to DocuGate with GitHub',
+        flags: [],
+        examples: ['docugate login'],
+        account: 'none',
+    },
+    {
+        name: 'logout',
+        group: 'Account',
+        summary: 'Sign out and delete saved credentials',
+        flags: [],
+        examples: ['docugate logout'],
+        account: 'none',
+    },
+    {
+        name: 'whoami',
+        group: 'Account',
+        summary: 'Print the currently signed-in user',
+        flags: [],
+        examples: ['docugate whoami'],
+        account: 'none',
+    },
+    {
+        name: 'help',
+        group: 'Help',
+        summary: 'Show help for everything, or for one command',
+        positional: '[command]',
+        flags: [],
+        examples: ['docugate help sync', 'docugate sync --help'],
+        account: 'none',
+    },
+    {
+        name: 'completion',
+        group: 'Help',
+        summary: 'Print a shell completion script (bash, zsh or powershell)',
+        positional: '<shell>',
+        flags: [],
+        examples: ['docugate completion powershell | Out-String | Invoke-Expression'],
+        account: 'none',
+    },
+];
+export const GLOBAL_FLAGS = [
+    { name: 'help', description: 'Show help (also -h)' },
+    { name: 'version', description: 'Print the version (also -v)' },
+    { name: 'no-input', description: 'Never ask a question; fail with the fix instead (always so in CI)' },
+];
+export const GROUP_ORDER = ['Docs sync', 'Setup', 'Checks', 'Walkthrough', 'Account', 'Help'];
+export const findCommand = (name) => COMMANDS.find((c) => c.name === name);
+/** Every flag that takes a value, anywhere: needed to read the line before the command is known. */
+export const VALUE_FLAG_NAMES = new Set(COMMANDS.flatMap((c) => c.flags.filter((f) => f.value).map((f) => f.name)));
+/** The flags a command accepts, with the ones every command accepts. */
+export const flagsOf = (c) => [...c.flags, ...GLOBAL_FLAGS];
+// ── Rendering ───────────────────────────────────────────────────────────
+const pad = (text, width) => text + ' '.repeat(Math.max(2, width - text.length));
+/** The page `docugate --help` prints. */
+export function renderHelp(site) {
+    const lines = [`docugate: keep your docs in step with your code`, '', 'Usage', '  docugate <command> [options]', '  docugate               (in a terminal: an interactive menu)', ''];
+    const width = Math.max(...COMMANDS.map((c) => c.name.length)) + 2;
+    for (const group of GROUP_ORDER) {
+        lines.push(group);
+        for (const c of COMMANDS.filter((x) => x.group === group))
+            lines.push(`  ${pad(c.name + (c.positional ? ` ${c.positional}` : ''), width + 8)}${c.summary}`);
+        lines.push('');
+    }
+    lines.push('Run `docugate help <command>` for a command\'s options and examples.', 'Run it from the root of your repository.', site, '');
+    return lines.join('\n');
+}
+/** The page `docugate help <command>` and `docugate <command> --help` print. */
+export function renderCommandHelp(c, command = 'docugate') {
+    const lines = [`${bold(`${command} ${c.name}`)}  ${dim(c.summary)}`, ''];
+    if (c.description)
+        lines.push(c.description, '');
+    lines.push('Usage', `  ${command} ${c.name}${c.positional ? ` ${c.positional}` : ''}${c.flags.length ? ' [options]' : ''}`, '');
+    const all = flagsOf(c);
+    const width = Math.max(...all.map((f) => `--${f.name}${f.value ? ` <${f.value}>` : ''}`.length)) + 2;
+    lines.push('Options');
+    for (const f of all)
+        lines.push(`  ${pad(`--${f.name}${f.value ? ` <${f.value}>` : ''}`, width)}${f.description}`);
+    if (c.examples.length) {
+        lines.push('', 'Examples');
+        for (const e of c.examples)
+            lines.push(`  ${gold(e.replace(/^docugate/, command))}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/** What `docugate tour` and `docugate sync hook` list when given no sub-command. */
+export function renderGroupHelp(prefix, command = 'docugate') {
+    const subs = COMMANDS.filter((c) => c.name.startsWith(`${prefix} `));
+    const width = Math.max(...subs.map((c) => c.name.length)) + 2;
+    return [`${bold(`${command} ${prefix}`)}`, '', ...subs.map((c) => `  ${pad(c.name, width)}${c.summary}`), ''].join('\n');
+}
+// ── Completions ─────────────────────────────────────────────────────────
+export function renderCompletion(shell) {
+    const names = COMMANDS.map((c) => c.name);
+    const words = [...new Set(names.map((n) => n.split(' ')[0]))];
+    const flagsFor = (c) => flagsOf(c).map((f) => `--${f.name}`);
+    if (shell === 'bash') {
+        // For each first word: the sub-commands and flags that can follow it.
+        const cases = words.map((w) => {
+            const group = COMMANDS.filter((c) => c.name.split(' ')[0] === w);
+            const subs = [...new Set(group.filter((c) => c.name.includes(' ')).map((c) => c.name.split(' ')[1]))];
+            const flags = [...new Set(group.flatMap(flagsFor))];
+            return `    ${w}) COMPREPLY=($(compgen -W "${[...subs, ...flags].join(' ')}" -- "$cur"));;`;
+        });
+        return [
+            '_docugate() {',
+            '  local cur="${COMP_WORDS[COMP_CWORD]}"',
+            `  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W "${words.join(' ')}" -- "$cur")); return; fi`,
+            '  case "${COMP_WORDS[1]}" in',
+            ...cases,
+            '  esac',
+            '}',
+            'complete -F _docugate docugate',
+            '',
+        ].join('\n');
+    }
+    if (shell === 'zsh') {
+        return [
+            '#compdef docugate',
+            '_docugate() {',
+            '  local -a cmds',
+            `  cmds=(${words.map((w) => `'${w}:${(findCommand(w)?.summary ?? `${w} commands`).replace(/'/g, '')}'`).join(' ')})`,
+            '  if (( CURRENT == 2 )); then _describe command cmds; else _files; fi',
+            '}',
+            '_docugate "$@"',
+            '',
+        ].join('\n');
+    }
+    if (shell === 'powershell' || shell === 'pwsh') {
+        return [
+            "Register-ArgumentCompleter -Native -CommandName docugate -ScriptBlock {",
+            '  param($wordToComplete, $commandAst, $cursorPosition)',
+            `  $words = @(${words.map((w) => `'${w}'`).join(', ')})`,
+            '  $tokens = $commandAst.CommandElements | Select-Object -Skip 1 | ForEach-Object { $_.ToString() }',
+            '  if ($tokens.Count -le 1) { $words | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_) } }',
+            '}',
+            '',
+        ].join('\n');
+    }
+    return null;
+}

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+import type { DocugateConfig } from './rules.js';
+export type Issue = {
+    file?: string;
+    message: string;
+};
+export type LoadedConfig = {
+    /** Whether docugate.json exists at all. It is optional. */
+    found: boolean;
+    config: DocugateConfig;
+    docsDir: string;
+    errors: Issue[];
+    warnings: Issue[];
+};
+/**
+ * Reads docugate.json from the repository root, where DocuGate looks for it.
+ *
+ * The server treats an unreadable file as if it were not there and falls back
+ * to `docs/`, silently. That is the right thing for a reader and the wrong
+ * thing for the person who wrote the file, so here it is an error.
+ */
+export declare function loadConfig(root: string): LoadedConfig;
+export declare const CONFIG_FILE = "docugate.json";

package/dist/config.js

@@ -1,7 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { KNOWN_KEYS } from './rules.js';
+import { FRESHNESS_VALUES, KNOWN_KEYS } from './rules.js';
+import { readText } from './text.js';
 const FILE = 'docugate.json';
+const SYNC_KEYS = new Set(['provider', 'model', 'include', 'exclude', 'map', 'maxFiles', 'digest']);
 /**
  * Reads docugate.json from the repository root, where DocuGate looks for it.
  *
@@ -18,7 +20,7 @@ export function loadConfig(root) {
     }
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(path, 'utf8'));
+        parsed = JSON.parse(readText(path));
     }
     catch (error) {
         errors.push({
@@ -47,7 +49,45 @@ export function loadConfig(root) {
         (!Array.isArray(config.sidebar) || config.sidebar.some((s) => typeof s !== 'string'))) {
         errors.push({ file: FILE, message: '"sidebar" must be a list of file and folder names.' });
     }
+    if (config.freshness !== undefined && !FRESHNESS_VALUES.includes(config.freshness)) {
+        errors.push({ file: FILE, message: `"freshness" must be one of ${FRESHNESS_VALUES.join(', ')}.` });
+    }
+    if (config.sync !== undefined)
+        errors.push(...validateSync(config.sync));
     const docsDir = typeof config.docsDir === 'string' ? config.docsDir.replace(/^\/|\/$/g, '') || 'docs' : 'docs';
     return { found: true, config: config, docsDir, errors, warnings };
 }
+const isStringList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+function validateSync(sync) {
+    const bad = (message) => ({ file: FILE, message });
+    if (!sync || typeof sync !== 'object' || Array.isArray(sync))
+        return [bad('"sync" must be an object.')];
+    const s = sync;
+    const errors = [];
+    for (const key of Object.keys(s)) {
+        if (!SYNC_KEYS.has(key))
+            errors.push(bad(`"sync" has an unknown key "${key}".`));
+    }
+    if (s.provider !== undefined && s.provider !== 'anthropic' && s.provider !== 'openai') {
+        errors.push(bad('"sync.provider" must be "anthropic" or "openai".'));
+    }
+    if (s.model !== undefined && typeof s.model !== 'string')
+        errors.push(bad('"sync.model" must be a string.'));
+    for (const key of ['include', 'exclude']) {
+        if (s[key] !== undefined && !isStringList(s[key]))
+            errors.push(bad(`"sync.${key}" must be a list of path globs.`));
+    }
+    if (s.map !== undefined) {
+        const map = s.map;
+        const ok = map && typeof map === 'object' && !Array.isArray(map) && Object.values(map).every((v) => isStringList(v));
+        if (!ok)
+            errors.push(bad('"sync.map" must map a page to a list of code globs, like {"docs/api.md": ["server/**"]}.'));
+    }
+    if (s.maxFiles !== undefined && !(Number.isInteger(s.maxFiles) && s.maxFiles > 0)) {
+        errors.push(bad('"sync.maxFiles" must be a whole number above zero.'));
+    }
+    if (s.digest !== undefined && typeof s.digest !== 'boolean')
+        errors.push(bad('"sync.digest" must be true or false.'));
+    return errors;
+}
 export const CONFIG_FILE = FILE;

package/dist/developers.d.ts

@@ -0,0 +1,35 @@
+import type { IO } from './init.js';
+/**
+ * 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 declare function findSpecs(root: string, maxDepth?: number): string[];
+export type SpecSummary = {
+    title: string | null;
+    operations: number;
+    tags: string[];
+    swagger2: boolean;
+};
+/** What a spec holds, enough to say so in a line. Null when it cannot be read. */
+export declare function readSpec(path: string): SpecSummary | null;
+/** Where the server will find a spec without being told: openapi.json/.yaml/.yml at the root or in the docs folder. */
+export declare function specIsFoundByDefault(spec: string, docsDir: string): boolean;
+export type Framework = 'express' | 'hono' | 'fastify';
+/** The web framework a Node backend uses, from its package.json. */
+export declare function detectFramework(root: string): Framework | null;
+/** The lines that make a backend check keys, for the framework it uses. */
+export declare function middlewareSnippet(framework: Framework | null): string[];
+/** A scope name the server accepts, from an OpenAPI tag: `Shipments` → `shipments:read`. */
+export declare function scopeFromTag(tag: string): string | null;
+/** The first pages of a developer space. Only the ones missing are written. */
+export declare function starterPages(title: string, spec: SpecSummary | null): {
+    file: string;
+    body: string;
+}[];
+export type DevelopersOptions = {
+    io?: IO;
+    yes?: boolean;
+    dir?: string;
+};
+export declare function developersFlow(root: string, options?: DevelopersOptions): Promise<void>;