my-frontend-observer 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [Unreleased]
+
+## 0.8.0 - 2026-09-10
+
+Interactive Local Observation Viewer.
+
+- New `view` command: starts a loopback-only (`127.0.0.1`) Node server
+  serving a React + TypeScript + Vite viewer application, usable in a normal
+  browser or as an installed Progressive Web App, over an existing evidence
+  root (`--root`). Metadata-first evidence discovery and on-demand
+  artifact/media loading; never mutates target source or any Observer
+  evidence artifact.
+- Observation inspection: screenshot plus SVG target overlays, geometry,
+  semantics, visibility/overflow/scroll evidence, and on-demand layout
+  relationships.
+- Comparison/contract inspection: before/after side-by-side views and
+  contract/change-scope evaluation results, including the required
+  protected/preserved-failure safety case (a locally successful requested
+  change alongside a genuine protected/preserved regression, shown as
+  overall `FAIL`).
+- External reference/candidate inspection: reference image and region
+  overlays, explicit (never auto-selected) candidate selection,
+  reference/candidate compatibility and applicability.
+- Explicit reference-region/runtime-target binding cross-selection
+  (`--bindings-file`), independent bounded zoom/pan, conditional view lock,
+  and on-demand reference-fidelity evaluation shown independently alongside
+  any selected contract evaluation.
+- Bounded agent context inspection (`--context-file`): session-only display
+  of context identity, adequacy, omissions/truncations, and runtime/static
+  correlation, plus safe raw-evidence navigation. The viewer never rebuilds
+  a bounded context or its correlation and never runs `@dailephd/my-dev-kit`.
+- PWA hardening: real service-worker registration, an application-shell
+  precache that excludes `/api/` routes, and a proven server-down behavior
+  that never presents stale evidence as current.
+- No second evidence engine: every canonical result the viewer displays is
+  produced by the same single engine the CLI uses, called from at most one
+  designated server-side call site.
+- Security hardening found during pre-release readiness: the viewer's media
+  route now rejects any evidence filename that is itself a symlink/junction
+  pointing outside the evidence root, instead of following it.
+- Cross-platform packed-candidate validation: the pre-version-bump
+  implementation candidate tarball `my-frontend-observer-0.7.0.tgz`
+  (SHA-256 `b80729bc64b3b01378effd2b8aa3b7743ccedc46b3148ba0b1ff1ae5a4b68c55`)
+  was hash-verified and proven on Windows, Linux, and macOS, including an
+  installed-package smoke of the new `view` command (loopback binding,
+  read-only API, path containment, SVG overlay/media, service-worker
+  registration, the PWA no-authoritative-cache boundary, and the
+  server-down stale-evidence hard gate) alongside every pre-existing
+  v0.1-v0.7 packed behavior, before this release's version bump - see
+  `docs/reports/v0.8-prerelease-readiness-cross-platform-security-code-rot.md`.
+
 ## 0.7.0 - 2026-09-06
 
 End-to-End Coding-Agent Frontend Change Review.

package/README.md

@@ -6,10 +6,11 @@ in [docs/PROJECT_DESCRIPTION.md](docs/PROJECT_DESCRIPTION.md).
 
 ## Current status
 
-`v0.7.0`, End-to-End Coding-Agent Frontend Change Review, is the current
-published release. It builds on `v0.6.0`, Bounded Agent Context and Native
-my-dev-kit Ecosystem Integration, and `v0.5.0`, Executable Frontend
-Contracts and Explicit Change Scope: `my-frontend-observer observe` launches a real,
+`v0.8.0`, Interactive Local Observation Viewer, is the current published
+release. It builds on `v0.7.0`, End-to-End Coding-Agent Frontend Change
+Review, `v0.6.0`, Bounded Agent Context and Native my-dev-kit Ecosystem
+Integration, and `v0.5.0`, Executable Frontend Contracts and Explicit Change
+Scope: `my-frontend-observer observe` launches a real,
 sandboxed Chromium browser, enforces a loopback-only safety policy, captures
 a viewport screenshot plus bounded page/target evidence, and persists it as
 one portable `manifest.json` + `screenshot.png` artifact (observation schema
@@ -170,6 +171,36 @@ this package) makes the actual source change between review attempts. See
 and [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for the full
 implementation record.
 
+### Interactive local viewer (v0.8.0)
+
+`my-frontend-observer view --root <evidence-root> [--bindings-file <json-file>] [--context-file <json-file>] [--port <n>] [--no-open]`
+starts a loopback-only (`127.0.0.1`) Node server that serves a React +
+TypeScript + Vite viewer application - usable in a normal browser or as an
+installed Progressive Web App - over the same evidence root used by every
+other command above. It never edits target source, never mutates any
+evidence artifact, and never runs `@dailephd/my-dev-kit`:
+
+```powershell
+my-frontend-observer view --root observations --port 4319 --no-open
+```
+
+(From a source checkout, use `node dist/cli.js view ...` instead.)
+
+The viewer shows observation screenshots and SVG target overlays,
+before/after comparisons and contract/change-scope results, approved
+external references beside candidate observations with explicit binding
+cross-selection and on-demand fidelity evaluation, and - when
+`--context-file` supplies one - a read-only inspection of a bounded agent
+context's adequacy, omissions/truncations, and runtime/static correlation.
+Both `--bindings-file` and `--context-file` are explicit, session-only
+input: read once at startup, held only in server memory, never persisted,
+and never exposed as a filesystem path to the browser. See
+[docs/COMMANDS.md](docs/COMMANDS.md#view) for the full flag reference and
+[docs/WORKFLOWS.md](docs/WORKFLOWS.md) for the viewer workflow.
+
+See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for the exact current
+implementation and release state.
+
 Validation:
 
 ```powershell
@@ -188,8 +219,8 @@ Planning authorities:
   intent and responsibility boundaries.
 - [Project Milestones](docs/PROJECT_MILESTONES.md): complete ordered capability
   design and cross-milestone rules.
-- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.7 are
-  released; v0.8+ remain future.
+- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.8 are
+  released; v0.9+ remain future.
 - [Current State](docs/CURRENT_STATE.md): retained scaffold and release state.
 
 No sibling ecosystem repository is a runtime dependency of the retained

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync, readFileSync } from 'node:fs';
+import { realpathSync, readFileSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { normalizeRequest } from './request/request.js';
 import { getProducerInfo } from './domain/schema.js';
@@ -9,6 +9,10 @@ import { approveAndPersistBaseline, persistPerChangeContract } from './applicati
 import { evaluateAndPersistFromArtifactRoots } from './application/frontendContractEvaluationService.js';
 import { importExternalReference, approveExternalReference } from './application/externalReferencePersistenceService.js';
 import { evaluateReferenceCandidateFidelityFromArtifactRoots } from './application/referenceFidelityEvaluationService.js';
+import { startViewer } from './viewerServer/viewerService.js';
+import { openInDefaultBrowser } from './viewerServer/openBrowser.js';
+import { DEFAULT_VIEWER_PORT } from './viewerServer/port.js';
+import { classifyContextFileContent, MAX_CONTEXT_FILE_BYTES } from './viewerServer/context.js';
 const defaultIO = {
     stdout: (text) => {
         process.stdout.write(text);
@@ -48,6 +52,9 @@ Commands:
                         reference/candidate compatibility, and explicit
                         region-to-target bindings. Prints a structured
                         result; persists nothing.
+  view                   Start the local, loopback-only viewer server and
+                        print its URL for a normal browser or an installed
+                        Progressive Web App.
 
 Options:
   --help     Show this help.
@@ -55,6 +62,80 @@ Options:
 
 Run "my-frontend-observer <command> --help" for command-specific options.
 `;
+const VIEW_HELP = `Usage:
+  my-frontend-observer view --root <evidence-root> [--bindings-file <json-file>] [--context-file <json-file>] [options]
+
+Required:
+  --root <path>   Local evidence-root directory the viewer session
+                  represents. Validated operationally (must exist and be a
+                  directory) - this batch does not read or interpret any
+                  Observer artifacts under it.
+
+Options:
+  --port <n>      TCP port to bind, in [0, 65535]. Defaults to ${DEFAULT_VIEWER_PORT}.
+                  An explicit alternate port is a different web origin than
+                  the default - an installed PWA is not portable across
+                  origins. If the requested port is already in use, this
+                  command fails with an actionable error; it never silently
+                  falls back to a different port.
+  --bindings-file <json-file>  Local JSON file of the form
+                  { "bindings": [ { "referenceRegion": "...", "runtimeTarget": "..." } ] }
+                  (the exact same operational wrapper format as
+                  \`evaluate-reference-fidelity --bindings-file\`, sharing its
+                  parser). Explicit, session-only viewer input: read once at
+                  startup, never persisted, never written into any Observer
+                  artifact, and never exposed as a path to the browser. Its
+                  declarations become available for on-demand binding/
+                  fidelity evaluation once a reference and candidate are
+                  explicitly selected in the viewer. Reference-specific
+                  validity (region existence, etc.) is checked when a
+                  reference is actually selected, not at startup - only the
+                  file's own readability/JSON/wrapper shape is validated at
+                  startup. Omit to run with no binding declarations (the
+                  viewer remains fully usable; cross-selection stays
+                  disabled).
+  --context-file <json-file>  Local JSON file containing exactly one
+                  BoundedAgentContextArtifact value directly (no wrapper
+                  object) - e.g. { "artifactKind":
+                  "my-frontend-observer/bounded-agent-context",
+                  "schemaVersion": "1.0.0", ... }. Explicit, session-only
+                  viewer input: read once at startup, validated through the
+                  existing canonical isValidBoundedAgentContextArtifact,
+                  held only in server memory, never persisted, never written
+                  into any Observer artifact, and never exposed as a path to
+                  the browser. Bounded agent context remains programmatic-
+                  only as an Observer-produced contract - this command does
+                  not add a way to generate, save, or write one; the viewer
+                  never rebuilds it (no projectBoundedAgentContext call) and
+                  never derives runtime/static correlation (no
+                  deriveRuntimeStaticCorrelations/attachRuntimeStaticCorrelations
+                  call) - it only displays the exact context it was given.
+                  A recognized artifactKind with a schemaVersion other than
+                  the currently supported one starts the viewer showing an
+                  honest "unsupported version" context state rather than
+                  failing. An unreadable file, invalid JSON, wrong
+                  artifactKind, or a structurally invalid current-schema
+                  artifact fails startup clearly. Omit to run with no
+                  bounded context supplied (the viewer remains fully usable;
+                  the context panel says none was supplied). May be combined
+                  with --bindings-file.
+  --no-open       Do not attempt to open the system default browser after
+                  the server starts. Browser auto-open is a best-effort
+                  convenience only: its failure is never fatal and never
+                  affects server startup success.
+  --help          Show this help.
+
+Starts one Node HTTP server bound only to 127.0.0.1, serving the built
+React + TypeScript + Vite viewer application (and its PWA manifest/service
+worker) plus one minimal read-only status endpoint. The server never writes
+to the supplied evidence root, never exposes it as a generic static
+directory, and never launches a browser observation. The process keeps
+running (serving the viewer) until interrupted. On success, prints the
+viewer URL and exits only when the server stops. On invalid syntax, a
+missing/non-directory --root, an invalid --port, or a port already in use,
+prints structured diagnostics to stderr and exits nonzero without starting
+a server.
+`;
 const OBSERVE_HELP = `Usage:
   my-frontend-observer observe --url <loopback-url> [options]
 
@@ -715,6 +796,51 @@ function loadBindingsFile(filePath) {
     }
     return { ok: true, bindings: record.bindings };
 }
+/**
+ * v0.8 Batch 7 CLI/input-boundary-only responsibility, mirroring
+ * `loadBindingsFile`'s exact shape: read one local JSON file (size-bounded
+ * via `MAX_CONTEXT_FILE_BYTES`, checked via `statSync` before ever reading
+ * the file's bytes), parse it, and hand the parsed value to
+ * `classifyContextFileContent` - every artifactKind/schemaVersion/structural
+ * rule stays owned there (which itself defers all current-schema structural
+ * validation to the existing canonical `isValidBoundedAgentContextArtifact`,
+ * never a second validator). Unlike `--bindings-file`, the context file's
+ * root IS the artifact value directly (task §12) - no wrapper object. The
+ * file path itself is never returned beyond this function.
+ */
+function loadContextFile(filePath) {
+    let size;
+    try {
+        size = statSync(filePath).size;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--context-file could not be read: ${message}` };
+    }
+    if (size > MAX_CONTEXT_FILE_BYTES) {
+        return { ok: false, error: `--context-file exceeds the bounded size limit (${MAX_CONTEXT_FILE_BYTES} bytes)` };
+    }
+    let rawText;
+    try {
+        rawText = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--context-file could not be read: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--context-file is not valid JSON: ${message}` };
+    }
+    const classified = classifyContextFileContent(parsed);
+    if (!classified.ok)
+        return { ok: false, error: classified.error };
+    return { ok: true, state: classified.state };
+}
 /**
  * CLI/input-boundary-only responsibility: read one local JSON file, validate
  * only the root wrapper this file format owns (object root, exactly the
@@ -1858,6 +1984,173 @@ async function runEvaluateReferenceFidelityCommand(argv, io) {
         return 1;
     return 0;
 }
+/** CLI-syntax-only parsing, mirroring `parseApproveBaselineArgs`. `--port` shape/range checking happens here; root existence/directory-ness is the application layer's job (see `startViewer`). */
+function parseViewArgs(argv) {
+    const errors = [];
+    let root;
+    let rootFlagCount = 0;
+    let port;
+    let portFlagCount = 0;
+    let noOpen = false;
+    let bindingsFilePath;
+    let bindingsFileFlagCount = 0;
+    let contextFilePath;
+    let contextFileFlagCount = 0;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--root': {
+                const value = argv[(i += 1)];
+                rootFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--root requires a path argument');
+                else if (rootFlagCount > 1)
+                    errors.push('--root may only be specified once');
+                else
+                    root = value;
+                break;
+            }
+            case '--port': {
+                const value = argv[(i += 1)];
+                portFlagCount += 1;
+                if (value === undefined) {
+                    errors.push('--port requires a numeric argument');
+                }
+                else if (portFlagCount > 1) {
+                    errors.push('--port may only be specified once');
+                }
+                else {
+                    const parsed = Number(value);
+                    if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+                        errors.push(`--port must be an integer between 0 and 65535; got ${JSON.stringify(value)}`);
+                    }
+                    else {
+                        port = parsed;
+                    }
+                }
+                break;
+            }
+            case '--no-open':
+                noOpen = true;
+                break;
+            case '--bindings-file': {
+                const value = argv[(i += 1)];
+                bindingsFileFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--bindings-file requires a file path argument');
+                else if (bindingsFileFlagCount > 1)
+                    errors.push('--bindings-file may only be specified once');
+                else
+                    bindingsFilePath = value;
+                break;
+            }
+            case '--context-file': {
+                const value = argv[(i += 1)];
+                contextFileFlagCount += 1;
+                if (value === undefined)
+                    errors.push('--context-file requires a file path argument');
+                else if (contextFileFlagCount > 1)
+                    errors.push('--context-file may only be specified once');
+                else
+                    contextFilePath = value;
+                break;
+            }
+            default:
+                errors.push(`unrecognized argument: ${arg}`);
+        }
+    }
+    if (root === undefined)
+        errors.push('--root is required');
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return {
+        ok: true,
+        root: root,
+        ...(port === undefined ? {} : { port }),
+        noOpen,
+        ...(bindingsFilePath === undefined ? {} : { bindingsFilePath }),
+        ...(contextFilePath === undefined ? {} : { contextFilePath }),
+    };
+}
+/**
+ * Thin orchestration only: parse args, delegate to the existing
+ * `startViewer` application function exactly once, print status, and
+ * optionally attempt a best-effort browser open. Never parses Observer
+ * artifacts, never derives evidence, never mutates anything. Returns as soon
+ * as the server is confirmed listening (or has failed to start) - the
+ * process itself keeps running afterward only because the server's open
+ * listening socket keeps the Node event loop alive, not because this
+ * function blocks.
+ */
+async function runViewCommand(argv, io) {
+    if (argv.includes('--help')) {
+        io.stdout(VIEW_HELP);
+        return 0;
+    }
+    const parsedArgs = parseViewArgs(argv);
+    if (!parsedArgs.ok) {
+        for (const error of parsedArgs.errors)
+            io.stderr(`error: ${error}\n`);
+        io.stderr(VIEW_HELP);
+        return 1;
+    }
+    // Reuses the exact same operational binding-file wrapper parser as `evaluate-reference-fidelity --bindings-file`
+    // (see loadBindingsFile above) - one shared parser, never a second divergent one. Reference-specific declaration
+    // validity (region existence, shape) is deferred to the moment a reference is actually selected in the viewer,
+    // via the existing canonical isValidReferenceRuntimeBindingDeclarations - never checked here without a reference.
+    let bindingDeclarations = [];
+    if (parsedArgs.bindingsFilePath !== undefined) {
+        const loaded = loadBindingsFile(parsedArgs.bindingsFilePath);
+        if (!loaded.ok) {
+            io.stderr(`error: ${loaded.error}\n`);
+            io.stderr(VIEW_HELP);
+            return 1;
+        }
+        if (!Array.isArray(loaded.bindings)) {
+            io.stderr('error: --bindings-file "bindings" property must be an array\n');
+            io.stderr(VIEW_HELP);
+            return 1;
+        }
+        bindingDeclarations = loaded.bindings;
+    }
+    // Reuses the exact same canonical validator (isValidBoundedAgentContextArtifact, via
+    // classifyContextFileContent) that owns current-schema structural validity - never a second validator.
+    // A recognized-kind, non-current-schema file is not a startup failure (task §16); every other problem is.
+    let contextState = { status: 'none' };
+    if (parsedArgs.contextFilePath !== undefined) {
+        const loaded = loadContextFile(parsedArgs.contextFilePath);
+        if (!loaded.ok) {
+            io.stderr(`error: ${loaded.error}\n`);
+            io.stderr(VIEW_HELP);
+            return 1;
+        }
+        contextState = loaded.state;
+    }
+    const result = await startViewer({
+        root: parsedArgs.root,
+        ...(parsedArgs.port === undefined ? {} : { port: parsedArgs.port }),
+        bindingDeclarations,
+        context: contextState,
+    });
+    if (!result.ok) {
+        for (const diagnostic of result.diagnostics)
+            io.stderr(`${formatDiagnostic(diagnostic)}\n`);
+        return 1;
+    }
+    io.stdout(`Viewer: ${result.url}\n`);
+    io.stdout(`Root: ${result.root}\n`);
+    io.stdout(`Press Ctrl+C to stop.\n`);
+    if (!parsedArgs.noOpen) {
+        try {
+            await openInDefaultBrowser(result.url);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            io.stderr(`note: could not open the default browser automatically: ${message}\n`);
+        }
+    }
+    return 0;
+}
 /** Testable CLI entry point: pure function of argv (+ injectable IO), no direct process.exit. */
 export async function runCli(argv, io = defaultIO) {
     const [command, ...rest] = argv;
@@ -1897,6 +2190,9 @@ export async function runCli(argv, io = defaultIO) {
     if (command === 'evaluate-reference-fidelity') {
         return runEvaluateReferenceFidelityCommand(rest, io);
     }
+    if (command === 'view') {
+        return runViewCommand(rest, io);
+    }
     io.stderr(`error: unrecognized command "${command}"\n`);
     io.stderr(TOP_LEVEL_HELP);
     return 1;