@davmash/bygone 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -2,8 +2,16 @@
 
 ## Unreleased
 
-- Added modified-file detection and drill-down for directory comparisons
-- Added prototype three-directory comparison with adjacent multi-panel file drill-down
+## 0.7.0
+
+- Expanded directory comparison into an N-panel workspace with asynchronous diff computation, drill-down, and complete file navigation
+- Added merge-base branch review with rename pairing, binary and image comparison, and consistent navigation across Git workflows
+- Improved semantic highlighting, structural replacement matching, line-click selection, connector rendering, and multi-panel interaction consistency
+- Added generated shell completions, desktop CLI installation, local rebuild/install automation, linting, and renderer bundle budgets
+- Added authored, code-connected change tours, bounded LLM context, coverage reporting, stacked and deconstructed explanations, the PR Tour Guide skill, and independent narrative and file navigation
+- Added refreshable sessions, pane-local find, persistent line wrapping, resizable sidebars, and horizontal multi-panel scrolling
+- Adopted the crisp-hybrid Bygone icon and strengthened release packaging across npm, VS Code, desktop, and Homebrew artifacts
+- Added a [guided 0.7 release tour](./tours/v0.7.bygone.yaml) covering the complete range from `v0.6.3`
 
 ## 0.2.0
 

package/README.md

@@ -1,3 +1,17 @@
+---
+author: David Mashburn
+created_at: 2026-06-01T20:35:08Z
+modified_at: 2026-07-31T20:56:06Z
+generated_by: Codex
+generated_for: David Mashburn
+reviewed_by:
+approved_by:
+repo: https://github.com/davidmashburn/bygone
+branch: main
+repo_branch_url: https://github.com/davidmashburn/bygone/tree/main
+repo_head_commit_url: https://github.com/davidmashburn/bygone/commit/183156146f54cc35b9304d6b2131e066b88e97dc
+---
+
 # Bygone
 
 Bygone is a VS Code extension and standalone desktop app for visual diff and file history.
@@ -10,19 +24,12 @@ Bygone is a VS Code extension and standalone desktop app for visual diff and fil
 - Dynamic adjacent multi-panel diff view
 - Flowing connectors, block contours, and inline change highlighting
 - Git file history viewer with commit-by-commit navigation
+- Local branch-review workspace using merge-base-to-tip semantics and changed-file progress
+- Binary-aware comparisons with side-by-side image previews and byte-equality reporting
 
 ## Status
 
-This project is usable as a local or private pre-release VS Code extension. The two-way diff and git history flows are the most complete. The multi-panel view is diff-focused, not a merge tool.
-
-## Migration Note
-
-This project was renamed from `Melden` to `Bygone`.
-
-- VS Code extension id changed from `davidmashburn.melden` to `davidmashburn.bygone`
-- CLI changed from `melden` to `bygone`
-- Git difftool names changed from `melden` / `melden-vscode` to `bygone` / `bygone-vscode`
-- Existing users should reinstall the extension and re-run the difftool setup scripts
+This project is usable as a VS Code extension and standalone desktop app. The two-way diff and git history flows are the most complete. The multi-panel view is diff-focused, not a merge tool.
 
 ## Install For Development
 
@@ -58,23 +65,59 @@ npm install -g .
 bygone
 bygone path/to/file-or-directory
 bygone --diff path/to/left path/to/right
+bygone --diff
 bygone --diff path/to/file1 path/to/file2 path/to/file3 [...]
-bygone --dir path/to/left-dir path/to/right-dir
-bygone --diff3 path/to/left path/to/middle path/to/right
-bygone --dir3 path/to/left-dir path/to/middle-dir path/to/right-dir
-bygone --history path/to/file
+bygone --history path/to/path
+bygone review
+bygone review feature/my-branch --base origin/main
+bygone present feature/my-branch --base origin/main
+bygone completion zsh
 bygone --help
 ```
 
-CLI defaults:
+For a one-command local sync that builds the repo, installs the global CLI, packages the desktop app, and auto-installs the VSIX and desktop app for your current platform:
 
-- `bygone` opens Git directory history for the current directory.
+```bash
+npm run dev:sync
+```
+
+CLI defaults:
+- In a Git repo, `bygone` opens directory history for the current directory.
+- Outside a Git repo, `bygone` opens a blank editable diff.
 - `bygone <file>` opens file history.
 - `bygone <directory>` opens Git directory history for that directory.
+- `bygone --history <path>` opens file or directory history.
+- `bygone review [<head>] [--base <base>]` reviews the committed branch tip against its merge base. The base is detected from `origin/HEAD`, `main`, or `master` when omitted.
+- `bygone present [<head>] [--base <base>]` opens the same committed range as an app-hosted change tour, grouped into a deterministic suggested reading order.
 - `bygone <left> <right>` auto-selects file diff or directory compare.
-- `bygone --diff <file1> <file2> <file3> ...` opens multi-panel diff.
+- `bygone --diff <file1> <file2> <file3> ...` opens multi-panel diff or multi-directory compare.
+
+On macOS, desktop-backed CLI commands and change tours route into the running
+Bygone app instead of opening another app instance and Dock item. Starting a
+new comparison brings the central app window forward and replaces its current
+session after any unsaved-change confirmation. Tours reuse a dedicated window
+owned by that same app process.
+
+Shell completion is generated from the same command specification as `bygone --help`, including contextual file arguments and local Git refs for branch review. `npm run dev:sync`, the desktop app's command-line installer, and the Homebrew packages install completions automatically. To install one manually, choose the command for your shell:
+
+```bash
+mkdir -p ~/.zfunc ~/.local/share/bash-completion/completions ~/.config/fish/completions
+bygone completion zsh > ~/.zfunc/_bygone # add ~/.zfunc to fpath before compinit
+bygone completion bash > ~/.local/share/bash-completion/completions/bygone
+bygone completion fish > ~/.config/fish/completions/bygone.fish
+```
+
+If the native desktop app is installed, the npm/source launcher prefers it and forwards the shell working directory. Set `BYGONE_FORCE_BUNDLED=1` to force the npm-bundled Electron runtime instead. The launcher removes `ELECTRON_RUN_AS_NODE` before starting Electron so editor-integrated terminals cannot accidentally force the app into Node mode.
+
+Branch review compares the selected head directly with `merge-base(base, head)`, so merge commits are represented correctly in the aggregate diff. Commit metadata retains every parent of merge commits for future temporal review. Dirty index and working-tree changes are reported but never silently included. Detected renames keep distinct old and new paths for correct drill-down and navigation without adding persistent cross-tree connectors.
+
+Two-file and directory drill-down comparisons detect binary content before decoding it as text. Images render side by side when they are small enough to preview inline; all binary comparisons report whether the underlying bytes are identical.
+
+Change tours can layer an authored, code-connected narrative over the complete generated change set. Pass a `.bygone.yaml` file with `--tour`; named source anchors compile to exact commit and line references, while an independent Files rail keeps every changed file available without adding filler scenes to the narrative. Try the self-referencing example with `bygone present --tour examples/bygone-history.bygone.yaml`, then see the [change tour format](./docs/change-tour-format.md).
+
+Agents can validate anchors and structure with `bygone tour validate <file.bygone.yaml> --json`, compile a portable manifest with `bygone tour compile`, and retrieve the authoring contract with `bygone tour schema`. See [Generating change tours with an LLM](./docs/generating-change-tours.md), or give a compatible agent the repository's vendor-neutral [`pr-tour-guide` skill](./skills/pr-tour-guide/SKILL.md).
 
-If the native desktop app is installed, the npm/source launcher prefers it and forwards the shell working directory. Set `BYGONE_FORCE_BUNDLED=1` to force the npm-bundled Electron runtime instead.
+`bygone tour context [<head>] --base <base>` produces a provider-neutral change dossier with bounded patches, changed ranges, file roles, symbol hints, commits, renames, and explicit binary omissions for an LLM to consume.
 
 The desktop app also includes `Help -> Install Command Line Tools...` for non-npm installs. Homebrew cask installs can provide the `bygone` command automatically.
 
@@ -114,7 +157,7 @@ npm run package:npm
 npm pack --dry-run ./dist/npm-package
 ```
 
-The root `package.json` is the VS Code extension manifest and intentionally keeps the unscoped extension name `bygone`. The npm distribution is staged separately as `@davidmashburn/bygone` so the global launcher can avoid the already-taken `bygone` package name while preserving the VS Code extension id `davidmashburn.bygone`.
+The root `package.json` is the VS Code extension manifest and intentionally keeps the unscoped extension name `bygone`. The npm distribution is staged separately as `@davmash/bygone` so the global launcher can avoid the already-taken `bygone` package name while preserving the VS Code extension id `davidmashburn.bygone`.
 
 Homebrew packaging templates live in `packaging/homebrew/`. They are staged for local validation only until release artifact URLs and checksums exist.
 
@@ -132,7 +175,7 @@ Publishing is intentionally explicit:
 npm run release:publish
 ```
 
-`release:publish` publishes the npm package, publishes the VS Code package, creates a GitHub release for desktop artifacts, and updates a Homebrew tap. Set `BYGONE_HOMEBREW_TAP` to a local tap checkout before publishing Homebrew formulas.
+`release:publish` publishes the npm package, creates a GitHub release for desktop artifacts, and updates a Homebrew tap. Set `BYGONE_HOMEBREW_TAP` to a local tap checkout before publishing Homebrew formulas. Until Marketplace trusted-publisher policies are publicly configurable, upload the packaged VSIX from the Visual Studio Marketplace publisher page.
 
 Run the release checks:
 
@@ -195,7 +238,7 @@ The wrapper scripts are:
 
 - `Bygone: Compare Files`
 - `Bygone: Compare Directories`
-- `Bygone: Compare Three Directories (Prototype)`
+- `Bygone: Compare Multiple Directories`
 - `Bygone: Compare Multiple Files`
 - `Bygone: Compare with Selected`
 - `Bygone: Compare Test Files`
@@ -207,7 +250,6 @@ The wrapper scripts are:
 - Bygone is intentionally diff-focused; merge tooling is not exposed as a product feature.
 - Directory compare supports modified-file detection and file drill-down; deep tree ergonomics are still early.
 - The git history viewer currently steps through single-parent commit history for one file at a time.
-- Marketplace publishing metadata is not finalized yet.
 
 ## Release Work
 

package/bin/bygone.js

@@ -4,57 +4,80 @@ const { spawn } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const packageJson = require('../package.json');
+const { generateCompletion, SUPPORTED_SHELLS } = require('../cli/completions.js');
+const { renderCliHelp, tokenMatches } = require('../cli/commandSpec.js');
+const { startPresentation } = require('../cli/present.js');
+const { runTourCommand } = require('../cli/tour.js');
 
 const args = process.argv.slice(2);
 const cliCwd = process.cwd();
+const packageRoot = path.join(__dirname, '..');
 
-if (args.includes('--help') || args.includes('-h')) {
-    process.stdout.write(`Bygone ${packageJson.version}
-
-Usage:
-  bygone
-  bygone <file-or-directory>
-  bygone <left> <right>
-  bygone --diff <left> <right>
-  bygone --diff <file1> <file2> <file3> [...]
-  bygone --diff3 <left> <middle> <right>
-  bygone --dir <left-dir> <right-dir>
-  bygone --dir3 <left-dir> <middle-dir> <right-dir>
-  bygone --history <file>
-  bygone --dir-history <directory>
-  bygone --test
-
-Notes:
-  - No args opens Git directory history for the current directory.
-  - One positional path opens file history or Git directory history.
-  - Two positional paths auto-select file diff or directory compare.
-  - \`--diff\` accepts 2 or more files; 3+ opens multi-panel diff.
-  - In the standalone app, drop 1 file for history, 2 files/directories for compare, 3+ files for multi-panel diff, or 3 directories for directory compare.
-`);
+if (args.some((arg) => tokenMatches('help', arg))) {
+    process.stdout.write(renderCliHelp(packageJson.version));
     process.exit(0);
 }
 
-if (args.includes('--version') || args.includes('-v')) {
+if (args.some((arg) => tokenMatches('version', arg))) {
     process.stdout.write(`${packageJson.version}\n`);
     process.exit(0);
 }
 
-const packageRoot = path.join(__dirname, '..');
+if (tokenMatches('completion', args[0])) {
+    const shell = args[1];
+    if (!SUPPORTED_SHELLS.includes(shell)) {
+        process.stderr.write(`Usage: bygone completion <${SUPPORTED_SHELLS.join('|')}>\n`);
+        process.exit(2);
+    }
+    process.stdout.write(generateCompletion(shell));
+    process.exit(0);
+}
+
+if (tokenMatches('tourCommand', args[0])) {
+    try {
+        runTourCommand(args.slice(1), cliCwd, packageRoot);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(args.includes('--json')
+            ? `${JSON.stringify({ ok: false, error: { message } }, null, 2)}\n`
+            : `Could not process change tour: ${message}\n`);
+        process.exitCode = 1;
+    }
+} else if (tokenMatches('present', args[0])) {
+    const installedApp = findInstalledApp();
+    if (installedApp && process.env.BYGONE_FORCE_BUNDLED !== '1') {
+        launchDesktopApp({ waitForExit: false });
+    } else {
+        startPresentation(args.slice(1), cliCwd, packageRoot).catch((error) => {
+            process.stderr.write(`Could not start change tour: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        });
+    }
+} else {
+    launchDesktopApp();
+}
+
+function launchDesktopApp({ waitForExit = true } = {}) {
 const electronBinary = process.platform === 'win32'
     ? '.\\node_modules\\.bin\\electron.cmd'
     : './node_modules/.bin/electron';
 const appEntry = './out/standalone-main.js';
 const forwardedArgs = ['--cwd', cliCwd, ...args];
 const installedApp = findInstalledApp();
-const preferBundledApp = fs.existsSync(path.join(packageRoot, '.git'));
 
 const child = installedApp && process.env.BYGONE_FORCE_BUNDLED !== '1'
-    && !preferBundledApp
-    ? spawnInstalledApp(installedApp, forwardedArgs)
+    ? spawnInstalledApp(installedApp, forwardedArgs, { waitForExit })
     : spawn(electronBinary, [appEntry, ...forwardedArgs], {
-    cwd: packageRoot,
-    stdio: 'inherit'
-});
+        cwd: packageRoot,
+        detached: !waitForExit,
+        stdio: waitForExit ? 'inherit' : 'ignore',
+        env: electronEnvironment()
+    });
+
+if (!waitForExit) {
+    child.unref();
+    return;
+}
 
 child.on('exit', (code, signal) => {
     if (signal) {
@@ -64,6 +87,7 @@ child.on('exit', (code, signal) => {
 
     process.exit(code ?? 0);
 });
+}
 
 function findInstalledApp() {
     if (process.platform === 'darwin') {
@@ -99,14 +123,24 @@ function findInstalledApp() {
     return candidates.find((candidate) => fs.existsSync(candidate));
 }
 
-function spawnInstalledApp(installedApp, launchArgs) {
+function spawnInstalledApp(installedApp, launchArgs, { waitForExit = true } = {}) {
+    const spawnOptions = {
+        detached: !waitForExit,
+        stdio: waitForExit ? 'inherit' : 'ignore',
+        env: electronEnvironment()
+    };
+
     if (process.platform === 'darwin') {
-        return spawn('open', ['-W', installedApp, '--args', ...launchArgs], {
-            stdio: 'inherit'
-        });
+        const executableName = path.basename(installedApp, '.app');
+        const executablePath = path.join(installedApp, 'Contents', 'MacOS', executableName);
+        return spawn(executablePath, launchArgs, spawnOptions);
     }
 
-    return spawn(installedApp, launchArgs, {
-        stdio: 'inherit'
-    });
+    return spawn(installedApp, launchArgs, spawnOptions);
+}
+
+function electronEnvironment() {
+    const environment = { ...process.env };
+    delete environment.ELECTRON_RUN_AS_NODE;
+    return environment;
 }

package/cli/commandSpec.js

@@ -0,0 +1,178 @@
+const CLI_SPEC = Object.freeze({
+    name: 'bygone',
+    summary: 'Visual diff and file history',
+    usages: [
+        'bygone',
+        'bygone <file-or-directory>',
+        'bygone <left> <right>',
+        'bygone --diff <left> <right>',
+        'bygone --diff',
+        'bygone --diff <file1> <file2> <file3> [...]',
+        'bygone --history <path>',
+        'bygone --git-diff <ref1> <ref2> [<ref3>...]',
+        'bygone review [<head>] [--base <base>]',
+        'bygone present [<head>] [--base <base>] [--tour <file.bygone.yaml>]',
+        'bygone tour validate <file.bygone.yaml> [--json]',
+        'bygone tour compile <file.bygone.yaml> [--output <tour.json>]',
+        'bygone tour context [<head>] [--base <base>] [--output <context.json>]',
+        'bygone tour coverage <file.bygone.yaml> [--json] [--minimum-coverage <0-100>]',
+        'bygone tour schema',
+        'bygone --branch-diff [-b BRANCH] [-m MAIN]',
+        'bygone completion <zsh|bash|fish>',
+        'bygone --test'
+    ],
+    entries: [
+        {
+            id: 'review',
+            kind: 'command',
+            tokens: ['review'],
+            description: 'Review a committed branch against its merge base',
+            argument: 'git-ref'
+        },
+        {
+            id: 'completion',
+            kind: 'command',
+            tokens: ['completion'],
+            description: 'Print shell completion source',
+            argument: 'shell'
+        },
+        {
+            id: 'present',
+            kind: 'command',
+            tokens: ['present'],
+            description: 'Open an app-hosted tour of a committed branch range',
+            argument: 'git-ref'
+        },
+        {
+            id: 'tourCommand',
+            kind: 'command',
+            tokens: ['tour'],
+            description: 'Validate, compile, or inspect authored change tours',
+            argument: 'tour-action'
+        },
+        {
+            id: 'diff',
+            kind: 'mode',
+            tokens: ['--diff'],
+            description: 'Compare files, or open a blank editable diff',
+            argument: 'files'
+        },
+        {
+            id: 'history',
+            kind: 'mode',
+            tokens: ['--history'],
+            description: 'Open Git history for a file or directory',
+            argument: 'path'
+        },
+        {
+            id: 'gitDiff',
+            kind: 'mode',
+            tokens: ['--git-diff'],
+            description: 'Compare two or more Git sources',
+            argument: 'git-refs'
+        },
+        {
+            id: 'branchDiff',
+            kind: 'mode',
+            tokens: ['--branch-diff'],
+            description: 'Legacy alias for branch review',
+            argument: 'git-ref'
+        },
+        {
+            id: 'test',
+            kind: 'mode',
+            tokens: ['--test'],
+            description: 'Open the built-in test comparison',
+            argument: 'none'
+        },
+        {
+            id: 'includeStaged',
+            kind: 'option',
+            tokens: ['--include-staged', '--staged'],
+            description: 'Include staged state in Git history',
+            argument: 'none'
+        },
+        {
+            id: 'base',
+            kind: 'option',
+            tokens: ['--base', '-m', '--main'],
+            description: 'Set the branch-review base ref',
+            argument: 'git-ref'
+        },
+        {
+            id: 'tour',
+            kind: 'option',
+            tokens: ['--tour'],
+            description: 'Use an authored change-tour YAML file',
+            argument: 'path'
+        },
+        {
+            id: 'branch',
+            kind: 'option',
+            tokens: ['-b', '--branch'],
+            description: 'Set the branch-review head ref',
+            argument: 'git-ref'
+        },
+        {
+            id: 'help',
+            kind: 'global',
+            tokens: ['-h', '--help'],
+            description: 'Show command help',
+            argument: 'none'
+        },
+        {
+            id: 'version',
+            kind: 'global',
+            tokens: ['-v', '--version'],
+            description: 'Show the installed version',
+            argument: 'none'
+        }
+    ],
+    notes: [
+        'No args opens Git directory history inside a Git repo, or a blank editable diff outside one.',
+        '`--diff` with no paths opens a blank editable diff.',
+        'One positional path opens file history or Git directory history.',
+        '`--history` accepts either files or directories.',
+        'Two positional paths auto-select file diff or directory compare.',
+        'Three or more positional paths auto-select multi-panel file diff or multi-directory compare.',
+        '`--git-diff` accepts branches, tags, SHAs, HEAD~1, stash@{0}, INDEX, and WORKTREE.',
+        '`review` compares merge-base(BASE,HEAD) with HEAD and detects the default base when omitted.',
+        '`present` turns the same range into an app-hosted, ordered change tour.',
+        '`tour validate` resolves every authored anchor; add `--json` for agent-readable output.',
+        '`tour compile` writes a portable manifest to stdout or `--output`; `tour schema` prints its source schema.',
+        '`tour context` emits compact, structured Git evidence for an LLM without invoking a model.',
+        '`tour coverage` reports referenced changed hunks and author-declared explanation depth.',
+        '`--branch-diff` is retained as an alias for `review`.',
+        '`completion` prints a completion script for Zsh, Bash, or Fish.',
+        'In the standalone app, drop 1 file for history, 2 files/directories for compare, or 3+ matching paths for multi-panel compare.'
+    ]
+});
+
+function getCliEntry(id) {
+    return CLI_SPEC.entries.find((entry) => entry.id === id);
+}
+
+function tokensFor(id) {
+    return getCliEntry(id)?.tokens ?? [];
+}
+
+function tokenMatches(id, token) {
+    return tokensFor(id).includes(token);
+}
+
+function renderCliHelp(version) {
+    const usage = CLI_SPEC.usages.map((line) => `  ${line}`).join('\n');
+    const entries = CLI_SPEC.entries.map((entry) => (
+        `  ${entry.tokens.join(', ')}\n      ${entry.description}`
+    )).join('\n');
+    const notes = CLI_SPEC.notes.map((line) => `  - ${line}`).join('\n');
+    return `Bygone ${version}\n\nUsage:\n${usage}\n\nCommands and options:\n${entries}\n\nNotes:\n${notes}\n`;
+}
+
+module.exports = {
+    CLI_SPEC,
+    getCliEntry,
+    renderCliHelp,
+    tokenMatches,
+    tokensFor
+};