docugate 0.4.0 → 0.4.1

package/README.md

@@ -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,9 +403,16 @@ 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://www.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.
 

package/dist/api.js

@@ -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}`;

package/dist/cli.js

@@ -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/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';
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docugate",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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": {