docugate 0.2.8 → 0.3.0

package/dist/banner.d.ts

@@ -0,0 +1,13 @@
+export declare const TAGLINE = "Tours and docs for your codebase";
+/** The wordmark as five plain lines, no color. */
+export declare function wordmark(text?: string, gap?: number): string[];
+export declare function packageVersion(): string;
+export type BannerOptions = {
+    /** Terminal width; unknown is treated as narrow. */
+    columns?: number;
+    color?: boolean;
+    version?: string;
+    env?: NodeJS.ProcessEnv;
+};
+/** The banner as lines to print, with a blank line above and below. */
+export declare function banner(options?: BannerOptions): string[];

package/dist/banner.js

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs';
+import { colorDepth, fg, logoBanner } from './logo.js';
+import { colorOn, isMintty } from './ui.js';
+// The banner: DOCUGATE in block letters, shaded from cream to gold like the
+// owl, with the tagline and version under it. It adapts to where it is drawn:
+// beside the owl in a wide terminal, alone in a normal one, as a single line
+// in a narrow one, and without color when color is off. It is only ever
+// printed to a real terminal, so logs and CI never see it.
+export const TAGLINE = 'Tours and docs for your codebase';
+const SITE = 'https://www.trydocugate.site';
+// A five-row block font, just the letters in the name. Every glyph is five
+// columns wide, so the wordmark's width is simply letters * 5 + gaps.
+const GLYPHS = {
+    D: ['████ ', '█   █', '█   █', '█   █', '████ '],
+    O: [' ███ ', '█   █', '█   █', '█   █', ' ███ '],
+    C: [' ████', '█    ', '█    ', '█    ', ' ████'],
+    U: ['█   █', '█   █', '█   █', '█   █', ' ███ '],
+    G: [' ████', '█    ', '█  ██', '█   █', ' ████'],
+    A: [' ███ ', '█   █', '█████', '█   █', '█   █'],
+    T: ['█████', '  █  ', '  █  ', '  █  ', '  █  '],
+    E: ['█████', '█    ', '████ ', '█    ', '█████'],
+};
+// Cream at the top, through gold, to deep gold at the bottom.
+const SHADES = [
+    [245, 240, 227],
+    [246, 222, 150],
+    [244, 196, 63],
+    [230, 175, 46],
+    [217, 154, 30],
+];
+/** Narrower than this and the wordmark would wrap, so one line is shown. */
+const WORDMARK_MIN_COLUMNS = 60;
+/** Wide enough for the owl beside the wordmark. */
+const OWL_MIN_COLUMNS = 96;
+/** The wordmark as five plain lines, no color. */
+export function wordmark(text = 'DOCUGATE', gap = 2) {
+    const letters = [...text.toUpperCase()].map((c) => GLYPHS[c]);
+    if (letters.some((g) => !g))
+        throw new Error(`The banner font has no glyph for every letter of "${text}".`);
+    return [0, 1, 2, 3, 4].map((row) => letters.map((g) => g[row]).join(' '.repeat(gap)).trimEnd());
+}
+export function packageVersion() {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+}
+/** The banner as lines to print, with a blank line above and below. */
+export function banner(options = {}) {
+    const { 
+    // mintty reports no width to a piped console; COLUMNS, or a usual window, stands in.
+    columns = process.stdout.columns ?? (Number(process.env.COLUMNS) || (isMintty() ? 100 : 0)), color = colorOn(), version = packageVersion(), env = process.env, } = options;
+    const dim = (t) => (color ? `\x1b[2m${t}\x1b[0m` : t);
+    if (columns < WORDMARK_MIN_COLUMNS) {
+        const full = `  DocuGate · ${TAGLINE} · v${version}`;
+        return ['', full.length <= columns ? full : `  DocuGate v${version}`, ''];
+    }
+    const depth = colorDepth(env);
+    const art = wordmark().map((line, row) => (color ? `${fg(SHADES[row], depth)}${line}\x1b[0m` : line));
+    const text = [...art, '', dim(TAGLINE), dim(`v${version} · ${SITE}`)];
+    if (color && columns >= OWL_MIN_COLUMNS)
+        return logoBanner(text, env);
+    return ['', ...text.map((t) => (t ? `  ${t}` : '')), ''];
+}

package/dist/check.d.ts

@@ -0,0 +1,22 @@
+import type { Issue } from './config.js';
+export type CheckResult = {
+    docsDir: string;
+    pages: number;
+    errors: Issue[];
+    warnings: Issue[];
+};
+/** Every file under `dir`, as forward-slash paths relative to it. */
+export declare function walk(dir: string): string[];
+/**
+ * Checks a repository's docs the way DocuGate will read them, so problems turn
+ * up on the command line or in CI rather than on the published page.
+ *
+ * Errors are things DocuGate will get wrong or refuse. Warnings are things it
+ * handles, but probably not the way the author meant.
+ */
+export declare function check(root: string, dirOverride?: string): CheckResult;
+/**
+ * Run tour checks against every tour file found under `.docugate/tour/`.
+ * Issues are warnings: the docs still publish; the tour may just be wrong.
+ */
+export declare function checkTours(root: string): Issue[];

package/dist/check.js

@@ -2,11 +2,12 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { loadConfig } from './config.js';
 import { MAX_FILES, firstHeading, landingPath, pathToSlug, resolveRelativeLink } from './rules.js';
+import { readText } from './text.js';
 import { loadTours } from './tour.js';
 /** Never part of a repository on GitHub, and huge when present locally. */
 const SKIP = new Set(['node_modules', '.git']);
 /** Every file under `dir`, as forward-slash paths relative to it. */
-function walk(dir) {
+export function walk(dir) {
     const out = [];
     const visit = (current) => {
         for (const entry of readdirSync(current, { withFileTypes: true })) {
@@ -95,7 +96,7 @@ export function check(root, dirOverride) {
     if (landing)
         slugs.add('');
     for (const page of pages) {
-        const content = readFileSync(join(base, page), 'utf8').replace(/\r\n/g, '\n');
+        const content = readText(join(base, page)).replace(/\r\n/g, '\n');
         if (content.startsWith('---\n')) {
             warnings.push({
                 file: shown(page),
@@ -183,7 +184,7 @@ function importsIn(text) {
  * Run tour checks against every tour file found under `.docugate/tour/`.
  * Issues are warnings: the docs still publish; the tour may just be wrong.
  */
-function checkTours(root) {
+export function checkTours(root) {
     const warnings = [];
     let tours;
     try {

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -1,143 +1,170 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs, UsageError } from './args.js';
+import { banner, packageVersion } from './banner.js';
 import { check } from './check.js';
+import { COMMANDS, findCommand, renderCommandHelp, renderCompletion, renderGroupHelp, renderHelp } from './commands.js';
 import { loadConfig } from './config.js';
-import { initFlow } from './init.js';
+import { developersFlow } from './developers.js';
+import { initFlow, makeDefaultIO } from './init.js';
+import { runMenu } from './menu.js';
 import { buildOpenApi, isCurrent, writeOpenApi } from './openapi.js';
+import { canPick } from './select.js';
+import { gatherStatus, renderStatus } from './status.js';
+import { syncCommand } from './sync/command.js';
 import { BobKeyMissingError, BobMissingError, tourInit } from './tour-init.js';
 import { tourInstall, hasPillSnippet, pillSnippetLine, DEFAULT_PORT } from './tour-install.js';
 import { loadTours } from './tour.js';
 import { startTourServer } from './tour-server.js';
 import { login, clearCredentials, loadCredentials } from './auth.js';
 import { BASE_URL, getSession } from './api.js';
+import { dim, gold, green, hint, isMintty, plural, red, suggest, yellow } from './ui.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 color = process.stdout.isTTY && !process.env.NO_COLOR;
-const paint = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
-const red = (t) => paint(31, t);
-const yellow = (t) => paint(33, t);
-const green = (t) => paint(32, t);
-const dim = (t) => paint(2, t);
-const VALUE_FLAGS = new Set(['dir', 'title', 'role', 'from', 'out', 'include', 'exclude', 'redact', 'max-cost', 'team-id', 'port']);
-function parse(argv) {
-    const flags = new Map();
-    const bools = new Set();
-    let command;
-    let sub;
-    let sub2;
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === '-h')
-            bools.add('help');
-        else if (arg === '-v')
-            bools.add('version');
-        else if (arg.startsWith('--')) {
-            const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
-            if (VALUE_FLAGS.has(name)) {
-                const value = inline ?? argv[++i];
-                if (value === undefined)
-                    fail(`--${name} needs a value.`);
-                flags.set(name, [...(flags.get(name) ?? []), value]);
-            }
-            else
-                bools.add(name);
-        }
-        else if (!command)
-            command = arg;
-        else if (command === 'tour' && !sub)
-            sub = arg;
-        else if (command === 'tour' && sub === 'export' && !sub2)
-            sub2 = arg;
-        else
-            fail(`Unexpected argument "${arg}".`);
-    }
-    return { command, sub, sub2, flags, bools };
-}
-function fail(message) {
-    // Phrased without a command name on purpose: this is the message somebody
-    // sees when they are already stuck, and it would be wrong for half of them.
-    // `docugate --help` is not a thing you can run if you reached this through
-    // npx, and `npx docugate --help` is not one if you installed it.
-    console.error(`${red('error')} ${message}\n${dim('See --help for usage.')}`);
-    process.exit(2);
-}
-function version() {
-    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-    return pkg.version;
+/** True while the launch menu is running: its commands do not print their own "Next". */
+let inMenu = false;
+function fail(message, tip) {
+    throw new UsageError(message, tip);
 }
 function report(label, issues, paintLabel) {
     for (const issue of issues) {
         console.log(`  ${paintLabel(label.padEnd(5))}  ${issue.file ? `${issue.file} ` : ''}${issue.message}`);
     }
 }
-const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
-async function main() {
-    const args = parse(process.argv.slice(2));
+function printHelp() {
+    // The banner only in a real terminal: piped help stays plain text.
+    if (process.stdout.isTTY)
+        for (const line of banner())
+            console.log(line);
+    console.log(renderHelp(SITE));
+}
+/** After a command in a terminal: the one thing worth doing next. */
+async function closing(root) {
+    if (inMenu || !process.stdout.isTTY || process.env.CI)
+        return;
+    try {
+        const status = await gatherStatus(root, { timeoutMs: 1500 });
+        if (status.next.done)
+            return;
+        console.log(`\n  ${dim('Next:')} ${gold(hint(status.next.command))} ${dim(`— ${status.next.why}`)}\n`);
+    }
+    catch {
+        /* a hint is never worth an error */
+    }
+}
+function reportError(error) {
+    if (error instanceof UsageError) {
+        // Phrased without a command name on purpose: this is the message somebody
+        // sees when they are already stuck, and it would be wrong for half of them.
+        console.error(`${red('error')} ${error.message}\n${dim(error.hint ?? 'See --help for usage.')}`);
+        process.exitCode = 2;
+    }
+    else {
+        console.error(`${red('error')} ${error.message}`);
+        process.exitCode = 1;
+    }
+}
+/**
+ * Whether somebody is at the keyboard. A real terminal says so; Git Bash's
+ * mintty window on Windows does not, because Node sees its console as a pipe,
+ * so it is recognised by the name it puts in TERM_PROGRAM instead. There the menu is the numbered
+ * one, which needs no raw keys.
+ */
+function isInteractive() {
+    if (process.stdin.isTTY && process.stdout.isTTY)
+        return true;
+    // mintty names itself; a script or a pipe run from Git Bash does not.
+    return isMintty() && !process.env.CI;
+}
+/** The launch menu: pick a step, run it, come back. */
+async function menuLoop(root) {
+    inMenu = true;
+    // The menu only opens for somebody at the keyboard, so the logo always shows.
+    for (const line of banner())
+        console.log(line);
+    for (;;) {
+        const status = await gatherStatus(root);
+        const action = await runMenu(status, { numbered: !canPick() });
+        if (!action)
+            return;
+        try {
+            await run(action);
+        }
+        catch (error) {
+            reportError(error);
+        }
+        process.exitCode = 0;
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const again = (await rl.question(dim('\n  Press Enter for the menu, or q to quit. '))).trim().toLowerCase() !== 'q';
+        rl.close();
+        if (!again)
+            return;
+    }
+}
+async function run(argv) {
+    const args = parseArgs(argv);
     const one = (name) => args.flags.get(name)?.at(-1);
     const many = (name) => args.flags.get(name) ?? [];
     const root = process.cwd();
-    if (args.bools.has('version'))
-        return console.log(version());
-    if (args.bools.has('help') || !args.command)
-        return console.log(HELP);
+    // No question is ever asked in CI, in a pipe, or when told not to.
+    const noInput = args.bools.has('no-input') || Boolean(process.env.CI);
+    if (args.version)
+        return console.log(packageVersion());
+    if (args.help) {
+        if (args.spec)
+            return console.log(renderCommandHelp(args.spec));
+        if (args.group)
+            return console.log(renderGroupHelp(args.group));
+        return printHelp();
+    }
+    if (args.group) {
+        // A group on its own is a command that was not finished: show the choices, and say it failed.
+        console.log(renderGroupHelp(args.group));
+        process.exitCode = 2;
+        return;
+    }
+    if (!args.command) {
+        // `docugate` on its own opens the app, the way `claude` does: a person typed
+        // it. Help is for a pipe, CI, or --no-input, where nobody can answer.
+        if (!inMenu && !noInput && isInteractive())
+            return menuLoop(root);
+        return printHelp();
+    }
     switch (args.command) {
+        case 'help': {
+            const topic = args.positional;
+            if (!topic)
+                return printHelp();
+            const spec = findCommand(topic);
+            if (spec)
+                return console.log(renderCommandHelp(spec));
+            if (COMMANDS.some((c) => c.name.startsWith(`${topic} `)))
+                return console.log(renderGroupHelp(topic));
+            const close = suggest(topic, COMMANDS.map((c) => c.name));
+            return fail(`There is no command "${topic}".`, close ? `Did you mean "${close}"?` : 'Run `docugate help` to see every command.');
+        }
+        case 'completion': {
+            const script = renderCompletion(args.positional ?? '');
+            if (!script)
+                fail('Say which shell: bash, zsh or powershell.');
+            process.stdout.write(script);
+            return;
+        }
+        case 'status': {
+            const status = await gatherStatus(root);
+            if (args.bools.has('json'))
+                return console.log(JSON.stringify(status, null, 2));
+            console.log();
+            for (const line of renderStatus(status))
+                console.log(line);
+            console.log();
+            return;
+        }
         case 'login': {
-            const creds = loadCredentials();
-            if (creds) {
-                // Already signed in — confirm with the server.
+            if (loadCredentials()) {
+                // Already signed in: confirm with the server.
                 try {
                     const { user } = await getSession();
                     if (user) {
@@ -149,21 +176,16 @@ async function main() {
                     // server unreachable; proceed to sign in again
                 }
             }
-            const { token } = await login(BASE_URL, args.bools.has('yes') ? {} : {});
+            await login(BASE_URL);
             try {
                 const { user } = await getSession();
-                if (user) {
-                    console.log(`Signed in as @${user.githubLogin}`);
-                }
-                else {
-                    console.log('Signed in.');
-                }
+                console.log(user ? `Signed in as @${user.githubLogin}` : 'Signed in.');
             }
             catch {
                 // token saved; just confirm
                 console.log('Signed in.');
             }
-            void token;
+            await closing(root);
             return;
         }
         case 'logout': {
@@ -172,9 +194,8 @@ async function main() {
             return;
         }
         case 'whoami': {
-            const creds = loadCredentials();
-            if (!creds) {
-                console.log('Not signed in. Run docugate login.');
+            if (!loadCredentials() && !process.env.DOCUGATE_TOKEN) {
+                console.log(`Not signed in. Run ${hint('login')}.`);
                 return;
             }
             let session;
@@ -186,12 +207,13 @@ async function main() {
                 process.exitCode = 1;
                 return;
             }
-            if (session.user) {
-                console.log(`@${session.user.githubLogin}`);
-            }
-            else {
-                console.log('Not signed in. Run docugate login.');
-            }
+            console.log(session.user ? `@${session.user.githubLogin}` : `Not signed in. Run ${hint('login')}.`);
+            return;
+        }
+        case 'developers': {
+            if (noInput && !args.bools.has('yes'))
+                fail('developers asks questions. Run it in a terminal, or add --yes to take every default.');
+            await developersFlow(root, { dir: one('dir'), yes: args.bools.has('yes') });
             return;
         }
         case 'init': {
@@ -206,6 +228,8 @@ async function main() {
                 role: roleFlag,
                 yes: args.bools.has('yes'),
                 port,
+                // Under --no-input or in CI nothing may be asked, even in a terminal.
+                io: noInput ? { ...makeDefaultIO(), isTTY: false } : undefined,
             });
             // 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
@@ -215,11 +239,23 @@ async function main() {
             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.`));
+                    ? `    The tour server is running in the background (port ${port}). After a restart: ${hint('tour serve')}`
+                    : `    Start the tour server with ${hint('tour serve')}, then open your app.`));
             }
             return;
         }
+        case 'sync': {
+            process.exitCode = await syncCommand(root, {
+                sub: args.sub,
+                sub2: args.sub2,
+                since: one('since'),
+                model: one('model'),
+                maxFiles: one('max-files'),
+                freshness: one('freshness'),
+                bools: args.bools,
+            });
+            return;
+        }
         case 'check': {
             const result = check(root, one('dir'));
             const strict = args.bools.has('strict');
@@ -233,6 +269,8 @@ async function main() {
                 console.log(`\n${plural(result.errors.length, 'error')}, ${plural(result.warnings.length, 'warning')}`);
             if (failed)
                 process.exitCode = 1;
+            else
+                await closing(root);
             return;
         }
         case 'openapi': {
@@ -257,7 +295,7 @@ async function main() {
                 }
                 else {
                     console.log(`${red('out of date')}  ${output} does not match ${from}.`);
-                    console.log(dim('Run `docugate openapi` and commit the result.'));
+                    console.log(dim(`Run ${hint('openapi')} and commit the result.`));
                     process.exitCode = 1;
                 }
                 return;
@@ -287,6 +325,11 @@ 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})`)}`);
+                    await closing(root);
                     return;
                 }
                 case 'init': {
@@ -297,31 +340,24 @@ 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).
-` +
-                                `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:
-` +
-                                `     PowerShell   [Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")
-` +
-                                `     macOS/Linux  export BOB_API_KEY=<key>   (add it to your shell profile)
-` +
+                            console.error(`${red('error')} Bob Shell needs an API key to run on its own (your IDE sign-in is not used here).\n` +
+                                `1. At https://bob.ibm.com, open your instance, then API keys, and create an Inference key.\n` +
+                                `2. Save it as the BOB_API_KEY environment variable, then open a new terminal:\n` +
+                                `     PowerShell   [Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")\n` +
+                                `     macOS/Linux  export BOB_API_KEY=<key>   (add it to your shell profile)\n` +
                                 dim('Keep the key out of your repository. https://bob.ibm.com/docs/ide/account/api-keys'));
-                            process.exit(2);
+                            process.exitCode = 2;
+                            return;
                         }
                         if (!(error instanceof BobMissingError))
                             throw error;
-                        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:
-` +
-                            `  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
-` +
+                        console.error(`${red('error')} Bob Shell is not installed, and tours are written by IBM Bob.\n` +
+                            `Install it (Node 24 or later), sign in, then run this again:\n` +
+                            `  Windows      powershell -c "irm -Uri https://bob.ibm.com/download/bobshell.ps1 | iex"\n` +
+                            `  macOS/Linux  curl -fsSL https://bob.ibm.com/download/bobshell.sh | bash\n` +
                             dim('https://bob.ibm.com/docs/shell/getting-started/install-and-setup'));
-                        process.exit(2);
+                        process.exitCode = 2;
+                        return;
                     }
                     for (const f of result.setup)
                         console.log(`  ${green('created')}  ${f}`);
@@ -337,17 +373,25 @@ async function main() {
                         stats?.durationMs !== undefined ? `${Math.round(stats.durationMs / 1000)}s` : '',
                         stats?.cost !== undefined ? `${stats.cost} Bobcoins` : '',
                     ].filter(Boolean);
-                    console.log(`
-${dim(`Bob: ${parts.join(', ')}`)}`);
+                    console.log(`\n${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 ${hint('tour serve')} to see why.`);
+                        return;
+                    }
+                    await serveTour(root, port);
                     return;
                 }
                 case 'export': {
-                    const outFile = args.sub2;
+                    const outFile = args.positional;
                     if (!outFile)
                         fail('Say where to write: docugate tour export <file>.');
                     const screens = loadTours(root);
@@ -357,17 +401,22 @@ ${dim(`Bob: ${parts.join(', ')}`)}`);
                     return;
                 }
                 default:
-                    fail(args.sub ? `Unknown tour command "${args.sub}".` : 'Say which: docugate tour init, tour install, or tour serve.');
+                    fail('Say which: docugate tour init, tour install, tour serve, or tour export.');
             }
         }
         default:
             fail(`Unknown command "${args.command}".`);
     }
 }
-main().catch((error) => {
-    console.error(`${red('error')} ${error.message}`);
-    process.exit(1);
-});
+main();
+async function main() {
+    try {
+        await run(process.argv.slice(2));
+    }
+    catch (error) {
+        reportError(error);
+    }
+}
 /**
  * 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