Open a rendered Inspector without hunting for its output path

Traceability

• Spec ID: inspector-open-flag
• Status: Implemented
• Extends the CLI contract of harness-inspector; the report content and evidence rules are unchanged.

Intent

harness-inspector render writes a self-contained HTML file and prints its path, so the shortest path to actually reading a report was to copy that path into a browser or a preview server by hand. This slice closes the last step of the loop: one flag that opens the file that was just written, plus repository scripts that make the default, current-project render a single command.

Opening is a convenience over an artifact that already exists. It must not change what is collected, and it must not turn a written report into a failed run when the machine has no usable handler.

Acceptance Scenarios

• AC-1: render --open opens the written report in the default handler and reports the launch as opened in its stdout summary. The file exists before the handler is launched.
• AC-2: Without --open, no handler is launched and the summary carries no opened field, so existing consumers of the summary are unaffected.
• AC-3: --open is a valueless flag: it does not consume the next argument, --open twice is a duplicate-option usage error, and --open true is a usage error rather than a silently swallowed value. Value options still require a value.
• AC-4: The handler receives an absolute file:// URL, so a relative --out and a Windows drive path both resolve to the intended file.
• AC-5: A failed or unavailable handler reports opened: false and keeps the exit code at 0; --help still prints help without opening anything.
• AC-6: npm run inspector renders the current project with default bounds and npm run inspector:open does the same and opens the result.

Non-goals

• Serving the report over HTTP or reusing the Canvas preview server.
• Choosing a specific browser, profile, or window.
• Changing default collection bounds, output path, or report content.
• Adding an open flag to other Better Harness commands.

Design Decisions

Reuse the existing platform seam. openRenderedReport wraps openBrowser from scripts/harness-analysis/preview-support/platform.mjs, which already resolves open, cmd /c start, and xdg-open per platform and detaches the child. No second cross-platform launcher is introduced.

File URL, not file path. The path is resolved and converted with pathToFileURL, because a bare relative path would resolve against the browser and a Windows path is not a URL.

Best effort, after the write. The launch happens after writeFile, and its result is reported rather than thrown. A report that exists on disk is the deliverable; the viewer is not.

Booleans are parsed as booleans. The render parser gained an explicit valueless-flag set instead of treating every flag as flag value, so --open cannot eat the following argument.

Injectable opener. main(argv, \{ open \}) takes the opener as runtime, which is how the wiring is tested without launching a browser in CI.

Test and Review Evidence

• AC-1/AC-2: render writes the report before opening it and reports the launch in its summary and render leaves the browser alone when --open is absent render into a seeded temporary Git workspace with an injected opener.
• AC-3: --open is parsed as a valueless flag without consuming the next argument.
• AC-4/AC-5: opening a report launches an absolute file URL and reports launch failure.
• AC-6: npm run inspector, npm run inspector:open, and node scripts/harness-inspector/cli.mjs render --open run against this repository; the summary reported opened: true and the report rendered.
• Regression: test/reporting/harness-inspector.test.mjs (23 tests) and test/reporting/preview-servers.test.mjs, which pins the packaged preview script entrypoints.

Risks

• Side effect: --open is the only Inspector flag that launches a process. It is opt-in, absent from --help execution, and unused by the default npm run inspector.
• Environment: a headless or handler-less machine reports opened: false; the written path stays the primary output.
• Privacy: the opened URL is the local output path the summary already prints; no new content is retained or transmitted.