@dailephd/my-frontend-observer 0.8.1

package/dist/viewerServer/openBrowser.js

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+/**
+ * Best-effort convenience only: opens the platform default browser at `url`
+ * using OS-native commands (no dependency). Failure here must never affect
+ * viewer server startup success - callers treat a rejected promise as
+ * non-fatal and continue with the server already running.
+ */
+export function openInDefaultBrowser(url) {
+    return new Promise((resolvePromise, reject) => {
+        let command;
+        let args;
+        if (process.platform === 'win32') {
+            command = 'cmd';
+            args = ['/c', 'start', '""', url];
+        }
+        else if (process.platform === 'darwin') {
+            command = 'open';
+            args = [url];
+        }
+        else {
+            command = 'xdg-open';
+            args = [url];
+        }
+        const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+        child.once('error', reject);
+        child.once('spawn', () => {
+            child.unref();
+            resolvePromise();
+        });
+    });
+}
+//# sourceMappingURL=openBrowser.js.map

package/dist/viewerServer/openBrowser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openBrowser.js","sourceRoot":"","sources":["../../src/viewerServer/openBrowser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE;QAC5C,IAAI,OAAe,CAAC;QACpB,IAAI,IAAc,CAAC;QACnB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,OAAO,GAAG,KAAK,CAAC;YAChB,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACpC,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACzC,OAAO,GAAG,MAAM,CAAC;YACjB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,UAAU,CAAC;YACrB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3F,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACvB,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,cAAc,EAAE,CAAC;QACnB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/viewerServer/port.d.ts

@@ -0,0 +1,16 @@
+/**
+ * v0.8 Batch 1: fixed default loopback origin for the local viewer server, so
+ * an installed PWA has a stable identity across launches. No fixture or test
+ * in this repository binds a fixed TCP port (see tests/fixtures/server.ts,
+ * which always requests port 0 / OS-assigned), so 4319 was chosen as an
+ * uncommon, unreserved default that does not collide with common local dev
+ * ports (3000, 5173/4173 Vite, 8080, 8000) or any port referenced elsewhere
+ * in this repository.
+ */
+export declare const DEFAULT_VIEWER_PORT = 4319;
+/** The viewer server binds only to loopback - never 0.0.0.0 or any other host. */
+export declare const VIEWER_HOST = "127.0.0.1";
+export declare const VIEWER_PORT_MIN = 1;
+export declare const VIEWER_PORT_MAX = 65535;
+/** Strict validation for an explicit --port value: an integer in the valid TCP port range (0 is allowed only for deterministic test use - the OS assigns an ephemeral port). */
+export declare function isValidViewerPort(value: number): boolean;

package/dist/viewerServer/port.js

@@ -0,0 +1,19 @@
+/**
+ * v0.8 Batch 1: fixed default loopback origin for the local viewer server, so
+ * an installed PWA has a stable identity across launches. No fixture or test
+ * in this repository binds a fixed TCP port (see tests/fixtures/server.ts,
+ * which always requests port 0 / OS-assigned), so 4319 was chosen as an
+ * uncommon, unreserved default that does not collide with common local dev
+ * ports (3000, 5173/4173 Vite, 8080, 8000) or any port referenced elsewhere
+ * in this repository.
+ */
+export const DEFAULT_VIEWER_PORT = 4319;
+/** The viewer server binds only to loopback - never 0.0.0.0 or any other host. */
+export const VIEWER_HOST = '127.0.0.1';
+export const VIEWER_PORT_MIN = 1;
+export const VIEWER_PORT_MAX = 65535;
+/** Strict validation for an explicit --port value: an integer in the valid TCP port range (0 is allowed only for deterministic test use - the OS assigns an ephemeral port). */
+export function isValidViewerPort(value) {
+    return Number.isInteger(value) && value >= 0 && value <= VIEWER_PORT_MAX;
+}
+//# sourceMappingURL=port.js.map

package/dist/viewerServer/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/viewerServer/port.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,kFAAkF;AAClF,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC;AAEvC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC,gLAAgL;AAChL,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,eAAe,CAAC;AAC3E,CAAC"}

package/dist/viewerServer/viewerService.d.ts

@@ -0,0 +1,62 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { ContextSessionState } from './context.js';
+/**
+ * Absolute path to the built browser viewer assets shipped inside this
+ * package's own `dist/viewer` directory, resolved relative to this module's
+ * own compiled location (never the caller's current working directory), so
+ * it works identically whether invoked from the repo, an installed global
+ * package, or a packed npm tarball.
+ */
+export declare function defaultViewerAssetsRoot(): string;
+export interface StartViewerOptions {
+    /** Explicit local evidence-root filesystem trust boundary. Validated operationally (exists, is a directory) - never interpreted as Observer evidence in Batch 1. */
+    root: string;
+    /** Defaults to {@link DEFAULT_VIEWER_PORT}. An explicit alternate port (including 0, for deterministic ephemeral test binding) is a different web origin than the default. */
+    port?: number;
+    /** Overrides the built viewer assets location. Defaults to {@link defaultViewerAssetsRoot}. Exposed only for tests exercising the static-serving boundary against fixture assets. */
+    assetsRoot?: string;
+    /**
+     * v0.8 Batch 6: explicit, session-only reference-region/runtime-target
+     * binding declarations, read once by the CLI at startup from an optional
+     * `--bindings-file` (never re-read, never persisted, never exposed as a
+     * path to the browser). Not yet validated against any specific reference
+     * here - that happens per-request, once a reference is actually selected,
+     * via the existing canonical `isValidReferenceRuntimeBindingDeclarations`.
+     * Defaults to an empty collection.
+     */
+    bindingDeclarations?: readonly unknown[];
+    /**
+     * v0.8 Batch 7: the already-classified bounded-agent-context session
+     * state, read once by the CLI at startup from an optional
+     * `--context-file` (never re-read, never persisted, never exposed as a
+     * path to the browser, never derived by the viewer itself). Defaults to
+     * `{status:'none'}`.
+     */
+    context?: ContextSessionState;
+    /** Ephemeral project-workflow display metadata keyed by exact POSIX evidence-relative directory. */
+    aliasMetadata?: ViewerAliasMetadata;
+}
+export interface ViewerAliasMetadata {
+    observationAliasesByRelativeDir: Readonly<Record<string, string>>;
+}
+export type StartViewerResult = {
+    ok: true;
+    url: string;
+    port: number;
+    host: string;
+    root: string;
+    /** Closes the underlying TCP listener. Safe to call once; awaits full shutdown. */
+    close: () => Promise<void>;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one application-level viewer use case for v0.8 Batch 1: validate the
+ * supplied evidence root and port, then start the loopback-only Node viewer
+ * server. Does not block - returns once the server is listening (or has
+ * failed to start), leaving lifecycle control (in particular, shutdown) to
+ * the caller. Never launches a browser, runs observation, or touches
+ * Observer artifacts.
+ */
+export declare function startViewer(options: StartViewerOptions): Promise<StartViewerResult>;

package/dist/viewerServer/viewerService.js

@@ -0,0 +1,88 @@
+import { stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createViewerServer } from './httpServer.js';
+import { DEFAULT_VIEWER_PORT, VIEWER_HOST, isValidViewerPort } from './port.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+function diagnostic(code, message) {
+    return { code, severity: DIAGNOSTIC_SEVERITY[code], message };
+}
+/**
+ * Absolute path to the built browser viewer assets shipped inside this
+ * package's own `dist/viewer` directory, resolved relative to this module's
+ * own compiled location (never the caller's current working directory), so
+ * it works identically whether invoked from the repo, an installed global
+ * package, or a packed npm tarball.
+ */
+export function defaultViewerAssetsRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', 'viewer');
+}
+/**
+ * The one application-level viewer use case for v0.8 Batch 1: validate the
+ * supplied evidence root and port, then start the loopback-only Node viewer
+ * server. Does not block - returns once the server is listening (or has
+ * failed to start), leaving lifecycle control (in particular, shutdown) to
+ * the caller. Never launches a browser, runs observation, or touches
+ * Observer artifacts.
+ */
+export async function startViewer(options) {
+    const diagnostics = [];
+    let rootInfo;
+    try {
+        rootInfo = await stat(options.root);
+    }
+    catch {
+        diagnostics.push(diagnostic('viewer-root-invalid', `--root does not exist or is not accessible: ${options.root}`));
+        return { ok: false, diagnostics };
+    }
+    if (!rootInfo.isDirectory()) {
+        diagnostics.push(diagnostic('viewer-root-invalid', `--root must be a directory: ${options.root}`));
+        return { ok: false, diagnostics };
+    }
+    const requestedPort = options.port ?? DEFAULT_VIEWER_PORT;
+    if (!isValidViewerPort(requestedPort)) {
+        diagnostics.push(diagnostic('viewer-port-unavailable', `--port must be an integer between 0 and 65535; got ${requestedPort}`));
+        return { ok: false, diagnostics };
+    }
+    const assetsRoot = options.assetsRoot ?? defaultViewerAssetsRoot();
+    const server = createViewerServer({
+        assetsRoot,
+        state: {
+            root: options.root,
+            bindingDeclarations: options.bindingDeclarations ?? [],
+            context: options.context ?? { status: 'none' },
+            aliasMetadata: options.aliasMetadata ?? { observationAliasesByRelativeDir: {} },
+        },
+    });
+    const listenResult = await new Promise((resolvePromise) => {
+        const onError = (err) => {
+            server.off('listening', onListening);
+            resolvePromise({ ok: false, message: err.code === 'EADDRINUSE' ? `port ${requestedPort} is already in use` : (err.message ?? String(err)) });
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolvePromise({ ok: true });
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(requestedPort, VIEWER_HOST);
+    });
+    if (!listenResult.ok) {
+        diagnostics.push(diagnostic('viewer-port-unavailable', `could not bind the viewer server to ${VIEWER_HOST}:${requestedPort}: ${listenResult.message}. Pass an explicit --port to use a different origin; the default port is never silently substituted.`));
+        return { ok: false, diagnostics };
+    }
+    const address = server.address();
+    const actualPort = address !== null && typeof address === 'object' ? address.port : requestedPort;
+    return {
+        ok: true,
+        url: `http://${VIEWER_HOST}:${actualPort}`,
+        port: actualPort,
+        host: VIEWER_HOST,
+        root: options.root,
+        close: () => new Promise((resolvePromise, reject) => {
+            server.close((err) => (err ? reject(err) : resolvePromise()));
+        }),
+    };
+}
+//# sourceMappingURL=viewerService.js.map

package/dist/viewerServer/viewerService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewerService.js","sourceRoot":"","sources":["../../src/viewerServer/viewerService.ts"],"names":[],"mappings":"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"}