docugate 0.2.6 → 0.2.8

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

@@ -53,6 +53,21 @@ 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);
         },
@@ -114,7 +129,7 @@ async function createDocsSpace(io, projectName, baseUrl, options) {
             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`, '');
+            await io.ask(`  On GitHub, add ${repo.repo} (or choose All repositories) and save. Then press Enter here:`, '');
         }
     }
     return undefined;
@@ -167,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;
@@ -231,16 +246,36 @@ 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;
@@ -275,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}.`);
@@ -475,7 +513,7 @@ 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;
@@ -525,7 +563,10 @@ export async function initFlow(root, options = {}) {
                         `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}`);
             }
@@ -571,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/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

@@ -375,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.6",
+  "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": {