@broberg/lens-daemon 0.1.20 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.20",
+  "version": "0.1.23",
   "description": "The Lens module of the cardmem daemon (flows, critic, coverage, capture sessions, the /lens/* routes and the cardmem-lens MCP) as a package. The daemon mounts createLensRouter(deps) + createLensMcpRouter(deps). Bun runtime.",
   "type": "module",
   "license": "MIT",
@@ -15,8 +15,8 @@
     "sharp": "^0.33.5",
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
-    "@broberg/lens-svg": "0.1.0",
-    "@broberg/lens-engine": "0.13.1"
+    "@broberg/lens-engine": "0.13.1",
+    "@broberg/lens-svg": "0.1.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/auth/index.ts

@@ -18,7 +18,7 @@
 //                    reuses the artifact F037's auth.setup.ts already produces.
 //   - cookieJwt    : a single named cookie holding a JWT. Covers cms.
 
-import { readFileSync } from 'node:fs';
+import { chmodSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
 import type { BrowserContext } from 'playwright';
 
@@ -36,6 +36,11 @@ export interface StorageStateAuth {
    *  the gitignored file it points at is — so this preserves "secret never in
    *  the call". Takes precedence over stateEnv. */
   statePath?: string;
+  /** F009.131 — write the context's cookies + storage BACK to statePath when the
+   *  run ends. Sites that rotate their session while you use it (Google, measured
+   *  15 Oct) kill the cookies a run started with, so a saved login lasted exactly
+   *  one run. statePath only: there is nothing to write back to otherwise. */
+  persist?: boolean;
 }
 
 export interface CookieJwtAuth {
@@ -287,6 +292,33 @@ async function applyCookieJwt(
   ]);
 }
 
+/** F009.131 — the statePath a run should write back to, or null. A persist that
+ *  cannot be honoured is refused rather than ignored: the caller believes the
+ *  login will survive, and a silent no-op is the next run's mystery logout. */
+export function persistTarget(cfg: AuthConfig | undefined): string | null {
+  if (!cfg || (cfg as { persist?: unknown }).persist === undefined) return null;
+  const persist = (cfg as { persist?: unknown }).persist;
+  if (typeof persist !== 'boolean') throw new Error('auth.persist must be a boolean');
+  if (!persist) return null;
+  if (cfg.adapter !== 'storageState') {
+    throw new Error(`auth.persist works with adapter "storageState" only — "${cfg.adapter}" mints or sets its credential per run, so there is nothing to keep`);
+  }
+  if (!cfg.statePath) {
+    throw new Error('auth.persist needs auth.statePath — a state read from an env var or inline JSON has no file to write the renewed login back to');
+  }
+  return cfg.statePath;
+}
+
+/** F009.131 — write the context's current state to `path`: temp file + rename so a
+ *  crash never leaves half a login, mode 0600 because it IS a login. */
+export async function persistStorageState(context: BrowserContext, path: string): Promise<void> {
+  const state = await context.storageState();
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+}
+
 /** Run the configured auth adapter against a fresh context. */
 export async function applyAuth(
   context: BrowserContext,

package/src/flow-store.ts

@@ -150,6 +150,8 @@ export async function recordFlowRun(
           source: auth.source,
           adapter: auth.adapter,
           ...(auth.note ? { note: auth.note } : {}),
+          // F009.131 — whether the renewed login was saved; only when asked for.
+          ...(result.auth_persisted ? { persisted: result.auth_persisted.ok, ...(result.auth_persisted.reason ? { persisted_reason: result.auth_persisted.reason } : {}) } : {}),
           // F074.36 — the measured verdict, not the intent: "a credential was
           // configured" and "a credential can reach this host" are different
           // facts, and only the second one means anything.

package/src/flow.ts

@@ -25,7 +25,7 @@ import {
 } from '@broberg/lens-engine';
 import { withPage, type LensEngine } from './browser.ts';
 import { deadline, defaultPopupOf, prepareExtension, seedExtensionStorage, SIMULATED_ACCESS_NOTE } from './extension-flow.ts';
-import { authPrepare, fetchMintJson, type AuthConfig, type AuthEnv } from './auth/index.ts';
+import { authPrepare, fetchMintJson, persistStorageState, persistTarget, type AuthConfig, type AuthEnv } from './auth/index.ts';
 import { takeShot, settleForShot } from './capture.ts';
 import { runCritic, topFindingMessage, type CriticMode, type CriticReport } from './critic.ts';
 import { waitForBuild, observeBuild } from './build-marker.ts';
@@ -402,9 +402,18 @@ export async function finishDownloads(pending: Promise<void>[], downloads: FlowD
 export interface FlowResult {
   /** F009.128 — files the run downloaded. Always present on a finished run. */
   downloads?: FlowDownload[];
+  /** F009.131 — set when auth.persist was asked for: whether the renewed login was
+   *  written back to statePath, and why not when it was not. Never a value. */
+  auth_persisted?: { ok: boolean; reason?: string };
   /** F009.125 — the extension this run loaded: its id (read at load time), the
    *  build path the caller named, and whether host access was SIMULATED on a copy. */
-  extension?: { id: string; path: string; host_access: 'as-built' | 'simulated'; note?: string } | null;
+  extension?: {
+    id: string; path: string; host_access: 'as-built' | 'simulated'; note?: string;
+    /** F009.129 — the chrome.storage.local KEYS seeded before step 0 (names only, never
+     *  values), and which one Lens minted itself. A failed mint never gets here — it
+     *  ends the run before step 0 naming url + status. */
+    storage_local?: { keys: string[]; minted: string | null };
+  } | null;
   name: string;
   status: 'pass' | 'fail' | 'error';
   steps: FlowStepResult[];
@@ -527,6 +536,7 @@ export function parseFlow(input: unknown): Flow {
       ...(mint ? { storage_local_mint: mint } : {}),
     };
   }
+  persistTarget(f.auth as AuthConfig | undefined); // F009.131 — refuse a persist that cannot be honoured
   validateAndNormalizeSteps(f.steps);
   if (!extension && usesPopup(f.steps as FlowStep[])) {
     throw new Error('openPopup / in:"popup" need flow.extension — there is no extension loaded to open a popup from');
@@ -3011,6 +3021,8 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
   // F009.128 — files the run downloads. A download is awaited before the context
   // closes; otherwise the bytes die with the browser and the report says nothing.
   const downloads: FlowDownload[] = [];
+  const persistPath = persistTarget(flow.auth);
+  let authPersisted: FlowResult['auth_persisted'] = persistPath ? { ok: false, reason: 'the run ended before the login could be saved' } : undefined;
   const pendingDownloads: Promise<void>[] = [];
   let currentStep: number | null = null;
   const watchDownloads = (context: BrowserContext): void => {
@@ -3157,6 +3169,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
             path: flow.extension.path,
             host_access: prepared.simulated ? 'simulated' : 'as-built',
             ...(prepared.simulated ? { note: SIMULATED_ACCESS_NOTE } : {}),
+            ...(Object.keys(seed).length ? { storage_local: { keys: Object.keys(seed), minted: mint?.key ?? null } } : {}),
           };
         }
         // F074.36 — measure the credential BEFORE driving, so a run that cannot
@@ -3266,6 +3279,15 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         // Bounded: a download that never finishes must not hang the run. Whatever is
         // still unfinished is reported as such, never dropped.
         await finishDownloads(pendingDownloads, downloads, DOWNLOAD_FINISH_MS);
+        // F009.131 — after the last step, pass or fail, while the context is open.
+        if (persistPath) {
+          try {
+            await persistStorageState(context, persistPath);
+            authPersisted = { ok: true };
+          } catch (err) {
+            authPersisted = { ok: false, reason: `could not write ${persistPath}: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}` };
+          }
+        }
       },
     );
   } catch (err) {
@@ -3273,7 +3295,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     // Keep the recording even on a crash — watching HOW it broke is the whole point.
     const video = await readVideo();
     await prepared?.cleanup();
-    return { downloads, ...(extensionInfo ? { extension: extensionInfo } : {}), name: flow.name, status: 'error', steps: results.sort((a, b) => a.index - b.index), failed_at: firstFailedAt, reason: leadWithRedirect(reason, firstRedirect), duration_ms: Date.now() - startedAt, video, build: observedBuild, final_url: finalUrl, redirected: firstRedirect, password_in_url: passwordInUrl(finalUrl, filledPasswords), not_listening: notListening[0] ?? null, reduced_motion: opts.reducedMotion ?? 'reduce' };
+    return { downloads, ...(authPersisted ? { auth_persisted: authPersisted } : {}), ...(extensionInfo ? { extension: extensionInfo } : {}), name: flow.name, status: 'error', steps: results.sort((a, b) => a.index - b.index), failed_at: firstFailedAt, reason: leadWithRedirect(reason, firstRedirect), duration_ms: Date.now() - startedAt, video, build: observedBuild, final_url: finalUrl, redirected: firstRedirect, password_in_url: passwordInUrl(finalUrl, filledPasswords), not_listening: notListening[0] ?? null, reduced_motion: opts.reducedMotion ?? 'reduce' };
   }
 
   const video = await readVideo();
@@ -3326,6 +3348,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     // ASKED for, defaulted the same way the context does, so the report and the
     // context can never disagree about it.
     reduced_motion: opts.reducedMotion ?? 'reduce',
+    ...(authPersisted ? { auth_persisted: authPersisted } : {}),
     ...(extensionInfo ? { extension: extensionInfo } : {}),
     downloads,
   };

package/src/mcp.ts

@@ -36,6 +36,7 @@ const authSchema = {
     adapter: { type: 'string', enum: ['storageState', 'cookieJwt', 'mintEndpoint'] },
     statePath: { type: 'string', description: 'storageState: path to a Playwright storageState JSON (relative → resolved against local_path/repo root). Preferred over stateEnv (no daemon restart).' },
     stateEnv: { type: 'string', description: 'storageState: env var holding the storageState path/JSON (needs daemon restart to inject).' },
+    persist: { type: 'boolean', description: 'F009.131 — storageState + statePath only (flows/manuscripts): write the renewed cookies + storage BACK to statePath when the run ends (atomic, 0600). Sites that rotate their session while used (Google) otherwise leave a saved login good for ONE run. The report says auth.persisted true|false.' },
     cookieName: { type: 'string' },
     domain: { type: 'string' },
     path: { type: 'string' },
@@ -369,7 +370,7 @@ export const TOOLS = [
                 path: { type: 'string' },
                 grant_host_access: { type: 'boolean' },
                 storage_local: { type: 'object', description: 'F009.126 — {key: JSON value} for chrome.storage.local, set before step 0.' },
-                storage_local_mint: { type: 'object', description: 'F009.129 — {key, url, method?, secretPath | secretEnv, body?}: the DAEMON calls the mint url (Bearer secret; secretPath relative to local_path, sandboxed) and writes the JSON answer to chrome.storage.local[key] before step 0, so a real token never passes through you. Wins over storage_local on the same key. Value and secret never appear in the report.' },
+                storage_local_mint: { type: 'object', description: 'F009.129 — {key, url, method?, secretPath | secretEnv, body?}: the DAEMON calls the mint url (Bearer secret; secretPath relative to local_path, sandboxed) and writes the JSON answer to chrome.storage.local[key] before step 0, so a real token never passes through you. Wins over storage_local on the same key. Value and secret never appear in the report; it carries extension.storage_local {keys, minted} — key NAMES only — so you can see the login was seeded. Steps after openPopup still run on the page under test: add in:"popup" to drive the popup.' },
               },
             },
             steps: {