sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/github-provider.js

@@ -0,0 +1,336 @@
+// GitHub-specific collection handling: URL parsing, default-branch
+// resolution, raw-URL normalization, recursive Contents-API scanner,
+// and the per-script file/display URL builders for the github-dir
+// collection kind. `directories.ts` dispatches to the exports here from
+// its collection-kind branches; nothing in this file is aware of file://
+// or local-filesystem collections.
+//
+// Two ergonomic problems we paper over here:
+//
+// 1. `github.com/<o>/<r>/blob/<ref>/<path>` URLs (what the user copies
+//    from the browser address bar) serve an HTML rendering of the
+//    file, not the raw bytes. `normalizeGithubInput` rewrites those to
+//    their `raw.githubusercontent.com` counterpart at add-collection time
+//    so the rest of the pipeline treats them as ordinary HTTP single-
+//    file / manifest collections. Recognised file shapes are `.user.js`
+//    files and the fixed `script_manifest.json` manifest filename.
+// 2. GitHub directory URLs (`/tree/<ref>/<path>` and, by extension, a
+//    misused `/blob/<ref>/<dir>` form) have no direct "give me all the
+//    `.user.js` files inside" endpoint. `scanGithubDir` uses the
+//    Contents API to walk the tree at scan time, returning the same
+//    `FoundScript` shape the other collection kinds produce.
+//
+// Bare repo URLs (`github.com/<o>/<r>` with no `/blob|tree/...`
+// segment) resolve to `tree/<default-branch>` via one repo-metadata
+// API call at add time; the resolved branch is baked into the stored
+// collection path so refreshes are deterministic afterwards.
+//
+// Branch names containing slashes (e.g. `feature/foo`) aren't
+// supported — the matcher takes the first ref segment and assumes the
+// rest is the path.
+import { MAX_SCAN_DEPTH, MANIFEST_FILENAME } from '../collection-scan.js';
+import { githubAuthHeaders, getGithubAuthToken } from '../github-auth.js';
+import { mapWithConcurrency, SCAN_GITHUB_DIRS_CONCURRENCY } from './concurrency.js';
+const GITHUB_URL_RE = /^https?:\/\/github\.com\/([^\/?#]+)\/([^\/?#]+)\/(blob|tree)\/([^\/?#]+)(?:\/([^?#]*))?(?:\?[^#]*)?(?:#.*)?$/i;
+// Matches a bare `https://github.com/<owner>/<repo>` URL — no
+// `/blob|tree/...` segment, no path. Used to recognise repo-root
+// inputs at add time so we can resolve the default branch and store
+// a canonical `/tree/<branch>` URL.
+const GITHUB_REPO_ROOT_RE = /^https?:\/\/github\.com\/([^\/?#]+)\/([^\/?#]+?)(?:\.git)?\/?(?:\?[^#]*)?(?:#.*)?$/i;
+// Parse a github.com browser URL. Returns null for anything that
+// doesn't match the `(blob|tree)/<ref>/...` shape (including repo-root
+// URLs and any non-github host).
+export function parseGithubUrl(input) {
+    const m = GITHUB_URL_RE.exec(input);
+    if (!m)
+        return null;
+    return {
+        owner: m[1],
+        repo: m[2].replace(/\.git$/, ''),
+        kind: m[3].toLowerCase(),
+        ref: m[4],
+        path: (m[5] ?? '').replace(/\/+$/, ''),
+    };
+}
+// True for a github.com URL pointing at a directory. `/tree/...` is the
+// canonical form, but we also accept `/blob/<ref>/<dir>` (the form a
+// user might end up with by editing a blob URL by hand) as long as the
+// path doesn't look like a recognised file: `.user.js` (single script)
+// or basename `script_manifest.json` (manifest).
+export function isGithubDirCollection(input) {
+    const p = parseGithubUrl(input);
+    if (!p)
+        return false;
+    return !isGithubFilePath(p.path);
+}
+// True when the parsed GitHub path points at one of the file shapes we
+// recognise (a userscript or a manifest under its fixed filename).
+function isGithubFilePath(p) {
+    if (p.endsWith('.user.js'))
+        return true;
+    if (p === MANIFEST_FILENAME)
+        return true;
+    if (p.endsWith('/' + MANIFEST_FILENAME))
+        return true;
+    return false;
+}
+// Build the raw.githubusercontent.com URL for a parsed file URL. Caller
+// must have already verified the URL's path is a recognised file shape
+// (see `isGithubFilePath` / `normalizeGithubInput`'s inline check).
+function githubFileUrlToRaw(p) {
+    return `https://raw.githubusercontent.com/${p.owner}/${p.repo}/${p.ref}/${p.path}`;
+}
+// Resolve a per-script entry under a github-dir collection to its raw
+// URL (what `fetchHttpText` reads). Exported for `directories.ts`'s
+// `scriptFileUrl` dispatch.
+export function githubDirScriptFileUrl(collectionPath, relativePath) {
+    const p = parseGithubUrl(collectionPath);
+    if (!p)
+        throw new Error(`Not a GitHub URL: ${collectionPath}`);
+    const full = p.path ? `${p.path}/${relativePath}` : relativePath;
+    return `https://raw.githubusercontent.com/${p.owner}/${p.repo}/${p.ref}/${full}`;
+}
+// Resolve a per-script entry under a github-dir collection to its
+// human-displayable github.com URL (what the viewer's Location row
+// shows). Exported for `directories.ts`'s `scriptAbsolutePath`
+// dispatch.
+export function githubDirScriptDisplayUrl(collectionPath, relativePath) {
+    const p = parseGithubUrl(collectionPath);
+    if (!p)
+        throw new Error(`Not a GitHub URL: ${collectionPath}`);
+    const full = p.path ? `${p.path}/${relativePath}` : relativePath;
+    return `https://github.com/${p.owner}/${p.repo}/blob/${p.ref}/${full}`;
+}
+// Parse a bare `github.com/<owner>/<repo>` URL — repo root, no ref.
+// Returns null for anything that already parses via `parseGithubUrl`
+// (i.e. URLs that bring their own `/blob|tree/...` segment).
+function parseGithubRepoRoot(input) {
+    if (parseGithubUrl(input))
+        return null;
+    const m = GITHUB_REPO_ROOT_RE.exec(input);
+    if (!m)
+        return null;
+    return { owner: m[1], repo: m[2].replace(/\.git$/, '') };
+}
+// True for any GitHub input a collection can be built from without
+// naming a file: a `/tree/...` (or file-less `/blob/...`) directory URL,
+// or a bare repo root. The repo root needs one API call to resolve its
+// default branch before it can be stored (`normalizeGithubInput`), but
+// recognising it takes none — which is what lets the collection
+// dialog classify a location on every keystroke.
+export function isGithubDirInput(input) {
+    return isGithubDirCollection(input) || parseGithubRepoRoot(input) !== null;
+}
+// Fetch a repo's default branch via the GitHub repository metadata
+// endpoint. One API call (counts against the same 60/hr/IP budget as
+// the Contents API for unauthenticated callers). Called only at
+// add-collection time for bare-repo URLs; resolved branch gets baked
+// into the canonical collection path so refresh is deterministic
+// afterwards.
+async function fetchGithubDefaultBranch(owner, repo) {
+    const apiUrl = `https://api.github.com/repos/${owner}/${repo}`;
+    let response;
+    try {
+        response = await fetch(apiUrl, {
+            cache: 'no-store',
+            headers: {
+                'Accept': 'application/vnd.github+json',
+                ...githubAuthHeaders(apiUrl),
+            },
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not read ${apiUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Every failure below shares the `Could not read <url>: <reason>`
+    // shape the rest of the fetch pipeline uses (`directories.ts`), so a
+    // GitHub failure and a plain HTTP one read the same way. "Repo
+    // metadata" was our name for this request, not something the reader
+    // asked for.
+    if (!response.ok) {
+        throw new Error(githubStatusError(apiUrl, response.status));
+    }
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (err) {
+        // The parser's own complaint is kept: `Unexpected token <` is how a
+        // captive portal or proxy error page announces itself, and dropping
+        // it would leave "not valid JSON" with nothing to act on.
+        throw new Error(`Could not read ${apiUrl}: the response is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const branch = json?.default_branch;
+    if (typeof branch !== 'string' || !branch) {
+        throw new Error(`Could not read ${apiUrl}: GitHub did not report the repo's default branch`);
+    }
+    return branch;
+}
+// At add-collection time, transparently rewrite a github.com input into
+// the canonical form the rest of the pipeline expects:
+//   - File URL — `/blob/<ref>/<path>.user.js` or a path whose basename
+//     is `script_manifest.json` — gets rewritten to its raw URL.
+//   - Bare repo URL (`github.com/<o>/<r>` with no ref) → `/tree/<default-branch>`,
+//     resolved via the repo metadata endpoint (one API call).
+//   - Directory URLs (`/tree/<ref>/...`) pass through unchanged.
+//   - Non-github inputs pass through unchanged (no network call).
+// Async because the repo-root case needs to consult the GitHub API to
+// resolve the default branch. Idempotent on canonical outputs so the
+// caller-and-callee normalize pattern (see `addCollection`) doesn't
+// double-up on API calls.
+export async function normalizeGithubInput(input) {
+    const p = parseGithubUrl(input);
+    if (p) {
+        if (p.path && isGithubFilePath(p.path)) {
+            return githubFileUrlToRaw(p);
+        }
+        return input;
+    }
+    const root = parseGithubRepoRoot(input);
+    if (root) {
+        const branch = await fetchGithubDefaultBranch(root.owner, root.repo);
+        return `https://github.com/${root.owner}/${root.repo}/tree/${branch}`;
+    }
+    return input;
+}
+// Build the GitHub Contents API URL for a directory inside a repo.
+// Empty `path` lists the repo root at the given ref.
+function githubContentsApiUrl(p, subPath) {
+    const base = `https://api.github.com/repos/${p.owner}/${p.repo}/contents`;
+    const full = subPath ? `${p.path ? p.path + '/' : ''}${subPath}` : p.path;
+    const encPath = full
+        ? '/' + full.split('/').map(encodeURIComponent).join('/')
+        : '';
+    return `${base}${encPath}?ref=${encodeURIComponent(p.ref)}`;
+}
+// Tack a private-repo / rate-limit hint onto the GitHub API error so
+// the failure is self-diagnosing. GitHub returns the same 404 for
+// "repo doesn't exist" and "repo exists but you can't see it without
+// auth", so the hint covers both. 403 unauthenticated almost always
+// means the per-IP rate limit ran out; an authenticated 403 means the
+// token doesn't have access to the repo or is missing a scope.
+// The hint text branches on whether a token is configured so the
+// user gets a next-step pointer rather than stale advice.
+//
+// A sentence of its own on a new line, after the status line's period
+// (`githubStatusError`). The collections page, the dialog, the Log tab
+// and sm-dev show the line break; a surface that collapses whitespace
+// shows a space.
+function githubAuthHint(status) {
+    const hasToken = !!getGithubAuthToken();
+    if (status === 404) {
+        if (hasToken) {
+            return 'Repo not found, or your token can\'t see this repo. Check the token\'s repo access on github.com.';
+        }
+        return 'Repo not found, or repo is private. Set a GitHub token on the Options page to fetch private repos.';
+    }
+    if (status === 403 || status === 429) {
+        if (hasToken) {
+            return 'Rate limit hit, or your token lacks the required scope. Authenticated requests get 5000/hour against api.github.com.';
+        }
+        return 'Likely the unauthenticated 60/hr API rate limit. Set a GitHub token on the Options page to raise it to 5000/hr.';
+    }
+    if (status === 401) {
+        return 'Token rejected. Re-check the value on the Options page.';
+    }
+    return '';
+}
+// A failed GitHub API read: the status, then the hint for it, if any.
+function githubStatusError(apiUrl, status) {
+    const hint = githubAuthHint(status);
+    return hint
+        ? `Could not read ${apiUrl}: HTTP ${status}.\n${hint}`
+        : `Could not read ${apiUrl}: HTTP ${status}`;
+}
+// Fetch a single Contents API response. Returns the parsed JSON array.
+// Throws on non-2xx, non-array, or network failure — caller
+// (refreshCollection) turns the error into a per-collection
+// `scanError`.
+async function fetchGithubContents(apiUrl) {
+    let response;
+    try {
+        response = await fetch(apiUrl, {
+            cache: 'no-store',
+            headers: {
+                'Accept': 'application/vnd.github+json',
+                ...githubAuthHeaders(apiUrl),
+            },
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not read ${apiUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!response.ok) {
+        // 403 with rate-limit headers is the common failure mode for
+        // unauthenticated repeat callers; 404 means either the repo / path
+        // doesn't exist OR it's a private repo (GitHub returns the same
+        // status for both unauthenticated). Surface the status plus the
+        // private-repo hint so the user has something concrete to act on.
+        throw new Error(githubStatusError(apiUrl, response.status));
+    }
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (err) {
+        // The parser's own complaint is kept: `Unexpected token <` is how a
+        // captive portal or proxy error page announces itself, and dropping
+        // it would leave "not valid JSON" with nothing to act on.
+        throw new Error(`Could not read ${apiUrl}: the response is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (!Array.isArray(json)) {
+        // GitHub answers a file path with an object rather than a listing,
+        // so this is the "you pointed at a file" case, not a broken API.
+        throw new Error(`Could not read ${apiUrl}: that path is not a folder in the repo`);
+    }
+    return json;
+}
+// Recursive scan of a GitHub directory collection via the Contents API.
+// Mirrors the shape of `scanForUserScripts` / `scanManifest`: returns a
+// flat `FoundScript[]` keyed by paths relative to the collection's root
+// dir, capped at MAX_SCAN_DEPTH levels deep.
+//
+// Cost: one Contents API call per directory walked. Unauthenticated
+// callers share a 60/hour budget per IP, so deep trees can drain
+// quickly; authenticated-collections support is in TODO.md.
+export async function scanGithubDir(input, depth = 0, prefix = '') {
+    const p = parseGithubUrl(input);
+    if (!p)
+        throw new Error(`Not a GitHub URL: ${input}`);
+    // `prefix` carries a trailing slash on every recursive call
+    // (`prefix + entry.name + '/'`); strip it so the Contents-API path
+    // ends in the directory name without an extra `/`.
+    const subPath = prefix.replace(/\/+$/, '');
+    const apiUrl = githubContentsApiUrl(p, subPath);
+    const entries = await fetchGithubContents(apiUrl);
+    const results = [];
+    const subdirs = [];
+    for (const entry of entries) {
+        if (entry.type === 'file' && entry.name.endsWith('.user.js')) {
+            const found = {
+                name: entry.name,
+                relativePath: prefix + entry.name,
+            };
+            if (typeof entry.size === 'number')
+                found.size = entry.size;
+            results.push(found);
+        }
+        else if (entry.type === 'dir' && depth < MAX_SCAN_DEPTH) {
+            subdirs.push(entry);
+        }
+    }
+    // Listed together rather than one after another — same reasoning as
+    // the local scan, but the round trips here are API calls rather than
+    // disk reads, so the saving is far bigger per directory. A repo whose
+    // root holds three subdirectories cost four serialized calls before.
+    //
+    // Bounded tighter than the local walk: these all hit api.github.com,
+    // which throttles concurrent bursts on top of the hourly quota. The
+    // request COUNT is unchanged either way, which is what the quota
+    // actually meters.
+    const nested = await mapWithConcurrency(subdirs, SCAN_GITHUB_DIRS_CONCURRENCY, (entry) => scanGithubDir(input, depth + 1, prefix + entry.name + '/'));
+    for (const sub of nested)
+        results.push(...sub);
+    results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return results;
+}

package/dist/extension/glyph.js

@@ -0,0 +1,84 @@
+// Rendering a glyph from the shared sprite (src/glyph-sprite.svg) into
+// the page.
+//
+// Every icon in the extension is one `<symbol>` in that sprite, inlined
+// once per page by the build. All this module does is build the tiny
+// `<svg><use href="#id">` that points at one — but it is shared because
+// the alternative is each caller inventing its own class name and
+// sizing, which is how two buttons wearing "the same" icon end up
+// different sizes.
+//
+// Colour and size come from CSS on the button (`.btn-glyph` in
+// styles.css), not from attributes here, so a glyph inherits
+// `currentColor` and tracks the surrounding font.
+const NS = 'http://www.w3.org/2000/svg';
+// The class the shared sizing/spin rules key off. Callers with their
+// own rules (the site-icon globe, the removal cans) pass their own.
+export const GLYPH_CLASS = 'btn-glyph';
+// Build an `<svg>` referencing one sprite symbol. `aria-hidden` on
+// every one of them: a glyph never carries the accessible name, the
+// button's own `aria-label` does.
+export function renderGlyph(doc, symbolId, className = GLYPH_CLASS) {
+    const svg = doc.createElementNS(NS, 'svg');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('class', className);
+    svg.setAttribute('aria-hidden', 'true');
+    const use = doc.createElementNS(NS, 'use');
+    use.setAttribute('href', symbolId.startsWith('#') ? symbolId : `#${symbolId}`);
+    svg.appendChild(use);
+    return svg;
+}
+// Replace a button's contents with a glyph (and optional label), and
+// give it `label` as its tooltip.
+//
+// `label` also becomes the accessible name, but ONLY for an icon-only
+// button. A button that shows words has to be announced by the words a
+// sighted user can read — an `aria-label` overrides them, so "Refresh
+// All" on screen would be announced (and matched by voice control) as
+// something else entirely.
+export function setGlyphButton(btn, symbolId, label, opts = {}) {
+    const doc = btn.ownerDocument;
+    btn.textContent = '';
+    btn.classList.add('icon-btn');
+    btn.appendChild(renderGlyph(doc, symbolId));
+    // Truthy, not `!== undefined`: an empty label would render an empty
+    // `.btn-label`, which `setGlyphButtonLabel` then reads as "this
+    // button shows its own text" and drops the `aria-label` for — a
+    // button announced as nothing at all.
+    if (opts.text) {
+        const span = doc.createElement('span');
+        span.className = 'btn-label';
+        span.textContent = opts.text;
+        btn.appendChild(span);
+    }
+    setGlyphButtonLabel(btn, label);
+}
+// Retitle a glyph button without rebuilding it. The busy state uses
+// this: the glyph itself has to survive, because it is what spins.
+//
+// The `aria-label` goes on only where there is no visible label to
+// override — see `setGlyphButton`. A labelled button's accessible name
+// is its own text, and its `title` is the longer explanation.
+export function setGlyphButtonLabel(btn, label) {
+    btn.title = label;
+    if (btn.querySelector('.btn-label'))
+        btn.removeAttribute('aria-label');
+    else
+        btn.setAttribute('aria-label', label);
+}
+// The in-flight state for a button whose action takes a while.
+//
+// The glyph spins in place rather than the label changing to
+// "Refreshing…". That used to be the only signal, and it can't survive
+// an icon-only button — but it was also the thing that made the button
+// change width mid-click, nudging its neighbours. Spinning the glyph
+// says the same thing and moves nothing.
+//
+// `aria-live` is deliberately not used: the tooltip and the disabled
+// state carry it, and a row of collections each announcing their own
+// refresh would be worse than silence.
+export function setGlyphButtonBusy(btn, busy, labels) {
+    btn.disabled = busy;
+    btn.querySelector(`.${GLYPH_CLASS}`)?.classList.toggle('spinning', busy);
+    setGlyphButtonLabel(btn, busy ? labels.busy : labels.idle);
+}