sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/local-delete.js

@@ -0,0 +1,276 @@
+// Deleting a local copy — the script file itself, and optionally the
+// dependency files that were copied beside it — off the disk.
+//
+// The counterpart of `local-copy.ts`, and it can only undo what that
+// module did: `chrome.downloads.removeFile` deletes a file the browser
+// itself downloaded, found by its absolute path in Chrome's download
+// history. Nothing else an extension can call deletes a file, so a copy
+// whose history entry is gone can only be reported, not removed.
+//
+// See docs/local-delete.md.
+import { isFileUrl, locationFsPath } from '../file-locations.js';
+import { describeError, } from './script-store.js';
+import { dlog } from '../debug-log.js';
+import { downloadsCopiesDir, readDownloadsCopiesSetting, } from './local-copy.js';
+// The copies setting, or null when it can't be read — a surface that
+// asks "is this row a local copy?" while painting must not be taken
+// down by a storage failure, and null is the safe answer (no row
+// offers a file deletion). One helper so the pages that ask can't
+// drift on what a failure means.
+export async function readCopiesSetting() {
+    try {
+        return await readDownloadsCopiesSetting();
+    }
+    catch (err) {
+        dlog(`[SourceMonkey] could not read the local-copies setting: ${describeError(err)}`);
+        return null;
+    }
+}
+// ---------- Which scripts can be deleted from disk ----------
+// The absolute path of `script`'s file when it is a copy we wrote, and
+// null when it isn't. `collection` is the row's own collection.
+//
+// Both halves are required, and the collection is the important one:
+// the row has to sit in the directory collection AT the copies
+// directory. That is what makes the rest of this module's reasoning
+// true — a file in that directory is shared only within that
+// collection, so its scripts are the whole set that could be reading
+// it, and `copyDeletePlan` can answer "does anything else need this?"
+// from one collection's rows.
+//
+// A row somewhere else whose file happens to be in that directory — an
+// individual script the user added by hand at that path — is refused.
+// Deleting through it would compute the shared/own split against the
+// wrong set of scripts and could take a library another copy is
+// loading. Individual-file rows, overlapping directories and manifests
+// all break the assumption in the same way; none of them is worth the
+// mess (see TODO.md).
+//
+export function deletableCopyPath(script, collection, setting) {
+    if (!setting || !collection)
+        return null;
+    const dir = downloadsCopiesDir(setting.downloadsDir);
+    if (!isCopiesDir(collection.path, dir))
+        return null;
+    const path = locationFsPath(script.fileUrl);
+    return path.startsWith(`${dir}/`) ? path : null;
+}
+// Is this collection the one at the copies directory? Compared as
+// paths, so the collection is recognized however it was created — the
+// one our first copy made, or one the user had already added there and
+// we adopted (see local-copy.md).
+function isCopiesDir(collectionPath, copiesDir) {
+    return locationFsPath(collectionPath).replace(/\/+$/, '') === copiesDir;
+}
+// What deleting `script` would remove, given every script in its
+// collection (`siblings`, which may include `script` itself).
+//
+// Only siblings are consulted because only they can be reading these
+// files: a local stand-in is searched for under the script's own folder
+// and its collection root (see local-file-overrides.md), so a file
+// under the copies directory is invisible to a script outside it.
+export function copyDeletePlan(script, siblings, copiesDir) {
+    // Which files another script in the collection is loading. Only
+    // whether, not which scripts: the dialog doesn't name them — a
+    // userscript name is long and there can be several.
+    const others = new Set();
+    for (const other of siblings) {
+        if (other.id === script.id)
+            continue;
+        for (const path of localDependencyPaths(other, copiesDir).keys())
+            others.add(path);
+    }
+    const own = [];
+    const shared = [];
+    for (const [path, url] of localDependencyPaths(script, copiesDir)) {
+        const dep = {
+            path,
+            relativePath: path.slice(copiesDir.length + 1),
+            url,
+        };
+        (others.has(path) ? shared : own).push(dep);
+    }
+    const path = locationFsPath(script.fileUrl);
+    return {
+        path,
+        relativePath: path.startsWith(`${copiesDir}/`) ? path.slice(copiesDir.length + 1) : path,
+        own,
+        shared,
+    };
+}
+// The files under `copiesDir` a script is currently loading its
+// `@require` / `@resource` entries from, as path → declared URL.
+//
+// What the load pipeline actually read is the authority, so this lists
+// files in use rather than paths a copy might once have written: the
+// `localUrl` of a stand-in for a web URL, or the `file://` URL itself
+// of a relative ref. Deduped by path — one file can serve two
+// declarations.
+function localDependencyPaths(script, copiesDir) {
+    const out = new Map();
+    for (const file of [...(script.requires ?? []), ...(script.resources ?? [])]) {
+        const readFrom = file.localUrl ?? (isFileUrl(file.url) ? file.url : null);
+        if (!readFrom)
+            continue;
+        const path = locationFsPath(readFrom);
+        if (!path.startsWith(`${copiesDir}/`) || out.has(path))
+            continue;
+        out.set(path, file.url);
+    }
+    return out;
+}
+// ---------- Which files the browser can still be asked about ----------
+// Every completed download whose file is this path AND that Chrome
+// still believes is on disk. `filename` is an exact match on the
+// absolute path, and the record outlives the session — it is cleared
+// with the user's browsing data, not on restart.
+//
+// `exists` is the important half. Chrome refuses `removeFile` with
+// *Download file already deleted* for a record it has marked gone, and
+// that mark is sticky: it is set by Chrome's own existence checks, so a
+// copy edited by a tool that saves via write-to-temp-and-rename can
+// carry it while the file is sitting right there. Filtering here means
+// the dialog's lists and the deletion agree — a file Chrome won't act
+// on is shown as one we can't delete, before anything is pressed,
+// rather than failing half way through.
+function completedDownloads(path) {
+    return chrome.downloads.search({ filename: path, state: 'complete', exists: true });
+}
+// The subset of `paths` Chrome still holds a download record for — the
+// only ones `removeFile` can act on. Asked up front so the dialog can
+// say which files are going and which are being left, rather than
+// finding out one failure at a time.
+//
+// A search that throws counts as "no record": the answer is only used
+// to decide what to attempt, and attempting a file we can't ask about
+// would fail anyway.
+export async function trackedFiles(paths) {
+    const tracked = new Set();
+    await Promise.all(paths.map(async (path) => {
+        try {
+            if ((await completedDownloads(path)).length > 0)
+                tracked.add(path);
+        }
+        catch (err) {
+            dlog(`[SourceMonkey] could not look up the download record for ${path}: ${describeError(err)}`);
+        }
+    }));
+    return tracked;
+}
+// ---------- Deleting ----------
+// Chrome holds no usable download record for the file, so `removeFile`
+// has nothing to act on — the user cleared their downloads, or Chrome
+// has marked the file gone (see `completedDownloads`). Two sentences,
+// both punctuated: this lands in the dialog's error slot and in the
+// viewer's message line, never spliced after a prefix
+// (docs/diagnostics.md#wording).
+//
+// `subject` names what could not be deleted. The script's own file is
+// `SCRIPT_FILE`, with no path in it: the dialog is already showing the
+// file and its full path two rows up, and a relative path with a
+// subdirectory in it makes the sentence hard to read. A dependency
+// file, reported away from any list of its own, carries its path.
+//
+// `alsoOthers` when the same block would have taken other files with
+// it — the copy's own dependencies. They are all still on disk, so the
+// second line names them all rather than just the one it reports on.
+//
+// The second line says what to do next, not just that we can't. With
+// `watched`, the dialog is showing this for the script file with its
+// Delete disabled, and the row has no other trash can (a directory
+// collection's rows are removed by refreshing, which scans the file
+// straight back in) — so without it the user is looking at a dead
+// end. The dialog watches for the file going and then offers to
+// remove the entry (`watchDisk` in the dialog), which is what the
+// line promises. Without `watched` — a dependency reported after the
+// script has already gone, or a dialog that can't watch because file
+// access is off — the line promises nothing.
+export const SCRIPT_FILE = 'Script file';
+export function noDownloadRecord(subject, alsoOthers = false, watched = false) {
+    const files = alsoOthers ? 'files' : 'file';
+    return `${subject} is no longer in Chrome download history, so SourceMonkey cannot delete it.\n`
+        + (watched
+            ? `Delete the ${files} by hand, and Delete will then remove this script.`
+            : `You can delete the ${files} by hand.`);
+}
+// Ends with a period, unlike most messages: it is joined with the
+// other per-file reports into one line (the viewer's not-found detail,
+// the collections page's error line), where an unpunctuated sentence
+// runs into the next one. Nothing splices it after a prefix.
+function deleteFailed(name, detail) {
+    return `Deleting ${name} failed: ${detail}.`;
+}
+// Delete one file the browser downloaded, by its absolute path.
+// Resolves with null on success, or the message to show.
+//
+// `removeFile` deletes the bytes; `erase` then drops the history row,
+// which would otherwise sit in the user's downloads list pointing at a
+// file that is gone. Erasing is best effort — the file is already gone
+// by then, which is what was asked for.
+//
+// **Nothing is erased unless the file went.** The record is the only
+// handle there is on that file: erasing one we failed to delete with
+// would leave the file on disk and take away the one way of ever
+// removing it.
+async function deleteDownloadedFile(path, name, kind = 'File', alsoOthers = false) {
+    let items;
+    try {
+        items = await completedDownloads(path);
+    }
+    catch (err) {
+        return deleteFailed(name, describeError(err));
+    }
+    if (items.length === 0) {
+        return noDownloadRecord(kind === 'Script' ? SCRIPT_FILE : `File ${name}`, alsoOthers);
+    }
+    // Newest first: one path can have been written several times over
+    // (every Replace adds a record), and the latest is the one whose
+    // file is on disk now. Older records for the same path are erased
+    // too, so the downloads list doesn't keep rows for a file that has
+    // gone.
+    const ordered = [...items].sort((a, b) => (b.startTime ?? '').localeCompare(a.startTime ?? ''));
+    let lastError = '';
+    for (const item of ordered) {
+        try {
+            await chrome.downloads.removeFile(item.id);
+        }
+        catch (err) {
+            // Chrome refuses a record it believes is already gone. Another
+            // record for the same path may still hold the live one, so this
+            // is only fatal once every record has been tried — and the
+            // record we couldn't delete with is left alone.
+            lastError = describeError(err);
+            continue;
+        }
+        // The file is gone, so every record for that path now points at
+        // nothing. Erased only from here.
+        for (const stale of ordered) {
+            try {
+                await chrome.downloads.erase({ id: stale.id });
+            }
+            catch (err) {
+                dlog(`[SourceMonkey] could not erase the download record for ${path}: ${describeError(err)}`);
+            }
+        }
+        return null;
+    }
+    return deleteFailed(name, lastError || 'The file could not be removed');
+}
+export async function deleteCopyFiles(request) {
+    if (request.script) {
+        const scriptError = await deleteDownloadedFile(request.script.path, request.script.relativePath, 'Script', 
+        // The dependencies were going with it and are staying too, so the
+        // message says so — the same answer the dialog gives when it knows
+        // up front that the script's record has gone.
+        request.dependencies.length > 0);
+        if (scriptError)
+            return { scriptError, dependencyErrors: [] };
+    }
+    const dependencyErrors = [];
+    for (const dep of request.dependencies) {
+        const err = await deleteDownloadedFile(dep.path, dep.relativePath);
+        if (err)
+            dependencyErrors.push(err);
+    }
+    return { scriptError: null, dependencyErrors };
+}

package/dist/extension/location-kinds.js

@@ -0,0 +1,108 @@
+// Pure naming helpers for script and collection locations, split from
+// directories.ts so pages that only label locations (the toolbar popup,
+// via collection-display.ts) don't load the scanning and fetch code.
+// directories.ts re-exports all of it.
+import { isHttpUrl } from '../file-locations.js';
+// Classify a script location by scheme: which built-in default
+// container it would install into, and which scheme chip its row wears
+// inside a container. github URLs here mean both the human-facing
+// `github.com/...` form and the already-normalized
+// `raw.githubusercontent.com/...` form, since `normalizeCollectionInput`
+// may have rewritten the input before this runs.
+export function containerKindForSingleFileInput(input) {
+    if (/^https?:\/\/(www\.)?github\.com\//i.test(input))
+        return 'github';
+    if (/^https?:\/\/raw\.githubusercontent\.com\//i.test(input))
+        return 'github';
+    if (isHttpUrl(input))
+        return 'http';
+    return 'file';
+}
+// ---------- Scratch scripts ----------
+//
+// A script whose only copy is its text in extension storage, with no
+// file or URL behind it. Only sm-dev, the development tool, writes
+// them, over the worker's test surface (docs/sm-dev-design.md).
+//
+// - Each sm-dev run has its own collection of them, its test
+//   collection, at `container:sm-dev:<run>`, where `<run>` is the run's
+//   unique id.
+// - Each "location" is a `scratch:///<run>/<path>.user.js` URL that
+//   names the storage row holding the text, so the ordinary refresh
+//   pipeline reads it back like any other body and a rewrite of the
+//   same name is picked up as a content change.
+// - The run in the URL is what lets the script run: only in tabs that
+//   run's claim holds (sm-dev-link.ts).
+const SM_DEV_CONTAINER_PREFIX = 'container:sm-dev:';
+// Three slashes: with an empty host the run and name are the URL's
+// path, so the basename every label is cut from is the script's own
+// name rather than the whole URL.
+const SCRATCH_SCHEME = 'scratch:///';
+export const SCRATCH_TEXT_KEY_PREFIX = 'scratch:';
+export const SCRATCH_FILES_KEY_PREFIX = 'scratchFiles:';
+export const SCRATCH_SOURCE_KEY_PREFIX = 'scratchSource:';
+// Kept to a URL path segment's safe characters.
+function safeSegment(text) {
+    return text.replace(/[^A-Za-z0-9._-]+/g, '-');
+}
+export function isScratchUrl(input) {
+    return input.startsWith(SCRATCH_SCHEME);
+}
+// The location for run `run`'s scratch script called `name`: a name,
+// or the path sm-dev was given, relative or absolute, kept whole so
+// two files of the same name stay apart. Ends in `.user.js` so every
+// "is this a script" check reads it as one, and so its basename labels
+// it in the viewer and the logs.
+//
+// Its segments are percent-encoded, as a file:// URL's would be, so the
+// name reads back as written wherever it is shown decoded (the viewer,
+// stack lines): `My%20Script.user.js` stays that, not `My-20Script`.
+export function scratchUrl(run, name) {
+    // A lone surrogate has no encoding (encodeURIComponent throws on it),
+    // so it becomes U+FFFD, as a decoder would show it.
+    const whole = name.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '\uFFFD');
+    const segments = whole.split('/').map((segment) => encodeURIComponent(segment));
+    const base = (segments.pop() ?? '').replace(/\.user\.js$/i, '') || 'script';
+    return `${SCRATCH_SCHEME}${safeSegment(run)}/${[...segments, `${base}.user.js`].join('/')}`;
+}
+// The run a scratch script belongs to. Null for a script that isn't one.
+export function scratchRunOf(url) {
+    if (!isScratchUrl(url))
+        return null;
+    const rest = url.slice(SCRATCH_SCHEME.length);
+    const slash = rest.indexOf('/');
+    return slash < 0 ? '' : rest.slice(0, slash);
+}
+export function scratchTextKey(url) {
+    return SCRATCH_TEXT_KEY_PREFIX + url;
+}
+// The storage row holding the `@require` / `@resource` bodies sm-dev
+// pushed with a scratch script: the ones it read from disk, which the
+// extension couldn't (see `PushedFile` in external-files.ts).
+export function scratchFilesKey(url) {
+    return SCRATCH_FILES_KEY_PREFIX + url;
+}
+// The storage row naming the file on the developer's disk a scratch
+// script came from (`ScratchSource`), for sm-dev's `script list`.
+export function scratchSourceKey(url) {
+    return SCRATCH_SOURCE_KEY_PREFIX + url;
+}
+// The path of run `run`'s test collection.
+export function smDevContainerPath(run) {
+    return SM_DEV_CONTAINER_PREFIX + safeSegment(run);
+}
+// An sm-dev test collection, which only its run changes: no script is
+// moved into or out of one, or installed into one, by hand.
+export function isSmDevCollection(path) {
+    return smDevRunOfContainer(path) !== null;
+}
+// The run a test collection belongs to, or null for any other
+// collection.
+export function smDevRunOfContainer(path) {
+    return path.startsWith(SM_DEV_CONTAINER_PREFIX) ? path.slice(SM_DEV_CONTAINER_PREFIX.length) : null;
+}
+// The scheme chip's kind for a container script: where it came from.
+// A scratch script has no location; its only copy is in storage.
+export function scriptSchemeKind(location) {
+    return isScratchUrl(location) ? 'scratch' : containerKindForSingleFileInput(location);
+}

package/dist/extension/log-format.js

@@ -0,0 +1,158 @@
+// Formatting for the per-script event log.
+//
+// Two consumers, one set of strings:
+//   - the viewer's Log pane table (Time / Status / Source / Message)
+//   - the CSV the pane's Save and Copy buttons hand out
+//
+// Keeping both here is what makes an exported row read the same as the
+// row on screen: the timestamp spelling and the `tab 17 ·
+// script-wrapper` source label are written once.
+//
+// The Message column is the exception, and deliberately so. A message
+// carrying a stack trace only becomes readable after its refs are
+// mapped back through the injected entry's source map — which needs
+// the viewer's tabs and the script's current layout, neither of which
+// belongs in a pure module. So `formatLogCsv` takes the renderer as an
+// argument: the viewer passes the one behind its own table, and the
+// default here is the honest fallback for a caller that has no source
+// map to consult.
+//
+// Pure (no DOM, no chrome.*) so unit tests can drive it directly.
+import { describeDiagnostic } from '../diagnostic-location.js';
+import { formatScriptStatusLabel, logIdSuffix } from '../script-display.js';
+// Local wall-clock time, sortable spelling: `2026-08-05 14:03:22.017`.
+// Not ISO/UTC — the reader is looking at their own machine's log and
+// correlating it with what they just saw happen in a tab.
+export function formatLogTimestamp(ms) {
+    const d = new Date(ms);
+    const yyyy = String(d.getFullYear());
+    const mo = String(d.getMonth() + 1).padStart(2, '0');
+    const dd = String(d.getDate()).padStart(2, '0');
+    const hh = String(d.getHours()).padStart(2, '0');
+    const mm = String(d.getMinutes()).padStart(2, '0');
+    const ss = String(d.getSeconds()).padStart(2, '0');
+    const mmm = String(d.getMilliseconds()).padStart(3, '0');
+    return `${yyyy}-${mo}-${dd} ${hh}:${mm}:${ss}.${mmm}`;
+}
+// The Source cell: `tab 17 · script-wrapper` for anything that came
+// from injected code in a specific tab, the bare label otherwise.
+export function formatLogSource(entry) {
+    return entry.tabId !== undefined ? `tab ${entry.tabId} · ${entry.source}` : entry.source;
+}
+// The Status cell: the state the entry moved the script into, in the
+// Status badge's own words (`REFRESH FAILED`, `INVALID`, `OK`), or the
+// bare level (`info` / `warning` / `error`) for an entry about
+// something the script itself did. See `LogEntry.state`.
+export function formatLogStatus(entry) {
+    return entry.state !== undefined ? formatScriptStatusLabel(entry.state) : entry.level;
+}
+// The CSS class the pane colours the Status cell by: the display state
+// when the entry carries one, the level otherwise (`userscript.html`
+// defines both families).
+export function logStatusClass(entry) {
+    return entry.state !== undefined ? `log-state-${entry.state}` : `log-level-${entry.level}`;
+}
+// The Message cell as plain text, with a derived location flattened
+// into the same sentence the pane renders as a link.
+//
+// Correct for every entry SourceMonkey wrote about a script, and wrong
+// only for the stack refs inside an entry the script itself produced —
+// see the note at the top of the file, and `logMessageText` in
+// `userscript.ts` for the renderer that handles those.
+export function formatLogMessage(entry) {
+    return describeDiagnostic(entry.message, entry.location);
+}
+// Column headings, in order — the pane's `<th>` row and the CSV's
+// header row are the same four.
+export const LOG_COLUMNS = ['Time', 'Status', 'Source', 'Message'];
+// ---------- CSV ----------
+// Quote when the value would otherwise be ambiguous or awkward to read
+// back: the separator, the quote character itself, and any whitespace —
+// the last of which covers leading/trailing spaces a parser would
+// otherwise be free to trim.
+const NEEDS_QUOTING = /[",\s]/;
+export function csvField(value) {
+    if (!NEEDS_QUOTING.test(value))
+        return value;
+    return `"${value.replace(/"/g, '""')}"`;
+}
+// Fold a value onto one physical line: `\n`, `\r` as their two-
+// character escapes.
+//
+// CSV would allow the newline inside quotes, and a spreadsheet would
+// read it back — but this file is called `.log`, and one record per
+// line is what makes it work with the tools a log is actually reached
+// for. A stack trace spanning eight physical lines means `grep` finds
+// a fragment with no timestamp on it, `wc -l` counts frames instead of
+// events, and `tail -n` cuts an entry in half.
+//
+// Backslash is escaped first, and only for that reason: log messages
+// carry Windows paths and regex sources, so without it a literal `\n`
+// in the text and a real newline would decode to the same thing, and
+// the escape wouldn't be reversible.
+export function foldToOneLine(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+}
+// One record, one line — by construction, not by the caller
+// remembering to flatten first.
+export function csvRow(fields) {
+    return fields.map((f) => csvField(foldToOneLine(f))).join(',');
+}
+// The whole log as CSV text, header row first, one entry per line.
+//
+// Rows are newest-first, matching the pane's table rather than the
+// append order in storage: this is an export of what the reader is
+// looking at, and a log whose top line is the event they just saw is
+// the point of the ordering in both places.
+//
+// `renderMessage` is how the caller supplies its own Message column;
+// see the note at the top of the file.
+export function formatLogCsv(entries, renderMessage = formatLogMessage) {
+    const lines = [csvRow(LOG_COLUMNS)];
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        lines.push(csvRow([
+            formatLogTimestamp(e.timestamp),
+            formatLogStatus(e),
+            formatLogSource(e),
+            renderMessage(e),
+        ]));
+    }
+    return `${lines.join('\n')}\n`;
+}
+// Suggested filename for a saved log: the script's log ID with its
+// `.user.js` / `.js` extension swapped for `.log`, keeping its `#E4`
+// (or `#N`) suffix so two scripts sharing a basename don't suggest the
+// same file. `bold-on-hover.user.js#E4` → `bold-on-hover#E4.log`.
+//
+// `.log` rather than `.csv` even though the contents are CSV: this is
+// a log first, and a double-click should open a text editor rather
+// than a spreadsheet.
+export function logFileName(logId) {
+    // Suffix first, extension second — `logIdSuffix` explains
+    // why the `#N` match is anchored, and `script-source-url.ts` explains
+    // why the order matters (`Chapter #2.user.js`).
+    const trimmed = sanitizeFilename(logId).trim();
+    const dupe = logIdSuffix(trimmed);
+    // One alternation rather than two `.replace`s: chaining them strips
+    // twice for a name like `bar.js.user.js`, eating a `.js` that is part
+    // of the name.
+    const base = (dupe ? trimmed.slice(0, -dupe.length) : trimmed)
+        .replace(/\.(user\.)?js$/i, '');
+    // Fallback for a script we have no label for at all — the viewer
+    // asks for a filename whether or not the log ID map has landed.
+    return `${base || 'script'}${dupe}.log`;
+}
+// A log ID is a decoded on-disk filename, which is attacker-controlled
+// for an untrusted script bundle. Path separators are already gone
+// (`scriptBasename` takes the leaf twice), so what is left is control
+// characters, which have no business in a filename the browser is
+// about to write. Same substitution as `sanitizeLabel` in
+// `script-source-url.ts`, for the same reason.
+function sanitizeFilename(name) {
+    // eslint-disable-next-line no-control-regex
+    return name.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, '_');
+}