dsh-builtin-browser 0.4.0 → 0.4.2

package/lib/browser-electron/settings-store.js

@@ -8,7 +8,7 @@
  * defaults" rather than an error.
  * @module dsh-browser/browser-electron/settings-store
  */
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 /** Defaults for every switch: the documented out-of-the-box behaviour. */
@@ -22,6 +22,7 @@ export const DEFAULT_SETTINGS = {
     // it starts a real Chrome/Edge with its own profile.
     browser: { channel: 'bundled' },
     credentials: { allowRead: true },
+    actions: { allowExecute: true, allowDownload: true, allowCredentialWrite: true },
 };
 /**
  * Absolute path of the settings file, beside the browser profile and the
@@ -36,6 +37,37 @@ export function settingsPath() {
 function bool(value, fallback) {
     return typeof value === 'boolean' ? value : fallback;
 }
+/**
+ * Coerce one boolean field that GATES A CAPABILITY.
+ *
+ * The difference from {@link bool} is what a mistyped value means. Absent still takes the
+ * default — a document written before the switch existed is the documented behaviour. But
+ * present-and-not-a-boolean is a document this code cannot read, and for a switch that gates
+ * something the operator chose to limit, unreadable resolves to OFF. `bool`'s fallback made
+ * `"false"` (a string), `null` (a truncated write) and `1` all mean the same as `true`, so a
+ * single dropped byte reopened every capability that had been turned off.
+ * @param value - the raw value from the settings document.
+ * @param fallback - the default, used only when the field is absent.
+ * @returns the value when it is a boolean, `false` when it is anything else.
+ */
+function gate(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    return value === true;
+}
+/**
+ * What an unreadable document resolves to.
+ *
+ * Only the capability gates are refused; everything else keeps its default. The distinction is
+ * deliberate: refusing history, presentation or browser choice would punish the user for a
+ * corrupt file without protecting anything, while refusing the gates is the whole point —
+ * "the operator's intent cannot be read" must not resolve to "the operator permits".
+ */
+const SETTINGS_WHEN_UNREADABLE = {
+    ...DEFAULT_SETTINGS,
+    credentials: { allowRead: false },
+    actions: { allowExecute: false, allowDownload: false, allowCredentialWrite: false },
+};
 /**
  * Coerce the browser channel, keeping the default when it is not one of the
  * known choices. A hand-edited typo must not silently select a different browser.
@@ -71,6 +103,7 @@ export function resolveSettings(raw) {
     const vision = section(source, 'vision');
     const credentials = section(source, 'credentials');
     const browser = section(source, 'browser');
+    const actions = section(source, 'actions');
     return {
         history: {
             enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
@@ -85,7 +118,12 @@ export function resolveSettings(raw) {
         },
         vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
         browser: { channel: resolveChannel(browser.channel) },
-        credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
+        credentials: { allowRead: gate(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
+        actions: {
+            allowExecute: gate(actions.allowExecute, DEFAULT_SETTINGS.actions.allowExecute),
+            allowDownload: gate(actions.allowDownload, DEFAULT_SETTINGS.actions.allowDownload),
+            allowCredentialWrite: gate(actions.allowCredentialWrite, DEFAULT_SETTINGS.actions.allowCredentialWrite),
+        },
     };
 }
 /**
@@ -115,20 +153,35 @@ export class SettingsStore {
      */
     get() {
         let mtimeMs = -1;
-        let text;
         try {
-            if (existsSync(this.file)) {
-                mtimeMs = statSync(this.file).mtimeMs;
-                text = readFileSync(this.file, 'utf8');
-            }
+            // stat directly: existsSync costs about thirteen times what the stat does, and the
+            // stat already throws when the file is missing — which the catch below handles.
+            mtimeMs = statSync(this.file).mtimeMs;
         }
         catch {
             // Unreadable file: fall through to defaults below.
             mtimeMs = -1;
-            text = undefined;
         }
+        // Return the cache BEFORE reading. The read used to happen first "just in case", which
+        // made the cache pointless: every call paid for a synchronous read of the whole file and
+        // then discarded it. This is on the path of every tool call that consults a setting, so
+        // it was a stat plus a read per call where a single stat will do.
         if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs)
             return this.cached;
+        let text;
+        if (mtimeMs !== -1) {
+            try {
+                text = readFileSync(this.file, 'utf8');
+            }
+            catch {
+                // It was there a moment ago (the stat above) and cannot be read now: permissions, a
+                // lock, a directory in the way. That is not "no document" — the file is not absent, so
+                // what it said is unknown, and unknown resolves to the refusing document.
+                this.cached = SETTINGS_WHEN_UNREADABLE;
+                this.cachedMtimeMs = mtimeMs;
+                return this.cached;
+            }
+        }
         try {
             // A leading BOM is what ordinary Windows editors (Notepad, PowerShell's
             // `Set-Content -Encoding utf8`) leave behind, and `JSON.parse` rejects it.
@@ -139,8 +192,12 @@ export class SettingsStore {
             this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body));
         }
         catch {
-            // Malformed JSON: behave as defaults rather than fail startup.
-            this.cached = DEFAULT_SETTINGS;
+            // A document that EXISTS but cannot be parsed is not the same as no document at all: the
+            // first is a corrupted or half-written file whose contents were the operator's decisions,
+            // the second is a first run. Resolving both to the defaults meant a kill during the write,
+            // or one stray character, silently reopened the capabilities that had been switched off —
+            // so this side refuses them instead (see SETTINGS_WHEN_UNREADABLE).
+            this.cached = SETTINGS_WHEN_UNREADABLE;
         }
         this.cachedMtimeMs = mtimeMs;
         return this.cached;
@@ -155,7 +212,7 @@ export class SettingsStore {
         const merged = resolveSettings(deepMerge(current, patch));
         try {
             mkdirSync(dirname(this.file), { recursive: true });
-            writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`);
+            writeFileAtomic(this.file, `${JSON.stringify(merged, null, 2)}\n`);
         }
         catch (error) {
             // Do NOT publish the new value as cached, and do not pretend the file changed: a
@@ -171,6 +228,45 @@ export class SettingsStore {
         return merged;
     }
 }
+/**
+ * Replace a file's contents atomically: write a sibling temporary file, then rename it over
+ * the target.
+ *
+ * `writeFileSync(target, …)` truncates and rewrites in place, so a crash, a full disk or an
+ * antivirus lock in the middle leaves HALF a JSON document. That used to be silent: the reader
+ * resolved an unparseable file to the defaults, so a torn write flipped `credentials.allowRead`
+ * and the action switches back ON, and the next successful update wrote those defaults to disk
+ * for good. The read side no longer does that (see {@link SETTINGS_WHEN_UNREADABLE}) — but the
+ * write side still has to stop producing torn files at all, because half a document is not
+ * something this plugin should ever leave behind.
+ *
+ * The rename is the commit point: a reader sees either the old document or the new one,
+ * never a partial one. It stays in the same directory so the rename is atomic on Windows
+ * as well as POSIX (`renameSync` maps to MoveFileEx there: same-volume replaces are
+ * atomic, cross-volume ones are not supported at all).
+ *
+ * The temporary is written with a unique suffix rather than a fixed `.tmp`, so two writers
+ * (the settings panel and a second DSH process) cannot rename each other's half-written
+ * file into place. Shared with the history store, which had the same hole.
+ * @param file - the target path.
+ * @param contents - the complete new document.
+ */
+export function writeFileAtomic(file, contents) {
+    const temporary = `${file}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+    try {
+        writeFileSync(temporary, contents);
+        renameSync(temporary, file);
+    }
+    catch (error) {
+        // The rename is the commit point, so a failure before it leaves the target untouched —
+        // only the temporary has to go, and it must not be left behind as garbage.
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch { /* the temp is already the least of it */ }
+        throw error;
+    }
+}
 /** One-level-deep merge over the settings sections (patch wins). */
 function deepMerge(base, patch) {
     if (typeof patch !== 'object' || patch === null)

package/lib/browser-electron/system-browser.d.ts

@@ -24,6 +24,17 @@
  * only the carrier differs.
  * @module dsh-browser/browser-electron/system-browser
  */
+/**
+ * Starts a browser process and returns a handle to it.
+ *
+ * Injectable so tests can supply something that speaks CDP — the seam a recovery test needs
+ * and could not have while the launch was hardcoded to a stub that rejects Chromium's args.
+ * @param path - the executable to run.
+ * @param args - its arguments.
+ * @returns the child process.
+ */
+export type BrowserLauncher = (path: string, args: readonly string[]) => ReturnType<typeof spawn>;
+import { spawn } from 'node:child_process';
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
 /** Which browser the user asked for. */
 export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto';
@@ -59,13 +70,26 @@ export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.Proc
  * @param platform - the platform whose names and locations apply.
  * @returns the launcher names (as PATH lookups) and the fixed locations checked.
  */
-export declare function searchSummary(kind: DetectedBrowser['kind'], platform?: NodeJS.Platform): string[];
+export declare function searchSummary(kind: DetectedBrowser['kind'], platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string[];
 /** A system browser driven over CDP, presented as a browser view host. */
 export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     private readonly browser;
     private readonly profileDir;
     private readonly extraArgs;
     private readonly ephemeralDir?;
+    private readonly launcher;
+    /**
+     * viewId -> the session that view rides, and the client that issued it.
+     *
+     * The client is part of the value on purpose. A session id means nothing to a browser other
+     * than the one that handed it out, and this host replaces browsers routinely: the process
+     * dies, or its debugging socket closes while the process lives on. Keeping only the id meant
+     * the host could start a NEW browser successfully and then send every command to it carrying
+     * a session the old one had issued — `Session with given id not found`, on every call, with a
+     * browser that answers /json/version perfectly well and nothing the user can do short of
+     * restarting DSH. Comparing identity catches it with no round trip; validating each cached
+     * session against the browser would put one on every page command.
+     */
     private readonly views;
     private disposed;
     /**
@@ -77,16 +101,40 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * spawned when a view is actually needed.
      */
     private client;
+    /**
+     * Set when a command went unanswered rather than being refused.
+     *
+     * A timeout says nothing about the connection: the page may simply be slow. It marks the
+     * client for a cheap check before the next command trusts it, which keeps a slow page
+     * from being mistaken for a dead browser while still catching one that has truly stopped
+     * answering.
+     */
+    private clientSuspect;
     private child;
     private starting;
+    /**
+     * Browsers that ignored a kill.
+     *
+     * They are no longer this host's child — a replacement has taken that slot — but they
+     * are still running, still holding the profile, and still something release must try to
+     * stop. Forgetting them is what allowed a launch this host could not undo.
+     */
+    private readonly stubborn;
     /**
      * @param browser - the detected installation to launch on first use.
      * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
      * @param extraArgs - additional Chromium switches.
      * @param ephemeralDir - a directory to delete on release, when the user has turned
      *   persistence off so no login state outlives the session.
+     * @param launcher - how to start the browser, for tests.
+     *
+     *   Recovery after the browser dies was untestable without this: the suite spawns a stub
+     *   with Chromium's arguments, and a stub that is not a browser rejects them and exits, so
+     *   no CDP endpoint ever appears and no session is ever created. Verified by mutation —
+     *   removing every sessions.clear() left the recovery tests green. A launcher lets a test
+     *   provide something that actually speaks CDP, so the state those tests describe exists.
      */
-    constructor(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string | undefined);
+    constructor(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string | undefined, launcher?: BrowserLauncher);
     /** Which product this host would drive (for diagnostics). */
     get kind(): DetectedBrowser['kind'];
     /** Whether the browser has actually been started yet (diagnostics and tests). */
@@ -95,6 +143,20 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * The CDP client, starting the browser on first use.
      * @returns the connected client.
      */
+    /**
+     * Whether a client that reports itself open is actually answering.
+     *
+     * An open socket proves nothing: a browser can hold the connection and never reply, and
+     * that state must not be cached, or every later command waits out its own timeout. Asking
+     * the browser something cheap is a fact; reading the failure text is a guess, and the
+     * guess was wrong in both directions (it killed healthy browsers on a slow page, and it
+     * mistook the browser's own free text for a verdict).
+     *
+     * This is only reached when the socket is open, so the common path costs nothing.
+     * @param client - the client to question.
+     * @returns true when it answered.
+     */
+    private probeClient;
     private ensureClient;
     /**
      * Launch the browser with a private profile and connect over CDP.
@@ -146,7 +208,13 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * browser) simply tears down its bookkeeping.
      */
     dispose(): void;
-    /** The flattened session for a view, creating its page on first use. */
+    /**
+     * The flattened session for a view, creating its page on first use.
+     *
+     * No cache check here: the only caller has already established that the cached session does
+     * not belong to the client it is about to use. Re-checking would mean either a round trip or
+     * a second copy of that rule.
+     */
     private ensureSession;
     /** sessionId -> targetId, so a destroyed view can close the right page. */
     private readonly sessions;