fix: harden browser provider activation

2026-09-21 20:30:47 +02:00 · 2026-07-21 12:13:33 -07:00
parent e3effb3fc4
commit a84a6e233d
65 changed files with 1203 additions and 171 deletions
@@ -1,5 +1,5 @@
 <!-- GENERATED by scripts/gstack2/generate-skill-tree.ts; do not edit. -->
-<!-- GSTACK2_PROVENANCE source=design-consultation/SKILL.md.tmpl base=bb57306d98c97011b0919c6132705a15b1579781 blob=64af56ecdbd132cb7c28344e8e4ecb2e5dacf811 baseline_render_sha256=62b8141e0b3edb26dcfd175c25c7021d4713b64add121137ace0a123e6e6ea8a ported_render_sha256=d323457820291635bc4c46e4559ce6f4d194b940607b76208e95df0c86ffcb0b disposition=BUG_FIX -->
+<!-- GSTACK2_PROVENANCE source=design-consultation/SKILL.md.tmpl base=bb57306d98c97011b0919c6132705a15b1579781 blob=64af56ecdbd132cb7c28344e8e4ecb2e5dacf811 baseline_render_sha256=62b8141e0b3edb26dcfd175c25c7021d4713b64add121137ace0a123e6e6ea8a ported_render_sha256=13d5aa11be43cf78f7d77b9f8da081c5fedd3b7e767815ff9d650c6bc5d0738b disposition=BUG_FIX -->
 <!-- GSTACK2_ROUTING replacement=$design --mode Generate --module design-consultation visibility=primary depth=deep mutation=design-artifacts web=optional -->

 <!-- GSTACK2_LEGACY_BODY_START source=design-consultation -->
@@ -74,7 +74,7 @@ fi
 ```

 If `NEEDS_SETUP`:
-1. Tell the user: "The optional managed headless browser capability is missing. Do you want to preview its exact dependency-closed component plan and compressed bytes now?" Then STOP and wait.
+1. Tell the user: "The browser-backed capability is not ready. Do you want to see the local setup options—GStack-managed Chromium or a detected installed Chromium executable—with no network access or changes?" Then STOP and wait.
 2. Read `references/RUNTIME.md` and follow its explicit capability bootstrap. Never assume a standard-installed skill directory contains `./setup`.
 3. The approved managed runtime includes its own pinned Bun at `$GSTACK_BIN/bun`; never download or install another Bun from a skill workflow.

@@ -1,5 +1,5 @@
 <!-- GENERATED by scripts/gstack2/generate-skill-tree.ts; do not edit. -->
-<!-- GSTACK2_PROVENANCE source=design-html/SKILL.md.tmpl base=bb57306d98c97011b0919c6132705a15b1579781 blob=3cdec9a14d62d2e046ed924c972efc30a7d43aca baseline_render_sha256=d16ec32f4c07da49d32efc309e621b514854ce355db8347647b9f9fc215ff66d ported_render_sha256=40682d97ac83aa9178487348d5abf176334fd439e2d12f8e5cda1f8b20cd2c30 disposition=BUG_FIX -->
+<!-- GSTACK2_PROVENANCE source=design-html/SKILL.md.tmpl base=bb57306d98c97011b0919c6132705a15b1579781 blob=3cdec9a14d62d2e046ed924c972efc30a7d43aca baseline_render_sha256=d16ec32f4c07da49d32efc309e621b514854ce355db8347647b9f9fc215ff66d ported_render_sha256=775dfc9fdcc6b96d6e267f2b8c5e7eedcf8a1d98b764c134d7111a39f3f07301 disposition=BUG_FIX -->
 <!-- GSTACK2_ROUTING replacement=$design --mode Implement --module design-html visibility=primary depth=standard mutation=design-artifacts web=local-browser -->

 <!-- GSTACK2_LEGACY_BODY_START source=design-html -->
@@ -167,7 +167,7 @@ fi
 ```

 If `NEEDS_SETUP`:
-1. Tell the user: "The optional managed headless browser capability is missing. Do you want to preview its exact dependency-closed component plan and compressed bytes now?" Then STOP and wait.
+1. Tell the user: "The browser-backed capability is not ready. Do you want to see the local setup options—GStack-managed Chromium or a detected installed Chromium executable—with no network access or changes?" Then STOP and wait.
 2. Read `references/RUNTIME.md` and follow its explicit capability bootstrap. Never assume a standard-installed skill directory contains `./setup`.
 3. The approved managed runtime includes its own pinned Bun at `$GSTACK_BIN/bun`; never download or install another Bun from a skill workflow.

@@ -1,5 +1,5 @@
 <!-- GENERATED by scripts/gstack2/generate-skill-tree.ts; do not edit. -->
-<!-- GSTACK2_PROVENANCE source=design-review/SKILL.md.tmpl base=bb57306d98c97011b0919c6132705a15b1579781 blob=bdcda48e29b489a1cc49faa333922412251d4b41 baseline_render_sha256=ff6d5d4858ed45db1e9581080739c0b4c5029bca44ecabe0c385637ece68e0cb ported_render_sha256=fe15a4fae62fba41432ae18bbf4ef5620058b784b7bf9768304d0d1dd17bf45b disposition=BUG_FIX -->
+<!-- GSTACK2_PROVENANCE source=design-review/SKILL.md.tmpl base=bb57306d98c97011b0919c6132705a15b1579781 blob=bdcda48e29b489a1cc49faa333922412251d4b41 baseline_render_sha256=ff6d5d4858ed45db1e9581080739c0b4c5029bca44ecabe0c385637ece68e0cb ported_render_sha256=9d6828dd60fbe4ab9647c5f4456b0953c514ce22ddb1a9c1c3e572c70491f900 disposition=BUG_FIX -->
 <!-- GSTACK2_ROUTING replacement=$design --mode Implement --module design-review visibility=primary depth=deep mutation=fix-safe web=local-browser -->

 <!-- GSTACK2_LEGACY_BODY_START source=design-review -->
@@ -81,7 +81,7 @@ fi
 ```

 If `NEEDS_SETUP`:
-1. Tell the user: "The optional managed headless browser capability is missing. Do you want to preview its exact dependency-closed component plan and compressed bytes now?" Then STOP and wait.
+1. Tell the user: "The browser-backed capability is not ready. Do you want to see the local setup options—GStack-managed Chromium or a detected installed Chromium executable—with no network access or changes?" Then STOP and wait.
 2. Read `references/RUNTIME.md` and follow its explicit capability bootstrap. Never assume a standard-installed skill directory contains `./setup`.
 3. The approved managed runtime includes its own pinned Bun at `$GSTACK_BIN/bun`; never download or install another Bun from a skill workflow.

@@ -123,13 +123,36 @@ export async function main(argv = process.argv.slice(2), options = {}) {
      throw bootstrapError("Browser options require a browser-backed capability", "BOOTSTRAP_USAGE");
    }
    if (parsed.source) {
+      const sourceHome = path.resolve(parsed.home ?? process.env.GSTACK_HOME ?? path.join(os.homedir(), ".gstack"));
+      const active = await inspectReusableRuntime(sourceHome, BOOTSTRAP_RUNTIME_VERSION).catch(() => null);
+      if (!browserChoice && active?.browserChoice) {
+        browserChoice = await resolveBrowserChoice(active.browserChoice, {
+          platform,
+          env: options.env,
+          homeDir: options.homeDir,
+        });
+      }
+      parsed.capabilities = mergeRetainedCapabilities(parsed.capabilities, active, browserChoice);
+      if (browserChoiceRequired(parsed.capabilities) && !browserChoice) {
+        throw bootstrapError(
+          "The active browser capability does not record a reusable browser provider; choose a browser provider before changing this runtime.",
+          "BOOTSTRAP_BROWSER_CHOICE_REQUIRED",
+        );
+      }
+      if (browserChoice) assertBrowserChoiceSupportsCapabilities(browserChoice, parsed.capabilities);
      if (parsed.action === "preview") {
        io.stdout.write("Reviewed-source fallback has no signed compressed-byte manifest; the local installer can provide an on-disk preview only.\n");
        return 0;
      }
      if (!parsed.yes) throw bootstrapError("Installation requires explicit --yes after review", "BOOTSTRAP_CONSENT_REQUIRED");
      io.stderr.write("Developer-only source install: only continue with a checkout you reviewed and trust.\n");
-      return await installFromSource(parsed.source, parsed, { ...options, ...io, prepared: false, browserChoice });
+      return await installFromSource(parsed.source, parsed, {
+        ...options,
+        ...io,
+        prepared: false,
+        replaceCapabilities: true,
+        browserChoice,
+      });
    }

    const fetch_ = options.fetch ?? globalThis.fetch;
@@ -146,7 +169,23 @@ export async function main(argv = process.argv.slice(2), options = {}) {
    });
    validateManifest(manifest, target);
    const home = path.resolve(parsed.home ?? process.env.GSTACK_HOME ?? path.join(os.homedir(), ".gstack"));
-    const reusable = await inspectReusableRuntime(home, manifest.version).catch(() => null);
+    const active = await inspectReusableRuntime(home, manifest.version).catch(() => null);
+    const reusable = active?.releaseMatches ? active : null;
+    if (!browserChoice && active?.browserChoice) {
+      browserChoice = await resolveBrowserChoice(active.browserChoice, {
+        platform,
+        env: options.env,
+        homeDir: options.homeDir,
+      });
+    }
+    parsed.capabilities = mergeRetainedCapabilities(parsed.capabilities, active, browserChoice);
+    if (browserChoiceRequired(parsed.capabilities) && !browserChoice) {
+      throw bootstrapError(
+        "The active browser capability does not record a reusable browser provider; preview browser setup options before changing this runtime.",
+        "BOOTSTRAP_BROWSER_CHOICE_REQUIRED",
+      );
+    }
+    if (browserChoice) assertBrowserChoiceSupportsCapabilities(browserChoice, parsed.capabilities);
    const plan = buildComponentPlan(manifest, target, parsed.capabilities, reusable, browserChoice);
    if (parsed.json) io.stdout.write(`${JSON.stringify({ ok: true, action: parsed.action, ...plan }, null, 2)}\n`);
    else printComponentPlan(io.stdout, plan);
@@ -300,6 +339,24 @@ function selectedComponents(capabilities, browserChoice) {
  return applyBrowserProviderToComponents([...selected], browserChoice);
 }

+function mergeRetainedCapabilities(requested, reusable, browserChoice) {
+  const selected = new Set([
+    ...(Array.isArray(reusable?.selectedCapabilities) ? reusable.selectedCapabilities : []),
+    ...requested,
+  ]);
+  if (browserChoice?.provider === "installed") selected.delete("browser-visible");
+  const pending = [...selected];
+  while (pending.length) {
+    for (const dependency of CAPABILITY_DEPENDENCIES[pending.pop()] ?? []) {
+      if (!selected.has(dependency)) {
+        selected.add(dependency);
+        pending.push(dependency);
+      }
+    }
+  }
+  return [...selected].sort();
+}
+
 function buildComponentPlan(manifest, target, capabilities, reusable, browserChoice) {
  const components = selectedComponents(capabilities, browserChoice);
  const retained = new Set(reusable?.components ?? []);
@@ -341,10 +398,31 @@ async function inspectReusableRuntime(home, version) {
  const stat = await fs.lstat(root);
  if (!stat.isDirectory() || stat.isSymbolicLink()) return null;
  const bundle = JSON.parse(await fs.readFile(path.join(root, ".gstack-bundle.json"), "utf8"));
-  if (bundle?.schemaVersion !== 2 || bundle?.version !== version || !Array.isArray(bundle.runtimeComponents) ||
+  const releaseMatches = bundle?.version === version ||
+    (typeof bundle?.version === "string" && bundle.version.startsWith(`${version}-caps-`));
+  if (bundle?.schemaVersion !== 2 || typeof bundle.version !== "string" ||
+      !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(bundle.version) || !Array.isArray(bundle.runtimeComponents) ||
      !Array.isArray(bundle.files)) return null;
  const components = [...new Set(bundle.runtimeComponents)];
  if (!components.length || components.some((component) => !Object.hasOwn(COMPONENT_DEPENDENCIES, component))) return null;
+  const selectedCapabilities = Array.isArray(bundle.selectedCapabilities)
+    ? [...new Set(bundle.selectedCapabilities)]
+    : [];
+  if (selectedCapabilities.some((capability) => !CAPABILITIES.has(capability))) return null;
+  let browserChoice = null;
+  if (browserChoiceRequired(selectedCapabilities)) {
+    const explicit = bundle.browserChoice;
+    if (!explicit || !["managed", "installed"].includes(explicit.provider)) return null;
+    if (explicit.provider === "installed") {
+      if (selectedCapabilities.includes("browser-visible") ||
+          typeof explicit.executablePath !== "string" || !path.isAbsolute(explicit.executablePath) ||
+          components.includes("browser-headless") || components.includes("browser-visible")) return null;
+      browserChoice = { provider: "installed", executablePath: explicit.executablePath };
+    } else {
+      if (!components.includes("browser-headless") && !components.includes("browser-visible")) return null;
+      browserChoice = { provider: "managed", executablePath: null };
+    }
+  }
  await assertNoLinks(root);
  const files = [];
  const seen = new Set();
@@ -360,7 +438,7 @@ async function inspectReusableRuntime(home, version) {
        await sha256File(file) !== entry.sha256) return null;
    files.push(relative);
  }
-  return { root, components, files };
+  return { root, components, files, selectedCapabilities, browserChoice, releaseMatches };
 }

 async function seedReusableRuntime(reusable, destination, claimedFiles) {
@@ -496,6 +574,7 @@ async function installFromSource(source, parsed, options) {
  if (parsed.home) args.push("--home", path.resolve(parsed.home));
  if (options.version) args.push("--version", options.version);
  if (options.prepared) args.push("--prepared");
+  if (options.prepared || options.replaceCapabilities) args.push("--replace-capabilities");
  await run(options.nodeCommand ?? process.execPath, args);
  options.stdout.write(`Installed optional capabilities: ${parsed.capabilities.join(", ")}. No coding host was enrolled.\n`);
  return 0;