repremium/mokosh
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(01-13): wave-0 — clean broken Approach-A artifacts per 01-11-SUMMARY

Browse Source 
Restore a clean baseline before promoting the c647f61 prototype to
production paths (Wave 1) and building out Approach-B driver
scaffolding (Wave 2). All deletions trace back to falsifications
documented in 01-11-SUMMARY.md.

Deleted — broken Approach-A files:
  - src/test-hooks/sw-hooks.ts
      MV3 SW blocks dynamic import (Chromium es_modules.md;
      w3c/webextensions#212). The gated `await import('../test-hooks/
      sw-hooks')` from 01-11 Wave 1 never resolved → SW silently died →
      production listeners never registered. File was dead-on-arrival;
      no fix possible while MV3 SWs disallow dynamic import. Approach-B
      replaces SW-side instrumentation with the extension-internal
      harness page's chrome.action.* + chrome.notifications.* surface
      (full privilege; no monkey-patching needed).

  - tests/uat/lib/{launch,extension,sw,offscreen,assertions}.ts
      Popup-bridge architecture (01-11 dbd977c) — falsification 2 +
      falsification 3 in 01-11-SUMMARY: `sw.evaluate` exposes only
      chrome.{loadTimes,csi}, NOT chrome.action.* / chrome.notifications.*
      / chrome.runtime.sendMessage; setPopup-juggling for extension-id
      resolution turned out to be unnecessary (browser.extensions()
      works directly per the prototype). These files will be reborn in
      Wave 2 around the extension-page architecture.

      Kept: tests/uat/lib/zip.ts (host-side JSZip work — architecture-
      agnostic; A12+A13 still use it) and tests/uat/lib/test-hook-
      contract.d.ts (type mirror — extended in Wave 3 but kept as-is here).

  - tests/uat/prototype/probe_{offscreen,sw,tabs,tabs2}.mjs
      Feasibility-research probes (01-11 spike) that empirically falsified
      the Approach-A hypotheses. The findings are encoded in 01-11-
      SUMMARY.md; the probes themselves are dead code.

  - tests/uat/harness.test.ts
      01-11 Wave 2 popup-bridge orchestrator (dbd977c). Imports the
      now-deleted tests/uat/lib/{assertions,extension,sw,offscreen,launch}
      modules — would not typecheck after this commit. Reborn in
      Wave 3A as the Approach-B orchestrator (extension-internal page
      driver + A0 grep gate + 13 assertion drivers).

Reverted — SW-side dynamic-import gate comment block:
  - src/background/index.ts lines 13-29
      The existing comment block (post-spike) described the SW-side
      gated dynamic import that never landed. Rewritten to cite 01-13
      Approach-B explicitly, link to 01-11-SUMMARY.md falsification,
      and clarify that the Tier-1 grep gate's enduring value is
      catching regressions in the offscreen chunk's __MOKOSH_UAT__
      gate (the SW chunk is hook-free by construction).

Updated — Tier-1 grep gate FORBIDDEN_HOOK_STRINGS inventory:
  - tests/background/no-test-hooks-in-prod-bundle.test.ts
      Removed: `simulateUserStop` (Approach-A naming; replaced by
      Approach-B `dispatchEndedOnTrack` which matches the W3C
      dispatchEvent semantics per RESEARCH §7 BLOCKER — track.stop()
      does NOT fire 'ended' per spec, so the simulation MUST use
      dispatchEvent).
      Added: `installFakeDisplayMedia`, `uninstallFakeDisplayMedia`,
      `dispatchEndedOnTrack`, `__mokoshOffscreenQuery`.
      Total inventory: 8 surface strings (was 5). Each MUST be absent
      from every file under dist/ post-build.

Verification (all GREEN):
  - `npm run build` — exit 0; dist/ populated.
  - `grep -rln <forbidden> dist/` — 0 matches.
  - `npm run build:test` — exit 0; dist-test/ populated; offscreen-hooks
    chunk contains `installFakeDisplayMedia` (gate runs correctly
    against the test build's distinct artifact).
  - `npx tsc --noEmit` — exit 0 (root + tests/uat/tsconfig.json).
  - `npx vitest run` — 92/92 tests passing (was 89; the +3 new tests
    come from the FORBIDDEN_HOOK_STRINGS list expanding 5 → 8 — each
    forbidden string is one parametric `it(...)` block).

Both prior-failing tests now GREEN:
  - tests/background/sw-bundle-import.test.ts (was missing dist/ → 92/92
    requires the test run to have a current dist/; vitest gate test
    rebuilds via execFile when SKIP_BUILD≠1, otherwise relies on prior
    `npm run build`).
  - tests/background/no-test-hooks-in-prod-bundle.test.ts (was failing
    on stale dist; now GREEN against the freshly-rebuilt clean bundle).

Wave 1 (next): promote tests/uat/prototype/{extension-page-harness.html,
extension-page-harness.ts,a6.test.ts} to tests/uat/ via `git mv`;
update vite.test.config.ts rollup input.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mark
2026-05-18 14:54:41 +02:00
parent 70f4f4136a
commit a63066a289
13 changed files with 57 additions and 1991 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
src/background/index.ts
View File

@@ -10,22 +10,36 @@ import type {
import { remuxSegments } from './webm-remux';
import JSZip from 'jszip';
// ─── Plan 01-11: gated test-hook dynamic import ───────────────────────
// MUST run BEFORE any chrome.* addListener call below so the SW-side
// test hook's addListener monkey-patches catch every handler
// registration. The `__MOKOSH_UAT__` token is text-replaced by Vite at
// build time — `false` in production (vite.config.ts), `true` only in
// the test bundle (vite.test.config.ts). The `if (false)` branch is a
// static dead branch and Rollup tree-shakes the entire `await import`
// away (Plan 01-11 RESEARCH §6, refined: we use a dedicated token
// rather than `import.meta.env.MODE === 'test'` because vitest also
// runs with MODE='test' and gating on MODE would activate the hooks
// inside unit tests + clobber their vi.fn() chrome.* mocks).
// ─── Plan 01-13: NO SW-side test hook gate (Approach B) ──────────────
// Plan 01-11 originally planned a gated `await import('../test-hooks/sw-hooks')`
// here to instrument chrome.* handler registrations from the SW side.
// EMPIRICAL FALSIFICATION (01-11 spike, see 01-11-SUMMARY.md): MV3
// service workers BLOCK dynamic import (Chromium es_modules.md:
// "Dynamic import is currently blocked in Service Workers, but it
// will change in the future."; w3c/webextensions#212 still open as of
// May 2026). The `await import(...)` never resolved → the SW silently
// died at top-of-module init → production chrome.* listeners never
// registered → the entire service worker was non-functional.
//
// The Tier-1 grep gate `tests/background/no-test-hooks-in-prod-bundle
// .test.ts` enforces that `__mokoshTest` is absent from every file
// under `dist/` post-build (T-1-11-01 — Elevation of Privilege via
// leaked hook surface).
// Plan 01-13 (Approach B) DROPS the SW-side hook entirely:
// - The OFFSCREEN-side test hook (src/test-hooks/offscreen-hooks.ts)
// still works because offscreen IS a DOM document where dynamic
// import is supported. See src/offscreen/recorder.ts top-of-module
// for the surviving `if (__MOKOSH_UAT__) { await import(...) }`.
// - SW-side state (badge text, popup, isRecording proxy) is queried
// by the extension-internal harness page via chrome.action.*
// directly (the page has full chrome.* privilege, unlike the
// restricted CDP `sw.evaluate` surface that 01-11 tried first).
// - Architectural rationale + full falsification table:
// .planning/phases/01-stabilize-video-pipeline/01-11-SUMMARY.md
//
// SECURITY INVARIANT (T-1-11-01, retained): production bundle MUST
// contain NO test-hook surface strings. The Tier-1 grep gate
// `tests/background/no-test-hooks-in-prod-bundle.test.ts` enforces
// post-build. In Approach B this invariant is trivially satisfied for
// the SW chunk (no hook imports here at all); the gate's enduring
// value is catching regressions in the offscreen chunk's
// `__MOKOSH_UAT__` gate.
// Default MIME applied when a wire chunk somehow lacks a type
// field (defense-in-depth: in normal operation the offscreen recorder

311
src/test-hooks/sw-hooks.ts
View File

@@ -1,311 +0,0 @@
// src/test-hooks/sw-hooks.ts — Plan 01-11 Task 2 (SW-side test hook).
//
// Installs `globalThis.__mokoshTest` in the Service Worker isolate. The
// harness reads this surface via `sw.evaluate(...)` to:
// - re-fire captured chrome.* event handlers (assertion 8 — Bug A
// onStartup notification path);
// - count chrome.notifications.create invocations + snapshot the most
// recent options + accumulate ids (assertions 7, 8 — recovery +
// startup notifications).
//
// This module is imported ONLY from src/background/index.ts via a gated
// dynamic import:
// if (import.meta.env.MODE === 'test') {
// await import('../test-hooks/sw-hooks');
// }
// Vite's mode replacement makes the literal-comparison branch dead code
// in production mode (Plan 01-11 RESEARCH §6). The Tier-1 grep gate
// `tests/background/no-test-hooks-in-prod-bundle.test.ts` verifies the
// tree-shake landed by asserting `__mokoshTest` / `simulateUserStop` /
// `getSegmentCount` etc. are absent from every file in `dist/`.
//
// Load-order contract (CRITICAL): the dynamic import in
// src/background/index.ts MUST be at the TOP of the module — BEFORE any
// `chrome.action.onClicked.addListener` / `chrome.runtime.onStartup
// .addListener` / `chrome.notifications.onClicked.addListener` /
// `chrome.notifications.create` call. The hook monkey-patches each of
// those APIs; calls before the patch register lose handler capture +
// miss notification observability. The production listener registrations
// (src/background/index.ts:840+) run AFTER the top-of-module dynamic
// import resolves, so this ordering is satisfied by placement.
//
// Implementation note (overload variance): chrome.notifications.create
// is declared as a triple-overload (id+options+callback / options+callback /
// id+options as Promise-returning / options as Promise-returning). The
// monkey-patch wraps every shape by collecting all arguments via rest
// spread + dispatching to the original create at the end. The reassignment
// goes through `as unknown` (NOT `as any` per project style + CLAUDE.md
// rule "no `@ts-ignore`") — `as unknown` is the project-style escape
// hatch where typed overload variance is unavoidable.
//
// Reference for chrome.notifications.create overloads:
// https://developer.chrome.com/docs/extensions/reference/api/notifications#method-create
// Reference for monkey-patching event listeners safely (preserving `this`):
// MDN: Function.prototype.bind
// https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function/bind
import type { MokoshTestSurface } from './types';
// Module-level mutable cells holding the hook surface state. The exported
// `__mokoshTest` object closes over these so mutations land on the live
// surface the harness reads.
const handlers: MokoshTestSurface['handlers'] = {
onClicked: null,
onStartup: null,
notificationOnClicked: null,
};
const notificationIds: string[] = [];
let notificationCount = 0;
let lastNotificationOptions: chrome.notifications.NotificationOptions<true> | null = null;
// ─── Monkey-patch chrome.action.onClicked.addListener ─────────────────
// Capture the FIRST handler registration. Subsequent registrations
// (which the production code does not currently do — only one
// onClicked listener) would overwrite the capture; the harness
// asserts behavior, not exclusivity, so overwrite semantics are
// acceptable.
//
// We must bind() the original `addListener` so the production code's
// invocation context (the onClicked event object) is preserved when
// the patched function delegates back to it.
const origActionAddListener = chrome.action.onClicked.addListener.bind(
chrome.action.onClicked,
);
chrome.action.onClicked.addListener = ((callback: (tab: chrome.tabs.Tab) => void | Promise<void>): void => {
handlers.onClicked = callback;
origActionAddListener(callback);
}) as typeof chrome.action.onClicked.addListener;
// ─── Monkey-patch chrome.runtime.onStartup.addListener ────────────────
const origStartupAddListener = chrome.runtime.onStartup.addListener.bind(
chrome.runtime.onStartup,
);
chrome.runtime.onStartup.addListener = ((callback: () => void | Promise<void>): void => {
handlers.onStartup = callback;
origStartupAddListener(callback);
}) as typeof chrome.runtime.onStartup.addListener;
// ─── Monkey-patch chrome.notifications.onClicked.addListener ──────────
const origNotifClickedAddListener = chrome.notifications.onClicked.addListener.bind(
chrome.notifications.onClicked,
);
chrome.notifications.onClicked.addListener = ((callback: (notificationId: string) => void | Promise<void>): void => {
handlers.notificationOnClicked = callback;
origNotifClickedAddListener(callback);
}) as typeof chrome.notifications.onClicked.addListener;
// ─── Monkey-patch chrome.notifications.create (overload-variant) ──────
// The original create signature is overloaded — Chrome accepts:
// create(id, options, callback?) → string
// create(options, callback?) → string
// create(id, options) → Promise<string> (Chrome 88+)
// create(options) → Promise<string> (Chrome 88+)
// To wrap every shape uniformly we collect args via rest, normalize the
// (id, options) pair via type-guard on the first arg, then re-dispatch
// to the original. Both callback + Promise return paths funnel through
// the same id-capture path: callback-form via wrapping the user callback,
// Promise-form via .then() on the returned thenable. The capture lands
// in notificationIds regardless of which call shape the production code
// used (src/background/index.ts uses the (id, options) shape — both
// for startup and recovery notifications).
const origNotifCreate = chrome.notifications.create.bind(chrome.notifications);
type NotifCreateArgs =
| [chrome.notifications.NotificationOptions<true>]
| [chrome.notifications.NotificationOptions<true>, (notificationId: string) => void]
| [string, chrome.notifications.NotificationOptions<true>]
| [string, chrome.notifications.NotificationOptions<true>, (notificationId: string) => void];
/**
* Wrapping shim for chrome.notifications.create. Increments
* notificationCount, captures lastNotificationOptions, and records
* the resolved notification id in notificationIds — across BOTH the
* callback-style and Promise-style return paths.
*
* @param args - The original create arguments, captured via rest.
* @returns Whatever the original create returns (string id OR Promise<string>).
*/
function patchedNotifCreate(...args: NotifCreateArgs): string | Promise<string> {
// Normalize (id, options, callback) | (options, callback) into a
// unified (proposedId, options, userCallback) triple. The proposedId
// is null when the caller omitted it; Chrome auto-generates one and
// returns it via the callback / Promise.
let proposedId: string | null;
let options: chrome.notifications.NotificationOptions<true>;
let userCallback: ((id: string) => void) | undefined;
if (typeof args[0] === 'string') {
proposedId = args[0];
options = args[1] as chrome.notifications.NotificationOptions<true>;
userCallback = args[2] as ((id: string) => void) | undefined;
} else {
proposedId = null;
options = args[0];
userCallback = args[1] as ((id: string) => void) | undefined;
}
notificationCount += 1;
lastNotificationOptions = options;
/**
* Record the resolved id (the one Chrome actually assigned — same as
* proposedId when provided, otherwise auto-generated).
* @param resolvedId - The id Chrome returned.
*/
const recordId = (resolvedId: string): void => {
notificationIds.push(resolvedId);
};
// Dispatch through to the original create with a wrapping callback
// so the callback-form path captures the id. The wrapping callback
// chains to the user's callback if any.
if (userCallback !== undefined) {
const wrappingCallback = (resolvedId: string): void => {
recordId(resolvedId);
userCallback!(resolvedId);
};
if (proposedId !== null) {
return origNotifCreate(
proposedId,
options,
wrappingCallback,
) as unknown as string;
}
return origNotifCreate(
options,
wrappingCallback,
) as unknown as string;
}
// No user callback supplied — Chrome 88+ returns a Promise. Older
// Chromes return undefined and require a callback for the id. Since
// our manifest targets MV3 (Chrome 88+), Promise return is canonical.
// Chain a .then so we still record the id.
//
// Cast through `unknown` because @types/chrome's declared return for
// create-without-callback is `void` (the type maintainers haven't yet
// modeled Chrome 88+'s Promise return) — but the runtime DOES return a
// Promise<string>. We discriminate by runtime typeof / instanceof to
// be robust to both possibilities.
const ret: unknown = proposedId !== null
? origNotifCreate(proposedId, options)
: origNotifCreate(options);
// Some Chrome SW versions return string immediately; others return a
// Promise. Discriminate by typeof to be safe.
if (typeof ret === 'string') {
recordId(ret);
return ret;
}
if (ret instanceof Promise) {
return (ret as Promise<string>).then((resolvedId) => {
recordId(resolvedId);
return resolvedId;
});
}
// Defensive: neither string nor Promise — return as-is (caller can
// still see the count + options snapshot).
return ret as string;
}
(chrome.notifications.create as unknown) = patchedNotifCreate;
// ─── Install the global surface ───────────────────────────────────────
// Use Object.defineProperty for notificationIds to expose a defensive-
// copy getter (so test consumers cannot mutate the underlying record
// from inside an evaluate block).
globalThis.__mokoshTest = {
handlers,
get notificationCount() {
return notificationCount;
},
get lastNotificationOptions() {
return lastNotificationOptions;
},
get notificationIds() {
return notificationIds.slice();
},
} as MokoshTestSurface;
// ─── Harness message bridge ───────────────────────────────────────────
// EMPIRICAL ARCHITECTURE NOTE: Puppeteer 25 + Chrome 148 + headless
// cannot reliably evaluate against the SW directly. The harness
// queries chrome.* state through the popup page (which has full
// chrome.* API access) but cannot read the SW's globalThis.__mokoshTest
// because the popup is a SEPARATE V8 isolate. So we bridge: the popup
// sends chrome.runtime.sendMessage queries; this handler responds with
// the queried state.
//
// Protocol — popup → SW message: { type: '__mokoshTestQuery', op: <string> }
// Response shapes:
// op='snapshot' → { count, lastOptions, ids }
// op='fire-on-startup' → { ok: true } OR { ok: false, error: 'no-handler' }
// op='handler-types' → { onClicked, onStartup, notificationOnClicked }
// Unknown ops respond { ok: false, error: 'unknown-op' }.
//
// Returning `true` from the onMessage handler tells Chrome the
// response is async; we keep sendResponse as a closed-over callback.
// The bridge handler is registered AFTER the production listeners so
// the hook never accidentally intercepts a production message —
// __mokoshTest* messages are unambiguously test-only.
chrome.runtime.onMessage.addListener((rawMessage, _sender, sendResponse) => {
// Narrow the message — we accept ANY shape but only act on our type.
if (rawMessage === null || typeof rawMessage !== 'object') {
return false;
}
const message = rawMessage as { type?: unknown; op?: unknown };
if (message.type !== '__mokoshTestQuery') {
// Not our message — production handler will take it.
return false;
}
const op = String(message.op ?? '');
if (op === 'snapshot') {
sendResponse({
count: notificationCount,
lastOptions: lastNotificationOptions,
ids: notificationIds.slice(),
});
return false; // Sync response — return false per Chrome onMessage contract.
}
if (op === 'fire-on-startup') {
const h = handlers.onStartup;
if (h === null) {
sendResponse({ ok: false, error: 'no-handler' });
return false;
}
// Fire-and-respond. The handler may be async; we don't await it
// for the response, but if it throws synchronously the catch
// surfaces in the response.
try {
// Schedule on microtask so the response goes out first; the
// handler's side effects (notifications.create) happen right
// after, before the next harness assertion polls.
queueMicrotask(() => {
Promise.resolve(h()).catch((err) => {
// Swallow async errors — the assertion 8 check is on the
// notification side effect, not the handler's return value.
console.warn('[mokoshTest bridge] onStartup handler threw:', err);
});
});
sendResponse({ ok: true });
} catch (err) {
sendResponse({
ok: false,
error: err instanceof Error ? err.message : String(err),
});
}
return false;
}
if (op === 'handler-types') {
sendResponse({
onClicked: typeof handlers.onClicked,
onStartup: typeof handlers.onStartup,
notificationOnClicked: typeof handlers.notificationOnClicked,
});
return false;
}
sendResponse({ ok: false, error: 'unknown-op' });
return false;
});
export {};