@davmash/bygone 0.5.2 → 0.7.1

package/docs/change-tour-format.md

@@ -0,0 +1,62 @@
+# Change tour authoring format
+
+A `.bygone.yaml` file contains the human-authored reading order and narrative. It points to code with named anchors; it does not store generated hunk indexes or line numbers.
+
+Run it against a committed branch range, or omit the refs when the source file pins its own range:
+
+```sh
+bygone present <head> --base <base> --tour path/to/review.bygone.yaml
+bygone present --tour path/to/self-contained-review.bygone.yaml
+```
+
+The optional `range` makes a tour self-contained and reproducible; explicit command-line refs take precedence. The compiler resolves every anchor against the exact merge-base or head commit and writes the resulting commit IDs, line ranges, excerpts, file contents, and diffs into the portable JSON manifest served by the presenter. Compilation fails if an anchor has no match or has multiple matches without an explicit `occurrence`.
+
+## Structure
+
+```yaml
+version: 1
+title: A reviewer-facing title
+sourceUrl: https://example.test/pull/123
+range:
+  base: 0123456789abcdef
+  head: fedcba9876543210
+
+anchors:
+  event-contract:
+    file: src/events.py
+    revision: head
+    contains: "    parent_event_id: str | None"
+  durable-decision:
+    file: src/controller.py
+    revision: head
+    contains: "    store.persist(decision)"
+
+connections:
+  contract-to-write:
+    from: event-contract
+    to: durable-decision
+    label: The contract is applied before the side effect.
+
+chapters:
+  - id: causal-chain
+    title: The causal chain
+    scenes:
+      - id: decision-flow
+        title: From decision to action
+        summary: The short thesis for this walkthrough.
+        bullets: [One supporting point]
+        tags: [ordering]
+        takeaway: What the reviewer should retain.
+        steps:
+          - id: persist-first
+            title: Persist the recommendation
+            body: This exact line establishes the ordering guarantee.
+            focus: durable-decision
+            connection: contract-to-write
+```
+
+Only the active step's connection is shown. This keeps relationships useful without adding a permanent second layer of curves to Bygone's diff view. The Tour rail contains only authored scenes; the adjacent Files rail independently lists the complete change set. Browsing a file does not move the narrative, and “Return to tour” restores the file and annotation focused by the current scene.
+
+See [Bygone's self-referencing history tour](../examples/bygone-history.bygone.yaml) for a complete narrative that pins and explains the commit where branch review was introduced.
+
+For agent workflows, see [Generating change tours with an LLM](./generating-change-tours.md) and the machine-readable [JSON Schema](../schemas/change-tour-source.schema.json).

package/docs/generating-change-tours.md

@@ -0,0 +1,75 @@
+# Generating change tours with an LLM
+
+Bygone treats an LLM as a narrative planner and evidence selector, not as the authority on Git or source locations. The model writes `.bygone.yaml`; Bygone resolves its anchors against pinned commits and rejects missing, ambiguous, or structurally invalid references.
+
+For agents that support repository skills, use the agent-agnostic [`pr-tour-guide` skill](../skills/pr-tour-guide/SKILL.md). It packages the complete evidence, authoring, validation, and handoff workflow without depending on a particular agent vendor.
+
+## Recommended loop
+
+1. Generate a deterministic change dossier instead of asking the model to rediscover the Git range:
+
+   ```sh
+   bygone tour context HEAD --base origin/main --output change-context.json
+   ```
+
+   The context contains commits, file roles, rename metadata, bounded unified patches, changed line ranges, basic symbol hints, and explicit binary or oversized-patch omissions.
+
+2. Inspect the merge-base-to-head change, its commits, production files, tests, renames, and binaries.
+3. Identify the small set of reviewer questions that explain why the change exists and how it works.
+4. Arrange those questions into conceptual chapters rather than filename order.
+5. Attach every walkthrough step to an exact snippet in either the base or head revision.
+6. Add a connection only when it explains a meaningful relationship between two pieces of evidence.
+7. Write the `.bygone.yaml` source.
+8. Validate it and repair every reported problem:
+
+   ```sh
+   bygone tour validate review.bygone.yaml --json
+   ```
+
+9. Compile or present the verified result:
+
+   ```sh
+   bygone tour compile review.bygone.yaml --output review.tour.json
+   bygone present --tour review.bygone.yaml
+   ```
+
+Use `bygone tour schema` to print the current JSON Schema. The checked-in schema is also available at [`schemas/change-tour-source.schema.json`](../schemas/change-tour-source.schema.json).
+
+## Narrative constraints
+
+- Prefer one reviewer question per scene and three to seven steps per scene.
+- Lead with contracts, invariants, or architectural boundaries before their consumers.
+- Pair behavior with the tests or evidence that prove it.
+- Keep mechanical, generated, and lockfile changes out of the authored narrative unless they alter the reviewer’s conclusion; they remain visible in the complete Files rail.
+- Make each annotation explain why the focused code matters; do not merely paraphrase its syntax.
+- Avoid claims about runtime behavior, safety, or intent that have no linked evidence.
+- Use connections sparingly. A connection should answer “how are these two facts related?”
+- Preserve access to the complete change instead of presenting the tour as exhaustive review.
+
+## Anchor rules
+
+- Never emit line numbers or generated hunk indexes.
+- Prefer the shortest snippet that is still unique within its file and revision.
+- Include `occurrence` only when repeated text is intentional and the selected occurrence is stable.
+- Pin immutable commit IDs in `range` for a durable artifact.
+- Treat a failed anchor as useful feedback. Do not silently redirect it to nearby code.
+
+## Suggested generation prompt
+
+```text
+Create a Bygone change tour for the supplied Git range.
+
+First identify the central reviewer questions and the concrete code evidence for each answer.
+Then produce YAML conforming to the schema returned by `bygone tour schema`.
+
+Requirements:
+- pin the exact base and head commits;
+- organize the narrative by concepts, not filenames;
+- link every step to a unique source snippet;
+- connect code locations only when the relationship adds explanatory value;
+- include behavior and its proof;
+- leave secondary files to Bygone's complete Files rail;
+- run `bygone tour validate <file> --json` and repair all errors before finishing.
+```
+
+The generated prose remains a proposal. Validation proves that its evidence exists and is reproducible; a reviewer must still judge whether its interpretation is correct.

package/docs/releasing.md

@@ -0,0 +1,342 @@
+# Releasing Bygone
+
+This document describes the current release workflow for Bygone:
+
+- VS Code extension package (`.vsix`)
+- npm standalone package
+- desktop artifacts
+- Homebrew formula and cask
+
+It is based on the scripts already in this repository. It does not assume any extra tooling beyond what those scripts already call.
+
+## Quick Start
+
+Validate without publishing:
+
+```bash
+npm run release:check
+npm run standalone:smoke
+npm run release:build
+```
+
+Publish everything:
+
+```bash
+export BYGONE_HOMEBREW_TAP=/path/to/homebrew-tap
+npm whoami
+gh auth status
+npm run release:publish
+```
+
+Upload `bygone-<version>.vsix` from the Visual Studio Marketplace publisher
+page. GitHub OIDC support has merged into `vsce`, but Marketplace has not yet
+exposed the trusted-publisher policy needed to authorize a workflow.
+
+## What Exists Today
+
+The main scripts are:
+
+- `npm run release:check`
+  - runs tests
+  - packages the VSIX
+  - stages the npm package
+  - dry-runs the npm package
+- `npm run release:build`
+  - runs the full local artifact build without publishing
+- `npm run release:publish`
+  - publishes npm
+  - creates a GitHub release with desktop artifacts
+  - updates and pushes the Homebrew tap
+
+Related packaging commands:
+
+- `npm run package:vsix`
+- `npm run package:npm`
+- `npm run package:npm:dry-run`
+- `npm run package:desktop`
+- `npm run package:desktop:mac`
+- `npm run package:desktop:mac:zip`
+- `npm run package:desktop:linux`
+- `npm run package:desktop:win`
+- `npm run standalone:smoke`
+
+## Prerequisites
+
+Before publishing, verify:
+
+## Accounts You Need
+
+You need accounts on three services:
+
+### 1. npm
+
+This is required for publishing the standalone package.
+
+- Sign up: [npm signup](https://www.npmjs.com/signup)
+- Docs: [npm getting started](https://docs.npmjs.com/getting-started)
+
+After creating the account:
+
+```bash
+npm login
+npm whoami
+```
+
+### 2. GitHub
+
+This is required because the release script creates a GitHub release and uploads desktop artifacts with `gh`.
+
+- Sign up: [GitHub signup](https://github.com/signup)
+- Docs: [Creating an account on GitHub](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github)
+
+After creating the account, authenticate the CLI:
+
+```bash
+gh auth login
+gh auth status
+```
+
+### 3. Visual Studio Marketplace publisher access
+
+This is required for publishing the VS Code extension.
+
+This is a little different from npm and GitHub. Global Azure DevOps Personal
+Access Tokens are being retired, while GitHub OIDC support is not yet usable
+because Marketplace has not exposed its trusted-publisher policy UI. Until
+that rollout completes, publish the packaged VSIX through the Marketplace
+publisher page.
+
+Publisher/admin surface:
+
+- Marketplace management: [Visual Studio Marketplace manage](https://marketplace.visualstudio.com/manage)
+
+Current practical flow:
+
+1. Sign in to the Marketplace manage page with your Microsoft account.
+2. Confirm the publisher that matches `package.json`:
+   - current publisher: `davidmashburn`
+3. Open the existing extension's **More Actions** menu and choose **Update**.
+4. Upload `bygone-<version>.vsix` on the update page. Do not use
+   **New extension** for a listing that already exists.
+
+OIDC support is merged into `microsoft/vscode-vsce` but is not present in its
+latest npm release, 3.9.2. Once Marketplace exposes trusted-publisher policies,
+add a workflow scoped to `davidmashburn/bygone` and use the first stable
+`@vscode/vsce` release that contains `publish --oidc`.
+
+### 4. Homebrew tap repo access
+
+There is no separate Homebrew account for this flow.
+
+What you need is:
+
+- a local checkout of the tap repository
+- git push access to that repository
+
+Set:
+
+```bash
+export BYGONE_HOMEBREW_TAP=/path/to/homebrew-tap
+```
+
+This repository should contain the tap structure used by the release script:
+
+- `Formula/`
+- `Casks/`
+
+### 1. npm authentication
+
+```bash
+npm whoami
+```
+
+If that fails:
+
+```bash
+npm login
+```
+
+### 2. GitHub authentication
+
+```bash
+gh auth status
+```
+
+This is required because `release:publish` uses `gh release create`.
+
+### 3. VS Code Marketplace publishing
+
+Package the extension:
+
+```bash
+npm run package:vsix
+```
+
+Then upload the resulting VSIX through the publisher page. Do not add a new
+long-lived PAT merely to automate this temporary gap.
+
+### 4. Homebrew tap checkout
+
+Set:
+
+```bash
+export BYGONE_HOMEBREW_TAP=/path/to/homebrew-tap
+```
+
+That path must point at a local git checkout of the tap repo. The script writes:
+
+- `Formula/bygone.rb`
+- `Casks/bygone-desktop.rb`
+
+and then commits and pushes that tap repo.
+
+## Recommended Release Flow
+
+### Step 1. Confirm the version
+
+```bash
+node -p "require('./package.json').version"
+```
+
+### Step 2. Run the validation gate
+
+```bash
+npm run release:check
+npm run standalone:smoke
+```
+
+This is the closest thing the repo currently has to a release doctor.
+
+It does **not** check credentials or required environment variables. It only validates the build/package pipeline.
+
+### Step 3. Build all artifacts locally
+
+```bash
+npm run release:build
+```
+
+This builds:
+
+- VSIX
+- staged npm package
+- dry-run npm package check
+- macOS desktop artifacts
+- Linux AppImage
+- Windows artifacts
+- Homebrew style validation, if `brew` is available
+
+If local packaging is partially unavailable, use the lower-level script:
+
+```bash
+node ./scripts/release.mjs --skip-dmg
+node ./scripts/release.mjs --skip-windows
+```
+
+### Step 4. Inspect expected outputs
+
+Expected outputs include:
+
+- `bygone-<version>.vsix`
+- `dist/npm-package/`
+- `dist/davidmashburn-bygone-<version>.tgz` after pack
+- `dist/Bygone-<version>-arm64.dmg`
+- `dist/Bygone-<version>-arm64-mac.zip`
+- `dist/Bygone-<version>-arm64.AppImage`
+- `dist/Bygone Setup <version>.exe`
+
+### Step 5. Publish
+
+```bash
+npm run release:publish
+```
+
+This runs the full publish path:
+
+1. `npm publish dist/npm-package --access public`
+2. `gh release create v<version> ... --notes-file CHANGELOG.md`
+3. update, commit, and push the Homebrew tap
+
+Publish the VS Code extension separately by uploading the already-built
+`bygone-<version>.vsix` through the Marketplace publisher page.
+
+## Homebrew Notes
+
+Homebrew staging files live in:
+
+- `packaging/homebrew/bygone.rb`
+- `packaging/homebrew/bygone-desktop.rb`
+
+The publish script will:
+
+- pack the staged npm package into `dist/`
+- compute SHA256 for the npm tarball and DMG
+- rewrite the formula and cask in the tap checkout
+- run `brew style`
+- commit and push the tap
+
+If you want a manual audit step from a tap checkout:
+
+```bash
+brew audit --new --formula Formula/bygone.rb
+brew audit --new --cask Casks/bygone-desktop.rb
+```
+
+The repository-local packaging notes are also in:
+
+- [packaging/homebrew/README.md](../packaging/homebrew/README.md)
+
+## Troubleshooting
+
+### `npm run release:publish` fails immediately
+
+Check:
+
+- `npm whoami`
+- `gh auth status`
+- `echo $BYGONE_HOMEBREW_TAP`
+
+### VS Code publishing is not automated
+
+This is currently intentional. `vsce` has merged GitHub OIDC support, but the
+Marketplace policy required to authorize the workflow is not publicly
+configurable. Upload the VSIX manually and revisit the workflow when both the
+Marketplace UI and a stable OIDC-enabled `vsce` release are available.
+
+### DMG build fails on macOS
+
+Use:
+
+```bash
+node ./scripts/release.mjs --skip-dmg
+```
+
+Then fix the local DMG toolchain before attempting a full publish.
+
+### Windows packaging fails locally
+
+Use:
+
+```bash
+node ./scripts/release.mjs --skip-windows
+```
+
+### Homebrew publish fails
+
+Check:
+
+- `BYGONE_HOMEBREW_TAP` points at a real git checkout
+- the tap checkout has `Formula/` and `Casks/`
+- `brew style` runs successfully
+
+## Current Gap
+
+There is no dedicated `doctor` command yet.
+
+If we add one later, it should check:
+
+- npm auth
+- GitHub auth
+- Marketplace publisher-page access
+- `BYGONE_HOMEBREW_TAP`
+- presence of required build tools
+- expected artifacts after `release:build`

package/docs/walkthrough.md

@@ -0,0 +1,103 @@
+# Bygone Walkthrough
+
+This walkthrough uses Bygone on the Bygone source tree itself, so every screenshot shows real project data rather than sample filler.
+
+Source files used below:
+
+- `src/fileComparator.ts`
+- `media/script.js`
+- `media/dom.js`
+- the repository root for Git directory history
+
+## 1. Start In Directory History
+
+If you launch Bygone with no arguments from the repo root, it opens Git directory history for the current directory:
+
+```bash
+cd ~/code/bygone
+./bin/bygone.js
+```
+
+You can also be explicit:
+
+```bash
+./bin/bygone.js --history ~/code/bygone
+```
+
+![Directory history view](../media/walkthrough/directory-history.png)
+
+What to look for:
+
+- The timeline controls at the top move commit-by-commit.
+- The left rail defaults to `History`, with `Changed Files` available as a secondary scope.
+- The main panes compare directory snapshots, not individual files.
+- This is the best starting point when you want to answer “what changed in this repo over time?”
+
+## 2. Narrow Down To One File
+
+For a file-level history view, point Bygone at a single tracked file:
+
+```bash
+./bin/bygone.js --history ~/code/bygone/src/fileComparator.ts
+```
+
+![File history view](../media/walkthrough/file-history.png)
+
+What to look for:
+
+- The history rail stays visible and becomes the primary way to jump between commits for that file.
+- Commit labels stay pinned above the two panes, so it is always clear which revision is on each side.
+- Change navigation sits above the editors. `Cmd/Ctrl+Alt+Up` and `Cmd/Ctrl+Alt+Down` jump between diff hunks.
+- This view is useful when you already know the file and want to understand how a specific implementation evolved.
+
+## 3. Open A Direct Two-File Diff
+
+For a plain compare outside Git history, pass two files:
+
+```bash
+./bin/bygone.js ~/code/bygone/media/script.js ~/code/bygone/media/dom.js
+```
+
+![Direct file diff view](../media/walkthrough/direct-file-diff.png)
+
+What to look for:
+
+- There is no history rail here because this is a direct file-to-file compare, not a history session.
+- The compare stays focused on the diff canvas: current change position, copy controls, and hunk traversal.
+- `Editing On` indicates that both panes are editable in this mode.
+- This is the fastest path when you want to compare two working files directly, regardless of Git history.
+
+## 4. Recommended Mental Model
+
+The current UI makes the most sense if you think about it along two axes:
+
+- `file` vs `directory`
+- `git-backed history` vs `direct compare`
+
+That yields the core flows:
+
+- directory history
+- file history
+- directory diff
+- file diff
+
+The shell then stays mostly consistent:
+
+- context at the top
+- commit navigation only in history-backed views
+- history or changed-files navigation in the left rail when it adds value
+- change navigation and copy actions close to the diff panes
+
+## 5. Practical Shortcuts
+
+- `bygone` or `bygone <directory>`: open Git directory history
+- `bygone <file>`: open file history
+- `bygone <left> <right>`: open a direct file or directory compare
+- `Cmd/Ctrl+Alt+Down`: next change
+- `Cmd/Ctrl+Alt+Up`: previous change
+
+## 6. When To Use Which View
+
+- Start in directory history when the question is “what happened in this area of the repo?”
+- Switch to file history when the question becomes “how did this file get here?”
+- Use direct file diff when you already have two concrete files and just want the compare.

package/examples/bygone-history.bygone.yaml

@@ -0,0 +1,80 @@
+version: 1
+title: How Bygone learned to review a branch
+sourceUrl: https://github.com/davidmashburn/bygone/commit/75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
+range:
+  base: 292fe9248c5c49f762489dc688296fc100d120bc
+  head: 75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
+
+anchors:
+  choose-merge-base:
+    file: src/gitComparison.ts
+    revision: head
+    contains: "    const mergeBaseOids = runGit(['merge-base', '--all', baseOid, headOid], repoRoot)"
+  describe-range:
+    file: src/gitComparison.ts
+    revision: head
+    contains: "        changedPaths: listChangedPaths(repoRoot, mergeBaseOid, headOid, runGit),"
+  materialize-boundary:
+    file: src/gitComparison.ts
+    revision: head
+    contains: "export function materializeBranchReviewTrees("
+  open-review-surface:
+    file: src/fileComparator.ts
+    revision: head
+    contains: "            materializeBranchReviewTrees(range, leftRoot, rightRoot);"
+  prove-merge-base:
+    file: test/runTests.js
+    revision: head
+    contains: "    assert.equal(range.mergeBaseOid, baseOid);"
+
+connections:
+  range-to-snapshot:
+    from: choose-merge-base
+    to: materialize-boundary
+    label: The selected historical boundary determines the two trees a reviewer sees.
+  snapshot-to-surface:
+    from: materialize-boundary
+    to: open-review-surface
+    label: The Git model is converted into the ordinary directory comparison surface.
+  semantics-to-proof:
+    from: choose-merge-base
+    to: prove-merge-base
+    label: A repository fixture locks the branch comparison to merge-base semantics.
+
+chapters:
+  - id: branch-to-review
+    title: A branch becomes a review
+    scenes:
+      - id: review-pipeline
+        title: From Git history to a visual workspace
+        summary: Follow the branch-review feature through its historical boundary, portable model, presentation seam, and proof.
+        bullets:
+          - The comparison starts at merge-base rather than whichever ref happens to be named as the base.
+          - Git-specific work ends once two temporary trees have been materialized.
+          - Existing directory comparison then provides navigation and drill-down without a second renderer.
+        tags: [git, architecture, dogfood]
+        takeaway: Bygone reviews its own history using the same boundary it introduced in this commit.
+        steps:
+          - id: establish-boundary
+            title: Establish the historical boundary
+            body: The review represents everything introduced since the branch diverged, including changes made around merges.
+            focus: choose-merge-base
+          - id: make-range-portable
+            title: Describe the review as data
+            body: Changed paths and commits are collected into a range that neither renderer needs to rediscover.
+            focus: describe-range
+          - id: turn-history-into-files
+            title: Materialize two review trees
+            body: The Git-specific layer creates base and head snapshots for only the changed paths.
+            focus: materialize-boundary
+            connection: range-to-snapshot
+          - id: reuse-the-diff-surface
+            title: Reuse directory comparison
+            body: VS Code hands those snapshots to Bygone's existing directory workflow instead of introducing a branch-only view.
+            focus: open-review-surface
+            connection: snapshot-to-surface
+          - id: lock-the-semantics
+            title: Prove the range starts at divergence
+            body: The test creates a real repository and asserts the selected merge base, changed paths, and commits.
+            focus: prove-merge-base
+            connection: semantics-to-proof