peaks-loop 4.0.35 → 4.0.37

package/dist/services/web/web-artifact-paths.d.ts

@@ -0,0 +1,79 @@
+/** Sub-directory of the session dir that owns every `peaks web` artifact. */
+export declare const WEB_SUBDIR = "web";
+/** Sub-directory of the session dir that owns the per-dispatch storage state. */
+export declare const WEB_PROFILES_SUBDIR = "pw-profiles";
+/** `<root>/.peaks/_runtime/<sid>/web/` — the root of every web artifact. */
+export declare function webDir(projectRoot: string, sessionId: string): string;
+/**
+ * `<root>/.peaks/_runtime/<sid>/pw-profiles/` — the per-dispatch storage-state
+ * root. A SIBLING of `web/`, which is why the guard for `webContextStatePath`
+ * must use this resolver and never `webDir` (getting that wrong threw
+ * `WEB_PATH_ESCAPE` for every dispatch).
+ */
+export declare function webProfilesDir(projectRoot: string, sessionId: string): string;
+/** `<root>/.peaks/_runtime/<sid>/web/daemon/` — daemon info, lock, and log. */
+export declare function webDaemonDir(projectRoot: string, sessionId: string): string;
+/**
+ * `<root>/.peaks/_runtime/<sid>/web/shot-<ts>.png`.
+ * `<ts>` is `YYYYMMDDTHHMMSSmmmZ` — no colons, so the name is Windows-safe
+ * (tech-doc §7.1).
+ */
+export declare function webShotPath(projectRoot: string, sessionId: string, ts: string): string;
+/** `<root>/.peaks/_runtime/<sid>/web/daemon/daemon.json`. */
+export declare function webDaemonInfoPath(projectRoot: string, sessionId: string): string;
+/** `<root>/.peaks/_runtime/<sid>/web/daemon/daemon.lock` — the cold-start lock. */
+export declare function webSpawnLockPath(projectRoot: string, sessionId: string): string;
+/**
+ * `<homedir>/.peaks/web/install.lock` — the chromium install lock.
+ *
+ * MACHINE-GLOBAL, deliberately not per session (S3 repair, R4). The resource it
+ * guards is Playwright's own browser cache (`%LOCALAPPDATA%\ms-playwright`,
+ * `~/.cache/ms-playwright`), which every session, every project and every
+ * daemon of this user shares. A lock under `<root>/.peaks/_runtime/<sid>/web/`
+ * serialized nothing across sessions: N sessions could run N concurrent
+ * installers into that one cache, and `install --force` in one session could
+ * delete a browser another session's daemon has open. `~/.peaks` is the
+ * existing per-user peaks location (`config.json`, `logs/`), so this adds no
+ * new convention, and it stays outside the project root — AC1's "no root
+ * pollution" is untouched.
+ */
+export declare function webInstallLockPath(): string;
+/**
+ * `<homedir>/.peaks/web-profiles/` — the root of the user-level login profiles
+ * (S4, design §10.2).
+ *
+ * Deliberately CROSS-PROJECT: one logged-in session reused across every project
+ * and worktree is the feature's whole value, so it is scoped to the user, not to
+ * `(projectRoot, sessionId)`. AC1's "no root pollution" is untouched — this
+ * lives under the user's home, never under the project root.
+ *
+ * The name lives HERE rather than in `web-login-profile.ts` for the same reason
+ * `webInstallLockPath` does: this module is the only one under
+ * `src/services/web/` allowed to contain the `.peaks` literal (tech-doc §7.2
+ * rule 1).
+ */
+export declare function userWebProfilesDir(): string;
+/** `<root>/.peaks/_runtime/<sid>/web/daemon/daemon.log` — daemon stdout/stderr. */
+export declare function webLogPath(projectRoot: string, sessionId: string): string;
+/**
+ * `<root>/.peaks/_runtime/<sid>/pw-profiles/<dispatchId>/storageState.json`.
+ *
+ * The DIRECTORY convention is the existing `pw-profiles/<dispatchId>` one
+ * (`src/services/worktree/playwright-profile.ts:21`), reused rather than
+ * re-implemented. The FILE inside it is a Playwright `storageState.json`, not
+ * a Chromium `userDataDir`: orchestrator decision C1 — a persistent context
+ * per dispatch would spawn one browser process per dispatch and violate Q8.
+ *
+ * Note the sibling relationship: this path is NOT under `webDir(...)`. The
+ * guard parent for it is `webProfilesDir(...)`.
+ */
+export declare function webContextStatePath(projectRoot: string, sessionId: string, dispatchId: string): string;
+/**
+ * Throw unless `child` resolves to `parent` or to a path strictly inside it.
+ *
+ * The single write guard for the slice: every write site calls this before
+ * touching disk, and a violation surfaces as `WEB_PATH_ESCAPE` in a `fail()`
+ * envelope. Uses the shared `isInsidePath` so a bare `startsWith` sibling-prefix
+ * collision (`/proj2` vs `/proj`) cannot pass.
+ */
+export declare function assertUnder(child: string, parent: string): void;

package/dist/services/web/web-artifact-paths.js

@@ -0,0 +1,163 @@
+/**
+ * Canonical path resolvers for the `peaks web` artifact tree (slice S1, AC1).
+ *
+ * What is actually guaranteed here, and what is not:
+ *
+ *   - `sessionId` is validated against a strict slug before any `join`, so a
+ *     traversing sid (`..\..\..\tmp\pwn`) cannot move the whole tree out of the
+ *     project. A resolver rejects it outright.
+ *   - `assertUnder` then anchors each write to a parent this module derived
+ *     itself, so a traversing `dispatchId` cannot escape either.
+ *
+ * Both halves are needed: `assertUnder(child, parent)` takes a parent derived
+ * from the same `sessionId` the child is, so on its own it can only constrain
+ * the components BELOW the session dir. The sid slug check is what closes the
+ * sid itself.
+ *
+ * Every path is derived from `getSessionDir(projectRoot, sessionId)` — with two
+ * declared exceptions. `webContextStatePath` is built on the pre-existing
+ * `pw-profiles/<dispatchId>` convention (`playwright-profile.ts`) and therefore
+ * lands beside `web/`, not inside it. `webInstallLockPath` is not under the
+ * session at all: it guards Playwright's machine-global browser cache, so its
+ * scope is the user, not the session (see its docstring).
+ *
+ * This is the ONLY module under `src/services/web/` that may name `.peaks`;
+ * every other writer in the slice imports a resolver from here (tech-doc §7.2
+ * rule 1). Shape mirrors `canonicalQaDir()`
+ * (`src/services/workflow/artifact-paths.ts:55`).
+ *
+ * The write guard for the whole slice is `assertUnder` — it is a thin wrapper
+ * on the shared, cross-platform `isInsidePath` from `src/shared/path-utils.ts`
+ * (see `.peaks/memory/2026-08-04-cross-platform-path-utility-rule.md`), so the
+ * sibling-prefix case (`/proj2` vs `/proj`) is rejected by construction.
+ */
+import { resolve } from 'node:path';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { isInsidePath } from '../../shared/path-utils.js';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { playwrightProfilePaths } from '../worktree/playwright-profile.js';
+/** Sub-directory of the session dir that owns every `peaks web` artifact. */
+export const WEB_SUBDIR = 'web';
+/** Sub-directory of the session dir that owns the per-dispatch storage state. */
+export const WEB_PROFILES_SUBDIR = 'pw-profiles';
+/**
+ * A session id is a single path component. Anything else — a separator, `..`,
+ * or `.` — would let the value that names the session also relocate it.
+ */
+const SESSION_ID_SLUG_RE = /^[A-Za-z0-9._-]+$/;
+/**
+ * Reject a `sessionId` that is not a single, non-traversing path component.
+ *
+ * This is the check `assertUnder` structurally cannot make (see the module
+ * docstring): the guard's child and parent both descend from `sessionId`, so a
+ * traversing sid moves them together and the containment test still passes.
+ */
+function assertValidSessionId(sessionId) {
+    if (sessionId === '.' || sessionId === '..' || !SESSION_ID_SLUG_RE.test(sessionId)) {
+        throw new Error(`WEB_INVALID_SESSION_ID: ${JSON.stringify(sessionId)} is not a single path component`);
+    }
+}
+/** `<root>/.peaks/_runtime/<sid>/web/` — the root of every web artifact. */
+export function webDir(projectRoot, sessionId) {
+    assertValidSessionId(sessionId);
+    return join(getSessionDir(projectRoot, sessionId), WEB_SUBDIR);
+}
+/**
+ * `<root>/.peaks/_runtime/<sid>/pw-profiles/` — the per-dispatch storage-state
+ * root. A SIBLING of `web/`, which is why the guard for `webContextStatePath`
+ * must use this resolver and never `webDir` (getting that wrong threw
+ * `WEB_PATH_ESCAPE` for every dispatch).
+ */
+export function webProfilesDir(projectRoot, sessionId) {
+    assertValidSessionId(sessionId);
+    return join(getSessionDir(projectRoot, sessionId), WEB_PROFILES_SUBDIR);
+}
+/** `<root>/.peaks/_runtime/<sid>/web/daemon/` — daemon info, lock, and log. */
+export function webDaemonDir(projectRoot, sessionId) {
+    return join(webDir(projectRoot, sessionId), 'daemon');
+}
+/**
+ * `<root>/.peaks/_runtime/<sid>/web/shot-<ts>.png`.
+ * `<ts>` is `YYYYMMDDTHHMMSSmmmZ` — no colons, so the name is Windows-safe
+ * (tech-doc §7.1).
+ */
+export function webShotPath(projectRoot, sessionId, ts) {
+    return join(webDir(projectRoot, sessionId), `shot-${ts}.png`);
+}
+/** `<root>/.peaks/_runtime/<sid>/web/daemon/daemon.json`. */
+export function webDaemonInfoPath(projectRoot, sessionId) {
+    return join(webDaemonDir(projectRoot, sessionId), 'daemon.json');
+}
+/** `<root>/.peaks/_runtime/<sid>/web/daemon/daemon.lock` — the cold-start lock. */
+export function webSpawnLockPath(projectRoot, sessionId) {
+    return join(webDaemonDir(projectRoot, sessionId), 'daemon.lock');
+}
+/**
+ * `<homedir>/.peaks/web/install.lock` — the chromium install lock.
+ *
+ * MACHINE-GLOBAL, deliberately not per session (S3 repair, R4). The resource it
+ * guards is Playwright's own browser cache (`%LOCALAPPDATA%\ms-playwright`,
+ * `~/.cache/ms-playwright`), which every session, every project and every
+ * daemon of this user shares. A lock under `<root>/.peaks/_runtime/<sid>/web/`
+ * serialized nothing across sessions: N sessions could run N concurrent
+ * installers into that one cache, and `install --force` in one session could
+ * delete a browser another session's daemon has open. `~/.peaks` is the
+ * existing per-user peaks location (`config.json`, `logs/`), so this adds no
+ * new convention, and it stays outside the project root — AC1's "no root
+ * pollution" is untouched.
+ */
+export function webInstallLockPath() {
+    return join(homedir(), '.peaks', 'web', 'install.lock');
+}
+/**
+ * `<homedir>/.peaks/web-profiles/` — the root of the user-level login profiles
+ * (S4, design §10.2).
+ *
+ * Deliberately CROSS-PROJECT: one logged-in session reused across every project
+ * and worktree is the feature's whole value, so it is scoped to the user, not to
+ * `(projectRoot, sessionId)`. AC1's "no root pollution" is untouched — this
+ * lives under the user's home, never under the project root.
+ *
+ * The name lives HERE rather than in `web-login-profile.ts` for the same reason
+ * `webInstallLockPath` does: this module is the only one under
+ * `src/services/web/` allowed to contain the `.peaks` literal (tech-doc §7.2
+ * rule 1).
+ */
+export function userWebProfilesDir() {
+    return join(homedir(), '.peaks', 'web-profiles');
+}
+/** `<root>/.peaks/_runtime/<sid>/web/daemon/daemon.log` — daemon stdout/stderr. */
+export function webLogPath(projectRoot, sessionId) {
+    return join(webDaemonDir(projectRoot, sessionId), 'daemon.log');
+}
+/**
+ * `<root>/.peaks/_runtime/<sid>/pw-profiles/<dispatchId>/storageState.json`.
+ *
+ * The DIRECTORY convention is the existing `pw-profiles/<dispatchId>` one
+ * (`src/services/worktree/playwright-profile.ts:21`), reused rather than
+ * re-implemented. The FILE inside it is a Playwright `storageState.json`, not
+ * a Chromium `userDataDir`: orchestrator decision C1 — a persistent context
+ * per dispatch would spawn one browser process per dispatch and violate Q8.
+ *
+ * Note the sibling relationship: this path is NOT under `webDir(...)`. The
+ * guard parent for it is `webProfilesDir(...)`.
+ */
+export function webContextStatePath(projectRoot, sessionId, dispatchId) {
+    assertValidSessionId(sessionId);
+    const { userDataDir } = playwrightProfilePaths({ projectRoot, sessionId, dispatchId });
+    return join(userDataDir, 'storageState.json');
+}
+/**
+ * Throw unless `child` resolves to `parent` or to a path strictly inside it.
+ *
+ * The single write guard for the slice: every write site calls this before
+ * touching disk, and a violation surfaces as `WEB_PATH_ESCAPE` in a `fail()`
+ * envelope. Uses the shared `isInsidePath` so a bare `startsWith` sibling-prefix
+ * collision (`/proj2` vs `/proj`) cannot pass.
+ */
+export function assertUnder(child, parent) {
+    if (!isInsidePath(resolve(child), resolve(parent))) {
+        throw new Error(`WEB_PATH_ESCAPE: ${child} is not under ${parent}`);
+    }
+}

package/dist/services/web/web-client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Loopback HTTP client for the `peaks web` daemon (slice S1, file 6).
+ *
+ * The CLI layer never speaks HTTP itself: this class is the only thing it
+ * knows how to talk to, so every transport concern (bearer token, timeouts,
+ * envelope normalisation) lives here and every CLI test can stub the daemon
+ * with a plain `node:http` server.
+ */
+import type { WebDaemonInfo, WebOp, WebOpResponse } from './web-protocol.js';
+export declare class WebDaemonClient {
+    private readonly baseUrl;
+    private readonly token;
+    constructor(info: WebDaemonInfo);
+    /** True when a daemon is listening on the recorded port and accepting our token. */
+    health(): Promise<boolean>;
+    /** Invoke one op. A transport failure throws; an op failure comes back as `ok: false`. */
+    call<T>(op: WebOp, args: Readonly<Record<string, unknown>>, timeoutMs: number): Promise<WebOpResponse<T>>;
+    private headers;
+}

package/dist/services/web/web-client.js

@@ -0,0 +1,55 @@
+/** `/health` is a liveness probe; a wedged daemon must answer fast or not at all. */
+const HEALTH_TIMEOUT_MS = 500;
+export class WebDaemonClient {
+    baseUrl;
+    token;
+    constructor(info) {
+        this.baseUrl = `http://127.0.0.1:${info.port}`;
+        this.token = info.token;
+    }
+    /** True when a daemon is listening on the recorded port and accepting our token. */
+    async health() {
+        try {
+            const response = await fetch(`${this.baseUrl}/health`, {
+                headers: this.headers(),
+                signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS)
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Invoke one op. A transport failure throws; an op failure comes back as `ok: false`. */
+    async call(op, args, timeoutMs) {
+        const body = { op, args };
+        const response = await fetch(`${this.baseUrl}/op`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs)
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                data: null,
+                code: `WEB_DAEMON_HTTP_${response.status}`,
+                message: `peaks web daemon answered HTTP ${response.status}`,
+                warnings: [],
+                nextActions: ['Run `peaks web stop` and retry to respawn the daemon']
+            };
+        }
+        const parsed = (await response.json());
+        return {
+            ok: parsed.ok === true,
+            data: parsed.data ?? null,
+            code: parsed.code ?? null,
+            message: parsed.message ?? null,
+            warnings: Array.isArray(parsed.warnings) ? parsed.warnings : [],
+            nextActions: Array.isArray(parsed.nextActions) ? parsed.nextActions : []
+        };
+    }
+    headers() {
+        return { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' };
+    }
+}

package/dist/services/web/web-daemon-service.d.ts

@@ -0,0 +1,38 @@
+import { BrowserSessionManager, type CloseAllResult } from './browser-session-manager.js';
+import { type WebOp, type WebOpResponse } from './web-protocol.js';
+/** Loopback only: the bearer token is the second lock, not the only one. */
+export declare const DAEMON_HOST = "127.0.0.1";
+export interface WebDaemonConfig {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /** `peaks-loop` version written into `daemon.json`. */
+    readonly version: string;
+}
+export interface RunningWebDaemon {
+    readonly port: number;
+    readonly token: string;
+    /**
+     * Close every context, persist each dispatch's `storageState.json`, close the
+     * browser process, stop listening and remove `daemon.json`.
+     *
+     * Returns the teardown result rather than swallowing it: a `storageState.json`
+     * that could not be written is silent data loss for S4's login profile (R1).
+     */
+    readonly close: () => Promise<CloseAllResult>;
+}
+/**
+ * Start the daemon. Resolves once the server is listening and `daemon.json`
+ * exists, so the caller (and every poller in `ensureDaemon`) can treat the
+ * resolution as "reachable".
+ */
+export declare function startWebDaemon(config: WebDaemonConfig): Promise<RunningWebDaemon>;
+/**
+ * Serve one op. Exported separately from the server so every verb's payload
+ * shape and failure code are unit-testable without a socket.
+ *
+ * The manager arrives as a PROVIDER, not a value: acquiring it is what launches
+ * chromium, so it must happen only for ops that actually need a page. An op the
+ * daemon does not serve (`install`, `login`, a typo) must answer without
+ * starting a browser at all.
+ */
+export declare function routeOp(op: WebOp, args: Readonly<Record<string, unknown>>, managerFor: () => Promise<BrowserSessionManager>): Promise<WebOpResponse>;