@davmash/bygone 0.5.2 → 0.7.0

package/cli/completions.js

@@ -0,0 +1,321 @@
+const { CLI_SPEC, getCliEntry, tokensFor } = require('./commandSpec.js');
+
+const SUPPORTED_SHELLS = Object.freeze(['zsh', 'bash', 'fish']);
+
+function generateCompletion(shell) {
+    if (shell === 'zsh') {
+        return generateZshCompletion();
+    }
+    if (shell === 'bash') {
+        return generateBashCompletion();
+    }
+    if (shell === 'fish') {
+        return generateFishCompletion();
+    }
+    throw new Error(`Unsupported shell "${shell}". Choose: ${SUPPORTED_SHELLS.join(', ')}.`);
+}
+
+function completionFileName(shell) {
+    if (shell === 'zsh') {
+        return '_bygone';
+    }
+    if (shell === 'bash') {
+        return 'bygone';
+    }
+    if (shell === 'fish') {
+        return 'bygone.fish';
+    }
+    throw new Error(`Unsupported shell "${shell}".`);
+}
+
+function generateZshCompletion() {
+    const rootItems = completionEntries()
+        .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
+        .join('\n');
+    const reviewOptions = entriesByIds(['base', 'help'])
+        .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
+        .join('\n');
+    const presentOptions = entriesByIds(['base', 'tour', 'help'])
+        .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
+        .join('\n');
+    const legacyOptions = entriesByIds(['branch', 'base', 'help'])
+        .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
+        .join('\n');
+    const historyOptions = entriesByIds(['includeStaged', 'help'])
+        .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
+        .join('\n');
+
+    return `#compdef bygone
+# Generated from cli/commandSpec.js. Do not edit by hand.
+
+_bygone_git_refs() {
+    local -a refs
+    refs=(\${(f)"$(git for-each-ref --format='%(refname:short)' refs/heads refs/remotes refs/tags 2>/dev/null)"})
+    _describe 'git source' refs
+    compadd -- HEAD INDEX WORKTREE
+}
+
+_bygone() {
+    local first="\${words[2]}"
+    local previous="\${words[CURRENT-1]}"
+    local -a root_items review_options present_options legacy_options history_options shells tour_actions
+    root_items=(
+${rootItems}
+    )
+    review_options=(
+${reviewOptions}
+    )
+    present_options=(
+${presentOptions}
+    )
+    legacy_options=(
+${legacyOptions}
+    )
+    history_options=(
+${historyOptions}
+    )
+    shells=('zsh:Z shell' 'bash:Bash' 'fish:Fish shell')
+    tour_actions=('context:Build structured change evidence' 'validate:Validate source and anchors' 'compile:Compile a portable manifest' 'schema:Print the source schema')
+
+    if (( CURRENT == 2 )); then
+        _describe 'bygone command' root_items
+        _files
+        return
+    fi
+
+    case "$first" in
+        completion)
+            _describe 'shell' shells
+            ;;
+        tour)
+            if (( CURRENT == 3 )); then
+                _describe 'tour action' tour_actions
+            elif [[ "$words[3]" == "context" ]]; then
+                if [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
+                    _bygone_git_refs
+                elif [[ "$previous" == "--output" || "$previous" == "-o" ]]; then
+                    _files
+                else
+                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes
+                    _bygone_git_refs
+                fi
+            elif [[ "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
+                _files -g '*.bygone.yaml'
+            fi
+            ;;
+        review)
+            if [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
+                _bygone_git_refs
+            else
+                _describe 'review option' review_options
+                _bygone_git_refs
+            fi
+            ;;
+        present)
+            if [[ "$previous" == ${shellAlternation(tokensFor('tour'))} ]]; then
+                _files -g '*.bygone.yaml'
+            elif [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
+                _bygone_git_refs
+            else
+                _describe 'present option' present_options
+                _bygone_git_refs
+            fi
+            ;;
+        --branch-diff)
+            if [[ "$previous" == ${shellAlternation([...tokensFor('branch'), ...tokensFor('base')])} ]]; then
+                _bygone_git_refs
+            else
+                _describe 'review option' legacy_options
+                _bygone_git_refs
+            fi
+            ;;
+        --git-diff)
+            _bygone_git_refs
+            ;;
+        --history)
+            _describe 'history option' history_options
+            _files
+            ;;
+        --diff)
+            _files
+            ;;
+        *)
+            _files
+            ;;
+    esac
+}
+
+compdef _bygone bygone
+`;
+}
+
+function generateBashCompletion() {
+    const rootTokens = completionEntries().flatMap((entry) => entry.tokens).join(' ');
+    const reviewTokens = entriesByIds(['base', 'help']).flatMap((entry) => entry.tokens).join(' ');
+    const presentTokens = entriesByIds(['base', 'tour', 'help']).flatMap((entry) => entry.tokens).join(' ');
+    const legacyTokens = entriesByIds(['branch', 'base', 'help']).flatMap((entry) => entry.tokens).join(' ');
+    const historyTokens = entriesByIds(['includeStaged', 'help']).flatMap((entry) => entry.tokens).join(' ');
+    const baseTokens = tokensFor('base').join('|');
+    const refTokens = [...tokensFor('branch'), ...tokensFor('base')].join('|');
+
+    return `# Generated from cli/commandSpec.js. Do not edit by hand.
+_bygone_git_refs() {
+    git for-each-ref --format='%(refname:short)' refs/heads refs/remotes refs/tags 2>/dev/null
+    printf '%s\\n' HEAD INDEX WORKTREE
+}
+
+_bygone() {
+    local cur prev first refs
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    first="\${COMP_WORDS[1]}"
+
+    if (( COMP_CWORD == 1 )); then
+        COMPREPLY=( $(compgen -W '${rootTokens}' -- "$cur") $(compgen -f -- "$cur") )
+        compopt -o filenames 2>/dev/null || true
+        return
+    fi
+
+    case "$first" in
+        completion)
+            COMPREPLY=( $(compgen -W 'zsh bash fish' -- "$cur") )
+            ;;
+        tour)
+            if (( COMP_CWORD == 2 )); then
+                COMPREPLY=( $(compgen -W 'context validate compile schema' -- "$cur") )
+            elif [[ "\${COMP_WORDS[2]}" == "context" ]]; then
+                refs="$(_bygone_git_refs)"
+                if [[ "$prev" =~ ^(${baseTokens})$ ]]; then
+                    COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
+                elif [[ "$prev" == "--output" || "$prev" == "-o" ]]; then
+                    COMPREPLY=( $(compgen -f -- "$cur") )
+                    compopt -o filenames 2>/dev/null || true
+                else
+                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes '"$refs" -- "$cur") )
+                fi
+            else
+                COMPREPLY=( $(compgen -W '--json --output -o' -- "$cur") $(compgen -f -- "$cur") )
+                compopt -o filenames 2>/dev/null || true
+            fi
+            ;;
+        review)
+            refs="$(_bygone_git_refs)"
+            if [[ "$prev" =~ ^(${baseTokens})$ ]]; then
+                COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W '${reviewTokens} '"$refs" -- "$cur") )
+            fi
+            ;;
+        present)
+            refs="$(_bygone_git_refs)"
+            if [[ "$prev" == "--tour" ]]; then
+                COMPREPLY=( $(compgen -f -X '!*.bygone.yaml' -- "$cur") )
+                compopt -o filenames 2>/dev/null || true
+            elif [[ "$prev" =~ ^(${baseTokens})$ ]]; then
+                COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W '${presentTokens} '"$refs" -- "$cur") )
+            fi
+            ;;
+        --branch-diff)
+            refs="$(_bygone_git_refs)"
+            if [[ "$prev" =~ ^(${refTokens})$ ]]; then
+                COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W '${legacyTokens} '"$refs" -- "$cur") )
+            fi
+            ;;
+        --git-diff)
+            COMPREPLY=( $(compgen -W "$(_bygone_git_refs)" -- "$cur") )
+            ;;
+        --history)
+            COMPREPLY=( $(compgen -W '${historyTokens}' -- "$cur") $(compgen -f -- "$cur") )
+            compopt -o filenames 2>/dev/null || true
+            ;;
+        *)
+            COMPREPLY=( $(compgen -f -- "$cur") )
+            compopt -o filenames 2>/dev/null || true
+            ;;
+    esac
+}
+
+complete -F _bygone bygone
+`;
+}
+
+function generateFishCompletion() {
+    const lines = [
+        '# Generated from cli/commandSpec.js. Do not edit by hand.',
+        'function __bygone_git_refs',
+        "    git for-each-ref --format='%(refname:short)' refs/heads refs/remotes refs/tags 2>/dev/null",
+        '    printf "%s\\n" HEAD INDEX WORKTREE',
+        'end',
+        ''
+    ];
+
+    for (const entry of completionEntries()) {
+        const option = fishTokens(entry.tokens);
+        const argument = entry.argument === 'path' || entry.argument === 'files' ? ' -r' : '';
+        lines.push(`complete -c bygone -n '__fish_use_subcommand' ${option}${argument} -d '${escapeSingleQuoted(entry.description)}'`);
+    }
+
+    lines.push(
+        "complete -c bygone -n '__fish_seen_subcommand_from completion' -a 'zsh bash fish' -d 'Shell'",
+        "complete -c bygone -n '__fish_seen_subcommand_from tour' -a 'context validate compile schema' -d 'Tour action'",
+        "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l base -r -a '(__bygone_git_refs)' -d 'Set the change-context base ref'",
+        "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l output -s o -r -d 'Write the change context'",
+        "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l max-patch-bytes -r -d 'Maximum included patch size per file'",
+        "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l max-total-patch-bytes -r -d 'Maximum included patch size for the dossier'",
+        "complete -c bygone -n 'string match -q \"*tour validate*\" -- (commandline -opc)' -l json -d 'Print machine-readable validation output'",
+        "complete -c bygone -n 'string match -q \"*tour compile*\" -- (commandline -opc)' -l output -s o -r -d 'Write the compiled manifest'",
+        `complete -c bygone -n 'string match -q "*--history*" -- (commandline -opc)' ${fishTokens(tokensFor('includeStaged'))} -d '${escapeSingleQuoted(getCliEntry('includeStaged').description)}'`,
+        `complete -c bygone -n '__fish_seen_subcommand_from review' ${fishTokens(tokensFor('base'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('base').description)}'`,
+        "complete -c bygone -n '__fish_seen_subcommand_from review' -a '(__bygone_git_refs)' -d 'Git ref'",
+        `complete -c bygone -n '__fish_seen_subcommand_from present' ${fishTokens(tokensFor('base'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('base').description)}'`,
+        `complete -c bygone -n '__fish_seen_subcommand_from present' ${fishTokens(tokensFor('tour'))} -r -d '${escapeSingleQuoted(getCliEntry('tour').description)}'`,
+        "complete -c bygone -n '__fish_seen_subcommand_from present' -a '(__bygone_git_refs)' -d 'Git ref'",
+        `complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' ${fishTokens(tokensFor('branch'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('branch').description)}'`,
+        `complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' ${fishTokens(tokensFor('base'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('base').description)}'`,
+        `complete -c bygone -n 'string match -q "*--git-diff*" -- (commandline -opc)' -a '(__bygone_git_refs)' -d 'Git source'`
+    );
+    return `${lines.join('\n')}\n`;
+}
+
+function completionEntries() {
+    return CLI_SPEC.entries.filter((entry) => (
+        entry.kind === 'command' || entry.kind === 'mode' || entry.kind === 'global'
+    ));
+}
+
+function entriesByIds(ids) {
+    return ids.map((id) => getCliEntry(id)).filter(Boolean);
+}
+
+function shellAlternation(tokens) {
+    return `(${tokens.join('|')})`;
+}
+
+function fishTokenOption(token) {
+    if (token.startsWith('--')) {
+        return `-l ${token.slice(2)}`;
+    }
+    if (token.startsWith('-')) {
+        return `-s ${token.slice(1)}`;
+    }
+    return `-a ${token}`;
+}
+
+function fishTokens(tokens) {
+    return tokens.map(fishTokenOption).join(' ');
+}
+
+function escapeSingleQuoted(value) {
+    return String(value).replace(/'/g, "'\\''");
+}
+
+module.exports = {
+    SUPPORTED_SHELLS,
+    completionFileName,
+    generateCompletion
+};

package/cli/present.js

@@ -0,0 +1,166 @@
+const { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
+const { createServer } = require('http');
+const path = require('path');
+const { spawn } = require('child_process');
+const { buildChangeTourManifest, parseChangeTourStory } = require('../out/changeTour.js');
+const { tokenMatches } = require('./commandSpec.js');
+const { loadTourSource } = require('./tourFile.js');
+
+const MIME_TYPES = new Map([
+    ['.css', 'text/css; charset=utf-8'],
+    ['.html', 'text/html; charset=utf-8'],
+    ['.js', 'application/javascript; charset=utf-8'],
+    ['.json', 'application/json; charset=utf-8'],
+    ['.png', 'image/png'],
+    ['.svg', 'image/svg+xml; charset=utf-8'],
+    ['.ttf', 'font/ttf']
+]);
+
+async function startPresentation(args, cwd, packageRoot, options = {}) {
+    const { headRef, baseRef, tourPath, explicitHeadRef } = parsePresentArgs(args);
+    const story = process.env.BYGONE_TOUR_STORY
+        ? parseChangeTourStory(JSON.parse(readFileSync(path.resolve(cwd, process.env.BYGONE_TOUR_STORY), 'utf8')))
+        : undefined;
+    const source = tourPath ? loadTourSource(cwd, tourPath).source : undefined;
+    const manifest = buildChangeTourManifest(cwd, {
+        headRef: explicitHeadRef || source?.range?.head || headRef,
+        baseRef: baseRef || source?.range?.base,
+        title: process.env.BYGONE_TOUR_TITLE,
+        sourceUrl: process.env.BYGONE_TOUR_SOURCE_URL,
+        story,
+        source
+    });
+    const serializedManifest = `${JSON.stringify(manifest, null, 2)}\n`;
+    const outputPath = process.env.BYGONE_TOUR_OUTPUT;
+    if (outputPath) {
+        const resolvedOutput = path.resolve(cwd, outputPath);
+        mkdirSync(path.dirname(resolvedOutput), { recursive: true });
+        writeFileSync(resolvedOutput, serializedManifest, 'utf8');
+        process.stdout.write(`Wrote change-tour manifest to ${resolvedOutput}\n`);
+    }
+
+    const server = createServer((request, response) => {
+        const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
+        if (requestUrl.pathname === '/tour.json') {
+            response.writeHead(200, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Cache-Control': 'no-store'
+            });
+            response.end(serializedManifest);
+            return;
+        }
+        const targetPath = resolveAssetPath(packageRoot, requestUrl.pathname);
+        if (!targetPath) {
+            respond(response, 404, 'Not found');
+            return;
+        }
+        response.writeHead(200, {
+            'Content-Type': MIME_TYPES.get(path.extname(targetPath)) || 'application/octet-stream',
+            'Cache-Control': 'no-store'
+        });
+        createReadStream(targetPath).on('error', () => respond(response, 500, 'Read failed')).pipe(response);
+    });
+    const requestedPort = readPort(process.env.BYGONE_TOUR_PORT);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(requestedPort, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        server.close();
+        throw new Error('Could not determine the presentation server address.');
+    }
+    const url = `http://127.0.0.1:${address.port}/?manifest=/tour.json`;
+    if (options.announce !== false) {
+        process.stdout.write(`Bygone change tour running at ${url}\n`);
+        process.stdout.write('Press Ctrl+C to stop.\n');
+    }
+    if (options.open !== false && process.env.BYGONE_TOUR_NO_OPEN !== '1') {
+        const openUrl = typeof options.openUrl === 'function' ? options.openUrl : openBrowser;
+        try {
+            await openUrl(url);
+        } catch (error) {
+            server.close();
+            throw error;
+        }
+    }
+    return { manifest, server, url };
+}
+
+function parsePresentArgs(args) {
+    let headRef = 'HEAD';
+    let explicitHeadRef;
+    let baseRef;
+    let tourPath;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (tokenMatches('base', arg)) {
+            if (!args[index + 1]) {
+                throw new Error(`${arg} requires a Git ref.`);
+            }
+            baseRef = args[++index];
+            continue;
+        }
+        if (tokenMatches('tour', arg)) {
+            if (!args[index + 1]) throw new Error(`${arg} requires a YAML file.`);
+            tourPath = args[++index];
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new Error(`Unknown present option: ${arg}`);
+        }
+        if (explicitHeadRef) {
+            throw new Error('present accepts at most one head ref.');
+        }
+        headRef = arg;
+        explicitHeadRef = arg;
+    }
+    return { headRef, baseRef, tourPath, explicitHeadRef };
+}
+
+function resolveAssetPath(packageRoot, requestPath) {
+    if (requestPath === '/' || requestPath === '/index.html') {
+        return path.join(packageRoot, 'web', 'index.html');
+    }
+    if (!requestPath.startsWith('/web/') && !requestPath.startsWith('/media/')) {
+        return null;
+    }
+    const candidate = path.resolve(packageRoot, `.${requestPath}`);
+    if (!candidate.startsWith(`${path.resolve(packageRoot)}${path.sep}`) || !existsSync(candidate)) {
+        return null;
+    }
+    return candidate;
+}
+
+function openBrowser(url) {
+    const command = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore' });
+    child.unref();
+}
+
+function readPort(value) {
+    if (!value) {
+        return 0;
+    }
+    const port = Number.parseInt(value, 10);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error('BYGONE_TOUR_PORT must be an integer from 0 to 65535.');
+    }
+    return port;
+}
+
+function respond(response, statusCode, message) {
+    if (!response.headersSent) {
+        response.writeHead(statusCode, { 'Content-Type': 'text/plain; charset=utf-8' });
+    }
+    response.end(message);
+}
+
+module.exports = {
+    parsePresentArgs,
+    startPresentation
+};

package/cli/tour.js

@@ -0,0 +1,189 @@
+const { mkdirSync, readFileSync, writeFileSync } = require('fs');
+const path = require('path');
+const { buildChangeTourContext } = require('../out/changeTour.js');
+const { buildTourCoverageReport } = require('../out/tourCoverage.js');
+const { buildManifestForTourSource, loadTourSource } = require('./tourFile.js');
+
+const TOUR_ACTIONS = Object.freeze(['context', 'coverage', 'validate', 'compile', 'schema']);
+
+function runTourCommand(args, cwd, packageRoot, output = process.stdout) {
+    const options = parseTourArgs(args);
+    if (options.action === 'schema') {
+        output.write(readFileSync(path.join(packageRoot, 'schemas', 'change-tour-source.schema.json'), 'utf8'));
+        return { action: 'schema' };
+    }
+    if (options.action === 'context') {
+        const context = buildChangeTourContext(cwd, {
+            headRef: options.headRef,
+            baseRef: options.baseRef,
+            maxPatchBytes: options.maxPatchBytes,
+            maxTotalPatchBytes: options.maxTotalPatchBytes
+        });
+        return writeJsonResult('change-tour context', context, options.outputPath, cwd, output);
+    }
+
+    const { resolvedPath, source } = loadTourSource(cwd, options.sourcePath);
+    if (options.action === 'coverage') {
+        const report = buildTourCoverageReport(cwd, source);
+        output.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : renderCoverageReport(report));
+        if (options.minimumCoverage !== undefined && report.totals.coveragePercent < options.minimumCoverage) {
+            throw new Error(`Tour coverage ${report.totals.coveragePercent}% is below the required ${options.minimumCoverage}%.`);
+        }
+        return { action: 'coverage', sourcePath: resolvedPath, report };
+    }
+    const manifest = buildManifestForTourSource(cwd, source);
+    if (options.action === 'validate') {
+        const result = buildValidationResult(resolvedPath, manifest);
+        output.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : `Valid change tour: ${path.relative(cwd, resolvedPath) || path.basename(resolvedPath)} · ${result.walkthroughSteps} steps · ${result.summary.changedFiles} changed files · ${result.range.mergeBaseOid.slice(0, 7)} → ${result.range.headOid.slice(0, 7)}\n`);
+        return result;
+    }
+
+    const serialized = `${JSON.stringify(manifest, null, 2)}\n`;
+    if (options.outputPath) {
+        const resolvedOutput = path.resolve(cwd, options.outputPath);
+        mkdirSync(path.dirname(resolvedOutput), { recursive: true });
+        writeFileSync(resolvedOutput, serialized, 'utf8');
+        output.write(`Wrote compiled change tour to ${resolvedOutput}\n`);
+        return { action: 'compile', outputPath: resolvedOutput, manifest };
+    }
+    output.write(serialized);
+    return { action: 'compile', manifest };
+}
+
+function parseTourArgs(args) {
+    const [action, ...rest] = args;
+    if (!TOUR_ACTIONS.includes(action)) {
+        throw new Error(`Usage: bygone tour <${TOUR_ACTIONS.join('|')}> [file.bygone.yaml]`);
+    }
+    if (action === 'schema') {
+        if (rest.length > 0) throw new Error('tour schema does not accept additional arguments.');
+        return { action };
+    }
+    if (action === 'context') return parseContextArgs(rest);
+    let sourcePath;
+    let outputPath;
+    let json = false;
+    let minimumCoverage;
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--minimum-coverage') {
+            minimumCoverage = Number.parseInt(rest[++index], 10);
+            if (!Number.isInteger(minimumCoverage) || minimumCoverage < 0 || minimumCoverage > 100) {
+                throw new Error('--minimum-coverage requires an integer from 0 to 100.');
+            }
+            continue;
+        }
+        if (arg === '--output' || arg === '-o') {
+            if (!rest[index + 1]) throw new Error(`${arg} requires a file path.`);
+            outputPath = rest[++index];
+            continue;
+        }
+        if (arg.startsWith('-')) throw new Error(`Unknown tour option: ${arg}`);
+        if (sourcePath) throw new Error(`tour ${action} accepts exactly one source file.`);
+        sourcePath = arg;
+    }
+    if (!sourcePath) throw new Error(`tour ${action} requires a .bygone.yaml source file.`);
+    if (action === 'validate' && outputPath) throw new Error('--output is only valid with tour compile.');
+    if (action === 'compile' && json) throw new Error('--json is only valid with tour validate or coverage.');
+    if (action !== 'coverage' && minimumCoverage !== undefined) {
+        throw new Error('--minimum-coverage is only valid with tour coverage.');
+    }
+    return { action, sourcePath, outputPath, json, ...(action === 'coverage' ? { minimumCoverage } : {}) };
+}
+
+function renderCoverageReport(report) {
+    const lines = [
+        `Tour coverage: ${report.totals.coveredUnits}/${report.totals.includedUnits} hunks (${report.totals.coveragePercent}%)`,
+        `Depth: ${report.depth.mentioned} mentioned · ${report.depth.explained} explained · ${report.depth.contextualized} contextualized`
+    ];
+    if (report.totals.excludedUnits > 0) lines.push(`Excluded: ${report.totals.excludedUnits}/${report.totals.originalUnits} hunks`);
+    for (const file of report.files.filter((entry) => entry.uncoveredHunks.length > 0)) {
+        lines.push(`${file.path}: ${file.uncoveredHunks.length} uncovered (${file.uncoveredHunks.join(', ')})`);
+    }
+    for (const unsupported of report.unsupported) lines.push(`${unsupported.path}: ${unsupported.material} material not scored`);
+    return `${lines.join('\n')}\n`;
+}
+
+function parseContextArgs(args) {
+    let headRef;
+    let baseRef;
+    let outputPath;
+    let maxPatchBytes;
+    let maxTotalPatchBytes;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--base' || arg === '-m' || arg === '--main') {
+            if (!args[index + 1]) throw new Error(`${arg} requires a Git ref.`);
+            baseRef = args[++index];
+            continue;
+        }
+        if (arg === '--output' || arg === '-o') {
+            if (!args[index + 1]) throw new Error(`${arg} requires a file path.`);
+            outputPath = args[++index];
+            continue;
+        }
+        if (arg === '--max-patch-bytes') {
+            if (!args[index + 1]) throw new Error(`${arg} requires a positive integer.`);
+            maxPatchBytes = Number.parseInt(args[++index], 10);
+            if (!Number.isInteger(maxPatchBytes) || maxPatchBytes < 1) {
+                throw new Error(`${arg} requires a positive integer.`);
+            }
+            continue;
+        }
+        if (arg === '--max-total-patch-bytes') {
+            if (!args[index + 1]) throw new Error(`${arg} requires a positive integer.`);
+            maxTotalPatchBytes = Number.parseInt(args[++index], 10);
+            if (!Number.isInteger(maxTotalPatchBytes) || maxTotalPatchBytes < 1) {
+                throw new Error(`${arg} requires a positive integer.`);
+            }
+            continue;
+        }
+        if (arg.startsWith('-')) throw new Error(`Unknown tour context option: ${arg}`);
+        if (headRef) throw new Error('tour context accepts at most one head ref.');
+        headRef = arg;
+    }
+    return { action: 'context', headRef, baseRef, outputPath, maxPatchBytes, maxTotalPatchBytes };
+}
+
+function writeJsonResult(label, value, outputPath, cwd, output) {
+    const serialized = `${JSON.stringify(value, null, 2)}\n`;
+    if (!outputPath) {
+        output.write(serialized);
+        return { action: 'context', context: value };
+    }
+    const resolvedOutput = path.resolve(cwd, outputPath);
+    mkdirSync(path.dirname(resolvedOutput), { recursive: true });
+    writeFileSync(resolvedOutput, serialized, 'utf8');
+    output.write(`Wrote ${label} to ${resolvedOutput}\n`);
+    return { action: 'context', outputPath: resolvedOutput, context: value };
+}
+
+function buildValidationResult(sourcePath, manifest) {
+    return {
+        ok: true,
+        sourcePath,
+        title: manifest.title,
+        range: manifest.range,
+        summary: manifest.summary,
+        chapters: manifest.chapters.length,
+        walkthroughSteps: manifest.scenes.reduce(
+            (total, scene) => total + (
+                scene.kind === 'walkthrough' || scene.kind === 'stacked-diff' || scene.kind === 'deconstructed-diff'
+                    ? scene.steps.length
+                    : 0
+            ),
+            0
+        )
+    };
+}
+
+module.exports = {
+    parseTourArgs,
+    runTourCommand
+};