docugate 0.4.0 → 0.4.2

package/README.md

@@ -147,7 +147,7 @@ On Pro it carries on:
 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).
+Everything it sets stays editable in the space's settings on [trydocugate.site](https://trydocugate.site/dashboard).
 
 ## Docs that keep up with your code
 
@@ -363,7 +363,7 @@ Pin the version in CI, as above. Without a pin, the rules being enforced can cha
 | `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 connect` | `--space`, `--frequency`, `--type`, `--backend-dir`, `--no-audit`, `--yes` | Connect this project to your account, to run it from the dashboard. |
+| `docugate connect` | `--project`, `--section`, `--frequency`, `--type`, `--backend-dir`, `--no-audit`, `--yes` | Connect this codebase to a project, and publish its docs with the project's. |
 | `docugate audit` | `--fail-on`, `--json` | Check this project’s packages for known vulnerabilities. |
 | `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). |
@@ -403,13 +403,20 @@ Or try it without installing anything: https://docugate-demo.vercel.app/invoices
 
 ---
 
-## Several repositories in one space
+## One project, several codebases
 
-A space can merge docs from a frontend, a backend, and a mobile app into one set of pages. `docugate init` connects the repository it runs in to one of your spaces once you are signed in; you can also add repositories from a space's settings on [trydocugate.site](https://www.trydocugate.site/dashboard).
+A project is one set of docs fed by its codebases: a frontend and a backend, in two repositories or as two folders of one. Run `docugate connect` in each of them:
+
+```bash
+cd server && npx docugate connect   # pick the project, or start a new one
+cd ../public && npx docugate connect # pick the same project
+```
+
+The first codebase's docs sit at the top of the project's space; each one after it gets a section named after what it is (`frontend/`, `backend/`), so two pages with the same name cannot clash. A docs folder the space already reads is not added twice. Change the sections, or add repositories by hand, in a space's settings on [trydocugate.site](https://trydocugate.site/dashboard). Feeding one project from several codebases needs Pro or an organization plan.
 
 Run `init` and `check` in each repository that contributes docs, and answer the role question in each: the tour lives in the frontend, and its `source` lines can point into the backend. Every one gets its own `docugate.json`, naming its own docs folder. `check` reads the repository it is run in, which is why its 300-page limit is per repository rather than per space.
 
-See [Merging repositories](https://www.trydocugate.site/docs/merging-repositories).
+See [Merging repositories](https://trydocugate.site/docs/merging-repositories).
 
 ---
 
@@ -464,7 +471,7 @@ const verdict = await verifyKey(key, { secret: process.env.DOCUGATE_VERIFY_SECRE
 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).
+`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://trydocugate.site/docs/api-keys).
 
 ---
 
@@ -481,7 +488,7 @@ One per repository, at its root.
 | `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. |
+| `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://trydocugate.site/docs/api-reference) from it. |
 
 ---
 

package/dist/api.js

@@ -22,7 +22,7 @@ export function detectAgent(env = process.env) {
     return 'Terminal';
 }
 /** Module-level default, captured at import time (used by CLI commands). */
-export const BASE_URL = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
+export const BASE_URL = process.env.DOCUGATE_URL ?? 'https://trydocugate.site';
 const ERROR_MESSAGES = {
     pro_required_sources: 'Connecting more than one repository to a space needs DocuGate Pro',
     space_limit: 'The free plan has one space. Connect this repository to it, or upgrade to Pro',
@@ -32,6 +32,13 @@ const ERROR_MESSAGES = {
     repo_exists: 'You already have a repository with this name on GitHub',
     app_permission: "DocuGate isn't allowed to create repositories on your account yet. Accept the DocuGate app's updated permissions at https://github.com/settings/installations, then try again",
     github_required: 'Sign in with GitHub to create a space',
+    source_collision: 'Some pages would share an address with pages the space already has. Put them under a section',
+    duplicate_source: 'The space already reads that folder of that repository',
+    duplicate_mount: 'Another repository already uses that section. Choose another name',
+    bad_mount: 'A section is a short name: letters, numbers and dashes, up to three levels',
+    bad_path: 'DocuGate could not read which folder of the repository this is',
+    bad_space: 'That project is not one you can connect to',
+    forbidden: 'You can only change a space you own, or one whose repository you can push to',
 };
 function friendlyError(code) {
     return ERROR_MESSAGES[code] ?? `DocuGate said: ${code}`;
@@ -53,8 +60,18 @@ export async function apiFetch(path, init = {}) {
         headers['x-docugate-version'] = CLI_VERSION;
     }
     // Re-read the env at call time so tests that set DOCUGATE_URL after import work.
-    const base = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
-    const res = await fetch(`${base}${path}`, { ...init, headers });
+    const base = process.env.DOCUGATE_URL ?? 'https://trydocugate.site';
+    let res = await fetch(`${base}${path}`, { ...init, headers, redirect: 'manual' });
+    // fetch drops the Authorization header when a redirect changes host, so a
+    // move between www.trydocugate.site and trydocugate.site read as signed out.
+    // Followed here instead, once, and only between two names of the same site.
+    const moved = res.status >= 301 && res.status <= 308 ? res.headers.get('location') : null;
+    if (moved) {
+        const to = new URL(moved, base);
+        const bare = (host) => host.replace(/^www\./, '');
+        if (to.protocol === 'https:' && bare(to.host) === bare(new URL(base).host))
+            res = await fetch(to, { ...init, headers, redirect: 'manual' });
+    }
     // Renew token if the server sent a fresh one.
     const renewed = res.headers.get('x-docugate-token');
     if (renewed && !envToken)

package/dist/cli.js

@@ -23,7 +23,7 @@ import { startTourServer } from './tour-server.js';
 import { login, clearCredentials, loadCredentials } from './auth.js';
 import { BASE_URL, getSession } from './api.js';
 import { dim, gold, green, hint, isMintty, plural, red, suggest, yellow } from './ui.js';
-const SITE = 'https://www.trydocugate.site';
+const SITE = 'https://trydocugate.site';
 /** True while the launch menu is running: its commands do not print their own "Next". */
 let inMenu = false;
 function fail(message, tip) {
@@ -213,7 +213,9 @@ async function run(argv) {
         }
         case 'connect': {
             process.exitCode = await connectCommand(root, {
-                space: one('space'),
+                // --space is what it was called before a project could have several codebases.
+                project: one('project') ?? one('space'),
+                section: one('section'),
                 frequency: one('frequency'),
                 type: one('type'),
                 backendDir: one('backend-dir'),

package/dist/commands.js

@@ -166,18 +166,20 @@ export const COMMANDS = [
     {
         name: 'connect',
         group: 'Account',
-        summary: 'Connect this project to your account, to run it from the dashboard',
-        description: 'Links this repository to your DocuGate account. Then the dashboard decides which documentation it updates, how often, and what kind of project it is. ' +
+        summary: 'Connect this codebase to a project, and publish its docs with the project’s',
+        description: 'Run it in each codebase of a project: the backend, then the frontend, whether they are two repositories or two folders of one. ' +
+            'It asks which project the codebase belongs to, or starts a new one, and adds its docs folder to the project’s space, under a section of its own when the project already has docs. ' +
             'It shares the repository name, the tool running the CLI, the outcome of each sync, and the names and versions of public packages in your lockfiles. Never your code.',
         flags: [
-            { name: 'space', value: 'slug', description: 'The space this project updates' },
+            { name: 'project', value: 'name', description: 'The project to join, by slug, owner/slug or name (--space still works)' },
+            { name: 'section', value: 'name', description: 'The section its docs go under (default: frontend, backend… after the first codebase)' },
             { name: 'frequency', value: 'when', description: 'How often docs are checked: push, daily, weekly or off' },
             { name: 'type', value: 'kind', description: 'frontend, backend, serverless or monorepo (default: detected)' },
             { name: 'backend-dir', value: 'folder', description: 'In a monorepo, the folder that holds the backend' },
             { name: 'no-audit', description: 'Do not send package names to check for vulnerabilities' },
             YES,
         ],
-        examples: ['docugate connect', 'docugate connect --space handbook --frequency daily --type monorepo --backend-dir apps/api --yes'],
+        examples: ['docugate connect', 'docugate connect --project payments --type backend --yes', 'docugate connect --project payments --type frontend --section web --yes'],
         account: 'required',
     },
     {

package/dist/developers.js

@@ -13,7 +13,7 @@ import { bold, dim, gold, green, plural, yellow } from './ui.js';
 // 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';
+const SITE = 'https://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. */

package/dist/init.js

@@ -480,7 +480,7 @@ export async function initFlow(root, options = {}) {
         saveRole(root, role);
     }
     // ── Step 3: sign in and connect this repository ───────────────────────────
-    const BASE_URL = options.baseUrl ?? process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
+    const BASE_URL = options.baseUrl ?? process.env.DOCUGATE_URL ?? 'https://trydocugate.site';
     let connectError;
     // In CI (no TTY) skip sign-in entirely (hint already printed in the early-return branch above).
     if (!io.isTTY) {

package/dist/keys/core.js

@@ -9,7 +9,7 @@ import { looksLikeKey } from './format.js';
  * request. This file is that question and what to do with the answer. The
  * adapters for Express, Hono and Fastify are a few lines on top of it.
  */
-const DEFAULT_BASE_URL = 'https://www.trydocugate.site';
+const DEFAULT_BASE_URL = 'https://trydocugate.site';
 /** DocuGate could not be asked, or refused to answer. Never means a key is bad. */
 export class KeyServiceError extends Error {
     constructor(message, options) {

package/dist/project.d.ts

@@ -25,7 +25,7 @@ export type Finding = {
 };
 /** `owner/name` from the git remote, or the folder's name without one. */
 export declare function detectRepo(root: string): string;
-/** The token for this repository: CI's secret first, then what `connect` saved. */
+/** The token for this codebase: CI's secret first, then what `connect` saved for this folder, then for its repository. */
 export declare function projectToken(root: string, env?: NodeJS.ProcessEnv): string | null;
 /** A suggestion only. The person confirms it, and the dashboard can change it. */
 export declare function detectType(root: string): ProjectType;
@@ -61,12 +61,59 @@ export type AuditArgs = {
 /** `docugate audit`. Returns the exit code. */
 export declare function auditCommand(root: string, args: AuditArgs, env?: NodeJS.ProcessEnv): Promise<number>;
 export type ConnectArgs = {
-    space?: string;
+    /** The project to join: its slug, `owner/slug`, or name. */
+    project?: string;
     frequency?: string;
     type?: string;
     backendDir?: string;
+    /** The section this codebase's docs go under in the project's space. Empty is the top level. */
+    section?: string;
     noAudit: boolean;
     yes: boolean;
 };
-/** `docugate connect`. Returns the exit code. */
+/** A project `connect` can join: a space, with the codebases and docs folders already feeding it. */
+export type ProjectChoice = {
+    id: string;
+    name: string;
+    owner: string;
+    slug: string;
+    org: string | null;
+    sources: {
+        repo: string;
+        docsDir: string;
+        mount: string;
+    }[];
+    codebases: {
+        repo: string;
+        path: string;
+        type: string;
+    }[];
+};
+/**
+ * Which codebase this folder is: its repository, and where in it. A frontend and
+ * a backend side by side in one repository are two codebases, told apart by
+ * their folder. `path` is `''` at the top of the repository.
+ */
+export declare function codebaseOf(root: string, git?: (args: string[], cwd: string) => string): {
+    repo: string;
+    path: string;
+};
+/** Where a codebase's project token is kept: the repository, and the folder when it is not the whole of it. */
+export declare const tokenKey: (repo: string, path: string) => string;
+/**
+ * The section a codebase's docs go under. The first codebase of a project is the
+ * top level; each one after it gets a section named after what it is, so two
+ * pages called "Authentication" cannot clash.
+ */
+export declare function sectionFor(type: ProjectType, sources: {
+    mount: string;
+}[]): string;
+/** The project someone named: by slug, `owner/slug` or name, in any case. */
+export declare function pickProject(choices: ProjectChoice[], wanted: string): ProjectChoice | undefined;
+/**
+ * `docugate connect`, run in each codebase of a project: the backend, then the
+ * frontend, whether they are two repositories or two folders of one. It joins
+ * the codebase to the project, and adds its docs to the project's space so they
+ * are published with the rest. Returns the exit code.
+ */
 export declare function connectCommand(root: string, args: ConnectArgs): Promise<number>;

package/dist/project.js

@@ -1,8 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, join } from 'node:path';
+import { basename, join, relative, resolve, sep } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { apiFetch } from './api.js';
+import { login } from './auth.js';
 import { packageVersion } from './banner.js';
 import { loadConfig } from './config.js';
 import { guessRole } from './init.js';
@@ -17,7 +18,7 @@ import { bold, dim, green, plural, red, yellow } from './ui.js';
 export const PROJECT_TYPES = ['frontend', 'backend', 'serverless', 'monorepo'];
 export const FREQUENCIES = ['push', 'daily', 'weekly', 'off'];
 const TOKENS_FILE = () => join(process.env.DOCUGATE_HOME ?? join(homedir(), '.docugate'), 'projects.json');
-const base = () => process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
+const base = () => process.env.DOCUGATE_URL ?? 'https://trydocugate.site';
 function readTokens() {
     try {
         return JSON.parse(readFileSync(TOKENS_FILE(), 'utf8'));
@@ -38,9 +39,13 @@ export function detectRepo(root) {
     }
     return basename(root);
 }
-/** The token for this repository: CI's secret first, then what `connect` saved. */
+/** The token for this codebase: CI's secret first, then what `connect` saved for this folder, then for its repository. */
 export function projectToken(root, env = process.env) {
-    return env.DOCUGATE_PROJECT_TOKEN || readTokens()[detectRepo(root)] || null;
+    if (env.DOCUGATE_PROJECT_TOKEN)
+        return env.DOCUGATE_PROJECT_TOKEN;
+    const { repo, path } = codebaseOf(root);
+    const tokens = readTokens();
+    return tokens[tokenKey(repo, path)] || tokens[repo] || null;
 }
 /** A suggestion only. The person confirms it, and the dashboard can change it. */
 export function detectType(root) {
@@ -162,11 +167,56 @@ export async function auditCommand(root, args, env = process.env) {
     }
     return 0;
 }
+/**
+ * Which codebase this folder is: its repository, and where in it. A frontend and
+ * a backend side by side in one repository are two codebases, told apart by
+ * their folder. `path` is `''` at the top of the repository.
+ */
+export function codebaseOf(root, git = defaultGit) {
+    const repo = detectRepo(root);
+    try {
+        const top = git(['rev-parse', '--show-toplevel'], root).trim();
+        const path = relative(resolve(top), resolve(root)).split(sep).join('/');
+        return { repo, path: path.startsWith('..') ? '' : path };
+    }
+    catch {
+        return { repo, path: '' };
+    }
+}
+/** Where a codebase's project token is kept: the repository, and the folder when it is not the whole of it. */
+export const tokenKey = (repo, path) => (path ? `${repo}#${path}` : repo);
+/**
+ * The section a codebase's docs go under. The first codebase of a project is the
+ * top level; each one after it gets a section named after what it is, so two
+ * pages called "Authentication" cannot clash.
+ */
+export function sectionFor(type, sources) {
+    if (!sources.length)
+        return '';
+    const wanted = type === 'monorepo' ? 'app' : type;
+    const taken = new Set(sources.map((s) => s.mount));
+    if (!taken.has(wanted))
+        return wanted;
+    for (let n = 2;; n++)
+        if (!taken.has(`${wanted}-${n}`))
+            return `${wanted}-${n}`;
+}
+/** The project someone named: by slug, `owner/slug` or name, in any case. */
+export function pickProject(choices, wanted) {
+    const w = wanted.trim().toLowerCase();
+    return choices.find((p) => `${p.owner}/${p.slug}`.toLowerCase() === w) ?? choices.find((p) => p.slug.toLowerCase() === w) ?? choices.find((p) => p.name.toLowerCase() === w);
+}
 async function choose(question, options, fallback, ask) {
     const answer = (await ask(`  ${question} ${dim(`(${options.join(', ')})`)} [${fallback}] `)).trim().toLowerCase();
     return options.includes(answer) ? answer : fallback;
 }
-/** `docugate connect`. Returns the exit code. */
+const codeOf = (error) => error.code;
+/**
+ * `docugate connect`, run in each codebase of a project: the backend, then the
+ * frontend, whether they are two repositories or two folders of one. It joins
+ * the codebase to the project, and adds its docs to the project's space so they
+ * are published with the rest. Returns the exit code.
+ */
 export async function connectCommand(root, args) {
     if (args.type && !PROJECT_TYPES.includes(args.type)) {
         console.error(`${red('error')} --type must be one of ${PROJECT_TYPES.join(', ')}.`);
@@ -176,36 +226,68 @@ export async function connectCommand(root, args) {
         console.error(`${red('error')} --frequency must be one of ${FREQUENCIES.join(', ')}.`);
         return 2;
     }
-    const repo = detectRepo(root);
+    const { repo, path } = codebaseOf(root);
     const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI && !args.yes;
     const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
     const ask = async (q) => (rl ? rl.question(q) : '');
+    const where = path ? `${repo} ${dim(`(${path}/)`)}` : repo;
     try {
-        const { spaces } = (await (await apiFetch('/api/spaces/mine')).json());
+        // Signed in first: everything after this is done as someone.
+        const { user } = (await (await apiFetch('/api/auth/session')).json().catch(() => ({ user: null })));
+        if (!user) {
+            if (!rl || !/^(|y|yes)$/i.test((await ask(`  Sign in to DocuGate first? ${dim('(Y/n)')} `)).trim())) {
+                console.error(`${red('error')} Not signed in. Run docugate login, then docugate connect again.`);
+                return 1;
+            }
+            rl.pause();
+            await login(base());
+            rl.resume();
+        }
+        const { projects: choices } = (await (await apiFetch('/api/projects/choices')).json());
         console.log();
-        console.log(`  ${bold('Connect')} ${repo}`);
+        console.log(`  ${bold('Connect')} ${where}`);
         console.log(`  ${dim('Shared with DocuGate: this repository’s name, the tool running the CLI, the outcome of each sync, and the names,')}`);
         console.log(`  ${dim('versions and lockfile paths of public packages, to check them for known vulnerabilities. Never your code.')}`);
         console.log();
-        let spaceId = null;
-        if (args.space) {
-            const match = spaces.find((s) => s.slug === args.space);
-            if (!match) {
-                console.error(`${red('error')} You have no space called "${args.space}".`);
+        // The docs this codebase brings, as the repository sees the folder.
+        const config = loadConfig(root);
+        const docsDir = [path, config.docsDir].filter(Boolean).join('/');
+        const hasDocs = existsSync(join(root, config.docsDir));
+        let project;
+        if (args.project) {
+            project = pickProject(choices, args.project);
+            if (!project) {
+                console.error(`${red('error')} No project called "${args.project}" that you can connect to. Run docugate connect without --project to see them.`);
                 return 1;
             }
-            spaceId = match.id;
         }
-        else if (rl && spaces.length) {
-            spaces.forEach((s, i) => console.log(`    ${i + 1}. ${s.name} ${dim(s.slug)}`));
-            const n = Number((await ask(`  Which documentation does this project update? ${dim('(number, or empty for none yet)')} `)).trim());
-            spaceId = spaces[n - 1]?.id ?? null;
+        else if (rl && choices.length) {
+            console.log(`  ${bold('Which project is this codebase part of?')}`);
+            choices.forEach((p, i) => {
+                const parts = p.codebases.map((c) => `${c.type}: ${c.repo}${c.path ? `/${c.path}` : ''}`);
+                console.log(`    ${i + 1}. ${p.name}${p.org ? dim(` (${p.org})`) : ''} ${dim(parts.length ? `· ${parts.join(', ')}` : '· no codebase yet')}`);
+            });
+            console.log(`    ${dim('n. A new project, from this codebase’s docs')}`);
+            const answer = (await ask(`  ${dim('(number, n, or empty for none yet)')} `)).trim().toLowerCase();
+            if (answer === 'n') {
+                if (!hasDocs) {
+                    console.log(`  ${yellow('No docs folder here yet')} (${config.docsDir}/). Run docugate init in this folder to start one, then connect again.`);
+                    return 1;
+                }
+                const name = (await ask(`  What is the project called? [${repo.split('/').at(-1)}] `)).trim() || repo.split('/').at(-1);
+                const res = await apiFetch('/api/spaces', { method: 'POST', body: JSON.stringify({ repo, name, docsDir }) });
+                const { space } = (await res.json());
+                project = { ...space, org: null, sources: [{ repo, docsDir, mount: '' }], codebases: [] };
+                console.log(`  ${green('✓')} Created ${space.name}, published from ${docsDir}/.`);
+            }
+            else {
+                project = choices[Number(answer) - 1];
+            }
         }
-        else if (spaces.length === 1) {
-            spaceId = spaces[0].id;
+        else if (choices.length === 1) {
+            project = choices[0];
         }
-        const guessed = detectType(root);
-        const type = args.type ?? (await choose('What kind of project is this?', PROJECT_TYPES, guessed, ask));
+        const type = args.type ?? (await choose('What is this codebase?', PROJECT_TYPES, detectType(root), ask));
         let backendDir = args.backendDir ?? '';
         if (type === 'monorepo' && !backendDir) {
             const found = detectBackendDir(root);
@@ -214,20 +296,61 @@ export async function connectCommand(root, args) {
         const frequency = args.frequency ?? (await choose('How often should docs be checked?', FREQUENCIES, 'weekly', ask));
         const res = await apiFetch('/api/projects', {
             method: 'POST',
-            body: JSON.stringify({ repo, type, backendDir, frequency, spaceId, audit: !args.noAudit }),
+            body: JSON.stringify({ repo, path, type, backendDir, frequency, spaceId: project?.id ?? null, audit: !args.noAudit }),
         });
         const { token } = (await res.json());
-        const path = TOKENS_FILE();
-        mkdirSync(join(path, '..'), { recursive: true });
-        writeFileSync(path, JSON.stringify({ ...readTokens(), [repo]: token }, null, 2) + '\n', { mode: 0o600 });
+        const file = TOKENS_FILE();
+        mkdirSync(join(file, '..'), { recursive: true });
+        writeFileSync(file, JSON.stringify({ ...readTokens(), [tokenKey(repo, path)]: token }, null, 2) + '\n', { mode: 0o600 });
+        // Its docs join the project's, unless the space already reads that folder.
+        let section = null;
+        const read = project?.sources.some((s) => s.repo.toLowerCase() === repo.toLowerCase() && s.docsDir === docsDir);
+        if (project && hasDocs && !read) {
+            section = args.section ?? sectionFor(type, project.sources);
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    await apiFetch(`/api/spaces/${project.id}/sources`, {
+                        method: 'POST',
+                        body: JSON.stringify({ repo, docsDir, mount: section, label: path ? `${repo.split('/').at(-1)}/${path}` : repo.split('/').at(-1) }),
+                    });
+                    break;
+                }
+                catch (error) {
+                    const code = codeOf(error);
+                    // Two pages at one address: a section of its own settles it.
+                    if (code === 'source_collision' && attempt === 0) {
+                        const fallback = section || (type === 'monorepo' ? 'app' : type);
+                        section = rl ? (await ask(`  Some of its pages share an address with pages already there. Put them under a section? [${fallback}] `)).trim() || fallback : fallback;
+                        continue;
+                    }
+                    section = null;
+                    if (code === 'pro_required_sources')
+                        console.log(`  ${yellow('Its docs were not added.')} One project fed by several codebases needs Pro or an organization plan: ${base()}/pricing`);
+                    else if (code === 'no_repo_access')
+                        console.log(`  ${yellow('Its docs were not added.')} Install the DocuGate GitHub App on ${repo} (${base()}/api/auth/github?install=1), then run docugate connect again.`);
+                    else
+                        console.log(`  ${yellow('Its docs were not added.')} ${error.message}`);
+                    break;
+                }
+            }
+        }
         console.log();
-        console.log(`  ${green('Connected.')} Change any of this in the dashboard, under Projects.`);
+        if (project) {
+            const docs = section === null ? (read ? 'Its docs were already published.' : hasDocs ? '' : `It has no docs folder (${config.docsDir}/) to publish yet.`) : section ? `Its docs appear under ${section}.` : 'Its docs are at the top of the space.';
+            console.log(`  ${green('Connected')} ${where} (${type}) to ${bold(project.name)}. ${docs}`);
+            const others = project.codebases.filter((c) => !(c.repo === repo && c.path === path));
+            if (!others.length)
+                console.log(`  ${dim('Run docugate connect in its other codebases, the frontend or the backend, to add them to the same project.')}`);
+        }
+        else {
+            console.log(`  ${green('Connected')} ${where}. Choose its project in the dashboard, under Projects, or run docugate connect again.`);
+        }
         console.log();
         if (type === 'frontend')
             console.log(`  ${dim('A frontend needs no server package.')}`);
         else {
-            const where = type === 'monorepo' && backendDir ? `in ${backendDir}` : 'in your backend';
-            console.log(`  ${dim(`To check API keys, install the package ${where}:`)} npm i docugate`);
+            const inside = type === 'monorepo' && backendDir ? `in ${backendDir}` : 'in your backend';
+            console.log(`  ${dim(`To check API keys, install the package ${inside}:`)} npm i docugate`);
         }
         console.log();
         console.log(`  For scheduled syncs, add this token as a GitHub secret. It is shown once:`);

package/dist/sync/run.js

@@ -90,7 +90,7 @@ export async function runSync(root, options = {}, deps = {}) {
     writeSyncState(root, { lastSha: changes.to, lastRunAt: (deps.now ?? new Date()).toISOString() });
     if (options.pr) {
         const prFn = deps.prFn ?? defaultPr({ git, env });
-        const siteUrl = env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
+        const siteUrl = env.DOCUGATE_URL ?? 'https://trydocugate.site';
         result.pr = await prFn({
             root,
             title: `docs: sync with code changes (${changes.commits.length} commit${changes.commits.length === 1 ? '' : 's'})`,

package/dist/tour-server.js

@@ -104,7 +104,7 @@ export function publishedDocsUrl(root) {
     const space = loadConfig(root).config.space;
     if (!space || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(space))
         return undefined;
-    return `${process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site'}/${space}`;
+    return `${process.env.DOCUGATE_URL ?? 'https://trydocugate.site'}/${space}`;
 }
 function handleGetEvents(req, res, root) {
     const tourDir = join(root, '.docugate', 'tour');
@@ -379,13 +379,13 @@ export function startTourServer(root, port) {
                 // Somebody opened the tour server itself. Say what it is and where to go.
                 const screens = loadTours(root).length;
                 res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                res.end(`<!doctype html><html lang="en"><head><meta charset="utf-8"><title>DocuGate tour server</title>
-<style>body{margin:0;min-height:100vh;display:grid;place-items:center;background:#0F1014;color:#F5F0E3;font:15px/1.6 system-ui,sans-serif}
-main{max-width:440px;padding:32px;border:1px solid #25273a;border-radius:16px;background:#15173a}
-h1{font-size:20px;margin:0 0 8px}p{margin:0 0 12px;color:#aaa597}b{color:#F4C43F;font-weight:600}
-.dot{display:inline-block;width:8px;height:8px;border-radius:50%;background:#45d483;margin-right:8px}</style></head>
-<body><main><h1><span class="dot"></span>The DocuGate tour server is running</h1>
-<p>This is not a page to open. It feeds the Tour button in your app (${screens} screen${screens === 1 ? '' : 's'} in <b>.docugate/tour/</b>).</p>
+                res.end(`<!doctype html><html lang="en"><head><meta charset="utf-8"><title>DocuGate tour server</title>
+<style>body{margin:0;min-height:100vh;display:grid;place-items:center;background:#0F1014;color:#F5F0E3;font:15px/1.6 system-ui,sans-serif}
+main{max-width:440px;padding:32px;border:1px solid #25273a;border-radius:16px;background:#15173a}
+h1{font-size:20px;margin:0 0 8px}p{margin:0 0 12px;color:#aaa597}b{color:#F4C43F;font-weight:600}
+.dot{display:inline-block;width:8px;height:8px;border-radius:50%;background:#45d483;margin-right:8px}</style></head>
+<body><main><h1><span class="dot"></span>The DocuGate tour server is running</h1>
+<p>This is not a page to open. It feeds the Tour button in your app (${screens} screen${screens === 1 ? '' : 's'} in <b>.docugate/tour/</b>).</p>
 <p>Open <b>your app</b> instead, for example <b>http://localhost:5173</b> or <b>http://localhost:3000</b>. The Tour button is in the bottom-right corner.</p></main></body></html>`);
             }
             else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docugate",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Command-line tools for DocuGate: set up, check and prepare the documentation DocuGate reads straight from your repository. Also checks DocuGate API keys from Express, Hono and Fastify.",
   "type": "module",
   "bin": {