sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/sm-dev-link.js

@@ -0,0 +1,302 @@
+// The service worker's side of sm-dev, the development tool: which tabs
+// an sm-dev run controls (tab claims), and the events it streams to the
+// runs. Design: docs/sm-dev-design.md.
+//
+// Claims:
+// - A claim names the run that controls a tab: only the run's own
+//   scripts run there, the ones in its test collection, or none when
+//   the tab has its scripts off. `handleCheckPending` (background.ts)
+//   answers `skip` for the rest.
+// - Per tab, not per document: it holds across reloads and navigations.
+// - A lease: the run renews it, and an expired claim counts as gone, so
+//   a killed run can't leave the person's tab running no scripts.
+// - Kept in `chrome.storage.session` as well as memory, so a worker that
+//   Chrome stopped while idle answers the same after it starts again.
+//
+// Runs:
+// - Each run has a lease of its own, renewed with its claims, whether
+//   or not it holds a tab. A run's test collection outlives the lease
+//   by a grace period (`staleRuns`), then the worker removes it: the
+//   run crashed or lost its browser connection.
+// - Kept in session storage too, like the claims.
+//
+// Events:
+// - Each live run subscribes; while any does, events are written to the
+//   worker's console as `console.debug(SM_DEV_EVENT, json)`, where
+//   Playwright reports them to the run. Without a subscriber nothing is
+//   written.
+// - A subscription is a lease too, renewed with the run's claims. It
+//   lives in memory only: a restarted worker has none, and the run
+//   subscribes again when it sees the new worker.
+//
+// Wrappers that skip asking:
+// - A `document-start` wrapper runs its body without asking where the
+//   answer can only be `run` (see `canSkipDecision` in
+//   userscript-prelude.js). A claim can `skip` on any navigation, so in
+//   a browser sm-dev is connected to every wrapper asks, unless its tab
+//   vouches for its script. sm-dev marks the tabs for that; see
+//   docs/sm-dev-design.md#making-wrappers-ask.
+import { SM_DEV_EVENT } from '../sm-dev-protocol.js';
+const CLAIMS_KEY = 'smDevClaims';
+const RUNS_KEY = 'smDevRuns';
+const LAST_SWEEP_KEY = 'smDevLastSweep';
+/**
+ * How long a run's test collection is kept after its lease runs out,
+ * in case the run was only stalled.
+ */
+export const RUN_GRACE_MS = 5 * 60_000;
+/**
+ * Sweeps come every minute while any test collection exists. A longer
+ * gap means the computer slept, or the browser stalled, and sm-dev with
+ * it, so the leases that ran out meanwhile say nothing about its runs.
+ */
+const SWEEP_GAP_MS = 3 * 60_000;
+const claims = new Map();
+// Run id → when its lease runs out.
+const runs = new Map();
+// When `staleRuns` last ran, or 0.
+let lastSweep = 0;
+// Run id → when its event subscription runs out.
+const subscribers = new Map();
+let loading = null;
+/**
+ * Resolves once the claims kept in session storage are in memory. Called
+ * before any answer that depends on them, so a worker that just started
+ * can't answer `run` for a claimed tab.
+ */
+export function claimsReady() {
+    loading ??= (async () => {
+        try {
+            const got = await chrome.storage.session.get([CLAIMS_KEY, RUNS_KEY, LAST_SWEEP_KEY]);
+            const stored = got[CLAIMS_KEY];
+            for (const [tabId, claim] of Object.entries(stored ?? {})) {
+                // Ones set in memory meanwhile are newer.
+                if (!claims.has(Number(tabId)))
+                    claims.set(Number(tabId), claim);
+            }
+            const storedRuns = got[RUNS_KEY];
+            for (const [runId, expires] of Object.entries(storedRuns ?? {})) {
+                if (!runs.has(runId))
+                    runs.set(runId, expires);
+            }
+            if (lastSweep === 0 && typeof got[LAST_SWEEP_KEY] === 'number')
+                lastSweep = got[LAST_SWEEP_KEY];
+        }
+        catch (err) {
+            console.info('[SourceMonkey] could not read the sm-dev tab claims:', err);
+        }
+    })();
+    return loading;
+}
+function persist() {
+    const stored = {};
+    for (const [tabId, claim] of claims)
+        stored[tabId] = claim;
+    chrome.storage.session.set({ [CLAIMS_KEY]: stored, [RUNS_KEY]: Object.fromEntries(runs), [LAST_SWEEP_KEY]: lastSweep }).catch((err) => {
+        console.info('[SourceMonkey] could not save the sm-dev tab claims:', err);
+    });
+}
+/** The tab's claim, if one is in force. Call after `claimsReady`. */
+export function activeClaim(tabId) {
+    const claim = claims.get(tabId);
+    if (!claim)
+        return null;
+    if (claim.expires < Date.now()) {
+        claims.delete(tabId);
+        persist();
+        return null;
+    }
+    return claim;
+}
+/**
+ * Whether a script may run in a tab with this claim. `scriptRun`: the
+ * run a scratch script belongs to (`scratchRunOf`), null for any other.
+ */
+export function claimAllows(claim, scriptRun) {
+    return !claim.scriptsOff && scriptRun === claim.runId;
+}
+export async function claimTab(tabId, runId, ttlMs) {
+    await claimsReady();
+    const expires = Date.now() + ttlMs;
+    claims.set(tabId, { runId, expires });
+    runs.set(runId, Math.max(runs.get(runId) ?? 0, expires));
+    persist();
+}
+// The navigations sm-dev names a tab by, by their fragment: each a
+// promise of the tab's id, null once it timed out.
+const namingNavigations = new Map();
+/**
+ * Watches for a top frame navigating to a URL ending in `#<fragment>`,
+ * for `namedTab` to say which tab it was. sm-dev knows a tab by its CDP
+ * target and the extension by its `chrome.tabs` id; neither sees the
+ * other's, so sm-dev sends the tab to `about:blank#<fragment>` between
+ * the two calls. Stops watching after `timeoutMs`.
+ */
+export function watchForNamingNavigation(fragment, timeoutMs) {
+    const wanted = `#${fragment}`;
+    namingNavigations.set(fragment, new Promise((resolve) => {
+        const heard = (details) => {
+            if (details.frameId !== 0 || !details.url.endsWith(wanted))
+                return;
+            stop();
+            resolve(details.tabId);
+        };
+        const stop = () => {
+            clearTimeout(timer);
+            chrome.webNavigation.onCommitted.removeListener(heard);
+            chrome.webNavigation.onReferenceFragmentUpdated.removeListener(heard);
+        };
+        // Gone from the table too, should nobody ask for it.
+        const timer = setTimeout(() => {
+            stop();
+            namingNavigations.delete(fragment);
+            resolve(null);
+        }, timeoutMs);
+        chrome.webNavigation.onCommitted.addListener(heard);
+        chrome.webNavigation.onReferenceFragmentUpdated.addListener(heard);
+    }));
+}
+/** The tab that made the navigation `fragment` names, or null if none did in time. */
+export async function namedTab(fragment) {
+    const found = namingNavigations.get(fragment);
+    namingNavigations.delete(fragment);
+    return found ?? null;
+}
+/** Turns a claimed tab's scripts off, or back on (`open --noscript` / `--script`). */
+export async function setTabScriptsOff(tabId, off) {
+    await claimsReady();
+    const claim = claims.get(tabId);
+    if (!claim)
+        return;
+    if (off)
+        claim.scriptsOff = true;
+    else
+        delete claim.scriptsOff;
+    persist();
+}
+/**
+ * Extends a run's lease, claims and event subscription by `ttlMs`.
+ *
+ * `tabs` are the tabs the run holds. One whose claim is gone (it ran
+ * out while the worker was stopped, or an extension reload cleared the
+ * session storage) is claimed again, if the tab is still open. Returns
+ * how many were.
+ */
+export async function renewRun(runId, ttlMs, tabs = []) {
+    await claimsReady();
+    const expires = Date.now() + ttlMs;
+    runs.set(runId, expires);
+    for (const claim of claims.values()) {
+        if (claim.runId === runId)
+            claim.expires = expires;
+    }
+    let restored = 0;
+    for (const tab of tabs) {
+        if (claims.has(tab.tabId))
+            continue;
+        const open = await chrome.tabs.get(tab.tabId).then(() => true, () => false);
+        if (!open)
+            continue;
+        claims.set(tab.tabId, { runId, expires, ...(tab.scriptsOff ? { scriptsOff: true } : {}) });
+        restored++;
+    }
+    subscribers.set(runId, expires);
+    persist();
+    return restored;
+}
+/**
+ * Ends a run's lease, claims and event subscription. The caller removes
+ * its test collection.
+ */
+export async function releaseRun(runId) {
+    await claimsReady();
+    for (const [tabId, claim] of claims) {
+        if (claim.runId === runId)
+            claims.delete(tabId);
+    }
+    runs.delete(runId);
+    subscribers.delete(runId);
+    persist();
+}
+/**
+ * Of the runs that have a test collection, the ones whose collection
+ * should go: their lease ran out more than `RUN_GRACE_MS` ago.
+ *
+ * - A run with no lease on record (one from before the browser
+ *   restarted) starts its grace period now.
+ * - After a gap since the last sweep (`SWEEP_GAP_MS`), every lease
+ *   starts its grace period now instead, and none is stale: a run that
+ *   slept with the computer renews again within seconds.
+ */
+export async function staleRuns(withCollections, now = Date.now()) {
+    await claimsReady();
+    const stale = [];
+    const gap = lastSweep > 0 && now - lastSweep > SWEEP_GAP_MS;
+    lastSweep = now;
+    for (const runId of withCollections) {
+        if (!runs.has(runId))
+            runs.set(runId, now);
+    }
+    if (gap) {
+        for (const [runId, expires] of runs)
+            runs.set(runId, Math.max(expires, now));
+        persist();
+        return stale;
+    }
+    // Every long-gone run is forgotten, one without a collection too (a
+    // run killed before it pushed a script).
+    for (const [runId, expires] of runs) {
+        if (expires + RUN_GRACE_MS >= now)
+            continue;
+        runs.delete(runId);
+        if (withCollections.includes(runId))
+            stale.push(runId);
+    }
+    persist();
+    return stale;
+}
+/** Forgets every claim, lease and subscription, for the e2e tests' reset. */
+export function resetSmDevLinkForTests() {
+    claims.clear();
+    runs.clear();
+    subscribers.clear();
+    lastSweep = 0;
+}
+/**
+ * A tab a claimed tab opened (`window.open`, a link to a new tab) gets
+ * its opener's claim. Called from `onCreatedNavigationTarget`, which
+ * comes before the new tab's scripts ask: they wait on `claimsReady`
+ * too, behind this.
+ */
+export async function inheritClaim(sourceTabId, tabId) {
+    await claimsReady();
+    const claim = activeClaim(sourceTabId);
+    if (!claim)
+        return;
+    claims.set(tabId, { ...claim });
+    persist();
+}
+export function dropClaim(tabId) {
+    if (!claims.delete(tabId))
+        return;
+    persist();
+}
+/** Sends an event to the subscribed runs, if any is live. */
+export function emitSmDevEvent(event) {
+    const now = Date.now();
+    let live = false;
+    for (const [runId, expires] of subscribers) {
+        if (expires < now)
+            subscribers.delete(runId);
+        else
+            live = true;
+    }
+    if (!live)
+        return;
+    try {
+        console.debug(SM_DEV_EVENT, JSON.stringify({ ...event, at: now }));
+    }
+    catch {
+        // An event that can't be serialized is dropped.
+    }
+}

package/dist/extension/solo-click.js

@@ -0,0 +1,58 @@
+// What an enable checkbox says, and the Ctrl/Cmd-click that opts it out
+// of turning a script's other copies off. Shared by every surface with
+// an enable checkbox: the viewer, the collections page, the toolbar
+// popup. See docs/script-enablement.md.
+import { ENABLE_TITLE } from '../script-display.js';
+// What every enable checkbox says, and the tail it adds when clicking
+// it would sweep other copies. Shared so every surface says exactly the
+// same thing: the hint is the only part of them that varies.
+//
+// Deliberately short, and deliberately fixed. Naming the copy would
+// repeat the Collection and Location cells an inch to the right, and
+// swapping to "Disable" when checked would make one control read two
+// ways for no gain.
+//
+// The hint names ONE key — the one this machine has. The handler
+// accepts either, but only one is usable here (on a Mac ctrl-click opens
+// the context menu, so Cmd is the one that works), and a message
+// offering both would be telling half its readers about a gesture their
+// keyboard doesn't have. The docs say "Ctrl/Cmd" because
+// they describe every platform at once; the app knows which one it is
+// running on.
+const SOLO_HINT = ` (${isApplePlatform() ? 'Cmd' : 'Ctrl'}-click for multi-enable)`;
+// Resolved once, at module load — the platform can't change under us.
+// `userAgentData` is the supported spelling and is present in every
+// Chrome that can run this extension; `platform` is the fallback for a
+// non-Chrome host and for the tests' DOM stubs.
+function isApplePlatform() {
+    const data = navigator.userAgentData;
+    if (data?.platform)
+        return data.platform === 'macOS';
+    return /mac|iphone|ipad/i.test(navigator.platform || '');
+}
+// Wording for an enable checkbox, hint included only when clicking it
+// would sweep other copies.
+export function enableTitle(sweepsOthers) {
+    return sweepsOthers ? `${ENABLE_TITLE}${SOLO_HINT}` : ENABLE_TITLE;
+}
+// Wire a checkbox so its `change` handler can find out whether the
+// click that produced it carried the exclusive-opt-out modifier.
+// Returns a consume-once reader.
+//
+// Read from `click`, not `change`: `change` carries no modifier state.
+// Keyboard activation (space) fires a click too, so nothing is lost —
+// and `ctrlKey` is simply false there, which is the right default.
+// `metaKey` covers Cmd-click on a Mac, where ctrl-click is the context
+// menu. Consumed on read, so a later `change` that arrives without a
+// click in front of it can't inherit a modifier pressed once.
+export function watchSoloModifier(box) {
+    let solo = false;
+    box.addEventListener('click', (ev) => {
+        solo = ev.ctrlKey || ev.metaKey;
+    });
+    return () => {
+        const was = solo;
+        solo = false;
+        return was;
+    };
+}

package/dist/extension/sticky-numbers.js

@@ -0,0 +1,188 @@
+// Sticky numbers: a short number for each installed script and each
+// collection, which sm-dev names them by (`E12`, `C3`). Log IDs carry the
+// script's (`foo.user.js#E12`). See docs/storage.md#sticky-numbers.
+//
+// - Each kind has one row (`scriptNumbers`, `collectionNumbers`), rather
+//   than a field on each script or collection row: those rows are
+//   rewritten from many places, and a number lost in one of those
+//   rewrites would be handed out again as a new one.
+// - Only the service worker writes the rows (`assignNumbers`, run before
+//   each registration sync), so two installs can't take the same number.
+//   Pages only read them.
+// - A removed item's number is held back for a while before reuse, so an
+//   id someone saw a moment ago never names a different item.
+import { sharedRows } from './row-cache.js';
+import { assertWorkerContext } from '../run-context.js';
+import { isSmDevCollection } from './directories.js';
+import { ensureCollectionKeysMigrated } from './script-store.js';
+export const SCRIPT_NUMBERS_KEY = 'scriptNumbers';
+export const COLLECTION_NUMBERS_KEY = 'collectionNumbers';
+/** How long a removed item's number waits before it can be reused. */
+export const NUMBER_HOLD_MS = 7 * 24 * 60 * 60 * 1000;
+/** The stored row, or an empty one; tolerates a malformed row. */
+export function numbersFrom(value) {
+    const row = value;
+    return {
+        byId: row?.byId && typeof row.byId === 'object' ? row.byId : {},
+        retired: row?.retired && typeof row.retired === 'object' ? row.retired : {},
+    };
+}
+/** The numbers by id, for log IDs. */
+export function numberMap(numbers) {
+    return new Map(Object.entries(numbers.byId));
+}
+/**
+ * The numbers after reconciling them with the items that should have
+ * one (`wanted`, in the order new numbers are handed out):
+ *
+ * - a wanted item keeps its number; if two share one (a restored
+ *   backup, say), the first keeps it and the other gets a new one;
+ * - a number whose item is gone, or no longer wanted, is retired from
+ *   `now`, unless it was already;
+ * - a retired number held for `holdMs` is free again;
+ * - a wanted item without a number gets the lowest free one.
+ *
+ * Pure. `changed` is false when nothing moved, so the caller can skip
+ * the write.
+ */
+export function reconcileNumbers(prior, wanted, now, holdMs = NUMBER_HOLD_MS) {
+    const byId = {};
+    const retired = { ...prior.retired };
+    const used = new Set();
+    for (const id of wanted) {
+        const n = prior.byId[id];
+        if (!Number.isInteger(n) || n < 1 || used.has(n))
+            continue;
+        byId[id] = n;
+        used.add(n);
+        // In use again (a reconcile that went wrong earlier): not retired.
+        delete retired[n];
+    }
+    for (const [id, n] of Object.entries(prior.byId)) {
+        if (byId[id] === n || used.has(n) || String(n) in retired)
+            continue;
+        retired[n] = now;
+    }
+    for (const [n, at] of Object.entries(retired)) {
+        if (now - at >= holdMs)
+            delete retired[n];
+    }
+    let next = 1;
+    for (const id of wanted) {
+        if (id in byId)
+            continue;
+        while (used.has(next) || String(next) in retired)
+            next++;
+        byId[id] = next;
+        used.add(next);
+    }
+    const numbers = { byId, retired };
+    return { numbers, changed: !sameNumbers(prior, numbers) };
+}
+function sameNumbers(a, b) {
+    const same = (x, y) => {
+        const keys = Object.keys(x);
+        return keys.length === Object.keys(y).length && keys.every((k) => x[k] === y[k]);
+    };
+    return same(a.byId, b.byId) && same(a.retired, b.retired);
+}
+function byPath(collections) {
+    return [...collections].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/**
+ * The collections that get a number, by path. Not sm-dev's test
+ * collections, which a run names itself, and adds and drops too often
+ * to number.
+ */
+export function numberedCollectionIds(collections) {
+    return byPath(collections).filter((c) => !isSmDevCollection(c.path)).map((c) => c.id);
+}
+/**
+ * The scripts that get a number, in the order new ones are handed out:
+ * collections by path, then each collection's own order. Not the
+ * scripts in sm-dev's test collections, which a run names `1`, `2`
+ * itself, and pushes and removes too often to number.
+ */
+export function numberedScriptIds(scriptIds, collections) {
+    const present = new Set(scriptIds);
+    const ids = [];
+    const seen = new Set();
+    for (const collection of byPath(collections)) {
+        if (isSmDevCollection(collection.path)) {
+            for (const id of collection.scriptIds)
+                seen.add(id);
+            continue;
+        }
+        for (const id of collection.scriptIds) {
+            if (!present.has(id) || seen.has(id))
+                continue;
+            seen.add(id);
+            ids.push(id);
+        }
+    }
+    // A script row whose collection doesn't list it still gets a number.
+    for (const id of scriptIds)
+        if (!seen.has(id))
+            ids.push(id);
+    return ids;
+}
+let assigning = Promise.resolve(null);
+/**
+ * Reconciles the stored numbers with the stored scripts and collections,
+ * writes the rows that moved, and resolves to the numbers (null when
+ * they couldn't be read). Serialized, so two calls never write over each
+ * other. Service worker only: it is the rows' one writer.
+ *
+ * Runs before every registration sync, so it reads only what it needs:
+ * which scripts and collections exist (from the worker's row cache,
+ * else the keys and the collection rows) and the numbers rows.
+ */
+export function assignNumbers() {
+    const run = assigning.then(async () => {
+        // Collection rows may still be under their old key spelling.
+        await ensureCollectionKeysMigrated();
+        // Which scripts and collections exist: from the worker's row cache
+        // when it's on (frozen rows, read only), else from storage.
+        const isRow = (k) => k.startsWith('script:') || k.startsWith('collection:');
+        const cached = await sharedRows(isRow);
+        const keys = cached ? Object.keys(cached) : await chrome.storage.local.getKeys();
+        const scriptIds = keys.filter((k) => k.startsWith('script:')).map((k) => k.slice('script:'.length));
+        const got = {
+            ...(cached ? Object.fromEntries(Object.entries(cached).filter(([k]) => k.startsWith('collection:'))) : {}),
+            ...await chrome.storage.local.get([
+                ...(cached ? [] : keys.filter((k) => k.startsWith('collection:'))), SCRIPT_NUMBERS_KEY, COLLECTION_NUMBERS_KEY,
+            ]),
+        };
+        const collections = Object.entries(got)
+            .filter(([k]) => k.startsWith('collection:'))
+            .map(([, v]) => v);
+        const now = Date.now();
+        const scripts = reconcileNumbers(numbersFrom(got[SCRIPT_NUMBERS_KEY]), numberedScriptIds(scriptIds, collections), now);
+        const colls = reconcileNumbers(numbersFrom(got[COLLECTION_NUMBERS_KEY]), numberedCollectionIds(collections), now);
+        const writes = {};
+        if (scripts.changed)
+            writes[SCRIPT_NUMBERS_KEY] = scripts.numbers;
+        if (colls.changed)
+            writes[COLLECTION_NUMBERS_KEY] = colls.numbers;
+        assertWorkerContext('write storage');
+        if (Object.keys(writes).length)
+            await chrome.storage.local.set(writes);
+        return { scripts: scripts.numbers, collections: colls.numbers };
+    });
+    // A failure is logged, and doesn't block the next attempt.
+    assigning = run.catch((err) => {
+        console.info('[SourceMonkey] script and collection numbers could not be updated', err);
+        return null;
+    });
+    return assigning;
+}
+/** The stored numbers, read fresh. */
+export async function readNumbers() {
+    const got = await chrome.storage.local.get([SCRIPT_NUMBERS_KEY, COLLECTION_NUMBERS_KEY]);
+    return { scripts: numbersFrom(got[SCRIPT_NUMBERS_KEY]), collections: numbersFrom(got[COLLECTION_NUMBERS_KEY]) };
+}
+/** The stored script numbers, read fresh. */
+export async function readScriptNumbers() {
+    const got = await chrome.storage.local.get(SCRIPT_NUMBERS_KEY);
+    return numbersFrom(got[SCRIPT_NUMBERS_KEY]);
+}