@davmash/bygone 0.7.1 → 0.8.0

package/docs/product-surface.md

@@ -0,0 +1,124 @@
+# Product surface overview
+
+This is the internal map of Bygone's user-facing product. Update it whenever a
+command, launch form, comparison mode, tour scene, or release artifact is added
+or materially changed.
+
+## Product boundaries
+
+- **Explore — desktop:** open-ended file, directory, history, revision,
+  multi-panel, and branch-change investigation.
+- **Present — desktop/browser:** generated and authored tours with narrative,
+  exact source evidence, and an independent changed-files rail.
+- **VS Code companion:** contextual file comparison and file history near the
+  current editor. Repository-, directory-, multi-panel-, and tour-scale work
+  should hand off to desktop.
+- **CLI and agent tools:** launch automation plus tour context, authoring,
+  validation, compilation, schema, and coverage.
+- **Development only:** fixtures, smoke/capture modes, generated screenshots,
+  and developer tools. These must not appear in production menus or packages.
+
+The shared Monaco renderer supplies diff semantics and presentation. Sharing a
+renderer does not make every workflow appropriate in every host.
+
+## Standalone Explore
+
+| User question | Discovery and launch | Session/source | Mutability and lifecycle | Maturity | Verification |
+| --- | --- | --- | --- | --- | --- |
+| Start without source material | CLI `bygone` outside Git; blank startup | Blank multi-diff | Writable untitled panels; normal undo and dirty state | Core | `testBlankMultiDiffStartsWithTwoEditablePanels` |
+| Compare files | File → Compare Files; drag/drop; `bygone left right`; `--diff` | Files, two-way or multi-diff | Files are writable; save, reload, refresh, and external-change policy apply | Core | standalone smoke and multi-diff tests |
+| Compare directories | File → Compare Directories; drag/drop; two or more directory arguments | Directory comparison | Directory rows are read-only; writable file drill-down depends on source/review state | Core | directory smoke and directory-diff tests |
+| Follow one file or directory through Git | Git → View File or Directory History; one path; `--history` | Git commits plus supported index/worktree states | Commits are read-only; worktree/index provenance is explicit | Core | Git history and directory-history tests |
+| Compare named revisions | `bygone --git-diff <refs…>` | Git blobs/revisions | Read-only snapshots | Secondary; CLI discovery needs improvement | Git comparison tests |
+| Explore the current branch change | Git → Explore Current Branch Change; `bygone review` | Merge-base-to-tip branch inventory | Read-only review snapshots; dirty state is reported, not silently included | Core | branch comparison and review-path tests |
+| Search comparison code | Edit → Find or Search Comparison | Active, visible, all loaded panels, unopened changed text snapshots, or one file's Git history | Search is read-only; history distinguishes content occurrence from introduction/removal; Replace requires the active writable model | Core | find, comparison-search, change-set-search, and history-search tests |
+| Search or safely replace in a filesystem tree | Edit → Search in Files; explicit directory root | System ripgrep 14+ with include/exclude, hidden, ignore, and result-limit controls | Search is read-only and cancellable; completed case-sensitive literal searches can build an exclusion-aware, revalidated, atomic replacement preview with guarded undo | Optional system capability | repository search/replace contracts, benchmark, and host-protocol tests |
+| Move through a multi-panel comparison | Strip buttons, panel headers, gutters, wheel, or `Alt+Arrow` | Active panel and adjacent pair | Does not change source identity | Core | focused-strip controller and standalone smoke tests |
+| Search an authored tour | Presenter search or `Cmd/Ctrl+Shift+F` | Authored narrative plus compiled base/head code snapshots | Read-only; narrative hits navigate scenes/steps and code hits preserve Return to tour | Core | tour-search and presenter-host tests |
+
+The File menu owns sources and persistence; Edit owns focused text operations;
+Git owns historical/revision questions; Present changes product area; Navigate
+owns movement within the current session; View owns display preferences; Window
+owns native window lifecycle. Developer fixtures appear only when Electron is
+not packaged.
+
+## Standalone Present and browser presenter
+
+| User question | Discovery and launch | Identity/provenance | Mutability | Maturity | Verification |
+| --- | --- | --- | --- | --- | --- |
+| Explain the current branch automatically | Present → Present Current Branch; `bygone present` | Committed merge-base-to-tip range | Read-only | Core | presentation launch and generated-tour tests |
+| Open an authored walkthrough | Present → Open Authored Tour; `bygone present --tour`; VS Code hand-off | Manifest range, scene, step, exact source anchor | Read-only | Core | reproducible example and tour validation tests |
+| Explain a real stack | `stacked-diff` scene | Exact real Git revisions per panel | Read-only | Advanced | `examples/stacked-diff.bygone` |
+| Explain a change in conceptual stages | `deconstructed-diff` scene | Explicitly labeled synthetic explanation stages backed by exact hunk IDs | Read-only | Advanced/experimental authoring | `examples/deconstructed-diff.bygone` |
+| Browse away from the narration | Files rail, change navigation | Browsed file versus active tour focus remain distinct | Read-only; Return to Tour restores narrative focus | Core | tour focus and persistent-anchor tests |
+
+Tour authoring remains file/CLI/agent driven. The desktop UI opens and presents
+tours but does not attempt to duplicate schema-aware authoring forms.
+
+## VS Code companion
+
+| Command | Intended ownership | Current state | Editing contract | Follow-up |
+| --- | --- | --- | --- | --- |
+| Compare Active File With / Compare Selected Files / Compare With Selected | VS Code contextual comparison | Independent, restorable editor-area tabs | Trusted local panes use `TextDocument` and `WorkspaceEdit`; non-local panes are read-only | Core |
+| View Active File History | VS Code contextual history | Implemented in the editor area | Historical content is read-only; an open unsaved worktree buffer is preserved | Core |
+| Open This Comparison in Desktop | Desktop hand-off | Implemented for active local file pairs | No source content crosses the boundary | Core |
+| Explore Current Branch in Desktop | Desktop hand-off | Implemented for a local configured executable | No source content crosses the boundary | Disabled for untrusted, remote, and virtual workspaces |
+| Present Current Branch in Desktop | Desktop hand-off | Implemented | Read-only presentation | Same launch-contract hardening |
+| Open Authored Tour in Desktop | Desktop hand-off | Implemented | Read-only presentation | Same launch-contract hardening |
+| Compare Directories / Three or More Files in Desktop | Desktop hand-off | Implemented with local multi-selection | Desktop owns the comparison and writable lifecycle | Keep contextual visibility narrow |
+| Legacy in-extension directory, N-panel, and branch-review commands | Desktop-owned | Removed from production contributions | Parallel extension state is not the target product | Internal compatibility code can be removed with the deferred host rewrite |
+| Install or Open Desktop App | Setup fallback | Implemented | Not applicable | Opens settings or release downloads when no executable is configured |
+
+The production extension does not contribute test fixtures. The VSIX is checked
+against an explicit runtime-file allowlist. VS Code repository search should use
+VS Code's native Search rather than another bundled ripgrep process.
+
+## CLI and authoring tools
+
+| Surface | Purpose | Mutability/maturity |
+| --- | --- | --- |
+| `bygone`, paths, `--diff`, `--history`, `--git-diff`, `review` | Launch Explore sessions | Core launcher; desktop owns writes |
+| `present` and `present --tour` | Launch Present sessions | Core, read-only presentation |
+| `tour context` | Produce a bounded provider-neutral change dossier | Authoring support, read-only |
+| `tour validate`, `compile`, `schema`, and coverage options | Validate exact evidence and build portable manifests | Advanced authoring, read-only except explicit output files |
+| `completion` | Generate shell completions from the shared command specification | Supporting tooling |
+
+## Provenance and mutability vocabulary
+
+Use these labels consistently:
+
+- **Writable file:** filesystem/worktree content participating in dirty, undo,
+  save, reload, watcher, and refresh behavior.
+- **Read-only snapshot:** committed Git, history, tour, or supplied content that
+  cannot be replaced or saved over a source file.
+- **INDEX** and **WORKTREE:** repository work states; do not describe them as
+  commits.
+- **Explanation stage:** synthetic deconstructed content; never imply that it
+  is a real commit.
+- **Real revision:** a panel resolved from an exact Git object identity.
+
+Paths and labels are descriptive; object IDs, source descriptors, and compiled
+tour locators are authoritative identities.
+
+## Artifacts and production boundary
+
+| Artifact | Intended contents | Exclusions/check |
+| --- | --- | --- |
+| VSIX | Extension manifest, extension bundle, shared renderer assets/workers, public docs and icon | `scripts/check-vsix-contents.mjs` rejects unexpected files |
+| Desktop packages | Electron host, shared renderer, presenter, runtime assets | Production menus hide fixtures and DevTools |
+| npm CLI package | Launcher, CLI/tour runtime, required desktop support | Dry-run package-content validation |
+| Compiled tour | Bounded manifest plus exact referenced source evidence | Validation, reproducibility, and coverage checks |
+
+Only open-source Bygone fixtures may be committed to tests, examples,
+benchmarks, screenshots, tours, or release artifacts. Do not derive fixtures
+from proprietary repositories even if names and paths are removed.
+
+## Update checklist
+
+When changing the product surface:
+
+1. Add or revise the applicable row above.
+2. State the owning host, source identity, mutability, and lifecycle behavior.
+3. Link a representative automated test or checked-in example.
+4. Update command help, menus, package contributions, and user docs together.
+5. Verify production packages contain no development or proprietary material.

package/docs/repository-search-prototype.md

@@ -0,0 +1,67 @@
+# Repository search prototype
+
+Bygone exposes a read-only desktop **Edit → Search in Files…** workflow backed
+by the host-side `rg --json` adapter. Choose an explicit root, enter a query,
+and run the search; results stream into a bounded panel and open as read-only
+single-panel source views at the exact matched line.
+
+After a complete case-sensitive literal search, enter replacement text and
+choose **Preview Replace**. The preview groups occurrences by file and allows
+individual files to be excluded. Bygone confirms the selected totals, hashes
+and revalidates every file before writing, uses atomic same-directory writes,
+rolls back completed writes if a later write fails, and offers immediate Undo.
+Undo is rejected if any replaced file changed afterward. Regex and
+case-insensitive Replace in Files are intentionally unavailable because their
+match semantics must not diverge from ripgrep search results.
+
+## Current contract
+
+- The host passes an absolute root and structured options.
+- The adapter spawns an executable with an argument array and `shell: false`.
+- JSON lines are validated at runtime before becoming normalized matches.
+- Result paths must remain inside the selected root.
+- Result and stderr sizes are bounded.
+- Cancellation and truncation terminate the child process.
+- A superseding query cancels the previous process and stale batches are ignored.
+- Result navigation accepts only identities emitted by the active search,
+  rechecks root containment and file type, and rejects files modified after
+  the search began.
+- Unsaved editors, Git blobs, index content, tours, and synthetic stages are
+  outside this filesystem adapter and require their owning source adapters.
+
+## Distribution decision
+
+Bygone currently requires a detected system `rg`. It
+requires ripgrep 14 or newer, uses `BYGONE_RG_PATH` as an explicit executable
+override, and exposes **Help → Repository Search Status…**. **Search in Files…**
+routes to that status when the capability is unavailable. Missing,
+unparseable, and unsupported versions are explicit capability states. Bygone
+does not silently use a different regex/search engine.
+
+This keeps desktop packages small and makes availability explicit; repository
+search is therefore an optional system capability rather than a zero-setup
+core feature. The alternatives remain:
+
+1. Bundle verified, signed ripgrep binaries for every supported desktop target
+   and maintain their license/provenance/security updates.
+2. Require a system executable and provide clear capability, version, setup,
+   and unsupported-state guidance.
+3. Add a compatible fallback only with tests proving its regex, ignore, hidden,
+   symlink, binary, Unicode, and cancellation behavior matches the advertised
+   contract.
+
+Silent fallback to a different search language remains unacceptable.
+
+## Open-source benchmark
+
+Run:
+
+```bash
+npm run compile
+npm run perf:search
+```
+
+The benchmark creates a temporary synthetic tree, searches literal and regex
+queries, reports elapsed time and match counts, and deletes the tree. Adjust
+its scale with `BYGONE_SEARCH_BENCH_FILES`. It must not be pointed at or seeded
+from proprietary repositories for committed evidence.

package/docs/search.md

@@ -0,0 +1,56 @@
+# Search scopes and semantics
+
+Bygone uses the engine that owns each source. This keeps unsaved editor text,
+filesystem state, Git snapshots, and compiled tours accurate without pretending
+that their regex dialects or lifecycle rules are identical.
+
+| Scope | Engine/source | Options | Limit and freshness | Result behavior |
+| --- | --- | --- | --- | --- |
+| Active pane | Monaco model | Monaco Find options | Current in-memory model | Selects in the active pane; Replace only when writable |
+| Visible or all panels | Monaco models | Literal/regex, case | 500 current in-memory matches | Selects the exact loaded panel and range |
+| Current change set | Materialized session snapshots | Literal/JavaScript regex, case | 500 matches per request; rebuilt on request | Opens the changed file comparison and exact side |
+| File Git history | Materialized Git parent/commit blobs | Literal/JavaScript regex, case; content or introduction/removal | 500 matches per request; tied to loaded history | Opens the exact revision pair and base/head side |
+| Search in Files | System ripgrep 14+ | Literal/ripgrep regex, case, whole word, include/exclude globs, hidden and ignore policy | User-selected 100–5,000; cancellable; file revalidated before open | Opens a read-only source panel at the exact working-tree line |
+| Authored tour | Compiled manifest narrative and base/head snapshots | Case-insensitive literal; narrative/code scope | 300 manifest matches | Opens the exact scene/step or code side and preserves Return to tour |
+
+## Deliberate differences
+
+- Broad JavaScript-backed snapshot searches are line-oriented. Their regular
+  expressions do not span lines. Zero-length matches advance safely.
+- Search in Files uses ripgrep syntax and ignore behavior; Bygone does not
+  silently substitute JavaScript regular expressions when ripgrep is missing.
+- Tour search is intentionally literal and case-insensitive so presenter
+  navigation stays lightweight and predictable.
+- Whole-word matching is currently a ripgrep/Monaco capability, not a promise
+  made by every snapshot adapter.
+- Replace in Files is narrower than Search in Files: only completed,
+  case-sensitive literal searches can produce a preview. This lets the write
+  core reproduce exact matches without claiming regex-dialect compatibility.
+- Binary contents, OCR, submodules, remote workspaces, Git blobs outside the
+  loaded history, and unsaved Monaco text are not filesystem-search inputs.
+
+## Provenance and stale results
+
+Every scope keeps the identity needed by its owner: panel and range, changed
+file side, history entry and revision side, filesystem path and coordinates,
+or tour scene/step/file side. Filesystem result paths must remain within the
+selected real root, must have been emitted by the active request, and are
+rejected if the file changed after the search began. Superseding or closing a
+filesystem search cancels the ripgrep process and ignores late batches.
+Replacement previews additionally retain before/after hashes and bytes,
+revalidate all selected files before any write, roll back on write failure,
+and permit undo only while the after-hashes still match.
+
+## Performance fixtures
+
+All committed fixtures are generated locally from Bygone-owned text. Run:
+
+```bash
+npm run perf:search
+npm run perf:search-adapters
+```
+
+The repository benchmark covers 4,000 generated files. The adapter benchmark
+covers 120 change-set snapshots, 250 history revisions, and a 120-file tour.
+Each in-memory adapter has a deliberately generous 1,000 ms regression budget,
+overridable with `BYGONE_SEARCH_ADAPTER_BUDGET_MS` for profiling.

package/examples/deconstructed-diff.bygone

@@ -0,0 +1,49 @@
+version: 1
+title: Explain persistent tour markers in conceptual stages
+range:
+  base: d040a442657547340e5fa4dcc58bfc0d233ab989
+  head: b05ecc2c8998aa7569934dc7914c2e9924f7d0be
+anchors: {}
+connections: []
+chapters:
+  - id: explanation-order
+    title: Synthetic explanation stages
+    scenes:
+      - id: persistent-markers
+        kind: deconstructed-diff
+        title: Separate persistent markers from active emphasis
+        summary: Reorder one real commit into synthetic cumulative stages for teaching.
+        bullets:
+          - The source contract first permits several annotations.
+          - The presenter then marks every anchor and identifies the active one.
+          - The renderer finally separates persistent gutter markers from active text emphasis.
+        tags: [tours, explanation, synthetic]
+        takeaway: These panels are explanation stages, not historical commits.
+        base: d040a442657547340e5fa4dcc58bfc0d233ab989
+        target: b05ecc2c8998aa7569934dc7914c2e9924f7d0be
+        stages:
+          - id: contract
+            title: Carry every anchor
+            narration: Expand the host contract from one annotation to an active-marked collection.
+            changes:
+              - file: src/webviewMessages.ts
+                hunks: [hunk-64e041c7407c, hunk-f81ce869a41a]
+          - id: presentation
+            title: Build persistent and active annotations
+            narration: The tour host emits all anchors for the file and marks the current step active.
+            changes:
+              - file: web/host.js
+                hunks: [hunk-baa2982f00b2, hunk-a11ba6c61eab, hunk-c32fa33b08c9, hunk-3d642f820720, hunk-34282593627a]
+          - id: rendering
+            title: Emphasize only the active anchor
+            narration: The renderer gives every anchor a gutter decoration while reserving the text class and reveal target for the active one.
+            changes:
+              - file: media/script.js
+                hunks: [hunk-7ab25ee9fe44, hunk-229ff9b95257, hunk-208bf1e2739a, hunk-195c64e7ce9d, hunk-ca648f8b7f6d, hunk-0a640980b9b7, hunk-d005d43f28c8, hunk-814c1fb6cdf3, hunk-208dd701b2db, hunk-cd8f327f0940, hunk-9f54024f461a, hunk-56e6f514f9ae, hunk-45626d68d23d]
+              - file: test/runTests.js
+                hunks: [hunk-69f71617ff01, hunk-55f5ba472e6c]
+        exclusions:
+          - file: web/web-host.js
+            reason: Generated browser bundle; the source host is assigned above.
+          - file: web/web-host.js.map
+            reason: Generated source map; it carries no independent product behavior.

package/examples/stacked-diff.bygone

@@ -0,0 +1,55 @@
+version: 1
+title: Real revisions build the tour system
+range:
+  base: 23aa253d130338096a28860498bee67f7727636b
+  head: 7a6d000203a25410e44fac0f2393fb4ef4b6b9d1
+anchors: {}
+connections: []
+chapters:
+  - id: revision-stack
+    title: Follow real Git milestones
+    scenes:
+      - id: tour-capabilities
+        kind: stacked-diff
+        title: Grow the authored-tour contract
+        summary: Each panel is a real immutable revision in Bygone's open-source history.
+        bullets:
+          - The inventory establishes stable changed units.
+          - Coverage maps authored evidence onto those units.
+          - Stacked scenes then expose selected revisions as adjacent panels.
+        tags: [git, tours, history]
+        takeaway: Use stacked diffs only when the real revisions are meaningful milestones.
+        stack:
+          - id: baseline
+            ref: f66275c808b3dedca74f95cb355e3693287eeedd
+            label: Before tour inventory
+          - id: inventory
+            ref: fa61c9e7be161792531e6568db774a03c2fba3ba
+            label: Stable inventory
+          - id: coverage
+            ref: a532c60c2e44335efcee5c2d3bafa77bfd5628c4
+            label: Coverage reporting
+          - id: stacked
+            ref: 7a6d000203a25410e44fac0f2393fb4ef4b6b9d1
+            label: Stacked tours
+        files:
+          - src/changeTour.ts
+        steps:
+          - id: inventory-stage
+            title: Establish change identity
+            body: The first selected revision gives later authored evidence a stable change model.
+            file: src/changeTour.ts
+            pair: [baseline, inventory]
+            side: right
+          - id: coverage-stage
+            title: Connect evidence to coverage
+            body: The next real revision makes explanation depth and omitted work measurable.
+            file: src/changeTour.ts
+            pair: [inventory, coverage]
+            side: right
+          - id: stacked-stage
+            title: Present the historical sequence
+            body: The final revision compiles these real milestones into adjacent panels.
+            file: src/changeTour.ts
+            pair: [coverage, stacked]
+            side: right