@davmash/bygone 0.8.14 → 0.9.2

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## Unreleased
 
+## 0.9.2
+
+- Documented the stable v3 tour contract, compatibility policy, and evidence-linked review notes
+- Updated Electron and vulnerable packaging dependencies within their existing major versions
+- Shared the expanded commit navigator across tours, History, and Compare, with explicit draft submission and loaded-panel badges
+- Kept History's commit axis and expanded panels stable across files, with markers for commits that changed the current file
+- Preserved navigator tabs and comparison drafts across mode switches
+- Replaced tour mode and comparison endpoint drop-downs with direct mode buttons and multi-select revision comparison
+- Added two-or-more-panel Compare views ordered from oldest to newest with adjacent diffs
+- Unified Present navigation into one Tour, Files, or Commits navigator
+- Made tours a continuous reading flow through title, chapters, scene overviews, and steps, with a collapsible outline and scene context above each step
+- Added shared workspace tour discovery, editable skill-based v3 authoring prompts, and same-repository transitions into History
+- Clarified tour mode restoration and directory overview scope while preserving first-visit History context
+
+macOS desktop downloads are unsigned and not notarized. If Gatekeeper reports
+the app as damaged, run `xattr -cr /Applications/Bygone.app`, then reopen it.
+
+## 0.9.1
+
+- Restored authored Final walkthroughs and legacy Final deep links for version 2 deconstructed tours
+- Reused the full revision rail and toolbar in tour History mode while preserving the selected file on first entry
+- Expanded Files and Tour details by default and kept Scene context available alongside the active step
+
+## 0.9.0
+
+- Added independently authored Historical and Deconstructed tours with stable per-mode reading positions
+- Added optional scene-level directory overviews with safe repository-relative scoping and authored comparison endpoints
+- Added evidence-linked review notes for concepts, boundaries, tradeoffs, and open questions
+- Introduced source and manifest format v3 for the new tour metadata while preserving v1 and v2 compatibility
+
+## 0.8.16
+
+- Clarified authored-tour errors when a document requires a newer format version
+- Made tag-triggered npm release checks fetch repository history needed by checked-in tour fixtures
+
+## 0.8.15
+
+- Fixed v2 deconstructed-tour coverage so authored Final-mode walkthrough anchors determine coverage while Explanation assignment completeness remains a separate metric
+- Added distinct Final walkthrough coverage and Explanation assignment indicators to authored tours in the Present sidebar
+
 ## 0.8.14
 
 - Reorganized desktop menus around familiar File, Edit, Git, Present, Navigate, View, and Window responsibilities while exposing file, directory, revision, branch, history, tour, and blank-comparison workflows

package/README.md

@@ -123,7 +123,7 @@ Change tours can layer an authored, code-connected narrative over the complete g
 
 Packaged macOS builds register `.bygone` with the desktop app, so Finder can open a presentation directly. Windows and Linux builds currently require opening the file through Bygone or the `bygone` command; they do not install an operating-system file association.
 
-Agents can validate anchors and structure with `bygone tour validate <file.bygone> --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).
+Agents can validate anchors and structure with `bygone tour validate <file.bygone> --json`, compile a repository-bound 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).
 
 Install the agent skill:
 
@@ -210,7 +210,7 @@ Publishing is intentionally explicit:
 npm run release:publish
 ```
 
-Run `release:publish` after committing the version and release changes. It aborts unless the worktree is clean and the current branch is `main`, pushes `main`, waits for that exact commit's GitHub Release Check workflow, rebuilds and installs all local artifacts, publishes the npm package, creates a GitHub release for desktop artifacts, and updates the Homebrew tap. It launches npm browser login when needed and pauses immediately before an unpublished version's time-limited passkey challenge. The tap checkout defaults to the sibling `homebrew-bygone` directory; set `BYGONE_HOMEBREW_TAP` to override it. Until Marketplace trusted-publisher policies are publicly configurable, upload the packaged VSIX from the Visual Studio Marketplace publisher page.
+Run `release:publish` after committing the version and release changes. It aborts unless the worktree is clean and the current branch is `main`, pushes `main`, waits for that exact commit's GitHub Release Check workflow, rebuilds and installs all local artifacts, creates a GitHub release for desktop artifacts, and updates the Homebrew tap. The release tag triggers the protected GitHub Actions Release workflow, which publishes the npm package through trusted publishing after approval. The tap checkout defaults to the sibling `homebrew-bygone` directory; set `BYGONE_HOMEBREW_TAP` to override it. Until Marketplace trusted-publisher policies are publicly configurable, upload the packaged VSIX from the Visual Studio Marketplace publisher page.
 
 Reinstall the current built artifacts without rebuilding:
 

package/cli/commandSpec.js

@@ -10,6 +10,7 @@ const CLI_SPEC = Object.freeze({
         'bygone --diff <file1> <file2> <file3> [...]',
         'bygone --history <path>',
         'bygone --git-diff <ref1> <ref2> [<ref3>...]',
+        'bygone --read-only <desktop-arguments...>',
         'bygone review [<head>] [--base <base>]',
         'bygone -C <directory> <command-or-path> [...]',
         'bygone present [<head>] [--base <base>] [--tour <file.bygone>]',
@@ -107,6 +108,13 @@ const CLI_SPEC = Object.freeze({
             description: 'Use an authored .bygone presentation',
             argument: 'path'
         },
+        {
+            id: 'readOnly',
+            kind: 'global',
+            tokens: ['--read-only'],
+            description: 'Open live Explore sources without allowing edits',
+            argument: 'none'
+        },
         {
             id: 'directory',
             kind: 'global',
@@ -144,13 +152,15 @@ const CLI_SPEC = Object.freeze({
         '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.',
+        'In `--git-diff`, committed refs and INDEX are read-only; WORKTREE (also WORKDIR or WORKINGTREE) is live and writable.',
+        '`--read-only` prevents editing every live file or WORKTREE panel in the launched Explore session.',
         '`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.',
         '`-C <directory>` resolves relative paths and Git refs from that directory without changing the shell working directory.',
         '`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 compile` writes a repository-bound 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.',
+        '`tour coverage` reports authored walkthrough anchor coverage and author-declared explanation depth; for v2 tours it reads Final mode and reports deconstructed Explanation assignment separately, while `--minimum-coverage` gates the walkthrough metric.',
         '`--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.'

package/cli/completions.js

@@ -75,7 +75,7 @@ ${legacyOptions}
 ${historyOptions}
     )
     shells=('zsh:Z shell' 'bash:Bash' 'fish:Fish shell')
-    tour_actions=('context:Build structured change evidence' 'coverage:Measure authored tour coverage' 'validate:Validate source and anchors' 'compile:Compile a portable manifest' 'schema:Print the source schema')
+    tour_actions=('context:Build structured change evidence' 'coverage:Measure authored tour coverage' 'validate:Validate source and anchors' 'compile:Compile a repository-bound manifest' 'schema:Print the source schema')
 
     if (( CURRENT == 2 )); then
         _describe 'bygone command' root_items

package/cli/present.js

@@ -3,9 +3,11 @@ const { createServer } = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
 const { buildChangeTourManifest, parseChangeTourStory } = require('../out/changeTour.js');
+const { buildTourAuthoringCoverage, buildTourCoverageReport } = require('../out/tourCoverage.js');
 const { buildTourWindowTitle } = require('../out/windowTitle.js');
 const { tokenMatches } = require('./commandSpec.js');
-const { loadTourSource } = require('./tourFile.js');
+const { loadTourSource, parseTourSourceText, buildManifestForTourSource } = require('./tourFile.js');
+const { createTourHistory } = require('./tourHistory.js');
 
 const MIME_TYPES = new Map([
     ['.css', 'text/css; charset=utf-8'],
@@ -19,20 +21,24 @@ const MIME_TYPES = new Map([
 
 async function startPresentation(args, cwd, packageRoot, options = {}) {
     const { headRef, baseRef, tourPath, explicitHeadRef } = parsePresentArgs(args);
-    const story = process.env.BYGONE_TOUR_STORY
+    const story = !options.ignoreEnvironment && 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, {
+    const builtManifest = 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,
+        title: options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_TITLE,
+        sourceUrl: options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_SOURCE_URL,
         story,
         source
     });
+    const manifest = source
+        ? { ...builtManifest, authoringCoverage: buildTourAuthoringCoverage(buildTourCoverageReport(cwd, source)) }
+        : builtManifest;
+    const history = createTourHistory(manifest);
     const serializedManifest = `${JSON.stringify(manifest, null, 2)}\n`;
-    const outputPath = process.env.BYGONE_TOUR_OUTPUT;
+    const outputPath = options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_OUTPUT;
     if (outputPath) {
         const resolvedOutput = path.resolve(cwd, outputPath);
         mkdirSync(path.dirname(resolvedOutput), { recursive: true });
@@ -43,9 +49,75 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
     const tourWindowTitle = buildTourWindowTitle(manifest, 'Bygone');
     const presenterIndexPath = path.join(packageRoot, 'web', 'index.html');
     let presenterIndexTemplate;
+    // Uploaded documents remain immutable, scoped to this existing repository,
+    // and addressed independently so opening one cannot mutate another tab.
+    const uploadedTours = new Map();
 
     const server = createServer((request, response) => {
         const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
+        if (requestUrl.pathname === '/tour/open') {
+            if (request.method !== 'POST') return respondJson(response, 405, { error: 'Method not allowed' });
+            if (!isSameOriginLoopbackRequest(request)) return respondJson(response, 403, { error: 'Forbidden' });
+            if (uploadedTours.size >= 16) return respondJson(response, 409, { error: 'This presentation has reached its open-document limit. Start a new presentation to open more documents.' });
+            let body = '';
+            request.setEncoding('utf8');
+            request.on('data', (chunk) => {
+                body += chunk;
+                if (Buffer.byteLength(body, 'utf8') > 2 * 1024 * 1024) { respondJson(response, 413, { error: 'Request too large' }); request.destroy(); }
+            });
+            request.on('end', () => {
+                if (response.writableEnded) return;
+                try {
+                    const uploadedSource = parseTourSourceText(JSON.parse(body).source);
+                    const loaded = buildManifestForTourSource(cwd, uploadedSource);
+                    const id = String(uploadedTours.size + 1);
+                    uploadedTours.set(id, { manifest: loaded, history: createTourHistory(loaded) });
+                    respondJson(response, 200, { manifestUrl: `/loaded/${id}/tour.json`, repository: loaded.repository?.root || cwd, range: loaded.range });
+                } catch (error) { respondJson(response, 400, { error: `Invalid tour for this repository: ${error.message}` }); }
+            });
+            return;
+        }
+        const loadedMatch = requestUrl.pathname.match(/^\/loaded\/(\d+)\/(tour\.json|history\/(?:list|diff|compare|compare-many|revisions))$/);
+        const loadedTour = loadedMatch ? uploadedTours.get(loadedMatch[1]) : null;
+        if (loadedMatch && !loadedTour) return respondJson(response, 404, { error: 'Loaded document not found' });
+        if (loadedTour && loadedMatch[2] === 'tour.json') return respondJson(response, 200, loadedTour.manifest);
+        const requestHistory = loadedTour ? loadedTour.history : history;
+        if (loadedMatch) requestUrl.pathname = `/${loadedMatch[2]}`;
+        if (requestUrl.pathname === '/history/list' || requestUrl.pathname === '/history/diff'
+            || requestUrl.pathname === '/history/compare' || requestUrl.pathname === '/history/compare-many'
+            || requestUrl.pathname === '/history/revisions') {
+            if (request.method !== 'POST') return respondJson(response, 405, { error: 'Method not allowed' });
+            if (!isSameOriginLoopbackRequest(request)) return respondJson(response, 403, { error: 'Forbidden' });
+            if (!requestHistory) return respondJson(response, 404, { error: 'History requires a version 2 tour.' });
+            let body = '';
+            request.setEncoding('utf8');
+            request.on('data', chunk => {
+                body += chunk;
+                if (body.length > 8192) {
+                    respondJson(response, 413, { error: 'Request too large' });
+                    request.destroy();
+                }
+            });
+            request.on('end', () => {
+                if (response.writableEnded) return;
+                try {
+                    const input = JSON.parse(body);
+                    const result = requestUrl.pathname === '/history/list'
+                        ? requestHistory.list(input)
+                        : requestUrl.pathname === '/history/diff'
+                            ? requestHistory.diff(input)
+                            : requestUrl.pathname === '/history/compare'
+                                ? requestHistory.compare(input)
+                                : requestUrl.pathname === '/history/compare-many'
+                                    ? requestHistory.compareMany(input)
+                                    : requestHistory.revisions(input);
+                    respondJson(response, 200, result);
+                } catch {
+                    respondJson(response, 400, { error: 'Could not load history for this file and revision.' });
+                }
+            });
+            return;
+        }
         if (requestUrl.pathname === '/narration/claim') {
             if (request.method !== 'POST') {
                 respond(response, 405, 'Method not allowed');
@@ -94,7 +166,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         });
         createReadStream(targetPath).on('error', () => respond(response, 500, 'Read failed')).pipe(response);
     });
-    const requestedPort = readPort(process.env.BYGONE_TOUR_PORT);
+    const requestedPort = readPort(options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_PORT);
     await new Promise((resolve, reject) => {
         server.once('error', reject);
         server.listen(requestedPort, '127.0.0.1', resolve);
@@ -194,6 +266,16 @@ function respond(response, statusCode, message) {
     response.end(message);
 }
 
+function respondJson(response, statusCode, body) {
+    if (!response.headersSent) {
+        response.writeHead(statusCode, {
+            'Content-Type': 'application/json; charset=utf-8',
+            'Cache-Control': 'no-store'
+        });
+    }
+    response.end(JSON.stringify(body));
+}
+
 function isSameOriginLoopbackRequest(request) {
     const origin = request.headers.origin;
     const host = request.headers.host;

package/cli/tour.js

@@ -27,7 +27,8 @@ function runTourCommand(args, cwd, packageRoot, output = process.stdout) {
         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}%.`);
+            const label = report.version === 2 ? 'Final walkthrough coverage' : 'Tour coverage';
+            throw new Error(`${label} ${report.totals.coveragePercent}% is below the required ${options.minimumCoverage}%.`);
         }
         return { action: 'coverage', sourcePath: resolvedPath, report };
     }
@@ -98,10 +99,20 @@ function parseTourArgs(args) {
 }
 
 function renderCoverageReport(report) {
+    const coverageLabel = report.version === 2 ? 'Final walkthrough coverage' : 'Tour coverage';
     const lines = [
-        `Tour coverage: ${report.totals.coveredUnits}/${report.totals.includedUnits} hunks (${report.totals.coveragePercent}%)`,
+        `${coverageLabel}: ${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.version === 2) {
+        for (const assignment of report.explanationAssignments) {
+            const suffix = report.explanationAssignments.length > 1 ? ` (${assignment.sceneId})` : '';
+            lines.push(
+                `Explanation assignment${suffix}: ${assignment.completeUnits}/${assignment.totalUnits} hunks `
+                + `(${assignment.assignmentPercent}%; ${assignment.assignedUnits} assigned, ${assignment.excludedUnits} excluded)`
+            );
+        }
+    }
     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(', ')})`);

package/cli/tourFile.js

@@ -48,6 +48,14 @@ function readTourSourceDocument(sourcePath, options = {}) {
         throw new Error(`Could not decode Bygone source ${sourceLabel} as UTF-8: ${errorMessage(error)}`, { cause: error });
     }
 
+    return parseTourSourceText(text, sourceLabel, { maxBytes });
+}
+
+function parseTourSourceText(text, sourceLabel = 'uploaded tour', options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_TOUR_SOURCE_BYTES;
+    if (typeof text !== 'string' || Buffer.byteLength(text, 'utf8') > maxBytes || text.includes('\0')) {
+        throw new Error('Invalid tour text or source size limit exceeded.');
+    }
     let documents;
     try {
         documents = loadYamlDocuments(text);
@@ -84,5 +92,6 @@ module.exports = {
     DEFAULT_MAX_TOUR_SOURCE_BYTES,
     buildManifestForTourSource,
     loadTourSource,
+    parseTourSourceText,
     readTourSourceDocument
 };