docugate 0.2.6 → 0.2.9

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';
@@ -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;
         }
@@ -288,6 +287,10 @@ async function main() {
                         // already / no-op
                         console.log(`  ${dim('unchanged')}  ${result.target}`);
                     }
+                    if (result.hookAction === 'inserted')
+                        console.log(`  ${green('installed')}  package.json ${dim(`(${result.hook}: the tour server starts with your app)`)}`);
+                    if (result.hookAction === 'removed')
+                        console.log(`  ${green('removed')}    package.json ${dim(`(${result.hook})`)}`);
                     return;
                 }
                 case 'init': {
@@ -344,7 +347,16 @@ ${dim(`Bob: ${parts.join(', ')}`)}`);
                     return;
                 }
                 case 'serve': {
-                    await serveTour(root, parseInt(one('port') ?? '4178', 10));
+                    const port = parseInt(one('port') ?? '4178', 10);
+                    if (args.bools.has('background')) {
+                        // Run from the app's predev script: start (or reuse) the server,
+                        // say so in one line, and hand the terminal back to the app.
+                        mkdirSync(join(root, '.docugate', 'tour'), { recursive: true });
+                        const up = await startServerInBackground(root, port);
+                        console.log(up ? `${green('DocuGate')} tour ready on port ${port}` : `${yellow('DocuGate')} could not start the tour server. Run docugate tour serve to see why.`);
+                        return;
+                    }
+                    await serveTour(root, port);
                     return;
                 }
                 case 'export': {
@@ -369,6 +381,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,13 +182,15 @@ 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;
     }
     useBobKeyForThisRun(key);
-    io.print('  Using the key for this run only. To keep it for next time, set it in your environment:');
+    // Say it arrived, without showing it: the last four characters and the length.
+    io.print(`  ${green('✓')} Key received (…${key.slice(-4)}, ${key.length} characters). Using it for this run only.`);
+    io.print('  To keep it for next time, set it in your environment:');
     io.print(process.platform === 'win32'
         ? '    [Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")   (then open a new terminal)'
         : '    export BOB_API_KEY=<key>   (add it to your shell profile)');
@@ -231,16 +248,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 +312,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 +515,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;
@@ -511,21 +551,24 @@ export async function initFlow(root, options = {}) {
             try {
                 tourResult = tourInit(root, { runBob: options.runBob });
                 stop();
-                io.print(`  IBM Bob wrote the tour.`);
+                io.print(`  ${green('✓')} IBM Bob wrote the tour (${tourResult.added.length} screen${tourResult.added.length === 1 ? '' : 's'}).`);
             }
             catch (error) {
                 stop();
                 // Bob missing or failed — describe what went wrong, then continue.
                 if (error instanceof BobKeyMissingError) {
                     tourError =
-                        `IBM Bob did not accept the key. Check BOB_API_KEY holds an Inference key from bob.ibm.com, then run docugate tour init.`;
+                        `✗ IBM Bob did not accept this key. Check it is 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}`);
             }
@@ -571,7 +614,38 @@ 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']);
+        if (installResult?.hook)
+            rows.push(['Starts with', `npm run ${installResult.hook.replace(/^pre/, '')}`]);
+    }
+    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.')}`);
+        const run = installResult?.hook ? `npm run ${installResult.hook.replace(/^pre/, '')}` : 'npm run dev';
+        io.print(`    Start your project as usual (${gold(run)}) 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-install.js

@@ -24,6 +24,59 @@ export const CANDIDATES = [
     'app/index.html',
     'public/index.html',
 ];
+/** What the app's own start script runs first, so the tour server comes up with it. */
+export const SERVE_HOOK = 'docugate tour serve --background';
+/**
+ * Adds `docugate tour serve --background` as the `predev` script (or
+ * `prestart`, for apps started with npm start), so running the project the
+ * usual way also starts the tour server. npm runs pre-scripts by itself, on
+ * every platform. An existing pre-script keeps running first. Only this
+ * repository's package.json, and only its scripts, are touched.
+ */
+export function installStartHook(root, options = {}) {
+    const path = join(root, 'package.json');
+    if (!existsSync(path))
+        return { action: 'none' };
+    const text = readFileSync(path, 'utf8');
+    let pkg;
+    try {
+        pkg = JSON.parse(text);
+    }
+    catch {
+        return { action: 'none' };
+    }
+    const scripts = pkg.scripts ?? {};
+    const base = scripts.dev ? 'dev' : scripts.start ? 'start' : null;
+    if (!base)
+        return { action: 'none' };
+    const hook = `pre${base}`;
+    const port = options.port ?? DEFAULT_PORT;
+    const command = port === DEFAULT_PORT ? SERVE_HOOK : `${SERVE_HOOK} --port ${port}`;
+    const existing = scripts[hook];
+    if (options.remove) {
+        if (!existing?.includes(SERVE_HOOK))
+            return { hook, action: 'already' };
+        const rest = existing
+            .split('&&')
+            .map((part) => part.trim())
+            .filter((part) => !part.startsWith(SERVE_HOOK))
+            .join(' && ');
+        if (rest)
+            scripts[hook] = rest;
+        else
+            delete scripts[hook];
+    }
+    else {
+        if (existing?.includes(SERVE_HOOK))
+            return { hook, action: 'already' };
+        scripts[hook] = existing ? `${existing} && ${command}` : command;
+    }
+    pkg.scripts = scripts;
+    const indent = text.match(/^[ \t]+(?=")/m)?.[0] ?? '  ';
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    writeFileSync(path, JSON.stringify(pkg, null, indent).replace(/\n/g, eol) + eol);
+    return { hook, action: options.remove ? 'removed' : 'inserted' };
+}
 /** Returns true if any candidate file already contains the pill snippet. */
 export function hasPillSnippet(root) {
     for (const rel of CANDIDATES) {
@@ -100,6 +153,11 @@ function removeSnippet(text, open, close) {
  * already present is a no-op.
  */
 export function tourInstall(root, options = {}) {
+    const result = installSnippet(root, options);
+    const started = installStartHook(root, options);
+    return { ...result, hook: started.hook, hookAction: started.action };
+}
+function installSnippet(root, options) {
     const port = options.port ?? DEFAULT_PORT;
     const remove = options.remove ?? false;
     for (const rel of CANDIDATES) {

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.9",
   "description": "Command-line tools for DocuGate: set up, check and prepare the documentation DocuGate reads straight from your repository.",
   "type": "module",
   "bin": {