docugate 0.2.9 → 0.3.0

package/README.md

@@ -1,11 +1,18 @@
 # docugate
 
-DocuGate publishes documentation straight from the markdown in your GitHub repositories and shows a walkthrough pill on your running app so any developer can see what each element on screen is and where its data comes from.
+DocuGate publishes documentation straight from the markdown in your GitHub repositories. This package is its command line, and it does three things:
+
+- **Keeps the docs true.** `docugate sync` reads what changed in your code, works out which pages that made wrong, and opens a pull request with the fix. Nobody has to remember to update the docs. [More](#docs-that-keep-up-with-your-code).
+- **Explains your app.** A walkthrough pill on your running app shows any developer what each element on screen is and where its data comes from. [More](#tours).
+- **Checks the result.** `docugate check` reads your docs and tours the way DocuGate will, so problems show up in CI instead of on the published page.
 
 ```sh
 npm i -g docugate
+docugate              # opens DocuGate in your terminal: pick what to do next
 ```
 
+Type `docugate` on its own and it opens, the way `claude` does: where your account, docs and space stand, and every next step in a list, with the one worth doing now under Enter. Arrow keys pick; in Git Bash and other terminals without them, type the number.
+
 ---
 
 ## Quick start, step by step
@@ -13,29 +20,30 @@ npm i -g docugate
 Follow these in order. Every question during setup is a numbered choice: type
 the number and press Enter, or just press Enter for the suggested one.
 
-**1. Install DocuGate, once per computer.**
+**1. Open your project's folder.**
 
 ```sh
-npm i -g docugate
+cd my-app
 ```
 
-This gives you the `docugate` command in every folder. To pin a version for a
-team instead, run `npm i -D docugate` inside the project and put `npx` in front
-of each command below.
+Use the root of the repository: the folder with `.git` and `package.json` in
+it. If your frontend and backend are two repositories, do steps 1 to 3 in each.
 
-**2. Open your project's folder.**
+**2. Install DocuGate in the project.**
 
 ```sh
-cd my-app
+npm i docugate
 ```
 
-Use the root of the repository: the folder with `.git` in it. If your frontend
-and backend are two repositories, do steps 2 to 4 in each one.
+Like any other package: everyone who clones the project gets the same version,
+and CI too. (A repository with no `package.json`, like a Go or Python backend,
+can install the command on the computer instead with `npm i -g docugate`, and
+then drop the `npx` from the commands below.)
 
 **3. Set everything up.**
 
 ```sh
-docugate init
+npx docugate init
 ```
 
 It asks, one at a time:
@@ -45,10 +53,9 @@ It asks, one at a time:
 | What is in this repository? | **1** Frontend, **2** Backend, or **3** Both (a `frontend/` and a `backend/` folder in one repository). It suggests one from your folders. |
 | Sign in to DocuGate? | **1** opens your browser to sign in with GitHub. You come back to your editor when it is done. **2** skips it; `docugate login` does it later. |
 | Where should the documentation live? | **1** creates a new space, with a new GitHub repository on your account to hold its markdown (`<project>-docs`, with a first page). Or pick one of your spaces. The pill then links to the published docs. |
-| How often should DocuGate check your docs still match the code? | On every push, daily (suggested, fewer AI runs), weekly, or never. |
+| How often should DocuGate check your docs still match the code? | On every push, daily (suggested, fewer AI runs), weekly, or never. The answer is saved as `freshness`; `docugate sync init` then adds the GitHub Action that does the checking. |
 | Set up the tour: which AI should write it? | **1** IBM Bob reads your code and writes the tour. **2** IBM watsonx is coming soon. **3** skips it; you can write the tour in the browser. Frontend and both only. |
 | Add the DocuGate pill to your app? | **1** adds a few lines to your `index.html` or Next.js layout that load the pill in development only. |
-| Start the tour server now? | **1** starts it, so the pill shows right away. |
 
 IBM Bob reads its API key from the `BOB_API_KEY` environment variable. If you
 saved it under another name (say `IBM_BOB_KEY`), setup finds it and asks before
@@ -61,24 +68,20 @@ export BOB_API_KEY=<key>                                                # macOS,
 ```
 
 Setup writes `docugate.json` and `.docugate/tour/`. Commit both, so the next
-person who clones the repository needs no setup.
-
-**4. Start the tour server while you work.**
-
-```sh
-docugate tour serve
-```
-
-Leave it running in its own terminal. The pill only appears while it runs,
-which is why the pill never shows in production. If you started it at the end
-of step 3, it is already running.
+person who clones the repository needs no setup. When setup finishes it starts
+the tour server in the background, so the pill is there the first time you open
+the app (`--no-serve` skips that).
 
-**5. Run your app as usual, in another terminal, and open it.**
+**4. Run your app as usual, and open it.**
 
 ```sh
 npm run dev
 ```
 
+Setup added a `predev` script, so `npm run dev` starts the DocuGate tour server
+first (one line, "DocuGate tour ready") and then your app. The pill only
+appears while that server runs, which is why it never shows in production.
+
 The DocuGate pill sits in the bottom-right corner. Click it:
 
 - **Walkthrough** lists the page's steps with your progress. Click a step to
@@ -89,10 +92,10 @@ The DocuGate pill sits in the bottom-right corner. Click it:
 
 Every change is saved straight into `.docugate/tour/`, so it shows up in `git diff`.
 
-**6. Keep the tour true.**
+**5. Keep the tour true.**
 
 ```sh
-docugate check
+npx docugate check
 ```
 
 It checks every step against the code and warns about any that went stale,
@@ -102,24 +105,146 @@ for example after a rename. Put it in CI so a stale tour fails the build (see
 **Later, when you need them:**
 
 ```sh
-docugate login           # sign in again, or on a new computer
-docugate whoami          # who am I signed in as?
-docugate tour init       # let IBM Bob write tours for screens that have none
-docugate tour install    # add the pill again (--remove takes it out)
-docugate logout          # disconnect this computer
+npx docugate                 # the menu: pick what to do next
+npx docugate status          # where things stand, and what to do next
+npx docugate sync            # update the docs from what changed in the code
+npx docugate login           # sign in again, or on a new computer
+npx docugate whoami          # who am I signed in as?
+npx docugate tour init       # let IBM Bob write tours for screens that have none
+npx docugate tour install    # add the pill again (--remove takes it out)
+npx docugate tour serve      # start the tour server by hand
+npx docugate logout          # disconnect this computer
 ```
 
 **Something not working?**
 
 | You see | Do this |
 | --- | --- |
-| No pill in the app | Check `docugate tour serve` is running, then refresh the page. |
+| No pill in the app | Start the app with `npm run dev` (it starts the tour server), or run `npx docugate tour serve`, then refresh the page. |
 | Bob can't run | Choose IBM Bob again in `docugate init` to paste a key, or install Bob Shell: https://bob.ibm.com/docs/shell/getting-started/install-and-setup |
 | Port 4178 is busy | `docugate tour serve --port 4179` and `docugate tour install --port 4179` |
 | "Already set up in ..." | You ran it in a subfolder. Run commands from the folder it names. |
 
 ---
 
+## A developer space
+
+```sh
+docugate developers
+```
+
+One guided run sets up the docs developers read before they build on your API:
+
+1. Signs you in, if you are not.
+2. Finds your OpenAPI file (`openapi.json`, `.yaml`, `swagger.*`) and says how many endpoints it describes.
+3. Writes the first pages, `index.md`, `quickstart.md`, `authentication.md` and `errors.md`, in `docs/developers/`, where they are missing. It never overwrites a file.
+4. Offers to commit and push them, since a space reads GitHub, not your disk.
+5. Creates a public space for them, or uses the one that already reads this repository, and saves it in `docugate.json`.
+
+On Pro it carries on:
+
+6. Claims a subdomain such as `acme.trydocugate.site`, live at once.
+7. Asks where the API console sends requests from: the reader's browser, or through DocuGate with no CORS setup.
+8. Switches on API keys, with a scope per OpenAPI tag to start from, makes the verify secret, offers to put it in `.env` when git ignores that file, and prints the lines your Express, Hono or Fastify backend needs.
+
+Everything it sets stays editable in the space's settings on [trydocugate.site](https://www.trydocugate.site/dashboard).
+
+## Docs that keep up with your code
+
+Documentation goes stale because updating it is a chore nobody owns. `docugate sync` does the chore: it reads what changed in the code, finds the pages those changes made wrong, asks an AI model to correct them, and gives you the edits to review.
+
+```sh
+npx docugate sync --dry-run   # free and instant: which pages are probably out of date
+npx docugate sync             # write the edits into your docs folder
+npx docugate sync --pr        # push them and open a pull request instead
+```
+
+`sync` needs an AI key of your own, in `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (set `DOCUGATE_AI_BASE_URL` to use another OpenAI-compatible service). It talks to the provider directly: nothing goes through DocuGate's servers, and it works without a DocuGate account.
+
+**What it does, step by step**
+
+1. **Reads the changes** from git: the commits and a trimmed diff of each changed file, since the last sync. The first run looks back a day, a week or one commit, depending on `freshness`. `--since 7d`, a branch or a commit overrides it. Documentation, lockfiles, build output, binaries and anything that looks like a secret (`.env`, `*.pem`, files named `secret` or `credentials`) are never read.
+2. **Finds the pages that are affected.** A page counts when it names a changed file, mentions something the change added or removed (a function, a route, an environment variable), or is pinned to that code in `sync.map`. This part is free, and it is all `--dry-run` does.
+3. **Asks the model** for the new text of those pages, and only those. It is told to change what the diff requires and nothing else, to invent nothing, and to treat the code as data rather than instructions.
+4. **Checks the answer before writing it.** An edit is dropped unless it is a markdown page inside your docs folder, within 300 pages, without front matter. After writing, `docugate check` runs again, and an edit that breaks a link is put back as it was.
+5. **Hands it over.** With `--pr` the edits go on one branch, `docugate/sync`, and one pull request that lists every page and why it changed. Each run updates that same pull request rather than opening another. Nothing is ever merged for you, and closing the pull request changes nothing. The sync moves forward only when you merge it.
+
+**Make it automatic**
+
+```sh
+npx docugate sync init
+```
+
+This writes `.github/workflows/docugate-sync.yml`, timed by `freshness` in `docugate.json`:
+
+| `freshness` | When it runs |
+| --- | --- |
+| `push` | On every push to your default branch. |
+| `daily` | Every day. |
+| `weekly` | Every Monday (the default). |
+| `off` | Never. No workflow is written. |
+
+Do two things on GitHub, once: add your AI key as a repository secret named `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY`), and under Settings, Actions, General, tick "Allow GitHub Actions to create and approve pull requests". `sync init` prints both steps. The workflow is pinned to the version that wrote it, so a new release never changes what your CI does by surprise; run `sync init --force` to upgrade it. A sync's own commits never start another sync.
+
+**A heads-up on your own machine**
+
+```sh
+npx docugate sync hook install
+```
+
+After every commit, a git hook runs `sync --dry-run` and, if pages look out of date, says so in one line. It sends nothing, changes nothing and never fails a commit. `sync hook remove` takes it out.
+
+**Settings**, in `docugate.json`:
+
+```json
+{
+  "freshness": "weekly",
+  "sync": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-5-5",
+    "include": ["server/**", "src/**"],
+    "exclude": ["**/*.test.ts"],
+    "map": { "docs/api.md": ["server/routes/**"] },
+    "maxFiles": 10,
+    "digest": false
+  }
+}
+```
+
+| Key | Meaning |
+| --- | --- |
+| `provider` | `anthropic` or `openai`. Defaults to whichever key is set. |
+| `model` | The model to use. |
+| `include` / `exclude` | Path globs for the code worth documenting. `*` stays within a folder, `**` crosses folders. |
+| `map` | Pin a page to the code it documents, when its text never names the files. DocuGate does not read front matter, so this is where that link lives. |
+| `maxFiles` | The most pages one run may change (10). |
+| `digest` | Also write a short "what changed" page, `changes/<date>.md`, for each run. |
+
+`sync` also lists tour stops that no longer match the code. It only reports them: a tour is yours, and DocuGate never edits one.
+
+**When it says no**
+
+| You see | Do this |
+| --- | --- |
+| "No AI key found" | Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` where you run it, or as an Actions secret. |
+| "shallow clone" | In GitHub Actions, set `fetch-depth: 0` on the checkout step. `sync init` already does. |
+| Pushed, but no pull request | Allow Actions to create pull requests (above), or set `GITHUB_TOKEN` when running it by hand. |
+| "Skipped: the changes only touch documentation" | Working as intended. A merged sync, or a docs-only change, never starts a sync. |
+
+---
+
+## Moving around
+
+Run `docugate` in a terminal and you get a menu: arrow keys to move, type to search, Enter to run, Esc to leave. It shows where you are (signed in or not, how many pages, how far the docs are behind the code) and puts the step worth taking next under Enter, with a dot beside it. Not connected to DocuGate yet? Connecting your account is that step. When a command finishes, the menu comes back.
+
+- `docugate status` prints the same picture: your account, your docs, the sync (last run, whether the workflow and hook are on, how many commits and pages are behind), your tour, and one line saying what to do next. `--json` is for scripts.
+- `docugate help <command>`, or `docugate <command> --help`, shows one command's options and examples.
+- Mistype and it helps: `docugate chekc` suggests `check`, and an option a command does not have is an error with the nearest real one, not silently ignored.
+- `docugate completion powershell|bash|zsh` prints a completion script.
+- In CI, in a pipe, or with `--no-input`, nothing is ever asked: the menu does not open, the help prints as plain text, and a command that needs an answer fails with what to do. To use your DocuGate account in CI, set `DOCUGATE_TOKEN`.
+
+---
+
 ## Tours
 
 A tour helps a developer who is new to a codebase see what each element on screen is and where its data comes from. For each screen there is one markdown file in `.docugate/tour/`. Each file has front matter with a `route` and a `title`, then one `##` section per stop.
@@ -224,18 +349,29 @@ Pin the version in CI, as above. Without a pin, the rules being enforced can cha
 
 | Command | Main flags | What it does |
 | --- | --- | --- |
-| `docugate init` | `--dir`, `--title`, `--role frontend\|backend\|both`, `--yes` | Set up this repository for DocuGate (interactive). |
+| `docugate` | | In a terminal: the menu. Elsewhere: the help. |
+| `docugate status` | `--json` | Where things stand: account, docs, sync and tour, and what to do next. |
+| `docugate sync` | `--dry-run`, `--since <when>`, `--pr`, `--yes`, `--max-files <n>`, `--model <name>`, `--quiet` | Update the docs from what changed in the code. |
+| `docugate sync init` | `--freshness push\|daily\|weekly\|off`, `--force` | Add the GitHub Action that runs sync on a schedule or on every push. |
+| `docugate sync hook install` | | Tell you after each commit which pages the code left behind. |
+| `docugate sync hook remove` | | Remove that hook. |
+| `docugate init` | `--dir`, `--title`, `--role frontend\|backend\|both`, `--yes`, `--no-serve` | Set up this repository for DocuGate (interactive). |
+| `docugate developers` | `--dir`, `--yes` | Set up a developer space: API reference, guides and keys (interactive). |
 | `docugate check` | `--dir`, `--strict` | Check docs and tour files the way DocuGate will read them. |
+| `docugate help [command]` | | Every command, or one command's options and examples. |
+| `docugate completion <shell>` | | Print a completion script for bash, zsh or powershell. |
 | `docugate openapi` | `--from`, `--out`, `--include`, `--exclude`, `--redact`, `--check` | Prepare an OpenAPI spec for the API reference. |
 | `docugate login` | | Sign in to DocuGate with GitHub. |
 | `docugate logout` | | Sign out and delete saved credentials. |
 | `docugate whoami` | | Print the currently signed-in user. |
 | `docugate tour init` | `--max-cost <n>`, `--team-id <id>` | Write the first tour with IBM Bob (uses Bob Shell). |
-| `docugate tour serve` | `--port <n>` (default 4178) | Start the local server that serves tour data for the pill. |
+| `docugate tour serve` | `--port <n>` (default 4178), `--background` | Start the local server that serves tour data for the pill. |
 | `docugate tour install` | `--port <n>`, `--remove` | Add (or remove) the pill loader from your app's HTML or layout. |
 | `docugate tour export <file>` | | Write every tour screen to a single JSON file. |
 
-Run every command from the root of your repository.
+Run every command from the root of your repository. Every command also takes
+`--help`, and `--no-input` (which CI implies) to make sure it never stops to
+ask a question: it fails with what to do instead.
 
 ---
 
@@ -307,6 +443,29 @@ Instead of passing flags every time, set the same options in `docugate.json`:
 
 ---
 
+## Checking API keys from your backend
+
+If you publish an API's docs on DocuGate Enterprise, the people reading them can generate an API key on the page. Your backend asks DocuGate whether each key is valid, with a secret from your space's settings, so a key you revoke stops on its next request. This package carries that check. It is separate from the command and has no dependencies of its own.
+
+```ts
+import { requireKey } from 'docugate/express' // or 'docugate/hono', 'docugate/fastify'
+
+app.use('/api', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))
+```
+
+The verified key is on `req.docugateKey` (Express and Fastify) or `c.get('docugateKey')` (Hono): who holds it, its scopes, and what is left of its allowance. Anything else, in any framework, can call the check directly:
+
+```ts
+import { verifyKey } from 'docugate/keys'
+
+const verdict = await verifyKey(key, { secret: process.env.DOCUGATE_VERIFY_SECRET! })
+if (!verdict.valid) return deny(verdict.code) // REVOKED, EXPIRED, USAGE_EXCEEDED, ...
+```
+
+`verifyKey` answers for every key, valid or not, and throws a `KeyServiceError` only when it could not get an answer. By default every request asks DocuGate, which is what makes a revoked key stop at once; `cacheSeconds` trades that for speed, and `failOpen` decides what happens when DocuGate cannot be reached (by default, the request is refused). The options, the exact request, and what each result means are in [API keys](https://www.trydocugate.site/docs/api-keys).
+
+---
+
 ## `docugate.json`
 
 One per repository, at its root.
@@ -316,33 +475,17 @@ One per repository, at its root.
 | `docsDir` | The folder DocuGate reads. Defaults to `docs`. |
 | `title` | The space's title. |
 | `role` | Repository role: `frontend`, `backend`, or `both`. Set by `docugate init`. |
-| `freshness` | How often DocuGate checks that the docs still match the code: `push`, `daily`, `weekly` or `off`. Set by `docugate init`; the scheduled check itself is coming soon. |
+| `freshness` | How often the docs are checked against the code: `push`, `daily`, `weekly` or `off`. Set by `docugate init` or `docugate sync init`, which writes the GitHub Action to match. |
+| `sync` | Settings for `docugate sync`; see [Docs that keep up with your code](#docs-that-keep-up-with-your-code). The DocuGate site ignores it. |
 | `sidebar` | File and folder names in the order the sidebar should show them. Orders this repository's own pages, not the whole space. |
 | `api.generate` | Defaults for `docugate openapi`. |
+| `api.spec` | Where the OpenAPI file is, for a repository that does not keep it at `openapi.json` in the root or the docs folder. DocuGate draws an [API reference](https://www.trydocugate.site/docs/api-reference) from it. |
 
 ---
 
-## IBM Bob 2.0 hackathon
-
-This repository is DocuGate's entry to the IBM Bob 2.0 hackathon (lablab.ai, September 25 to 27, 2026). To be clear about what was built when:
-
-**Before the event:** the CLI that was already in DocuGate's private repository: `docugate init`, `docugate check`, and `docugate openapi`. Moved here with its history.
-
-**During the event, with IBM Bob.** Each task has its session summary and export in `bob_sessions/`, and a plan where Bob planned first:
-
-| Task | What Bob built |
-| --- | --- |
-| 01 | The first tour: Bob read the Ledgerly demo and wrote `.docugate/tour/invoice-detail.md`, tracing each value to its endpoint and backend file. |
-| 02 | The tour format in code (`parseTourFile`, `serializeTourFile`, `loadTours`, `matchRoute`) and the tour checks in `docugate check`. |
-| 03 | `docugate tour serve` (tour data, live change events, saving stops) and `docugate tour export`. |
-| 04 | The pill: walkthrough, inspector and Add to tour, in a shadow DOM with no dependencies. |
-| 05 | One command: `docugate init` walks through the whole setup, and `docugate tour install` adds the pill to the app. |
-| 06 | `docugate login`, `logout` and `whoami`, and connecting the repository to a space during `init`. |
-| 07 | This README. |
-
-`docugate tour init` also runs IBM Bob itself, through Bob Shell. It installs a Tour Writer mode that may only edit `.docugate/tour/`, asks Bob to read the app's code, and never changes a tour file the user already has.
+## Built with IBM Bob
 
-**During the event, without Bob:** the Ledgerly demo app; the website side of `docugate login` on trydocugate.site; and fixes found while testing, such as Windows short paths in `tour serve` and the sign-in link on Windows.
+The tour and pill began as DocuGate's entry to the IBM Bob 2.0 hackathon (lablab.ai, September 25 to 27, 2026), and IBM Bob still writes the first tour (`docugate tour init` runs it through Bob Shell, in a Tour Writer mode that may only edit `.docugate/tour/` and never changes a tour file you already have). Demo video: https://youtu.be/mgLUA-0r5MM. Live demo: https://docugate-demo.vercel.app/invoices/inv_1004
 
 ---
 

package/dist/api.d.ts

@@ -0,0 +1,44 @@
+/** Module-level default, captured at import time (used by CLI commands). */
+export declare const BASE_URL: string;
+export declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;
+export interface DocugateUser {
+    githubLogin: string;
+    name: string;
+    email: string;
+    plan: string;
+}
+export interface SessionResponse {
+    user: DocugateUser | null;
+}
+export interface Space {
+    id: string;
+    owner: string;
+    slug: string;
+    name: string;
+    /** The repositories the space reads from. */
+    sources?: Array<{
+        repo: string;
+    }>;
+}
+export interface SpacesResponse {
+    spaces: Space[];
+}
+export declare function getSession(): Promise<SessionResponse>;
+export declare function getSpaces(): Promise<SpacesResponse>;
+export declare function createSpace(repo: string, name: string, docsDir: string, visibility?: 'public' | 'repo-access' | 'allowlist'): Promise<Space>;
+/** Creates an empty repository on the person's GitHub account, as them. */
+export interface CreatedRepo {
+    repo: string;
+    url: string;
+    cloneUrl: string;
+    /** For a docs repository: whether docs/index.md was written into it. */
+    seeded?: boolean;
+}
+/**
+ * Creates a repository on the person's GitHub account, as them. With `docs`,
+ * it is a documentation repository that starts with docs/index.md.
+ */
+export declare function createRepo(name: string, isPrivate: boolean, docs?: {
+    title: string;
+}): Promise<CreatedRepo>;
+export declare function connectRepo(spaceId: string, repo: string, docsDir: string): Promise<void>;

package/dist/api.js

@@ -15,7 +15,9 @@ function friendlyError(code) {
     return ERROR_MESSAGES[code] ?? `DocuGate said: ${code}`;
 }
 export async function apiFetch(path, init = {}) {
-    const creds = loadCredentials();
+    // DOCUGATE_TOKEN is for CI, where there is no browser to sign in with.
+    const envToken = process.env.DOCUGATE_TOKEN;
+    const creds = envToken ? { token: envToken } : loadCredentials();
     const headers = {
         'Content-Type': 'application/json',
         ...init.headers,
@@ -28,26 +30,30 @@ export async function apiFetch(path, init = {}) {
     const res = await fetch(`${base}${path}`, { ...init, headers });
     // Renew token if the server sent a fresh one.
     const renewed = res.headers.get('x-docugate-token');
-    if (renewed)
+    if (renewed && !envToken)
         saveCredentials(renewed);
     if (res.status === 401) {
         throw new Error('Run docugate login');
     }
     if (!res.ok) {
         let code;
+        let detail;
         try {
             const body = await res.clone().json();
             if (body && typeof body === 'object' && !Array.isArray(body)) {
                 const b = body;
                 if (typeof b.error === 'string')
                     code = b.error;
+                if (typeof b.detail === 'string' && b.detail)
+                    detail = b.detail;
             }
         }
         catch {
             // ignore JSON parse failure
         }
+        // GitHub's own reason, when the server passed it on, after ours.
         if (code)
-            throw Object.assign(new Error(friendlyError(code)), { code });
+            throw Object.assign(new Error(detail ? `${friendlyError(code)} (GitHub: ${detail})` : friendlyError(code)), { code, detail });
         throw new Error(`DocuGate request failed with status ${res.status}`);
     }
     return res;
@@ -60,10 +66,10 @@ export async function getSpaces() {
     const res = await apiFetch('/api/spaces/mine');
     return res.json();
 }
-export async function createSpace(repo, name, docsDir) {
+export async function createSpace(repo, name, docsDir, visibility) {
     const res = await apiFetch('/api/spaces', {
         method: 'POST',
-        body: JSON.stringify({ repo, name, docsDir }),
+        body: JSON.stringify({ repo, name, docsDir, ...(visibility ? { visibility } : {}) }),
     });
     return (await res.json()).space;
 }

package/dist/args.d.ts

@@ -0,0 +1,29 @@
+import type { Command } from './commands.js';
+/** A mistake in how the command was typed. Exit code 2, with a hint if there is one. */
+export declare class UsageError extends Error {
+    hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+export type Parsed = {
+    /** The command that was matched, if any. */
+    spec?: Command;
+    /** `tour` or `sync hook` typed with nothing after it: a group, not a command. */
+    group?: string;
+    /** The words of the command, split: `sync hook install` is sync / hook / install. */
+    command?: string;
+    sub?: string;
+    sub2?: string;
+    /** The trailing argument some commands take, like the file of `tour export`. */
+    positional?: string;
+    flags: Map<string, string[]>;
+    bools: Set<string>;
+    help: boolean;
+    version: boolean;
+};
+/**
+ * Reads the command line against the registry: it finds the command (including
+ * two- and three-word ones), and rejects an unknown command or option with the
+ * nearest valid one, rather than ignoring it.
+ */
+export declare function parseArgs(argv: string[]): Parsed;
+export declare const GLOBAL_FLAG_NAMES: string[];

package/dist/args.js

@@ -0,0 +1,121 @@
+import { COMMANDS, findCommand, flagsOf, GLOBAL_FLAGS, VALUE_FLAG_NAMES } from './commands.js';
+import { suggest } from './ui.js';
+/** A mistake in how the command was typed. Exit code 2, with a hint if there is one. */
+export class UsageError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+    }
+}
+const names = (list) => list.map((f) => f.name);
+/**
+ * Reads the command line against the registry: it finds the command (including
+ * two- and three-word ones), and rejects an unknown command or option with the
+ * nearest valid one, rather than ignoring it.
+ */
+export function parseArgs(argv) {
+    const flags = new Map();
+    const bools = new Set();
+    const words = [];
+    let help = false;
+    let version = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h')
+            help = true;
+        else if (arg === '-v')
+            version = true;
+        else if (arg.startsWith('--')) {
+            const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
+            if (name === 'help')
+                help = true;
+            else if (name === 'version')
+                version = true;
+            else if (VALUE_FLAG_NAMES.has(name)) {
+                const value = inline ?? argv[++i];
+                if (value === undefined)
+                    throw new UsageError(`--${name} needs a value.`);
+                flags.set(name, [...(flags.get(name) ?? []), value]);
+            }
+            else
+                bools.add(name);
+        }
+        else if (arg.startsWith('-') && arg.length > 1) {
+            throw new UsageError(`Unknown option ${arg}.`, 'Options start with two dashes, like --yes. -h and -v are the only short ones.');
+        }
+        else
+            words.push(arg);
+    }
+    const parsed = { flags, bools, help, version };
+    if (!words.length)
+        return parsed;
+    // `tour` or `sync hook` on their own: not a command, but the start of several.
+    const typed = words.join(' ');
+    if (words.length <= 2 && !findCommand(typed) && COMMANDS.some((c) => c.name.startsWith(`${typed} `))) {
+        return { ...parsed, group: typed, command: words[0], sub: words[1] };
+    }
+    // The longest run of words that is a command.
+    let spec;
+    let used = 0;
+    for (let n = Math.min(3, words.length); n >= 1; n--) {
+        const found = findCommand(words.slice(0, n).join(' '));
+        if (found) {
+            spec = found;
+            used = n;
+            break;
+        }
+    }
+    if (!spec) {
+        // `tour` or `sync hook` alone: a group of commands.
+        for (let n = Math.min(2, words.length); n >= 1; n--) {
+            const prefix = words.slice(0, n).join(' ');
+            if (words.length === n && COMMANDS.some((c) => c.name.startsWith(`${prefix} `)))
+                return { ...parsed, group: prefix, command: words[0], sub: words[1] };
+        }
+        // A known group with a sub-command that does not exist: `tour nope`.
+        const subs = [...new Set(COMMANDS.filter((c) => c.name.startsWith(`${words[0]} `)).map((c) => c.name.split(' ')[1]))];
+        if (subs.length) {
+            const close = suggest(words[1], subs);
+            throw new UsageError(`Unknown ${words[0]} command "${words[1]}".`, close ? `Did you mean "${words[0]} ${close}"?` : `Try: ${subs.map((s) => `${words[0]} ${s}`).join(', ')}.`);
+        }
+        const top = [...new Set(COMMANDS.map((c) => c.name.split(' ')[0]))];
+        const close = suggest(words[0], top);
+        throw new UsageError(`Unknown command "${words[0]}".`, close ? `Did you mean "${close}"?` : 'Run `docugate --help` to see every command.');
+    }
+    const rest = words.slice(used);
+    if (rest.length > (spec.positional ? 1 : 0)) {
+        const subs = COMMANDS.filter((c) => c.name.startsWith(`${spec.name} `)).map((c) => c.name.slice(spec.name.length + 1).split(' ')[0]);
+        if (!spec.positional && subs.length) {
+            const close = suggest(rest[0], [...new Set(subs)]);
+            throw new UsageError(`Unknown command "${spec.name} ${rest[0]}".`, close ? `Did you mean "${spec.name} ${close}"?` : `Try: ${[...new Set(subs)].map((s) => `${spec.name} ${s}`).join(', ')}.`);
+        }
+        throw new UsageError(`Unexpected argument "${rest[spec.positional ? 1 : 0]}".`);
+    }
+    // Options this command does not have are mistakes, not noise.
+    const allowed = flagsOf(spec);
+    const valueNames = new Set(spec.flags.filter((f) => f.value).map((f) => f.name));
+    for (const name of [...flags.keys(), ...bools]) {
+        if (!allowed.some((f) => f.name === name)) {
+            const close = suggest(name, names(allowed));
+            throw new UsageError(`"${spec.name}" has no option --${name}.`, close ? `Did you mean --${close}?` : `Run \`docugate help ${spec.name}\` to see its options.`);
+        }
+        if (valueNames.has(name) === false && flags.has(name)) {
+            throw new UsageError(`--${name} does not take a value for "${spec.name}".`);
+        }
+    }
+    for (const name of valueNames) {
+        if (bools.has(name))
+            throw new UsageError(`--${name} needs a value.`);
+    }
+    const parts = spec.name.split(' ');
+    return {
+        ...parsed,
+        spec,
+        command: parts[0],
+        sub: parts[1],
+        sub2: parts[2] ?? rest[0],
+        positional: rest[0],
+    };
+}
+export const GLOBAL_FLAG_NAMES = names(GLOBAL_FLAGS);

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+export type Credentials = {
+    token: string;
+};
+export declare function credentialsPath(): string;
+export declare function loadCredentials(): Credentials | null;
+export declare function saveCredentials(token: string): void;
+export declare function clearCredentials(): void;
+export interface LoginOptions {
+    /** Override the browser-open function (used in tests). */
+    openBrowser?: (url: string) => void;
+    /** Override the timeout in ms (used in tests; default 5 minutes). */
+    timeoutMs?: number;
+}
+/**
+ * Opens the browser at `baseUrl/api/auth/cli?port=…&state=…`, starts a local
+ * HTTP server to receive the callback, saves the token, and resolves once the
+ * user completes sign-in. Rejects after `timeoutMs` (default 5 minutes).
+ */
+export declare function login(baseUrl: string, opts?: LoginOptions): Promise<{
+    token: string;
+}>;