sourcemonkey 0.0.0-stage → 0.5.0

package/lib/userscript-header.d.ts

@@ -0,0 +1,33 @@
+export interface HeaderTag {
+    tag: string;
+    locale?: string;
+    value: string;
+    line?: number;
+}
+export interface ParsedHeader {
+    tags: HeaderTag[];
+    startLine?: number;
+}
+export declare const NO_METADATA_BLOCK = "No // ==UserScript== metadata block, so this is not a userscript";
+export declare const UNTERMINATED_METADATA_BLOCK = "The // ==UserScript== metadata block is never closed and needs a // ==/UserScript== line";
+export declare const USERSTYLE_NOT_SUPPORTED = "This is a user style (a /* ==UserStyle== block), not a userscript. User styles need a user style manager extension.";
+export type SplitError = typeof NO_METADATA_BLOCK | typeof UNTERMINATED_METADATA_BLOCK | typeof USERSTYLE_NOT_SUPPORTED;
+export interface SplitResult {
+    leadingText: string;
+    headerText: string;
+    bodyText: string;
+    error?: SplitError;
+    headerStartLine?: number;
+}
+export declare function splitHeaderBody(source: string): SplitResult;
+export declare function joinFullSource(leadingText: string, headerText: string, bodyText: string): string;
+export declare function parseHeader(source: string): ParsedHeader | null;
+export declare function getValue(header: ParsedHeader, tag: string): string | undefined;
+export declare function getValues(header: ParsedHeader, tag: string): string[];
+export declare function getLocalized(header: ParsedHeader, tag: string): Record<string, string>;
+export declare function hasTag(header: ParsedHeader, tag: string): boolean;
+export declare const SUPPORTED_RUN_AT: readonly string[];
+export declare function unsupportedRunAt(header: ParsedHeader | null | undefined): string | undefined;
+export declare const CONTEXT_MENU_RUN_AT = "context-menu";
+export declare const RUN_SCRIPT_LABEL = "Run this script";
+export declare function isContextMenuRunAt(header: ParsedHeader | null | undefined): boolean;

package/lib/userscript-header.js

@@ -0,0 +1,248 @@
+// Parser for the Tampermonkey-style metadata block at the top of a
+// userscript:
+//
+//   // ==UserScript==
+//   // @name        Hello
+//   // @match       https://example.com/*
+//   // @grant       none
+//   // ==/UserScript==
+//
+// We return a flat list of `{tag, locale?, value}` entries in source
+// order so callers can decide which tags are single-valued (@name,
+// @version) and which can repeat (@match, @grant, @require, …) without
+// the parser baking that policy in. Tag names are lowercased so lookups
+// are case-insensitive; locales like `@name:de` are kept on the side.
+// Every line-terminator shape the metadata-block scanner recognizes.
+// One definition so "which line is this tag on?" is counted by exactly
+// the rule the block is split by — count and split disagreeing is how
+// every header diagnostic in a DOS or classic-Mac file ends up one line
+// off.
+//
+// Deliberately NOT the same set as `countLines` in composed-source.ts,
+// which adds U+2028/U+2029 because V8 treats them as terminators. Those
+// can't appear in a metadata line anyway (`TAG_LINE`'s `.` doesn't
+// match them), and widening the split here would change what this
+// long-standing parser considers a line.
+const LINE_BREAK = /\r\n|\r|\n/;
+const LINE_BREAK_G = /\r\n|\r|\n/g;
+function countLineBreaks(text) {
+    return text.match(LINE_BREAK_G)?.length ?? 0;
+}
+// A marker line is `//`, optional spaces or tabs, then the marker, with
+// anything before or after it on the line, as VM matches it. GreasyFork
+// serves scripts opening with `/// ==UserScript==` or closing with
+// `// ==/UserScript==////`, and TM and VM both install them. Each match
+// takes the whole line, so text after a closing marker (part of that
+// comment) stays in the header rather than starting the body.
+//
+// `[^\r\n]` and a lookbehind rather than `/m` with `.`, `^` and `$`:
+// those also break at U+2028/U+2029, which `LINE_BREAK` deliberately
+// doesn't treat as line breaks.
+const BLOCK_START = /(?<![^\r\n])[^\r\n]*?\/\/[ \t]*==UserScript==[^\r\n]*/;
+const BLOCK_END = /(?<![^\r\n])[^\r\n]*?\/\/[ \t]*==\/UserScript==[^\r\n]*/;
+// Strip a single leading UTF-8 BOM. Most fetch paths (`response.text()`,
+// `TextDecoder`) drop it for us, but the page-context `file://` XHR path
+// (`directories.ts`) hands back `xhr.responseText` with the BOM intact.
+// The marker regexes would take it as text before the `//` on line 1,
+// leaving it in `headerText` (and GM_info's metadata string) rather than
+// dropped. The BOM only ever appears at file position 0.
+function stripLeadingBom(source) {
+    return source.charCodeAt(0) === 0xfeff ? source.slice(1) : source;
+}
+// The ways the split can fail, as the text a user reads.
+//
+// Named constants rather than inline literals because these strings are
+// both the message and the value something compares against — today the
+// corpus validator, which groups failures by message. A reworded
+// literal would silently stop matching.
+//
+// Phrased to read correctly in all three places they appear: alone in
+// the viewer's message bar, alone in the Log tab, and after the
+// preview's `This file cannot be installed: ` prefix. Capitalized and
+// unpunctuated per docs/diagnostics.md#wording; that still rules out a
+// bare fragment like `No metadata block`, which needs a subject.
+export const NO_METADATA_BLOCK = 'No // ==UserScript== metadata block, so this is not a userscript';
+// The fix is phrased as a need rather than an instruction ("it needs",
+// not "add"): this message carries a location, so it renders as
+// `… — add a … line (in f.user.js, line 1)`, where the parenthetical
+// reads as *where to add it*. Line 1 is where the block opened.
+export const UNTERMINATED_METADATA_BLOCK = 'The // ==UserScript== metadata block is never closed and needs a // ==/UserScript== line';
+// A file with no userscript block but a `/* ==UserStyle==` one is a
+// user style (CSS for a style manager extension, not a userscript).
+// GreasyFork lists them alongside userscripts, so naming what the file
+// is beats calling it "not a userscript".
+export const USERSTYLE_NOT_SUPPORTED = 'This is a user style (a /* ==UserStyle== block), not a userscript. User styles need a user style manager extension.';
+const USERSTYLE_START = /\/\*[ \t]*==UserStyle==/;
+// Split a userscript source into the (rare) text above the metadata
+// block, the raw metadata block itself, and the body text.
+//
+// Failure modes:
+//   - no `==UserScript==` line          → NO_METADATA_BLOCK, or
+//     USERSTYLE_NOT_SUPPORTED when there's a `/* ==UserStyle==` instead
+//   - open marker but no matching close → UNTERMINATED_METADATA_BLOCK
+// In every case we return leadingText = '', headerText = '', and
+// bodyText = the whole source so callers always have something to
+// display.
+export function splitHeaderBody(source) {
+    source = stripLeadingBom(source);
+    const startMatch = BLOCK_START.exec(source);
+    if (!startMatch) {
+        const error = USERSTYLE_START.test(source) ? USERSTYLE_NOT_SUPPORTED : NO_METADATA_BLOCK;
+        return { leadingText: '', headerText: '', bodyText: source, error };
+    }
+    const headerStartLine = countLineBreaks(source.slice(0, startMatch.index)) + 1;
+    const afterStart = source.slice(startMatch.index + startMatch[0].length);
+    const endMatch = BLOCK_END.exec(afterStart);
+    if (!endMatch) {
+        return {
+            leadingText: '',
+            headerText: '',
+            bodyText: source,
+            error: UNTERMINATED_METADATA_BLOCK,
+            headerStartLine,
+        };
+    }
+    const blockEnd = startMatch.index + startMatch[0].length + endMatch.index + endMatch[0].length;
+    // Skip a single trailing newline after the closing marker so bodyText
+    // doesn't start with a stray blank line.
+    let bodyStart = blockEnd;
+    if (source[bodyStart] === '\r')
+        bodyStart++;
+    if (source[bodyStart] === '\n')
+        bodyStart++;
+    return {
+        leadingText: source.slice(0, startMatch.index),
+        headerText: source.slice(startMatch.index, blockEnd),
+        bodyText: source.slice(bodyStart),
+        headerStartLine,
+    };
+}
+// One metadata line: `// @tag[:locale][ value]`. The value group is
+// `.*\S` so trailing whitespace is excluded; the whole value group is
+// optional so flag tags like `@noframes` parse with value = "".
+const TAG_LINE = /^[ \t]*\/\/[ \t]*@([A-Za-z][\w-]*)(?::([\w-]+))?(?:[ \t]+(.*\S))?[ \t]*$/;
+// Reassemble the original on-disk source from the three parts
+// produced by `splitHeaderBody`. The reassembly is line-for-line
+// faithful so that an error reported on injected line N also points
+// at line N of this reconstructed string (which is what the viewer
+// shows in the main tab).
+//
+// The `'\n'` between `headerText` and `bodyText` restores the line
+// break `splitHeaderBody` skipped past the closing marker; with no
+// metadata block, both `leadingText` and `headerText` are empty so
+// the body is returned verbatim.
+export function joinFullSource(leadingText, headerText, bodyText) {
+    if (!headerText)
+        return leadingText + bodyText;
+    return leadingText + headerText + '\n' + bodyText;
+}
+// Parse the metadata block. Returns null if there is no
+// `==UserScript==` / `==/UserScript==` pair.
+export function parseHeader(source) {
+    source = stripLeadingBom(source);
+    const startMatch = BLOCK_START.exec(source);
+    if (!startMatch)
+        return null;
+    const afterStart = source.slice(startMatch.index + startMatch[0].length);
+    const endMatch = BLOCK_END.exec(afterStart);
+    if (!endMatch)
+        return null;
+    const block = afterStart.slice(0, endMatch.index);
+    const startLine = countLineBreaks(source.slice(0, startMatch.index)) + 1;
+    const tags = [];
+    // Split on every line-terminator shape — `\r\n` (DOS), `\n` (Unix),
+    // and bare `\r` (classic Mac). `splitHeaderBody`'s marker regexes
+    // stop at all three too, so we keep parity here.
+    //
+    // `block` begins with the terminator that ended the `==UserScript==`
+    // line, so element 0 is always the empty remainder of that line and
+    // element i is `startLine + i` — no off-by-one correction needed.
+    for (const [i, rawLine] of block.split(LINE_BREAK).entries()) {
+        const m = TAG_LINE.exec(rawLine);
+        if (!m)
+            continue;
+        const [, tag, locale, value] = m;
+        const entry = {
+            tag: tag.toLowerCase(),
+            value: value ?? '',
+            line: startLine + i,
+        };
+        if (locale)
+            entry.locale = locale;
+        tags.push(entry);
+    }
+    return { tags, startLine };
+}
+// First non-localized value for `tag`, or undefined.
+export function getValue(header, tag) {
+    const t = tag.toLowerCase();
+    for (const e of header.tags) {
+        if (e.tag === t && e.locale === undefined)
+            return e.value;
+    }
+    return undefined;
+}
+// All non-localized values for `tag`, in source order.
+export function getValues(header, tag) {
+    const t = tag.toLowerCase();
+    const out = [];
+    for (const e of header.tags) {
+        if (e.tag === t && e.locale === undefined)
+            out.push(e.value);
+    }
+    return out;
+}
+// Map of locale → value for tags like `@name:de`. Excludes the
+// unlocalized form.
+export function getLocalized(header, tag) {
+    const t = tag.toLowerCase();
+    const out = {};
+    for (const e of header.tags) {
+        if (e.tag === t && e.locale !== undefined)
+            out[e.locale] = e.value;
+    }
+    return out;
+}
+// True if the tag appears at all (useful for flag-style tags like
+// `@noframes` or `@unwrap`).
+export function hasTag(header, tag) {
+    const t = tag.toLowerCase();
+    return header.tags.some((e) => e.tag === t);
+}
+// The `@run-at` values that pick a point in the page load. Anything
+// else (a typo) runs at `document-idle`: see `normalizeDeclaredRunAt`
+// in injector.ts. The exception is `context-menu`, which makes the
+// script manual instead (see `CONTEXT_MENU_RUN_AT`).
+export const SUPPORTED_RUN_AT = [
+    'document-start',
+    'document-body',
+    'document-end',
+    'document-idle',
+];
+// The script's declared `@run-at` when it is one we don't honor, so
+// the caller can say it runs at `document-idle` instead. Undefined when
+// the tag is absent, blank, supported, or `context-menu`.
+export function unsupportedRunAt(header) {
+    if (!header)
+        return undefined;
+    const value = (getValue(header, 'run-at') ?? '').trim();
+    if (value === '' || SUPPORTED_RUN_AT.includes(value.toLowerCase()))
+        return undefined;
+    if (value.toLowerCase() === CONTEXT_MENU_RUN_AT)
+        return undefined;
+    return value;
+}
+// Tampermonkey's `@run-at context-menu`: don't run on page load, run
+// from a right-click menu item instead. We call these manual scripts:
+// they match pages as usual, but run only when the person picks "Run
+// this script" in the popup (or sm-dev fires it). See
+// docs/manual-scripts.md.
+export const CONTEXT_MENU_RUN_AT = 'context-menu';
+// The command that runs a manual script now: first in its popup row,
+// and in sm-dev's `menu`.
+export const RUN_SCRIPT_LABEL = 'Run this script';
+export function isContextMenuRunAt(header) {
+    if (!header)
+        return false;
+    return (getValue(header, 'run-at') ?? '').trim().toLowerCase() === CONTEXT_MENU_RUN_AT;
+}

package/lib/version-compare.d.ts

@@ -0,0 +1,6 @@
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+export declare const LOCAL_EDIT_TAG = "local";
+export declare function localEditVersion(version: string): string;
+export declare function isLocalEditVersion(version: string): boolean;
+export type VersionRelation = 'same' | 'newer' | 'older' | 'edited' | 'unknown';
+export declare function versionRelation(loaded: string | undefined, other: string | undefined): VersionRelation;

package/lib/version-compare.js

@@ -0,0 +1,141 @@
+// `@version` ordering.
+//
+// Userscript versions are not semver — managers accept whatever the
+// author writes. Tampermonkey compares them as dot-separated segments
+// with an optional `-prerelease` tail, and that's what we implement:
+// enough structure to order the versions real scripts use, with a
+// deterministic answer for the ones that don't fit.
+//
+// Pure module — no DOM, no chrome.*, no fetching. The only consumer
+// that needs a verdict rather than an ordering is the UI, which uses
+// `versionRelation`.
+// Splits `1.2.3-beta.4` into `{ main: ['1','2','3'], pre: ['beta','4'] }`.
+// Only the FIRST `-` starts the prerelease tail, so `1.0-rc-2` has a
+// two-segment-free prerelease of `rc-2` rather than nesting further.
+//
+// A `+build` tail is dropped first, per semver: build metadata carries
+// no precedence. Without this, `1.0+b2` vs `1.0` would compare its last
+// main segment as `0+b2` vs `0` and report the metadata-only change as
+// a newer version — a false OUTDATED.
+function splitVersion(v) {
+    const plus = v.indexOf('+');
+    const trimmed = (plus < 0 ? v : v.slice(0, plus)).trim();
+    const dash = trimmed.indexOf('-');
+    const mainPart = dash < 0 ? trimmed : trimmed.slice(0, dash);
+    const prePart = dash < 0 ? '' : trimmed.slice(dash + 1);
+    return {
+        main: mainPart.split('.'),
+        pre: prePart ? prePart.split('.') : [],
+    };
+}
+const NUMERIC_RE = /^\d+$/;
+// Compare one segment pair. Numeric-vs-numeric compares as numbers so
+// `10` beats `9`; anything else falls back to code-unit order, which
+// happens to put digits below letters — the same direction semver
+// specifies for a numeric-vs-alphanumeric identifier.
+//
+// A consequence worth knowing: `1.0-beta` sorts *below* `1.0` (the
+// prerelease rule) but `1.0.beta` sorts *above* it (padded `'0'` vs
+// `'b'` here). Both follow from the rules as stated; only the `-` form
+// is a prerelease.
+function compareSegment(a, b) {
+    if (NUMERIC_RE.test(a) && NUMERIC_RE.test(b)) {
+        const x = Number(a);
+        const y = Number(b);
+        return x < y ? -1 : x > y ? 1 : 0;
+    }
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+// Missing trailing segments read as `0`, so `1.2` and `1.2.0` are the
+// same version. Authors bump `1.2` → `1.2.1` all the time and expect
+// exactly that.
+function compareMain(a, b) {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const cmp = compareSegment(a[i] ?? '0', b[i] ?? '0');
+        if (cmp !== 0)
+            return cmp;
+    }
+    return 0;
+}
+// Prerelease tails follow semver's precedence rules: a release outranks
+// any prerelease of the same main version (`1.0` > `1.0-rc1`), and
+// between two prereleases the one that runs out of segments first is
+// lower (`1.0-rc` < `1.0-rc.2`).
+function comparePre(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1;
+    if (b.length === 0)
+        return -1;
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const sa = a[i];
+        const sb = b[i];
+        if (sa === undefined)
+            return -1;
+        if (sb === undefined)
+            return 1;
+        const cmp = compareSegment(sa, sb);
+        if (cmp !== 0)
+            return cmp;
+    }
+    return 0;
+}
+// Total order over version strings. Always returns an ordering — there
+// is no "incomparable" verdict, because every caller ultimately has to
+// pick newer / older / same and a null would just push the arbitrary
+// choice up a layer. An empty string sorts below every non-empty one.
+export function compareVersions(a, b) {
+    const ta = a.trim();
+    const tb = b.trim();
+    if (!ta || !tb) {
+        if (ta === tb)
+            return 0;
+        return ta ? 1 : -1;
+    }
+    const va = splitVersion(ta);
+    const vb = splitVersion(tb);
+    const main = compareMain(va.main, vb.main);
+    if (main !== 0)
+        return main;
+    return comparePre(va.pre, vb.pre);
+}
+// The prerelease tag a local copy's `@version` carries: `13.2` copied
+// for editing becomes `13.2-local`. Lives here, next to the comparison
+// that has to recognise it — see `versionRelation`.
+export const LOCAL_EDIT_TAG = 'local';
+// The `@version` a local copy is given: the original with `-local`
+// appended. Always a plain append — `splitVersion` keys on the FIRST
+// `-`, so `1.0-beta` becomes `1.0-beta-local`, whose single prerelease
+// segment `beta-local` string-compares above `beta` and stays below
+// the `1.0` release. That copy therefore reads as newer than its
+// source, the ordinary "local edit running ahead" case; only a source
+// with no tail needs the `edited` relation below.
+export function localEditVersion(version) {
+    return `${version.trim()}-${LOCAL_EDIT_TAG}`;
+}
+// True when `version` is a local edit per `localEditVersion`: any
+// prerelease segment that is, or ends in, `-local`.
+export function isLocalEditVersion(version) {
+    const { pre } = splitVersion(version.trim());
+    return pre.some((seg) => seg === LOCAL_EDIT_TAG || seg.endsWith(`-${LOCAL_EDIT_TAG}`));
+}
+export function versionRelation(loaded, other) {
+    if (!loaded?.trim() || !other?.trim())
+        return 'unknown';
+    const cmp = compareVersions(other, loaded);
+    if (cmp > 0)
+        return isEditOf(loaded, other) ? 'edited' : 'newer';
+    if (cmp < 0)
+        return 'older';
+    return 'same';
+}
+// `loaded` is a local edit of `other`: same main segments, `other` has
+// no prerelease tail, and ours is a `-local` one.
+function isEditOf(loaded, other) {
+    const vl = splitVersion(loaded.trim());
+    const vo = splitVersion(other.trim());
+    return vo.pre.length === 0 && compareMain(vl.main, vo.main) === 0 && isLocalEditVersion(loaded);
+}

package/lib/version-probe.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedHeader } from './userscript-header.js';
+export type ProbeKind = 'update' | 'download';
+export interface ProbeTarget {
+    url: string;
+    kinds: ProbeKind[];
+}
+export interface VersionProbe extends ProbeTarget {
+    version?: string;
+    error?: string;
+    checkedAt: number;
+}
+export type ProbePolicy = 'force' | 'if-stale';
+export declare const PROBE_MIN_INTERVAL_MS: number;
+export declare function probeTargets(header: ParsedHeader | null, fileUrl: string): ProbeTarget[];
+export declare function probesAreFresh(probes: readonly VersionProbe[] | undefined, targets: readonly ProbeTarget[], now: number): boolean;
+export declare function outdatedProbe(loadedVersion: string | undefined, probes: readonly VersionProbe[] | undefined): VersionProbe | null;
+export declare function probeLabel(kinds: readonly ProbeKind[]): string;

package/lib/version-probe.js

@@ -0,0 +1,120 @@
+// Update probes: "what `@version` does the script's upstream claim?"
+//
+// A probe is deliberately NOT a refresh. A refresh fetches the bytes we
+// actually run, from the URL the user installed from, and can change a
+// script's status. A probe fetches somebody else's copy, reads one
+// header line out of it, and changes nothing but a display annotation.
+// Keeping them apart is the whole design: a `@downloadURL` pointing at
+// an origin the user never approved must never become an update
+// channel, and an unreachable probe host must never disable a working
+// script.
+//
+// What gets probed: only `@updateURL` / `@downloadURL` values that
+// differ from the URL we load the script from. We already auto-update
+// from our own collection — local files via the scan's size+mtime check,
+// http(s) via a conditional GET — so probing it would be a slower way
+// to learn what the refresh that just ran already established.
+//
+// That leaves exactly the interesting case: a copy whose official home
+// is somewhere we don't fetch from. We can't update it automatically,
+// so all we can do is say so. See [docs/updates.md].
+import { getValue } from './userscript-header.js';
+import { versionRelation } from './version-compare.js';
+// How long a recorded probe stays fresh. Probes hit third-party hosts
+// on somebody else's page load, and an upstream release is a
+// once-in-weeks event, so this is deliberately hours rather than the
+// seconds the collection-refresh gate uses.
+export const PROBE_MIN_INTERVAL_MS = 6 * 60 * 60 * 1000;
+// Canonical form for comparing a probe URL against the script's own
+// location. Returns null for anything that isn't an absolute http(s)
+// URL: a relative `@updateURL` has no meaning (updates come from a
+// fixed home, not from wherever this copy happens to sit), and a
+// `file://` one would turn a header line into a host-file read.
+function canonicalProbeUrl(raw) {
+    if (!raw?.trim())
+        return null;
+    try {
+        const u = new URL(raw.trim());
+        return u.protocol === 'http:' || u.protocol === 'https:' ? u.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+// The distinct upstream URLs worth asking about, in `update`-first
+// order. Deduped by canonical URL, so the common GreasyFork shape
+// (`@downloadURL` = the `.user.js` we installed from, `@updateURL` =
+// the sibling `.meta.js`) yields one target, not two.
+export function probeTargets(header, fileUrl) {
+    if (!header)
+        return [];
+    // A `file://` script canonicalizes to null and simply never matches
+    // an http(s) target, which is the right answer.
+    const own = canonicalProbeUrl(fileUrl);
+    const byUrl = new Map();
+    for (const kind of ['update', 'download']) {
+        const url = canonicalProbeUrl(getValue(header, `${kind}URL`));
+        if (!url || url === own)
+            continue;
+        const existing = byUrl.get(url);
+        if (existing)
+            existing.kinds.push(kind);
+        else
+            byUrl.set(url, { url, kinds: [kind] });
+    }
+    return [...byUrl.values()];
+}
+// Whether the stored probes still stand in for a fresh check. Stale in
+// either direction, because both mean the stored set no longer
+// describes what the script declares:
+//
+//   - a target with no row, or a row aged past the interval — the
+//     normal case, and what makes a newly-added `@updateURL` get
+//     probed on the next check rather than in six hours;
+//   - a row whose URL is no longer a target — the script dropped that
+//     header, and leaving the row would keep reporting OUTDATED
+//     against a URL it no longer names.
+export function probesAreFresh(probes, targets, now) {
+    const stored = probes ?? [];
+    if (targets.length === 0)
+        return stored.length === 0;
+    const targetUrls = new Set(targets.map((t) => t.url));
+    if (stored.some((p) => !targetUrls.has(p.url)))
+        return false;
+    const byUrl = new Map(stored.map((p) => [p.url, p]));
+    return targets.every((t) => {
+        const probe = byUrl.get(t.url);
+        return probe !== undefined && now - probe.checkedAt < PROBE_MIN_INTERVAL_MS;
+    });
+}
+// The probe that says our copy is behind, or null when none does.
+// Picks the highest version among those ahead of us, so a script whose
+// update and download URLs disagree is judged against the further-ahead
+// one — being told about the smaller gap would understate it.
+export function outdatedProbe(loadedVersion, probes) {
+    let furthestAhead = null;
+    for (const probe of probes ?? []) {
+        if (versionRelation(loadedVersion, probe.version) !== 'newer')
+            continue;
+        if (!furthestAhead || versionRelation(furthestAhead.version, probe.version) === 'newer') {
+            furthestAhead = probe;
+        }
+    }
+    return furthestAhead;
+}
+// Row label for a probe: "update URL" or "download URL".
+//
+// When ONE url is named by both headers the label says "update URL"
+// rather than spelling out both. `@updateURL` is the header that means
+// "check here for a new version", so it is the accurate name for what
+// we did; `@downloadURL` naming the same file is a detail of the
+// script's headers, not of the check. Spelling out both made the
+// longest label in the panel, for a distinction the reader can't act
+// on — the row's tooltip carries the URL either way.
+//
+// No ambiguity with a plain update probe: the combined form only
+// exists when the two headers resolve to the same URL, and two probes
+// for one URL is exactly what it's collapsing.
+export function probeLabel(kinds) {
+    return kinds.includes('update') ? 'update URL' : 'download URL';
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "sourcemonkey",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "description": "Developer tools for building and testing userscripts, using a real browser and the SourceMonkey extension: the sm-dev command-line tool, Playwright test fixture, and skills for agentic development",
+  "license": "MIT",
+  "homepage": "https://github.com/jshute96/SourceMonkey",
+  "bugs": "https://github.com/jshute96/SourceMonkey/issues",
+  "keywords": [
+    "userscript",
+    "chrome-extension",
+    "playwright",
+    "tampermonkey",
+    "violentmonkey"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jshute96/SourceMonkey.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./lib/harness/index.js",
+    "./harness": "./lib/harness/index.js",
+    "./package.json": "./package.json",
+    "./*": "./lib/*.js"
+  },
+  "files": [
+    "dist",
+    "lib",
+    "skills"
+  ],
+  "bin": {
+    "sm-dev": "./lib/harness/cli.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "playwright-core": "^1.64.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.1",
+    "@types/chrome": "^0.0.287",
+    "@types/node": "^22.20.5",
+    "@types/prismjs": "^1.26.6",
+    "fflate": "^0.8.3",
+    "prismjs": "^1.30.0",
+    "terser": "^5.51.2",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.48.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  }
 }