docugate 0.2.8 → 0.2.9

package/dist/cli.js

@@ -13,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);
@@ -287,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': {
@@ -297,28 +301,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);
@@ -337,13 +341,22 @@ 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;
                 }
                 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': {

package/dist/init.js

@@ -188,7 +188,9 @@ async function askForBobKey(io, openUrl) {
         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)');
@@ -549,14 +551,14 @@ 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 =
@@ -623,6 +625,8 @@ export async function initFlow(root, options = {}) {
     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')}`);
@@ -636,7 +640,8 @@ export async function initFlow(root, options = {}) {
     }
     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:`);
+        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 {

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

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