docugate 0.2.5 → 0.2.8

package/README.md

@@ -44,14 +44,15 @@ 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. |
-| Which DocuGate space should document this repository? | **1** creates a new space for it, or pick one of yours. A space already reading this repository is marked. |
+| 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. |
 | 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 it is
-not set, setup opens the page where you create a key and lets you paste it for
+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
+using it. If there is none, setup opens the page where you create a key and lets you paste it for
 that one run; DocuGate never saves it. To set it for good (then open a new terminal):
 
 ```powershell

package/dist/api.js

@@ -7,6 +7,8 @@ const ERROR_MESSAGES = {
     pro_required: 'Private repositories need DocuGate Pro',
     no_repo_access: "DocuGate can't see this repository. Install the DocuGate GitHub App on it first",
     slug_taken: 'You already have a space with this name',
+    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',
 };
 function friendlyError(code) {
@@ -45,7 +47,7 @@ export async function apiFetch(path, init = {}) {
             // ignore JSON parse failure
         }
         if (code)
-            throw new Error(friendlyError(code));
+            throw Object.assign(new Error(friendlyError(code)), { code });
         throw new Error(`DocuGate request failed with status ${res.status}`);
     }
     return res;
@@ -65,6 +67,17 @@ export async function createSpace(repo, name, docsDir) {
     });
     return (await res.json()).space;
 }
+/**
+ * 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 async function createRepo(name, isPrivate, docs) {
+    const res = await apiFetch('/api/repos', {
+        method: 'POST',
+        body: JSON.stringify({ name, private: isPrivate, docs: Boolean(docs), title: docs?.title }),
+    });
+    return (await res.json());
+}
 export async function connectRepo(spaceId, repo, docsDir) {
     await apiFetch(`/api/spaces/${spaceId}/sources`, {
         method: 'POST',

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
+import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { check } from './check.js';
 import { loadConfig } from './config.js';
-import { choose, initFlow, makeDefaultIO } from './init.js';
+import { initFlow } from './init.js';
 import { buildOpenApi, isCurrent, writeOpenApi } from './openapi.js';
 import { BobKeyMissingError, BobMissingError, tourInit } from './tour-init.js';
 import { tourInstall, hasPillSnippet, pillSnippetLine, DEFAULT_PORT } from './tour-install.js';
@@ -12,57 +13,57 @@ import { startTourServer } from './tour-server.js';
 import { login, clearCredentials, loadCredentials } from './auth.js';
 import { BASE_URL, getSession } from './api.js';
 const SITE = 'https://www.trydocugate.site';
-const HELP = `docugate: set up and check the docs DocuGate reads from your repository
-
-Usage
-  docugate <command> [options]
-
-Commands
-  init              Set up this repository for DocuGate (interactive)
-  login             Sign in to DocuGate with GitHub
-  logout            Sign out and delete saved credentials
-  whoami            Print the currently signed-in user
-  check             Check the docs the way DocuGate will read them
-  openapi           Prepare an OpenAPI spec for DocuGate's API reference
-  tour init         Write the first tour of this app with IBM Bob
-  tour install      Add the pill loader to your app
-  tour serve        Start a local server that serves tour data for the pill
-  tour export       Write every tour screen to a single JSON file
-
-init
-  --dir <folder>       Docs folder (default: docs)
-  --title <text>       Space title (default: this folder's name)
-  --role <role>        Repository role: frontend, backend, or both
-  --yes                Accept every default without asking
-
-check
-  --dir <folder>       Check this folder instead of docugate.json's docsDir
-  --strict             Treat warnings as errors
-
-openapi
-  --from <file|url>    The spec to read (or api.generate.from in docugate.json)
-  --out <file>         Where to write it (default: openapi.json)
-  --include <glob>     Keep only paths that match; repeatable
-  --exclude <glob>     Drop paths that match; repeatable
-  --redact <name>      Remove a property from every schema and example; repeatable
-  --check              Fail if the file is out of date, instead of writing it
-
-tour init
-  --max-cost <n>       Most Bobcoins the run may spend (default: 3)
-  --team-id <id>       Bob team to run under, for API keys that need one
-
-tour install
-  --port <n>           Port the pill server listens on (default: 4178)
-  --remove             Remove the pill snippet instead of adding it
-
-tour serve
-  --port <n>           Port to listen on (default: 4178)
-
-tour export <file>
-  Write all tour screens to <file> as JSON.
-
-Run it from the root of your repository.
-${SITE}
+const HELP = `docugate: set up and check the docs DocuGate reads from your repository
+
+Usage
+  docugate <command> [options]
+
+Commands
+  init              Set up this repository for DocuGate (interactive)
+  login             Sign in to DocuGate with GitHub
+  logout            Sign out and delete saved credentials
+  whoami            Print the currently signed-in user
+  check             Check the docs the way DocuGate will read them
+  openapi           Prepare an OpenAPI spec for DocuGate's API reference
+  tour init         Write the first tour of this app with IBM Bob
+  tour install      Add the pill loader to your app
+  tour serve        Start a local server that serves tour data for the pill
+  tour export       Write every tour screen to a single JSON file
+
+init
+  --dir <folder>       Docs folder (default: docs)
+  --title <text>       Space title (default: this folder's name)
+  --role <role>        Repository role: frontend, backend, or both
+  --yes                Accept every default without asking
+
+check
+  --dir <folder>       Check this folder instead of docugate.json's docsDir
+  --strict             Treat warnings as errors
+
+openapi
+  --from <file|url>    The spec to read (or api.generate.from in docugate.json)
+  --out <file>         Where to write it (default: openapi.json)
+  --include <glob>     Keep only paths that match; repeatable
+  --exclude <glob>     Drop paths that match; repeatable
+  --redact <name>      Remove a property from every schema and example; repeatable
+  --check              Fail if the file is out of date, instead of writing it
+
+tour init
+  --max-cost <n>       Most Bobcoins the run may spend (default: 3)
+  --team-id <id>       Bob team to run under, for API keys that need one
+
+tour install
+  --port <n>           Port the pill server listens on (default: 4178)
+  --remove             Remove the pill snippet instead of adding it
+
+tour serve
+  --port <n>           Port to listen on (default: 4178)
+
+tour export <file>
+  Write all tour screens to <file> as JSON.
+
+Run it from the root of your repository.
+${SITE}
 `;
 const color = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
@@ -206,18 +207,16 @@ async function main() {
                 yes: args.bools.has('yes'),
                 port,
             });
-            // The pill only shows while the tour server runs, so setup ends by
-            // offering to start it rather than leaving one more command to remember.
+            // The Tour button only shows while the tour server runs, so setup starts
+            // it in the background instead of asking: the next thing the person
+            // does is open their app, and the button is there.
             const where = result.alreadySetUp ?? root;
             const hasTour = result.role === 'frontend' || result.role === 'both';
-            if (hasTour && process.stdin.isTTY && !args.bools.has('yes')) {
-                const io = makeDefaultIO();
-                const pick = await choose(io, 'Start the tour server now, so the pill shows in your app?', [
-                    'Yes, start it (leave this terminal open, then run your app as usual)',
-                    'Later: docugate tour serve',
-                ]);
-                if (pick === 1)
-                    await serveTour(where, port);
+            if (hasTour && !args.bools.has('no-serve')) {
+                const started = await startServerInBackground(where, port);
+                console.log(dim(started
+                    ? `    The tour server is running in the background (port ${port}). After a restart: docugate tour serve`
+                    : `    Start the tour server with docugate tour serve, then open your app.`));
             }
             return;
         }
@@ -298,28 +297,28 @@ async function main() {
                     }
                     catch (error) {
                         if (error instanceof BobKeyMissingError) {
-                            console.error(`${red('error')} Bob Shell needs an API key to run on its own (your IDE sign-in is not used here).
+                            console.error(`${red('error')} Bob Shell needs an API key to run on its own (your IDE sign-in is not used here).
 ` +
-                                `1. At https://bob.ibm.com, open your instance, then API keys, and create an Inference key.
+                                `1. At https://bob.ibm.com, open your instance, then API keys, and create an Inference key.
 ` +
-                                `2. Save it as the BOB_API_KEY environment variable, then open a new terminal:
+                                `2. Save it as the BOB_API_KEY environment variable, then open a new terminal:
 ` +
-                                `     PowerShell   [Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")
+                                `     PowerShell   [Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")
 ` +
-                                `     macOS/Linux  export BOB_API_KEY=<key>   (add it to your shell profile)
+                                `     macOS/Linux  export BOB_API_KEY=<key>   (add it to your shell profile)
 ` +
                                 dim('Keep the key out of your repository. https://bob.ibm.com/docs/ide/account/api-keys'));
                             process.exit(2);
                         }
                         if (!(error instanceof BobMissingError))
                             throw error;
-                        console.error(`${red('error')} Bob Shell is not installed, and tours are written by IBM Bob.
+                        console.error(`${red('error')} Bob Shell is not installed, and tours are written by IBM Bob.
 ` +
-                            `Install it (Node 24 or later), sign in, then run this again:
+                            `Install it (Node 24 or later), sign in, then run this again:
 ` +
-                            `  Windows      powershell -c "irm -Uri https://bob.ibm.com/download/bobshell.ps1 | iex"
+                            `  Windows      powershell -c "irm -Uri https://bob.ibm.com/download/bobshell.ps1 | iex"
 ` +
-                            `  macOS/Linux  curl -fsSL https://bob.ibm.com/download/bobshell.sh | bash
+                            `  macOS/Linux  curl -fsSL https://bob.ibm.com/download/bobshell.sh | bash
 ` +
                             dim('https://bob.ibm.com/docs/shell/getting-started/install-and-setup'));
                         process.exit(2);
@@ -338,7 +337,7 @@ async function main() {
                         stats?.durationMs !== undefined ? `${Math.round(stats.durationMs / 1000)}s` : '',
                         stats?.cost !== undefined ? `${stats.cost} Bobcoins` : '',
                     ].filter(Boolean);
-                    console.log(`
+                    console.log(`
 ${dim(`Bob: ${parts.join(', ')}`)}`);
                     console.log('Next: read the new files, fix anything Bob got wrong, and commit them. They are yours now.');
                     return;
@@ -369,6 +368,37 @@ main().catch((error) => {
     console.error(`${red('error')} ${error.message}`);
     process.exit(1);
 });
+/**
+ * Starts `docugate tour serve` detached, so it outlives this command. When one
+ * is already answering on the port, that one is kept. True when a server is
+ * answering afterwards.
+ */
+async function startServerInBackground(root, port) {
+    const answering = async () => {
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/pill.js`, { signal: AbortSignal.timeout(800) });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (await answering())
+        return true;
+    const child = spawn(process.execPath, [process.argv[1], 'tour', 'serve', '--port', String(port)], {
+        cwd: root,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.unref();
+    for (let i = 0; i < 20; i++) {
+        await new Promise((r) => setTimeout(r, 150));
+        if (await answering())
+            return true;
+    }
+    return false;
+}
 /**
  * Serves the tour to the pill until Ctrl-C. Starts even when there is no tour
  * yet: the pill then shows on every page, and its inspector writes the first

package/dist/init.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { basename, dirname, join } from 'node:path';
 import { CONFIG_FILE, loadConfig } from './config.js';
 import { tourInit, BobMissingError, BobKeyMissingError, readBobKey, useBobKeyForThisRun } from './tour-init.js';
+import { bobKeyCandidates, startSpinner } from './spinner.js';
 import { tourInstall, pillSnippetLine, DEFAULT_PORT } from './tour-install.js';
 import { login, loadCredentials } from './auth.js';
 /**
@@ -52,11 +53,87 @@ export function makeDefaultIO() {
                 });
             });
         },
+        askSecret(question, defaultAnswer) {
+            // Keys must never be shown on screen, where screenshots and recordings
+            // pick them up: print the question, then echo nothing while typing.
+            return new Promise((resolve) => {
+                const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+                const muted = rl;
+                process.stdout.write(`${question} `);
+                muted._writeToOutput = () => undefined;
+                rl.question('', (answer) => {
+                    rl.close();
+                    process.stdout.write('[hidden]\n');
+                    resolve(answer.trim() || defaultAnswer);
+                });
+            });
+        },
         print(line) {
             console.log(line);
         },
     };
 }
+/**
+ * A new space and the repository that holds its docs: the repository is
+ * created on the person's account with docs/index.md in it, then the space is
+ * made from it. Returns the space, or undefined when something stopped it
+ * (every reason is printed).
+ */
+async function createDocsSpace(io, projectName, baseUrl, options) {
+    const visibility = await choose(io, 'Who can read the docs repository on GitHub?', [
+        'Public',
+        'Private (a space from a private repository needs DocuGate Pro)',
+    ]);
+    const repoName = `${projectName.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-|-$/g, '')}-docs`;
+    const stop = startSpinner(['Creating the docs repository on GitHub', 'Writing its first page', 'Almost there']);
+    let repo;
+    try {
+        repo = await (options.createDocsRepoFn ?? (async (name, priv, title) => {
+            const { createRepo } = await import('./api.js');
+            return createRepo(name, priv, { title });
+        }))(repoName, visibility === 2, projectName);
+        stop();
+        io.print(`  Created ${repo.url}`);
+    }
+    catch (err) {
+        stop();
+        io.print(`  warning  ${err.message}`);
+        return undefined;
+    }
+    const createFn = options.createSpaceFn ?? (async (r, name, dir) => {
+        const { createSpace } = await import('./api.js');
+        return createSpace(r, name, dir);
+    });
+    // A space only ever reads a repository DocuGate can see. One installed on
+    // selected repositories may not include the new one yet: offer the install
+    // and try again once.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const stopSpace = startSpinner(['Setting up your space', 'Reading the docs repository']);
+        try {
+            const space = await createFn(repo.repo, projectName, 'docs');
+            stopSpace();
+            io.print(`  Created space "${space.name}"`);
+            if (repo.seeded === false)
+                io.print(`  Add markdown files to docs/ in ${repo.repo} and they become pages.`);
+            return space;
+        }
+        catch (err) {
+            stopSpace();
+            io.print(`  warning  ${err.message}`);
+            if (err.code !== 'no_repo_access' || attempt > 0)
+                return undefined;
+            const fix = await choose(io, `The DocuGate GitHub App can't see ${repo.repo} yet.`, [
+                'Add it to the app (opens GitHub), then try again',
+                'Skip for now',
+            ]);
+            if (fix !== 1)
+                return undefined;
+            (options.openUrl ?? openInBrowser)(`${baseUrl}/api/auth/github?install=1`);
+            await io.ask(`  On GitHub, add ${repo.repo} (or choose All repositories) and save. Then press Enter here:`, '');
+        }
+    }
+    return undefined;
+}
 /**
  * The nearest folder above `root`, inside the same Git repository, that has
  * DocuGate set up already (a docugate.json), if any.
@@ -105,7 +182,7 @@ async function askForBobKey(io, openUrl) {
     io.print(`  In your Bob instance: API keys, then create an Inference key.`);
     io.print(`  ${BOB_KEYS_URL}`);
     (openUrl ?? openInBrowser)(BOB_KEYS_URL);
-    const key = (await io.ask('  Paste the key and press Enter (used for this run only, never saved)', '')).trim();
+    const key = (await (io.askSecret ?? io.ask)('  Paste the key and press Enter (hidden, used for this run only, never saved):', '')).trim();
     if (!key) {
         io.print('  No key pasted. Skipped the tour: run docugate tour init when you have one.');
         return false;
@@ -169,69 +246,42 @@ export function guessRole(root) {
         return 'backend';
     return undefined;
 }
+// ── Look ───────────────────────────────────────────────────────────────────
+// Color only in a real terminal, and never when NO_COLOR is set, so logs and
+// CI stay plain text.
+const colorOn = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const paint = (code) => (text) => (colorOn() ? `\x1b[${code}m${text}\x1b[0m` : text);
+const bold = paint('1');
+const dimmed = paint('2');
+const gold = paint('38;2;244;196;63');
+const cream = paint('38;2;245;240;227');
+const green = paint('32');
+/** DocuGate's owl, drawn small: cream eyes, gold beak. */
+export function banner() {
+    return [
+        '',
+        `   ${dimmed('╭─────╮')}`,
+        `   ${dimmed('│')} ${cream('◉ ◉')} ${dimmed('│')}   ${bold('DocuGate')}`,
+        `   ${dimmed('│')}  ${gold('▾')}  ${dimmed('│')}   ${dimmed('Tours and docs for your codebase')}`,
+        `   ${dimmed('╰─────╯')}`,
+    ];
+}
 /**
  * A numbered choice: prints the options, and takes only a number. Enter picks
  * the default. Nobody types a word during setup.
  */
 export async function choose(io, question, options, fallback = 1) {
     io.print('');
-    io.print(`  ${question}`);
-    options.forEach((option, i) => io.print(`    ${i + 1}  ${option}`));
+    io.print(`  ${bold(question)}`);
+    options.forEach((option, i) => io.print(`    ${gold(String(i + 1))}  ${option}`));
     for (;;) {
-        const answer = (await io.ask(`  Choose 1-${options.length} [${fallback}]`, String(fallback))).trim();
+        const answer = (await io.ask(`  ${dimmed(`Choose 1-${options.length} [${fallback}]`)}:`, String(fallback))).trim();
         const n = Number(answer);
         if (Number.isInteger(n) && n >= 1 && n <= options.length)
             return n;
         io.print(`  Type a number from 1 to ${options.length}.`);
     }
 }
-function run(cmd, args, cwd) {
-    try {
-        const out = execFileSync(cmd, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32' });
-        return { ok: true, out: out.trim() };
-    }
-    catch (err) {
-        const e = err;
-        return { ok: false, out: (e.stderr ?? e.message).trim() };
-    }
-}
-/**
- * A space reads from a GitHub repository. When the project has none yet, offer
- * to create one with the GitHub CLI, which is already signed in as the person,
- * and push the code to it. Returns owner/name, or null when skipped or failed.
- * DocuGate's own GitHub sign-in is not given the right to create repositories.
- */
-async function createGitHubRepo(root, io) {
-    const pick = await choose(io, 'This project is not on GitHub yet, and a space reads from a GitHub repository.', [
-        'Create a GitHub repository for it now (uses the GitHub CLI)',
-        'Skip for now',
-    ]);
-    if (pick !== 1)
-        return null;
-    if (!run('gh', ['auth', 'status'], root).ok) {
-        io.print('  The GitHub CLI is not installed or not signed in.');
-        io.print('  Install it from https://cli.github.com, run gh auth login, then docugate init again.');
-        return null;
-    }
-    if (!run('git', ['rev-parse', 'HEAD'], root).ok) {
-        io.print('  Commit your code first (git add -A, then git commit), then run docugate init again.');
-        return null;
-    }
-    const visibility = await choose(io, 'Who can see the repository?', [
-        'Public',
-        'Private (a space from a private repository needs DocuGate Pro)',
-    ]);
-    const name = basename(root).replace(/[^A-Za-z0-9._-]+/g, '-');
-    const made = run('gh', ['repo', 'create', name, visibility === 1 ? '--public' : '--private', '--source', '.', '--remote', 'origin', '--push'], root);
-    if (!made.ok) {
-        io.print(`  Could not create the repository: ${made.out.split(/\r?\n/).pop()}`);
-        return null;
-    }
-    const slug = defaultGetRemote(root);
-    if (slug)
-        io.print(`  Created https://github.com/${slug} and pushed your code.`);
-    return slug;
-}
 function defaultGetRemote(root) {
     try {
         const remote = execFileSync('git', ['remote', 'get-url', 'origin'], {
@@ -260,6 +310,9 @@ export async function initFlow(root, options = {}) {
     // One project gets one setup and one tour. Run inside frontend/ of a
     // project already set up at its root, and init points there instead of
     // starting a second one.
+    if (io.isTTY)
+        for (const line of banner())
+            io.print(line);
     const parent = setUpAbove(root);
     if (parent) {
         io.print(`  This project is already set up in ${parent}.`);
@@ -366,93 +419,76 @@ export async function initFlow(root, options = {}) {
                 }
             }
         }
-        // ── 3b: connect this repository to a space ────────────────────────────────
+        // ── 3b: the space that holds this project's documentation ─────────────────
+        // A space reads markdown from a GitHub repository. A new space gets its own
+        // documentation repository, created on the person's account; an existing
+        // space can be picked instead. Either way docugate.json remembers it, so the
+        // pill can link to the published docs.
         if (signedIn) {
-            // Read git remote; a project not on GitHub yet can be put there first.
-            let repoSlug = getRemoteFn(root);
-            if (!repoSlug && !yes) {
-                repoSlug = await (options.createRepoFn ?? createGitHubRepo)(root, io);
+            const repoSlug = getRemoteFn(root);
+            let spaces = [];
+            try {
+                spaces = (await getSpacesFn()).spaces;
             }
-            if (!repoSlug) {
-                io.print(`  A space reads from a GitHub repository, so this one can't be connected yet.`);
+            catch (err) {
+                connectError = `Couldn't load spaces: ${err.message}`;
+                io.print(`  warning  ${connectError}`);
             }
-            else {
-                // List spaces.
-                let spaces = [];
+            const { docsDir: repoDocsDir, config } = loadConfig(root);
+            const projectName = config.title ?? repoSlug?.split('/')[1] ?? basename(root);
+            const hasRepo = (sp) => Boolean(repoSlug) && (sp.sources ?? []).some((src) => src.repo.toLowerCase() === repoSlug.toLowerCase());
+            const already = spaces.find(hasRepo);
+            const linkSpace = (sp) => {
+                saveSetting(root, 'space', `${sp.owner}/${sp.slug}`);
+                io.print(`  Docs will be published at ${BASE_URL}/${sp.owner}/${sp.slug}`);
+            };
+            const connectProject = async (sp) => {
+                if (!repoSlug || hasRepo(sp))
+                    return;
                 try {
-                    const res = await getSpacesFn();
-                    spaces = res.spaces;
+                    await connectFn(sp.id, repoSlug, repoDocsDir);
+                    io.print(`  Connected ${repoSlug} to space "${sp.name}".`);
                 }
                 catch (err) {
-                    connectError = `Couldn't load spaces: ${err.message}`;
+                    connectError = err.message;
                     io.print(`  warning  ${connectError}`);
                 }
-                const { docsDir: repoDocsDir } = loadConfig(root);
-                const hasRepo = (sp) => (sp.sources ?? []).some((src) => src.repo.toLowerCase() === repoSlug.toLowerCase());
-                const already = spaces.find(hasRepo);
-                if (connectError) {
-                    // the warning is printed already; carry on with the rest of setup
+            };
+            if (connectError) {
+                // the warning is printed already; carry on with the rest of setup
+            }
+            else if (yes) {
+                // --yes: use the space only when there is no doubt which one is meant.
+                const only = already ?? (spaces.length === 1 ? spaces[0] : undefined);
+                if (only) {
+                    await connectProject(only);
+                    linkSpace(only);
                 }
-                else if (yes) {
-                    // --yes: connect only when there is no doubt which space is meant.
-                    if (already) {
-                        io.print(`  ${repoSlug} is already in space "${already.name}".`);
-                    }
-                    else if (spaces.length === 1) {
-                        try {
-                            await connectFn(spaces[0].id, repoSlug, repoDocsDir);
-                            io.print(`  Connected ${repoSlug} to space "${spaces[0].name}".`);
-                        }
-                        catch (err) {
-                            connectError = err.message;
-                            io.print(`  warning  ${connectError}`);
-                        }
-                    }
-                    else if (spaces.length > 1) {
-                        io.print(`  Several spaces found: run docugate init again without --yes to choose.`);
-                    }
+                else if (spaces.length > 1) {
+                    io.print(`  Several spaces found: run docugate init again without --yes to choose.`);
+                }
+            }
+            else {
+                const choices = [
+                    'Create a new space, with a new repository for its docs',
+                    ...spaces.map((sp) => `${sp.name}  (${sp.owner}/${sp.slug})${hasRepo(sp) ? '  already has this project' : ''}`),
+                    'Skip for now',
+                ];
+                const pick = await choose(io, `Where should the documentation for ${projectName} live?`, choices, already ? spaces.indexOf(already) + 2 : 1);
+                if (pick === 1) {
+                    const created = await createDocsSpace(io, projectName, BASE_URL, options);
+                    if (created)
+                        linkSpace(created);
+                    else
+                        connectError = 'The space was not created.';
+                }
+                else if (pick <= spaces.length + 1) {
+                    const sp = spaces[pick - 2];
+                    await connectProject(sp);
+                    linkSpace(sp);
                 }
                 else {
-                    // Interactive: create a space, or pick one, or skip. Numbers only.
-                    const choices = [
-                        `Create a new space for ${repoSlug}`,
-                        ...spaces.map((sp) => `${sp.name}  (${sp.owner}/${sp.slug})${hasRepo(sp) ? '  already reads this repository' : ''}`),
-                        'Skip for now',
-                    ];
-                    const pick = await choose(io, `Which DocuGate space should document ${repoSlug}?`, choices, already ? spaces.indexOf(already) + 2 : 1);
-                    if (pick === 1) {
-                        try {
-                            const createFn = options.createSpaceFn ?? (async (repo, name, dir) => {
-                                const { createSpace } = await import('./api.js');
-                                return createSpace(repo, name, dir);
-                            });
-                            const created = await createFn(repoSlug, loadConfig(root).config.title ?? repoSlug.split('/')[1], repoDocsDir);
-                            io.print(`  Created space "${created.name}": ${BASE_URL}/${created.owner}/${created.slug}`);
-                        }
-                        catch (err) {
-                            connectError = err.message;
-                            io.print(`  warning  ${connectError}`);
-                        }
-                    }
-                    else if (pick <= spaces.length + 1) {
-                        const sp = spaces[pick - 2];
-                        if (hasRepo(sp)) {
-                            io.print(`  ${repoSlug} is already in space "${sp.name}". Nothing to change.`);
-                        }
-                        else {
-                            try {
-                                await connectFn(sp.id, repoSlug, repoDocsDir);
-                                io.print(`  Connected ${repoSlug} to space "${sp.name}".`);
-                            }
-                            catch (err) {
-                                connectError = err.message;
-                                io.print(`  warning  ${connectError}`);
-                            }
-                        }
-                    }
-                    else {
-                        io.print(`  Skipped. docugate init connects it any time.`);
-                    }
+                    io.print(`  Skipped. docugate init sets it up any time.`);
                 }
             }
         }
@@ -477,29 +513,60 @@ export async function initFlow(root, options = {}) {
                 'IBM Bob (uses Bobcoins)',
                 'IBM watsonx (coming soon)',
                 'Skip, I will write it in the browser',
-            ], 3);
+            ]);
             if (pick === 2)
                 io.print('  IBM watsonx is coming soon. Skipped for now: run docugate tour init when you are ready.');
             runTour = pick === 1;
-            if (runTour && !readBobKey() && !options.runBob)
-                runTour = await askForBobKey(io, options.openUrl);
+            if (runTour && !readBobKey() && !options.runBob) {
+                // The key may be in the environment under another name.
+                const [other] = bobKeyCandidates();
+                if (other) {
+                    const use = await choose(io, `BOB_API_KEY is not set, but ${other} is. Is that your IBM Bob key?`, [
+                        `Yes, use ${other} for this run`,
+                        'No',
+                    ]);
+                    if (use === 1) {
+                        useBobKeyForThisRun(process.env[other]);
+                        io.print(`  Tip: rename it to BOB_API_KEY in your environment so Bob finds it next time.`);
+                    }
+                }
+                if (!readBobKey())
+                    runTour = await askForBobKey(io, options.openUrl);
+            }
         }
         if (runTour) {
+            // Bob takes a minute or two. Show it working, the way an assistant does.
+            const stop = options.runBob
+                ? () => undefined
+                : startSpinner([
+                    'IBM Bob is reading your screens and routes',
+                    'Following each value to the endpoint it comes from',
+                    'Tracing it into the backend',
+                    'Writing the tour, one step per element',
+                    'Checking every file it names exists',
+                    'Still working: bigger apps take a little longer',
+                ]);
             try {
                 tourResult = tourInit(root, { runBob: options.runBob });
+                stop();
+                io.print(`  IBM Bob wrote the tour.`);
             }
             catch (error) {
+                stop();
                 // Bob missing or failed — describe what went wrong, then continue.
                 if (error instanceof BobKeyMissingError) {
                     tourError =
-                        `Bob Shell needs an API key. Set BOB_API_KEY, then run docugate tour init.`;
+                        `IBM Bob did not accept the key. Check BOB_API_KEY holds an Inference key from bob.ibm.com, then run docugate tour init.`;
                 }
                 else if (error instanceof BobMissingError) {
                     tourError =
                         `Bob Shell is not installed. Install it, sign in, then run docugate tour init.`;
                 }
                 else {
-                    tourError = `Tour init failed: ${error.message}. Run docugate tour init to retry.`;
+                    // One calm line; the technical detail only when asked for.
+                    tourError = `IBM Bob couldn't write the tour this time. The pill still works: add steps in the browser, or run docugate tour init later.`;
+                    if (process.env.DOCUGATE_DEBUG)
+                        io.print(`  detail  ${error.message}`);
                 }
                 io.print(`  warning  ${tourError}`);
             }
@@ -545,7 +612,35 @@ export async function initFlow(root, options = {}) {
         io.print(`  installed pill in ${installResult.target}`);
     if (installResult?.action === 'already')
         io.print(`  pill already in ${installResult.target}`);
+    const hasPill = installResult?.action === 'inserted' || installResult?.action === 'already';
+    const final = loadConfig(root).config;
+    const freshness = FRESHNESS.find((f) => f.value === final.freshness);
+    const rows = [
+        ['Repository', role ? role.charAt(0).toUpperCase() + role.slice(1) : 'not set'],
+        ['Docs', final.space ?? 'no space yet'],
+        ['Checks', freshness ? freshness.label.split(' (')[0] : 'not set'],
+    ];
+    if (role !== 'backend') {
+        rows.push(['Tour', tourResult ? `IBM Bob wrote ${tourResult.added.length} screen${tourResult.added.length === 1 ? '' : 's'}` : 'add steps in the browser']);
+        rows.push(['Tour button', hasPill && installResult?.target ? installResult.target : 'not added']);
+    }
+    io.print(``);
+    io.print(`  ${dimmed('╭')} ${bold('DocuGate setup')}`);
+    rows.forEach(([label, value], i) => {
+        const branch = i === rows.length - 1 ? '╰' : '├';
+        io.print(`  ${dimmed(branch)} ${label.padEnd(12)} ${green(value)}`);
+    });
     io.print(``);
-    io.print(`Next: docugate tour serve`);
+    if (role === 'backend') {
+        io.print(`  ${green('✓')} ${bold('DocuGate is set up for this backend.')}`);
+    }
+    else if (hasPill) {
+        io.print(`  ${green('✓')} ${bold('DocuGate is set up.')}`);
+        io.print(`    Start your project as usual (for example ${gold('npm run dev')}) and open it:`);
+        io.print(`    the ${gold('Tour')} button is in the bottom-right corner.`);
+    }
+    else {
+        io.print(`  ${green('✓')} ${bold('DocuGate is set up.')} Run docugate tour install to add the Tour button to your app.`);
+    }
     return { ...base, role, tourResult, tourError, installResult, connectError };
 }

package/dist/rules.js

@@ -58,4 +58,4 @@ export function firstHeading(content) {
     const heading = content.match(/^#\s+(.+)$/m);
     return heading ? heading[1].trim() : null;
 }
-export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'sidebar', 'api']);
+export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'space', 'sidebar', 'api']);

package/dist/spinner.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+/**
+ * A live "working on it" line for the waits in setup: a spinner, the elapsed
+ * time, and a status that changes every few seconds, so a minute of IBM Bob
+ * reading the code never looks like a frozen terminal.
+ *
+ * It runs in a small child process, so it keeps moving even while the main
+ * process is blocked waiting on Bob Shell. Only in a terminal; elsewhere it
+ * prints the first status once.
+ */
+export function startSpinner(statuses) {
+    if (!process.stderr.isTTY || process.env.CI) {
+        process.stderr.write(`  ${statuses[0]}...\n`);
+        return (finalLine) => {
+            if (finalLine)
+                process.stderr.write(`${finalLine}\n`);
+        };
+    }
+    const script = `
+    const statuses = JSON.parse(process.argv[1]);
+    const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
+    const start = Date.now();
+    let i = 0;
+    const cols = () => process.stderr.columns || 80;
+    setInterval(() => {
+      const secs = Math.floor((Date.now() - start) / 1000);
+      const status = statuses[Math.min(Math.floor(secs / 6), statuses.length - 1)];
+      const line = '  ' + frames[i++ % frames.length] + ' ' + status + '... ' + secs + 's';
+      process.stderr.write('\\r' + line.slice(0, cols() - 1).padEnd(cols() - 1));
+    }, 90);
+  `;
+    const child = spawn(process.execPath, ['-e', script, JSON.stringify(statuses)], {
+        stdio: ['ignore', 'ignore', 'inherit'],
+    });
+    return (finalLine) => {
+        child.kill();
+        const width = process.stderr.columns || 80;
+        process.stderr.write(`\r${' '.repeat(width - 1)}\r`);
+        if (finalLine)
+            process.stderr.write(`${finalLine}\n`);
+    };
+}
+/** Environment variables that look like an IBM Bob key under another name. */
+export function bobKeyCandidates(env = process.env) {
+    return Object.keys(env)
+        .filter((name) => name !== 'BOB_API_KEY' && env[name])
+        .filter((name) => /BOB|IBM|WATSONX/i.test(name) && /KEY|TOKEN|SECRET/i.test(name))
+        .sort();
+}

package/dist/tour-init.js

@@ -1,7 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { isMap, isSeq, parseDocument } from 'yaml';
 // `docugate tour init` writes the first tour of an app by asking IBM Bob
 // (through Bob Shell) to read the code. Bob does the reading; this file makes
@@ -86,14 +86,37 @@ export function readBobKey() {
 export function useBobKeyForThisRun(key) {
     process.env.BOB_API_KEY = key;
 }
+/**
+ * On Windows, `bob` is an npm .cmd shim, and a .cmd only runs through cmd.exe,
+ * which splits a path at its spaces ("C:\Users\GUSENGA Thierry") and cannot
+ * carry the prompt's line breaks. The shim only starts Node on Bob Shell's
+ * script, so run that script with Node directly: no shell, nothing mangled.
+ */
+export function bobScript(pathEnv = process.env.PATH ?? '') {
+    for (const dir of pathEnv.split(';').filter(Boolean)) {
+        const shim = join(dir, 'bob.cmd');
+        if (!existsSync(shim))
+            continue;
+        const match = readFileSync(shim, 'utf8').match(/"%dp0%\\([^"]+\.js)"/);
+        if (!match)
+            continue;
+        const script = join(dir, match[1]);
+        if (existsSync(script))
+            return script;
+    }
+    return undefined;
+}
 const defaultRunBob = (args, cwd) => {
-    const result = spawnSync('bob', args, {
-        cwd,
-        encoding: 'utf8',
-        // `bob` is a .cmd shim on Windows, which only runs through a shell.
-        shell: process.platform === 'win32',
-        maxBuffer: 64 * 1024 * 1024,
-    });
+    const script = process.platform === 'win32' ? bobScript() : undefined;
+    const result = script
+        ? spawnSync(process.execPath, [script, ...args], { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+        : spawnSync('bob', args, {
+            cwd,
+            encoding: 'utf8',
+            // No shim script found on Windows: fall back to the shell.
+            shell: process.platform === 'win32',
+            maxBuffer: 64 * 1024 * 1024,
+        });
     if (result.error && result.error.code === 'ENOENT') {
         throw new BobMissingError('Bob Shell is not installed.');
     }

package/dist/tour-server.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, watch,
 import { join, relative, resolve, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadTours, matchRoute, parseTourFile, routeToFilename, serializeTourFile } from './tour.js';
+import { loadConfig } from './config.js';
 // ---------------------------------------------------------------------------
 // Security helpers
 // ---------------------------------------------------------------------------
@@ -91,11 +92,19 @@ function handleGetTour(req, res, root) {
     const pathname = url.searchParams.get('path') ?? '/';
     const tours = loadTours(root);
     const match = tours.find((t) => matchRoute(t.route, pathname));
+    const docsUrl = publishedDocsUrl(root);
     if (!match) {
-        sendJson(res, 404, { error: 'not found' });
+        sendJson(res, 404, { error: 'not found', docsUrl });
         return;
     }
-    sendJson(res, 200, { route: match.route, title: match.title, file: match.file, stops: match.stops });
+    sendJson(res, 200, { route: match.route, title: match.title, file: match.file, docsUrl, stops: match.stops });
+}
+/** Where this project's docs are published, from the space docugate init saved. */
+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}`;
 }
 function handleGetEvents(req, res, root) {
     const tourDir = join(root, '.docugate', 'tour');
@@ -366,6 +375,19 @@ export function startTourServer(root, port) {
             else if (req.method === 'GET' && path === '/pill.js') {
                 handleGetPill(res);
             }
+            else if (req.method === 'GET' && path === '/') {
+                // 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>
+<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 {
                 sendText(res, 404, 'Not found');
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docugate",
-  "version": "0.2.5",
+  "version": "0.2.8",
   "description": "Command-line tools for DocuGate: set up, check and prepare the documentation DocuGate reads straight from your repository.",
   "type": "module",
   "bin": {

package/pill/dist/pill.js

@@ -104,11 +104,14 @@ async function fetchTour(base) {
     }
     try {
         const res = await fetch(`${base}/tour?path=${encodeURIComponent(pathname)}`, { signal: AbortSignal.timeout(3000) });
-        if (res.status === 404)
-            return { alive: true, tour: null };
+        if (res.status === 404) {
+            const body = (await res.json().catch(() => ({})));
+            return { alive: true, tour: null, docsUrl: body.docsUrl };
+        }
         if (!res.ok)
             return { alive: false, tour: null };
-        return { alive: true, tour: (await res.json()) };
+        const tour = (await res.json());
+        return { alive: true, tour, docsUrl: tour.docsUrl };
     }
     catch {
         return { alive: false, tour: null };
@@ -247,6 +250,8 @@ kbd {
   font-size: 12px;
   color: #8f8f8f;
 }
+.docs-link { margin-left: auto; color: #F4C43F; text-decoration: none; }
+.docs-link:hover { color: #ffd35c; background: rgba(244, 196, 63, 0.1); }
 .menu-foot .live { display: inline-flex; align-items: center; gap: 6px; }
 .menu-foot .live::before { content: ""; width: 6px; height: 6px; border-radius: 50%; background: #45d483; box-shadow: 0 0 0 3px rgba(69, 212, 131, 0.15); }
 .link-btn { border: 0; background: none; color: #a1a1a1; font: inherit; cursor: pointer; padding: 2px 4px; border-radius: 5px; }
@@ -601,6 +606,8 @@ class DocugatePill {
         this.listCollapsed = false;
         /** Hidden for this page view only: a reload, or Alt+Shift+D, brings it back. */
         this.hidden = false;
+        /** The project's published docs on DocuGate, when init linked a space. */
+        this.docsUrl = null;
         this.retarget = null;
         /** When a re-attached step is saved, the target it had before. */
         this.editingFrom = null;
@@ -640,9 +647,10 @@ class DocugatePill {
         this.render();
     }
     async load() {
-        const { alive, tour } = await fetchTour(this.base);
+        const { alive, tour, docsUrl } = await fetchTour(this.base);
         this.alive = alive;
         this.tour = tour;
+        this.docsUrl = docsUrl ?? null;
     }
     render() {
         this.removePill();
@@ -921,7 +929,17 @@ class DocugatePill {
         hide.textContent = 'Hide';
         hide.title = 'Hide the pill. Reload the page or press Alt+Shift+D to bring it back.';
         hide.addEventListener('click', () => this.setHidden(true));
-        foot.append(status, hide);
+        foot.append(status);
+        if (this.docsUrl && /^https:\/\//.test(this.docsUrl)) {
+            const docs = document.createElement('a');
+            docs.className = 'link-btn docs-link';
+            docs.href = this.docsUrl;
+            docs.target = '_blank';
+            docs.rel = 'noopener noreferrer';
+            docs.textContent = 'Open the docs ↗';
+            foot.append(docs);
+        }
+        foot.append(hide);
         return foot;
     }
     /** Steps seen on this screen in this tab, by target, so the checklist shows progress. */