docugate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gusenga Thierry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# docugate
+
+Command-line tools for [DocuGate](https://www.trydocugate.site), which publishes
+documentation straight from the markdown in your GitHub repository and decides
+who may read it.
+
+```sh
+npx docugate init     # set this repository up for DocuGate
+npx docugate check    # check the docs the way DocuGate will read them
+npx docugate openapi  # prepare an OpenAPI spec for the API reference
+```
+
+Works with npm, pnpm, yarn and bun. Requires Node 18.17 or later. Run every
+command from the root of your repository.
+
+## `init`
+
+Creates a `docugate.json` and, if your docs folder has no markdown yet, a first
+`index.md`. It never overwrites a file, so it is safe to run in a repository
+that already has docs.
+
+```sh
+npx docugate init --dir docs --title "Acme API"
+```
+
+Then push, and publish the space from your
+[DocuGate dashboard](https://www.trydocugate.site/dashboard/new).
+
+## `check`
+
+Reads your docs folder with DocuGate's own rules and reports what the
+published page would get wrong:
+
+- **Errors:** broken links between pages, links that leave the docs folder,
+  two files that become the same URL, an unreadable `docugate.json`, an empty
+  docs folder, or more than 300 pages.
+- **Warnings:** pages with no `# Title`, front matter, `.mdx` files, no landing
+  page, and `sidebar` entries that match nothing.
+
+It exits with 1 when there are errors (add `--strict` to fail on warnings too),
+so it works as a CI step:
+
+```yaml
+# .github/workflows/docs.yml
+name: Docs
+on: [push, pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx docugate check
+```
+
+## `openapi`
+
+Takes the OpenAPI 3 spec your backend already produces and writes the version
+you want published: only the public paths, without sensitive fields, with keys
+in a stable order so it reviews cleanly in a pull request.
+
+```sh
+npx docugate openapi --from http://localhost:3000/openapi.json \
+  --exclude "/internal/**" --redact passwordHash --out openapi.json
+```
+
+- `--from`: a `.json`, `.yaml` or `.yml` file, or a URL serving one.
+- `--include` / `--exclude`: path globs; `*` matches within one segment and
+  `**` matches across segments. Both can be repeated.
+- `--redact`: a property name to remove from every schema and example.
+  Can be repeated.
+- `--check`: don't write anything; exit with 1 if the committed file is out of
+  date. Useful in CI.
+
+Instead of passing flags every time, you can set the same options in
+`docugate.json`:
+
+```json
+{
+  "docsDir": "docs",
+  "api": {
+    "generate": {
+      "from": "http://localhost:3000/openapi.json",
+      "output": "openapi.json",
+      "exclude": ["/internal/**"],
+      "redact": ["passwordHash"]
+    }
+  }
+}
+```
+
+The `openapi` command doesn't read your code to infer a spec. Frameworks that
+already know their schemas can export one: NestJS (`@nestjs/swagger`), Fastify
+(`@fastify/swagger`), FastAPI, and Hono (`@hono/zod-openapi`). Point `--from`
+at that output.
+
+DocuGate's API reference pages, which are built from this file, are coming
+soon. See the
+[changelog](https://www.trydocugate.site/resources/changelog).
+
+## `docugate.json`
+
+| Key | Meaning |
+| --- | --- |
+| `docsDir` | The folder DocuGate reads. Defaults to `docs`. |
+| `title` | The space's title. |
+| `sidebar` | File and folder names in the order the sidebar should show them. |
+| `api.generate` | Defaults for `docugate openapi`. |
+
+## Licence
+
+MIT

package/dist/check.js

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { loadConfig } from './config.js';
+import { MAX_FILES, firstHeading, landingPath, pathToSlug, resolveRelativeLink } from './rules.js';
+/** Never part of a repository on GitHub, and huge when present locally. */
+const SKIP = new Set(['node_modules', '.git']);
+/** Every file under `dir`, as forward-slash paths relative to it. */
+function walk(dir) {
+    const out = [];
+    const visit = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (SKIP.has(entry.name))
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory())
+                visit(full);
+            else if (entry.isFile())
+                out.push(relative(dir, full).split(sep).join('/'));
+        }
+    };
+    visit(dir);
+    return out;
+}
+/** Links in a page, skipping fenced code, where a link is only an example. */
+function linksIn(content) {
+    const links = [];
+    let fenced = false;
+    for (const line of content.split('\n')) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        for (const match of line.replace(/`[^`]*`/g, '').matchAll(/\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g)) {
+            links.push(match[1]);
+        }
+    }
+    return links;
+}
+/**
+ * Checks a repository's docs the way DocuGate will read them, so problems turn
+ * up on the command line or in CI rather than on the published page.
+ *
+ * Errors are things DocuGate will get wrong or refuse. Warnings are things it
+ * handles, but probably not the way the author meant.
+ */
+export function check(root, dirOverride) {
+    const loaded = loadConfig(root);
+    const errors = [...loaded.errors];
+    const warnings = [...loaded.warnings];
+    const docsDir = (dirOverride ?? loaded.docsDir).replace(/^\/|\/$/g, '') || '.';
+    const base = docsDir === '.' ? root : join(root, docsDir);
+    if (!existsSync(base) || !statSync(base).isDirectory()) {
+        errors.push({
+            message: `The docs folder "${docsDir}" does not exist.${loaded.found ? '' : ' Set "docsDir" in docugate.json, or run `docugate init`.'}`,
+        });
+        return { docsDir, pages: 0, errors, warnings };
+    }
+    const files = walk(base);
+    const pages = files.filter((f) => /\.md$/i.test(f));
+    const shown = (p) => (docsDir === '.' ? p : `${docsDir}/${p}`);
+    for (const f of files.filter((f) => /\.mdx$/i.test(f))) {
+        warnings.push({ file: shown(f), message: 'is MDX, which DocuGate does not read. Rename it to .md.' });
+    }
+    if (pages.length === 0) {
+        errors.push({ message: `There are no .md files in "${docsDir}", so the space would be empty.` });
+        return { docsDir, pages: 0, errors, warnings };
+    }
+    if (pages.length > MAX_FILES) {
+        errors.push({
+            message: `"${docsDir}" has ${pages.length} markdown files. DocuGate refuses more than ${MAX_FILES}.`,
+        });
+    }
+    // Two files that route to the same URL: only one of them can be reached.
+    const bySlug = new Map();
+    for (const p of pages)
+        bySlug.set(pathToSlug(p), [...(bySlug.get(pathToSlug(p)) ?? []), p]);
+    for (const [slug, clash] of bySlug) {
+        if (clash.length > 1) {
+            errors.push({
+                message: `${clash.map(shown).join(' and ')} both become the page "/${slug}". Rename one.`,
+            });
+        }
+    }
+    const landing = landingPath(pages);
+    if (!landing) {
+        warnings.push({
+            message: `"${docsDir}" has no index.md or README.md, so the space has no landing page.`,
+        });
+    }
+    // Every slug a link could land on, with the README standing in as the index.
+    const slugs = new Set(pages.map(pathToSlug));
+    if (landing)
+        slugs.add('');
+    for (const page of pages) {
+        const content = readFileSync(join(base, page), 'utf8').replace(/\r\n/g, '\n');
+        if (content.startsWith('---\n')) {
+            warnings.push({
+                file: shown(page),
+                message: 'starts with front matter, which DocuGate shows as text rather than reading.',
+            });
+        }
+        if (!firstHeading(content)) {
+            warnings.push({
+                file: shown(page),
+                message: 'has no "# Title" heading, so its title is made from the file name.',
+            });
+        }
+        for (const href of linksIn(content)) {
+            const target = resolveRelativeLink(href, page);
+            if (target === null)
+                continue;
+            if (target === '\0outside') {
+                errors.push({
+                    file: shown(page),
+                    message: `links to ${href}, which is outside "${docsDir}" and will not be published.`,
+                });
+            }
+            else if (!slugs.has(target)) {
+                errors.push({ file: shown(page), message: `links to ${href}, which does not exist.` });
+            }
+        }
+    }
+    // Sidebar entries are file or folder names, matched at whatever level they
+    // sit. One that matches nothing is almost always a rename it missed.
+    const names = new Set(pages.flatMap((p) => p.split('/')));
+    for (const entry of loaded.config.sidebar ?? []) {
+        if (typeof entry === 'string' && !names.has(entry)) {
+            warnings.push({
+                file: 'docugate.json',
+                message: `"sidebar" lists "${entry}", which is not a file or folder in "${docsDir}".`,
+            });
+        }
+    }
+    return { docsDir, pages: pages.length, errors, warnings };
+}

package/dist/cli.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { check } from './check.js';
+import { loadConfig } from './config.js';
+import { init } from './init.js';
+import { buildOpenApi, isCurrent, writeOpenApi } from './openapi.js';
+const SITE = 'https://www.trydocugate.site';
+const HELP = `docugate — set up and check the docs DocuGate reads from your repository
+
+Usage
+  npx docugate <command> [options]
+
+Commands
+  init        Set up this repository for DocuGate
+  check       Check the docs the way DocuGate will read them
+  openapi     Prepare an OpenAPI spec for DocuGate's API reference
+
+init
+  --dir <folder>       Docs folder (default: docs)
+  --title <text>       Space title (default: this folder's name)
+
+check
+  --dir <folder>       Check this folder instead of docugate.json's docsDir
+  --strict             Treat warnings as errors
+
+openapi
+  --from <file|url>    The spec to read (or api.generate.from in docugate.json)
+  --out <file>         Where to write it (default: openapi.json)
+  --include <glob>     Keep only paths that match; repeatable
+  --exclude <glob>     Drop paths that match; repeatable
+  --redact <name>      Remove a property from every schema and example; repeatable
+  --check              Fail if the file is out of date, instead of writing it
+
+Run it from the root of your repository.
+${SITE}
+`;
+const color = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+const red = (t) => paint(31, t);
+const yellow = (t) => paint(33, t);
+const green = (t) => paint(32, t);
+const dim = (t) => paint(2, t);
+const VALUE_FLAGS = new Set(['dir', 'title', 'from', 'out', 'include', 'exclude', 'redact']);
+function parse(argv) {
+    const flags = new Map();
+    const bools = new Set();
+    let command;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h')
+            bools.add('help');
+        else if (arg === '-v')
+            bools.add('version');
+        else if (arg.startsWith('--')) {
+            const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
+            if (VALUE_FLAGS.has(name)) {
+                const value = inline ?? argv[++i];
+                if (value === undefined)
+                    fail(`--${name} needs a value.`);
+                flags.set(name, [...(flags.get(name) ?? []), value]);
+            }
+            else
+                bools.add(name);
+        }
+        else if (!command)
+            command = arg;
+        else
+            fail(`Unexpected argument "${arg}".`);
+    }
+    return { command, flags, bools };
+}
+function fail(message) {
+    console.error(`${red('error')} ${message}\n${dim('Run `npx docugate --help` for usage.')}`);
+    process.exit(2);
+}
+function version() {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+}
+function report(label, issues, paintLabel) {
+    for (const issue of issues) {
+        console.log(`  ${paintLabel(label.padEnd(5))}  ${issue.file ? `${issue.file} ` : ''}${issue.message}`);
+    }
+}
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+async function main() {
+    const args = parse(process.argv.slice(2));
+    const one = (name) => args.flags.get(name)?.at(-1);
+    const many = (name) => args.flags.get(name) ?? [];
+    const root = process.cwd();
+    if (args.bools.has('version'))
+        return console.log(version());
+    if (args.bools.has('help') || !args.command)
+        return console.log(HELP);
+    switch (args.command) {
+        case 'init': {
+            const result = init(root, { dir: one('dir'), title: one('title') });
+            for (const f of result.created)
+                console.log(`  ${green('created')}  ${f}`);
+            for (const f of result.kept)
+                console.log(`  ${dim('kept')}     ${f}`);
+            console.log(`\nNext: commit and push, then publish the space at ${SITE}/dashboard/new` +
+                `\nand pick "${result.docsDir}" as the docs folder.`);
+            return;
+        }
+        case 'check': {
+            const result = check(root, one('dir'));
+            const strict = args.bools.has('strict');
+            console.log(`docugate check ${dim(`— ${result.docsDir}/, ${plural(result.pages, 'page')}`)}`);
+            report('error', result.errors, red);
+            report('warn', result.warnings, yellow);
+            const failed = result.errors.length + (strict ? result.warnings.length : 0);
+            if (!result.errors.length && !result.warnings.length)
+                console.log(green('\nNo problems.'));
+            else
+                console.log(`\n${plural(result.errors.length, 'error')}, ${plural(result.warnings.length, 'warning')}`);
+            if (failed)
+                process.exitCode = 1;
+            return;
+        }
+        case 'openapi': {
+            const generate = loadConfig(root).config.api?.generate ?? {};
+            const from = one('from') ?? generate.from;
+            if (!from)
+                fail('Say which spec to read: --from openapi.yaml, or api.generate.from in docugate.json.');
+            const output = one('out') ?? generate.output ?? 'openapi.json';
+            const result = await buildOpenApi(root, {
+                from,
+                output,
+                include: args.flags.has('include') ? many('include') : (generate.include ?? []),
+                exclude: args.flags.has('exclude') ? many('exclude') : (generate.exclude ?? []),
+                redact: args.flags.has('redact') ? many('redact') : (generate.redact ?? []),
+            });
+            const summary = `${plural(result.operations, 'operation')}` +
+                (result.droppedPaths.length ? `, ${plural(result.droppedPaths.length, 'path')} left out` : '') +
+                (result.redacted ? `, ${plural(result.redacted, 'field')} redacted` : '');
+            if (args.bools.has('check')) {
+                if (isCurrent(root, output, result.text)) {
+                    console.log(`${green('up to date')}  ${output} ${dim(`(${summary})`)}`);
+                }
+                else {
+                    console.log(`${red('out of date')}  ${output} does not match ${from}.`);
+                    console.log(dim('Run `npx docugate openapi` and commit the result.'));
+                    process.exitCode = 1;
+                }
+                return;
+            }
+            writeOpenApi(root, output, result.text);
+            console.log(`${green('wrote')}  ${output} ${dim(`(${summary})`)}`);
+            return;
+        }
+        default:
+            fail(`Unknown command "${args.command}".`);
+    }
+}
+main().catch((error) => {
+    console.error(`${red('error')} ${error.message}`);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { KNOWN_KEYS } from './rules.js';
+const FILE = 'docugate.json';
+/**
+ * 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 function loadConfig(root) {
+    const path = join(root, FILE);
+    const errors = [];
+    const warnings = [];
+    if (!existsSync(path)) {
+        return { found: false, config: {}, docsDir: 'docs', errors, warnings };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        errors.push({
+            file: FILE,
+            message: `is not valid JSON (${error.message}). DocuGate ignores it and reads docs/.`,
+        });
+        return { found: true, config: {}, docsDir: 'docs', errors, warnings };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        errors.push({ file: FILE, message: 'must be a JSON object.' });
+        return { found: true, config: {}, docsDir: 'docs', errors, warnings };
+    }
+    const config = parsed;
+    for (const key of Object.keys(config)) {
+        if (!KNOWN_KEYS.has(key)) {
+            warnings.push({ file: FILE, message: `has an unknown key "${key}", which DocuGate ignores.` });
+        }
+    }
+    if (config.docsDir !== undefined && typeof config.docsDir !== 'string') {
+        errors.push({ file: FILE, message: '"docsDir" must be a string, like "docs".' });
+    }
+    if (config.title !== undefined && typeof config.title !== 'string') {
+        errors.push({ file: FILE, message: '"title" must be a string.' });
+    }
+    if (config.sidebar !== undefined &&
+        (!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.' });
+    }
+    const docsDir = typeof config.docsDir === 'string' ? config.docsDir.replace(/^\/|\/$/g, '') || 'docs' : 'docs';
+    return { found: true, config: config, docsDir, errors, warnings };
+}
+export const CONFIG_FILE = FILE;

package/dist/init.js

@@ -0,0 +1,36 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { CONFIG_FILE, loadConfig } from './config.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 function init(root, opts = {}) {
+    const created = [];
+    const kept = [];
+    const existing = loadConfig(root);
+    const docsDir = (opts.dir ?? existing.docsDir).replace(/^\/|\/$/g, '') || 'docs';
+    const title = opts.title ?? basename(root);
+    if (existing.found) {
+        kept.push(CONFIG_FILE);
+    }
+    else {
+        const config = { docsDir, title };
+        writeFileSync(join(root, CONFIG_FILE), JSON.stringify(config, null, 2) + '\n');
+        created.push(CONFIG_FILE);
+    }
+    const base = join(root, docsDir);
+    const hasMarkdown = existsSync(base) && readdirSync(base, { recursive: true }).some((f) => /\.md$/i.test(String(f)));
+    if (hasMarkdown) {
+        kept.push(`${docsDir}/`);
+    }
+    else {
+        mkdirSync(base, { recursive: true });
+        writeFileSync(join(base, 'index.md'), `# ${title}\n\nWelcome. This page is the landing page of your DocuGate space.\n\n` +
+            `Every \`.md\` file in \`${docsDir}/\` becomes a page, and every folder becomes a\n` +
+            `section in the sidebar. The first \`# heading\` in a file is its title.\n`);
+        created.push(`${docsDir}/index.md`);
+    }
+    return { created, kept, docsDir };
+}

package/dist/openapi.js

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+const METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+/**
+ * `*` matches within one path segment and `**` across them, so
+ * `/internal/**` drops everything under /internal and `/v1/*` keeps only
+ * direct children of /v1.
+ */
+export function globToRegExp(glob) {
+    let pattern = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*' && glob[i + 1] === '*') {
+            pattern += '.*';
+            i++;
+        }
+        else if (c === '*') {
+            pattern += '[^/]*';
+        }
+        else {
+            pattern += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${pattern}$`);
+}
+async function readSource(root, from) {
+    if (/^https?:\/\//i.test(from)) {
+        const res = await fetch(from, { signal: AbortSignal.timeout(20_000) });
+        if (!res.ok)
+            throw new Error(`${from} answered ${res.status}.`);
+        const type = res.headers.get('content-type') ?? '';
+        return { text: await res.text(), yaml: /ya?ml/i.test(type) || /\.ya?ml(\?|$)/i.test(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) };
+}
+/** Every `$ref` in the document, so external ones can be refused. */
+function refsIn(value, out = []) {
+    if (Array.isArray(value))
+        for (const v of value)
+            refsIn(v, out);
+    else if (value && typeof value === 'object') {
+        for (const [k, v] of Object.entries(value)) {
+            if (k === '$ref' && typeof v === 'string')
+                out.push(v);
+            else
+                refsIn(v, out);
+        }
+    }
+    return out;
+}
+/**
+ * Removes redacted property names from schemas (and their `required` lists)
+ * and from examples. Returns how many were removed.
+ */
+function redact(value, names, inExample = false) {
+    if (!names.size || !value || typeof value !== 'object')
+        return 0;
+    let removed = 0;
+    if (Array.isArray(value)) {
+        for (const v of value)
+            removed += redact(v, names, inExample);
+        return removed;
+    }
+    const obj = value;
+    if (inExample) {
+        for (const key of Object.keys(obj)) {
+            if (names.has(key)) {
+                delete obj[key];
+                removed++;
+            }
+            else
+                removed += redact(obj[key], names, true);
+        }
+        return removed;
+    }
+    const props = obj.properties;
+    if (props && typeof props === 'object' && !Array.isArray(props)) {
+        for (const key of Object.keys(props)) {
+            if (names.has(key)) {
+                delete props[key];
+                removed++;
+            }
+        }
+        if (Array.isArray(obj.required))
+            obj.required = obj.required.filter((r) => !names.has(String(r)));
+    }
+    for (const [key, child] of Object.entries(obj)) {
+        removed += redact(child, names, key === 'example' || key === 'examples');
+    }
+    return removed;
+}
+/** Keys sorted at every level, so the same spec always writes the same bytes. */
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((k) => [k, sortKeys(value[k])]));
+}
+/**
+ * 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 async function buildOpenApi(root, opts) {
+    const source = await readSource(root, opts.from);
+    let doc;
+    try {
+        doc = source.yaml ? parseYaml(source.text, { maxAliasCount: 100 }) : JSON.parse(source.text);
+    }
+    catch (error) {
+        // A .json URL that actually serves YAML, or the other way round.
+        try {
+            doc = source.yaml ? JSON.parse(source.text) : parseYaml(source.text, { maxAliasCount: 100 });
+        }
+        catch {
+            throw new Error(`${opts.from} is neither valid JSON nor YAML: ${error.message}`);
+        }
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+        throw new Error(`${opts.from} is not an OpenAPI document.`);
+    }
+    const spec = doc;
+    if (typeof spec.swagger === 'string') {
+        throw new Error(`${opts.from} is Swagger ${spec.swagger}. DocuGate reads OpenAPI 3.0 and 3.1; convert it first, for example with swagger2openapi.`);
+    }
+    if (typeof spec.openapi !== 'string' || !/^3\.[01]\./.test(spec.openapi)) {
+        throw new Error(`${opts.from} has no "openapi": "3.x" field, so it is not an OpenAPI 3 document.`);
+    }
+    if (!spec.paths || typeof spec.paths !== 'object') {
+        throw new Error(`${opts.from} has no "paths".`);
+    }
+    const external = refsIn(spec).filter((ref) => !ref.startsWith('#/'));
+    if (external.length) {
+        throw new Error(`${opts.from} references other files (${[...new Set(external)].slice(0, 3).join(', ')}). ` +
+            'Bundle it into one document first, for example with `npx @redocly/cli bundle`.');
+    }
+    const include = opts.include.map(globToRegExp);
+    const exclude = opts.exclude.map(globToRegExp);
+    const paths = spec.paths;
+    const droppedPaths = [];
+    for (const path of Object.keys(paths)) {
+        const kept = (!include.length || include.some((r) => r.test(path))) && !exclude.some((r) => r.test(path));
+        if (!kept) {
+            delete paths[path];
+            droppedPaths.push(path);
+        }
+    }
+    const redacted = redact(spec, new Set(opts.redact));
+    let operations = 0;
+    for (const item of Object.values(paths)) {
+        for (const method of Object.keys(item ?? {}))
+            if (METHODS.has(method))
+                operations++;
+    }
+    const text = JSON.stringify(sortKeys(spec), null, 2) + '\n';
+    return { spec, text, operations, droppedPaths, redacted };
+}
+/** Whether the committed file already matches what would be written. */
+export function isCurrent(root, output, text) {
+    const path = join(root, output);
+    return existsSync(path) && readFileSync(path, 'utf8').replace(/\r\n/g, '\n') === text;
+}
+export function writeOpenApi(root, output, text) {
+    writeFileSync(join(root, output), text);
+}

package/dist/rules.js

@@ -0,0 +1,61 @@
+/**
+ * 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 const MAX_FILES = 300;
+/** Turn `guides/deploying.md` into `guides/deploying`, and `index.md` into ''. */
+export function pathToSlug(path) {
+    const withoutExt = path.replace(/\.md$/i, '');
+    return withoutExt === 'index' ? '' : withoutExt.replace(/\/index$/i, '');
+}
+/**
+ * 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 function resolveRelativeLink(href, fromPath) {
+    if (!href || href.startsWith('#'))
+        return null;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//'))
+        return null;
+    const [rawPath] = href.split('#');
+    if (!/\.mdx?$/i.test(rawPath))
+        return null;
+    const dir = fromPath.includes('/') ? fromPath.slice(0, fromPath.lastIndexOf('/')) : '';
+    const segments = rawPath.startsWith('/') ? [] : dir.split('/').filter(Boolean);
+    for (const part of rawPath.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            // Climbing above the docs folder leaves it, and DocuGate only serves
+            // what is inside it.
+            if (!segments.length)
+                return '\0outside';
+            segments.pop();
+        }
+        else
+            segments.push(part);
+    }
+    return pathToSlug(segments.join('/'));
+}
+/**
+ * Where a docs folder has no index.md, its top-level README becomes the
+ * landing page — the same file GitHub shows first.
+ */
+export function landingPath(paths) {
+    const index = paths.find((p) => pathToSlug(p) === '');
+    if (index)
+        return index;
+    return paths.find((p) => !p.includes('/') && /^readme\.md$/i.test(p)) ?? null;
+}
+/** The page title DocuGate shows: the first `# heading`, if there is one. */
+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', 'sidebar', 'api']);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "docugate",
+  "version": "0.1.0",
+  "description": "Command-line tools for DocuGate: set up, check and prepare the documentation DocuGate reads straight from your repository.",
+  "type": "module",
+  "bin": {
+    "docugate": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "docugate",
+    "documentation",
+    "docs",
+    "markdown",
+    "openapi",
+    "github",
+    "cli"
+  ],
+  "homepage": "https://www.trydocugate.site",
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "~6.0.2"
+  }
+}