@warpgogol/forge 4.2.3 → 4.2.4

package/AGENTS.md

@@ -7,7 +7,7 @@ Portable governance skills and command modules extracted from the engine (RFC-03
 - `src/` — portable, no kernel imports. Contains skill schema, registry, validators, onboarding handlers, config module, canonical types, and utilities.
 - `os/` — ForgeModule registrations. RFC-0556: `os/compass/` and `os/werkstatt/` are fully autonomous — all command handlers are inlined in `os/*/handlers/` and no longer dynamically import `@warpgogol/*` packages. Other `os/` modules may still use dynamic imports where kernel integration is needed. RFC-0940: all `os/*.module.ts` files declare a required `runtime` field (`"autonomous"` or `"werkstatt-adapter"`). Only `os/werkstatt/` may import `@warpgogol/werkstatt-engine` — all other `os/` directories are autonomous. ADR-0019: `@warpgogol/werkstatt-shared` is no longer a dependency — `scanDirectoryForImports` is inlined in `os/core/handlers/forge-autonomy-validate.ts`. `forge.autonomy.validate` enforces FORGE-AUTONOMY-01. Type-only imports (`import type`) are exempt.
 - `bin/` — CLI entrypoint (`forge` command) for autonomous usage without `@warpgogol/werkstatt-engine`. **New `os/` modules MUST be registered manually in `bin/cli.ts` `buildRegistry()`** — the standalone CLI has no module auto-discovery. A module exported via `package.json` and wired in `tools/kernel.config.ts` profiles is still invisible to `forge <cmd>` until added to the registry array. Discovered 2026-09-16: `forge-adr` (and 6 other modules) existed in source but were unreachable via the CLI.
-- `skills/` — forge-managed skill definitions (29 fo skills + 5 shared + 3 meta = 37 skills). Project-declared skill packs (RFC-0539) live outside forge and are discovered via `discoverPackSkills` from `forge.yaml` `skillPacks` config.
+- `skills/` — forge-managed skill definitions (29 fo skills + 6 shared + 3 meta = 38 skills). Project-declared skill packs (RFC-0539) live outside forge and are discovered via `discoverPackSkills` from `forge.yaml` `skillPacks` config.
 
 ## RFC-0855 program control-plane boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "4.2.3",
+  "version": "4.2.4",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/skills/shared/extension-e2e-mitm/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: extension-e2e-mitm
+description: Intercept Chrome-extension tab navigations in Playwright e2e via a local CONNECT MITM proxy — the only reliable seam when page.route cannot see chrome.tabs.create traffic.
+invocation: user
+category: shared
+concerns: code-mutation
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+# extension-e2e-mitm
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+Use this skill when a Playwright e2e suite must control what a Chrome MV3 extension's tabs load — and `context.route` / `page.route` cannot see the traffic.
+
+## When this applies
+
+- The extension's service worker opens tabs via `chrome.tabs.create` (or `windows.create`).
+- Playwright route interception is installed but the fixture HTML never reaches the tab.
+- Symptom: `context.on("page")` fires with the real URL already in flight — the navigation started before the page surfaced to Playwright, so no route handler ever runs.
+
+This is a hard platform limitation, not a misconfiguration: extension-spawned navigations bypass the Playwright route layer entirely. Do not retry routing with different scopes (`context.route`, per-page `page.route`, `routeFromHAR`) — none of them see the request. Intercept at the network layer instead.
+
+## The pattern
+
+1. **Local CONNECT proxy** (`fixture-proxy.ts` in this skill's directory — copy it into the project's e2e folder). It listens on `127.0.0.1`, accepts CONNECT only for an allowlist of host suffixes, answers TLS with a per-run self-signed cert, and serves the currently-installed fixture HTML for every request. Non-allowlisted CONNECTs are refused — the proxy never tunnels real traffic.
+2. **Browser flags** at `chromium.launchPersistentContext`:
+   - `--proxy-server=http://127.0.0.1:<port>` — all browser traffic through the proxy.
+   - `--proxy-bypass-list=127.0.0.1;localhost` — the local API/backend must NOT go through the proxy.
+   - `--ignore-certificate-errors-spki-list=<spki>` — whitelist ONLY the proxy cert's SPKI fingerprint (exposed as `proxy.spkiFingerprint`). Never use blanket `--ignore-certificate-errors` — it disables TLS verification for the whole browser.
+3. **Fixture swap** — `proxy.setContent(html)` changes what every intercepted request returns. Install fixtures per spec, not per suite.
+
+## Integration steps
+
+1. Copy `fixture-proxy.ts` into the project's e2e directory.
+2. Pass the site's host suffixes to `startFixtureProxy({ hosts: [...] })` — the cert CN/SAN and the CONNECT allowlist derive from them.
+3. Launch the browser with the three flags above (proxy server, bypass list, spki-list).
+4. In each spec, `proxy.setContent(fixtureHtml)` before triggering the extension flow; assert on backend state (D1/API), not on page DOM.
+5. Close the proxy with the browser context (`context.on("close", () => proxy.close())`).
+
+## Parameters and limits
+
+- `hosts` — suffix list; `host === suffix || host.endsWith("." + suffix)` matches. Keep it tight: only the fixture-served sites.
+- The cert is generated per run via `openssl req -x509` into a temp dir — openssl must be on PATH; no secrets touch the repo.
+- The CONNECT parser reads the first TCP chunk — sufficient on loopback; do not reuse this proxy for real forwarding.
+- Headed browser required for MV3 service workers — wrap CI in `xvfb-run`.
+
+## Anti-patterns
+
+- Do not add runtime hooks to the extension to make it "testable" — the proxy keeps production code untouched.
+- Do not copy fixture HTML into the e2e folder — serve the canonical fixtures from their owning package.
+- Do not broaden the allowlist to "just make it work" — a refused CONNECT is the signal that a new host needs an explicit decision.

package/skills/shared/extension-e2e-mitm/fixture-proxy.ts

@@ -0,0 +1,113 @@
+/*
+@ai-invariant Fixture serving happens at the network layer — a local CONNECT proxy MITMs the allowlisted hosts.
+<MODULE_CONTRACT>
+<purpose>Starts a minimal CONNECT proxy on 127.0.0.1 that answers TLS for the allowlisted hosts with a per-run self-signed cert and serves the current fixture HTML for every request. Extension-spawned tab navigations bypass Playwright's route interception — the proxy intercepts them at the network layer instead.</purpose>
+<non-goals>
+  <item>Does not tunnel or forward real traffic — non-allowlisted CONNECTs are refused; the backend bypasses the proxy via --proxy-bypass-list.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Ported from dater RFC-0015 — parameterized host allowlist and cert SANs.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { createServer, type Server } from "node:net";
+import { TLSSocket, createSecureContext } from "node:tls";
+import { execFileSync } from "node:child_process";
+import { X509Certificate, createHash } from "node:crypto";
+import { readFileSync, mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+export interface FixtureProxy {
+  port: number;
+  /** Base64 SHA-256 of the leaf cert's SPKI — for --ignore-certificate-errors-spki-list. */
+  spkiFingerprint: string;
+  /** Swap the HTML served for every intercepted request. */
+  setContent(html: string): void;
+  close(): void;
+}
+
+export interface FixtureProxyOptions {
+  /** Host suffixes the proxy may MITM — e.g. ["example.com"] also covers sub.example.com. */
+  hosts: string[];
+}
+
+function generateCert(dir: string, hosts: string[]): { key: Buffer; cert: Buffer } {
+  const keyPath = join(dir, "key.pem");
+  const certPath = join(dir, "cert.pem");
+  const primary = hosts[0];
+  if (!primary) throw new Error("fixture proxy needs at least one host");
+  const san = hosts.flatMap((h) => [`DNS:${h}`, `DNS:*.${h}`]).join(",");
+  execFileSync("openssl", [
+    "req", "-x509", "-newkey", "rsa:2048", "-nodes",
+    "-keyout", keyPath,
+    "-out", certPath,
+    "-days", "1",
+    "-subj", `/CN=*.${primary}`,
+    "-addext", `subjectAltName=${san}`,
+  ]);
+  return { key: readFileSync(keyPath), cert: readFileSync(certPath) };
+}
+
+/** Base64 SHA-256 of the cert's SubjectPublicKeyInfo — Chromium's spki-list format. */
+function spkiFingerprintOf(cert: Buffer): string {
+  const spki = new X509Certificate(cert).publicKey.export({ format: "der", type: "spki" });
+  return createHash("sha256").update(spki).digest("base64");
+}
+
+/**
+ * Start a CONNECT proxy that MITMs the allowlisted hosts. Launch the browser
+ * with --proxy-server pointing here, --proxy-bypass-list for the local
+ * backend, and --ignore-certificate-errors-spki-list scoped to
+ * proxy.spkiFingerprint.
+ */
+export async function startFixtureProxy(options: FixtureProxyOptions): Promise<FixtureProxy> {
+  const dir = mkdtempSync(join(tmpdir(), "e2e-fixture-cert-"));
+  const { key, cert } = generateCert(dir, options.hosts);
+  const secureContext = createSecureContext({ key, cert });
+  const spkiFingerprint = spkiFingerprintOf(cert);
+  let content = "<html><body>no fixture installed</body></html>";
+
+  const server: Server = createServer((sock) => {
+    sock.once("data", (head) => {
+      const line = head.toString("utf8").split("\r\n")[0] ?? "";
+      const m = line.match(/^CONNECT ([^:]+):(\d+)/);
+      if (!m) {
+        sock.destroy();
+        return;
+      }
+      const host = m[1]!;
+      if (!options.hosts.some((s) => host === s || host.endsWith(`.${s}`))) {
+        sock.destroy();
+        return;
+      }
+      sock.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      const tls = new TLSSocket(sock, { secureContext, isServer: true });
+      tls.once("secure", () => {
+        tls.once("data", () => {
+          const body = content;
+          tls.end(
+            `HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`,
+          );
+        });
+      });
+      tls.on("error", () => sock.destroy());
+    });
+    sock.on("error", () => sock.destroy());
+  });
+
+  await new Promise<void>((resolveListen) => server.listen(0, "127.0.0.1", resolveListen));
+  const port = (server.address() as { port: number }).port;
+
+  return {
+    port,
+    spkiFingerprint,
+    setContent(html: string) {
+      content = html;
+    },
+    close() {
+      server.close();
+    },
+  };
+}