sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/save-html.d.ts

@@ -0,0 +1,39 @@
+import type { Page } from '@playwright/test';
+import { type PreparedScript } from './prepare.js';
+/** How a userscript is named in a saved file's header: its @name and @version. */
+export declare function userscriptLabel(script: PreparedScript): string;
+/**
+ * The page's current DOM as a standalone HTML document.
+ *
+ * A `<base>` keeps relative URLs pointing at the site. The page's own
+ * JavaScript is disabled (`type="text/plain"`, which keeps it readable
+ * while the browser skips it): served again it would re-fetch,
+ * redirect to a login, or rebuild the DOM the file was saved to
+ * preserve. What a clone cannot carry (typed form values, canvas
+ * pixels, shadow roots) is not in the file either.
+ *
+ * The header records the page's URL, for `--from-saved` to serve it
+ * there, and each of `userscripts` (see `userscriptLabel`), the ones
+ * running in the page, whose changes are in the file.
+ */
+export declare function pageHtml(page: Page, userscripts?: string[]): Promise<string>;
+/**
+ * The header comment lines for a page saved from `url` with
+ * `userscripts` running. Only `-->` (or `--!>`) ends a comment, and a
+ * URL the browser reports has any `>` percent-encoded, so the URL goes
+ * in as it is (`xn--` hosts included). A name gets its `>` escaped
+ * after `--`, which no real name has.
+ */
+export declare function savedHeaderLines(url: string, userscripts: string[]): string[];
+/** `pageHtml`, written to `file`. Returns the HTML. */
+export declare function savePageHtml(page: Page, file: string, userscripts?: string[]): Promise<string>;
+/** What a saved file's header says: its URL, if any, and the userscripts that were active. */
+export interface SavedPageHeader {
+    url: string | null;
+    userscripts: string[];
+}
+/**
+ * Reads a saved file's header. Only what comes before `<html` is
+ * looked at, so a comment in the page's own content never counts.
+ */
+export declare function readSavedHeader(html: string): SavedPageHeader;

package/lib/harness/save-html.js

@@ -0,0 +1,89 @@
+// Saving a page's DOM as a file, with a header saying where it came
+// from; and reading that header back (see saved-pages.ts for serving
+// the file).
+//
+// Shared by the `savehtml` run command (page-commands.ts) and the
+// fixture's `saveHtml`, so a developer recording a page by hand and a
+// test recording one produce the same file.
+import { writeFile } from 'node:fs/promises';
+import { preparedScriptName } from './prepare.js';
+// The header lines a saved file starts with, after its doctype. The
+// URL line is the "saved from" comment Internet Explorer's Mark of the
+// Web introduced, and Chrome's Save Page As still writes, so a page
+// saved from the browser's menu is read the same way. The number is
+// the URL's length, which nothing here relies on.
+const SAVED_FROM = /<!--\s*saved from url=\(\d+\)(\S+?)\s*-->/i;
+const USERSCRIPT_PREFIX = 'SourceMonkey: userscript active: ';
+const USERSCRIPT_LINE = new RegExp(`<!-- ${USERSCRIPT_PREFIX}(.*?) -->`, 'g');
+/** How a userscript is named in a saved file's header: its @name and @version. */
+export function userscriptLabel(script) {
+    const version = (script.script.header?.tags ?? []).find((t) => t.tag === 'version')?.value;
+    return version ? `${preparedScriptName(script)} ${version}` : preparedScriptName(script);
+}
+/**
+ * The page's current DOM as a standalone HTML document.
+ *
+ * A `<base>` keeps relative URLs pointing at the site. The page's own
+ * JavaScript is disabled (`type="text/plain"`, which keeps it readable
+ * while the browser skips it): served again it would re-fetch,
+ * redirect to a login, or rebuild the DOM the file was saved to
+ * preserve. What a clone cannot carry (typed form values, canvas
+ * pixels, shadow roots) is not in the file either.
+ *
+ * The header records the page's URL, for `--from-saved` to serve it
+ * there, and each of `userscripts` (see `userscriptLabel`), the ones
+ * running in the page, whose changes are in the file.
+ */
+export async function pageHtml(page, userscripts = []) {
+    const url = page.url();
+    const { doctype, body } = await page.evaluate((base) => {
+        const doc = document.documentElement.cloneNode(true);
+        const head = doc.querySelector('head');
+        if (head && !head.querySelector('base')) {
+            const el = document.createElement('base');
+            el.href = base;
+            head.prepend(el);
+        }
+        for (const script of doc.querySelectorAll('script'))
+            script.setAttribute('type', 'text/plain');
+        const dt = document.doctype;
+        return {
+            doctype: dt
+                ? `<!DOCTYPE ${dt.name}${dt.publicId ? ` PUBLIC "${dt.publicId}"` : ''}${dt.systemId ? ` "${dt.systemId}"` : ''}>`
+                : '',
+            body: doc.outerHTML,
+        };
+    }, url);
+    return [...(doctype ? [doctype] : []), ...savedHeaderLines(url, userscripts), body].join('\n');
+}
+/**
+ * The header comment lines for a page saved from `url` with
+ * `userscripts` running. Only `-->` (or `--!>`) ends a comment, and a
+ * URL the browser reports has any `>` percent-encoded, so the URL goes
+ * in as it is (`xn--` hosts included). A name gets its `>` escaped
+ * after `--`, which no real name has.
+ */
+export function savedHeaderLines(url, userscripts) {
+    return [
+        `<!-- saved from url=(${String(url.length).padStart(4, '0')})${url} -->`,
+        ...userscripts.map((name) => `<!-- ${USERSCRIPT_PREFIX}${name.replace(/--(!?)>/g, '--$1&gt;')} -->`),
+    ];
+}
+/** `pageHtml`, written to `file`. Returns the HTML. */
+export async function savePageHtml(page, file, userscripts = []) {
+    const html = await pageHtml(page, userscripts);
+    await writeFile(file, html);
+    return html;
+}
+/**
+ * Reads a saved file's header. Only what comes before `<html` is
+ * looked at, so a comment in the page's own content never counts.
+ */
+export function readSavedHeader(html) {
+    const end = html.search(/<html[\s>]/i);
+    const head = end >= 0 ? html.slice(0, end) : html;
+    return {
+        url: SAVED_FROM.exec(head)?.[1] ?? null,
+        userscripts: [...head.matchAll(USERSCRIPT_LINE)].map((m) => m[1]),
+    };
+}

package/lib/harness/saved-pages.d.ts

@@ -0,0 +1,120 @@
+import type { Page, Request } from '@playwright/test';
+import { type SavedPageHeader } from './save-html.js';
+/**
+ * The browser reports `https://example.test` as `https://example.test/`
+ * and never reports a fragment, so both sides are normalized the same
+ * way before comparing.
+ */
+export declare function comparableUrl(raw: string): string;
+/** What `routeSavedPage` serves, as it stands when a request is made. */
+export interface SavedPageServe {
+    /** The URL the page answers, matched exactly, query string included, fragment ignored. */
+    url: string;
+    /** The page's HTML. Read per request, so an edited file is served on the next load. */
+    html: () => Promise<string>;
+    /** Other requests to abort, rather than send on. */
+    block?: (request: Request) => boolean;
+    /** How the file is named when it can't be read. */
+    name: string;
+    /** Told why, when the file can't be read; the page shows it too. */
+    onError?: (message: string) => void;
+    /** The files saved beside the page, served from disk (see `companionFiles`). */
+    companion?: CompanionFiles;
+}
+/**
+ * The folder a browser's "Webpage, Complete" save puts beside the page
+ * (Chrome and Firefox both name it `<name>_files`), and the URL its
+ * files are asked for at: the page links them relatively
+ * (`./<name>_files/app.css`), so they resolve against the page's URL.
+ */
+export interface CompanionFiles {
+    /** The folder's URL path, decoded, on `origin`. */
+    origin: string;
+    path: string;
+    dir: string;
+}
+/** The companion folder for a saved `file` served at `url`, whether or not it exists. */
+export declare function companionFiles(file: string, url: string): CompanionFiles | undefined;
+/**
+ * Serves `current()` on `page`: its URL gets its HTML, and every other
+ * request falls through to the page's other routes and the network,
+ * unless `block` says to abort it. Undefined serves nothing, so a
+ * caller can change or end what is served without routing again.
+ */
+export declare function routeSavedPage(page: Page, current: () => SavedPageServe | undefined): Promise<void>;
+/**
+ * For `--offline`: blocks the requests a page makes while it shows the
+ * saved page at `url`. A load of a new page is never blocked, so
+ * following a link off it still works.
+ */
+export declare function offlineBlock(page: Page, url: string): (request: Request) => boolean;
+/**
+ * A saved page as sm-dev serves it in a tab: `file` at `url`, `offline`
+ * blocking the rest. `given`: the file as it was named, for messages.
+ */
+export interface SavedPageFile {
+    file: string;
+    given: string;
+    url: string;
+    offline: boolean;
+}
+/**
+ * What `routeSavedPage` serves for `saved` in `page`, for `--from-saved`:
+ * the file read fresh on each load, and a read failure told to `out` as
+ * well as shown.
+ */
+export declare function savedPageServe(page: Page, saved: SavedPageFile, out: (line: string) => void): SavedPageServe;
+/** How `start`, `open` and `newtab` say a tab is loading a saved page. */
+export declare function openingSavedLine(given: string, url: string, tab: string): string;
+/** `--offline` without `--from-saved`. */
+export declare const OFFLINE_NEEDS_SAVED = "The --offline flag goes with --from-saved";
+/** `--url` without `--from-saved` and exactly one saved page. */
+export declare const URL_NEEDS_ONE_SAVED = "The --url flag gives the URL for one saved page, so it goes with --from-saved and a single .html file";
+/** `--from-saved` with no page to open from a file. */
+export declare const NO_SAVED_FILE = "The --from-saved flag opens .html files, and none was given";
+/** How sm-dev's commands say to give a URL for a saved page. */
+export declare const GIVE_SAVED_URL = "Open it by itself, with --url.";
+/**
+ * The URL to serve a saved page at: `url`, else the one its header
+ * records. Or why there is none: no URL anywhere, or one a route
+ * can't answer (`about:blank`, `file://`). `remedy` is a sentence
+ * saying how to give one where it was named.
+ */
+export declare function savedPageUrl(given: string, header: SavedPageHeader, url: string | undefined, remedy: string): {
+    url: string;
+} | {
+    problem: string;
+};
+/** A saved page to open (`--from-saved`), with the userscripts its header lists. */
+export type SavedPageStart = SavedPageFile & {
+    userscripts: string[];
+};
+/** One page a command opens: a URL, or with `saved`, a saved page served at it. */
+export interface PageToOpen {
+    url: string;
+    saved?: SavedPageStart;
+}
+/** A page a command was given: the word as typed, and the URL it stands for. */
+export interface PageWord {
+    word: string;
+    url: string;
+}
+/**
+ * With `--from-saved` (`fromSaved`): each word naming a local `.html`
+ * file is a saved page, at the URL it records or `--url`; the others
+ * stay URLs. Without, `--url` and `--offline` are refused. Throws a
+ * `UsageError` naming the file for any saved page that can't be opened,
+ * before anything opens.
+ */
+export declare function pagesToOpen(words: PageWord[], opts: {
+    fromSaved: boolean;
+    url?: string;
+    offline: boolean;
+}, cwd?: string): Promise<PageToOpen[]>;
+/** Reads a saved file for serving, with its header. */
+export declare function loadSavedPage(file: string): Promise<{
+    html: string;
+    header: SavedPageHeader;
+}>;
+/** Why a saved page named with `--from-saved` could not be read. */
+export declare function savedReadMessage(given: string, err: NodeJS.ErrnoException): string;

package/lib/harness/saved-pages.js

@@ -0,0 +1,275 @@
+// Serving a saved page (from save-html.ts, or a browser's own Save Page
+// As) back at the URL it was saved from, so scripts match and run on it
+// as on the live site.
+//
+// Shared by `--from-saved` on `start`, `open` and `newtab`
+// (console-commands.ts, run.ts, cli.ts) and the fixture's `serveHtml`,
+// so both serve one the same way.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { UsageError } from './checks.js';
+import { isDirectoryMessage, noSuchFileMessage } from './prepare.js';
+import { readSavedHeader } from './save-html.js';
+/**
+ * The browser reports `https://example.test` as `https://example.test/`
+ * and never reports a fragment, so both sides are normalized the same
+ * way before comparing.
+ */
+export function comparableUrl(raw) {
+    try {
+        const u = new URL(raw);
+        u.hash = '';
+        return u.href;
+    }
+    catch {
+        return raw;
+    }
+}
+/** The companion folder for a saved `file` served at `url`, whether or not it exists. */
+export function companionFiles(file, url) {
+    const stem = path.basename(file).replace(/\.x?html?$/i, '');
+    let at;
+    try {
+        // Built by the URL parser, so it's encoded as the browser encodes
+        // the page's own relative links.
+        at = new URL(`./${stem}_files/`, url);
+    }
+    catch {
+        return undefined;
+    }
+    // Resolved, so the check that a request stays inside it compares like with like.
+    return { origin: at.origin, path: decodedPath(at) ?? at.pathname, dir: path.resolve(path.dirname(file), `${stem}_files`) };
+}
+// Where on disk a request for a companion file is, or null when it
+// isn't one. Never outside the folder, whatever `..` the URL has.
+function companionPath(companion, raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    const wanted = decodedPath(url);
+    if (url.origin !== companion.origin || !wanted?.startsWith(companion.path))
+        return null;
+    const file = path.resolve(companion.dir, wanted.slice(companion.path.length));
+    return file.startsWith(companion.dir + path.sep) ? file : null;
+}
+function decodedPath(url) {
+    try {
+        return decodeURIComponent(url.pathname);
+    }
+    catch {
+        return null;
+    }
+}
+// By extension: a stylesheet or module script served with the wrong
+// type is refused. Anything else is left for the browser to sniff.
+const CONTENT_TYPES = {
+    '.css': 'text/css', '.js': 'text/javascript', '.mjs': 'text/javascript', '.json': 'application/json',
+    '.html': 'text/html', '.htm': 'text/html', '.svg': 'image/svg+xml', '.png': 'image/png',
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.avif': 'image/avif',
+    '.ico': 'image/x-icon', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf',
+};
+/**
+ * Serves `current()` on `page`: its URL gets its HTML, and every other
+ * request falls through to the page's other routes and the network,
+ * unless `block` says to abort it. Undefined serves nothing, so a
+ * caller can change or end what is served without routing again.
+ */
+export async function routeSavedPage(page, current) {
+    await bypassServiceWorker(page);
+    await page.route('**/*', async (route) => {
+        const saved = current();
+        const request = route.request();
+        if (saved && comparableUrl(request.url()) === comparableUrl(saved.url)) {
+            let body;
+            try {
+                body = await saved.html();
+            }
+            catch (err) {
+                // Shown as the page too, where the person is looking.
+                const message = savedReadMessage(saved.name, err);
+                saved.onError?.(message);
+                await route.fulfill({ status: 500, contentType: 'text/plain; charset=utf-8', body: message });
+                return;
+            }
+            await route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body });
+            return;
+        }
+        // A file saved beside the page, while it shows, even with
+        // `--offline`. One that isn't there is a 404, not the live site's:
+        // the site never had it at that URL.
+        const showing = saved !== undefined && comparableUrl(page.url()) === comparableUrl(saved.url);
+        const local = showing && saved.companion ? companionPath(saved.companion, request.url()) : null;
+        if (local) {
+            const body = await readFile(local).catch(() => null);
+            const type = CONTENT_TYPES[path.extname(local).toLowerCase()];
+            await route.fulfill(body ? { status: 200, body, ...(type ? { contentType: type } : {}) } : { status: 404, body: '' });
+            return;
+        }
+        if (saved?.block?.(request)) {
+            await route.abort();
+            return;
+        }
+        // `fallback`, not `continue`: Playwright runs route handlers newest
+        // first, and only `fallback` hands a request to the next one. That
+        // lets a second saved page, or a HAR, sit beside this route.
+        await route.fallback();
+    });
+}
+/**
+ * For `--offline`: blocks the requests a page makes while it shows the
+ * saved page at `url`. A load of a new page is never blocked, so
+ * following a link off it still works.
+ */
+export function offlineBlock(page, url) {
+    return (request) => {
+        if (comparableUrl(page.url()) !== comparableUrl(url))
+            return false;
+        try {
+            return !(request.isNavigationRequest() && request.frame() === page.mainFrame());
+        }
+        catch {
+            // A service worker's request has no frame.
+            return true;
+        }
+    };
+}
+/**
+ * What `routeSavedPage` serves for `saved` in `page`, for `--from-saved`:
+ * the file read fresh on each load, and a read failure told to `out` as
+ * well as shown.
+ */
+export function savedPageServe(page, saved, out) {
+    return {
+        url: saved.url,
+        html: () => readFile(saved.file, 'utf8'),
+        block: saved.offline ? offlineBlock(page, saved.url) : undefined,
+        name: saved.given,
+        onError: (message) => out(`[sm-dev] ${message}`),
+        companion: companionFiles(saved.file, saved.url),
+    };
+}
+/** How `start`, `open` and `newtab` say a tab is loading a saved page. */
+export function openingSavedLine(given, url, tab) {
+    return `[sm-dev] Opening ${given} as ${url} in ${tab}`;
+}
+/** `--offline` without `--from-saved`. */
+export const OFFLINE_NEEDS_SAVED = 'The --offline flag goes with --from-saved';
+/** `--url` without `--from-saved` and exactly one saved page. */
+export const URL_NEEDS_ONE_SAVED = 'The --url flag gives the URL for one saved page, so it goes with --from-saved and a single .html file';
+/** `--from-saved` with no page to open from a file. */
+export const NO_SAVED_FILE = 'The --from-saved flag opens .html files, and none was given';
+/** How sm-dev's commands say to give a URL for a saved page. */
+export const GIVE_SAVED_URL = 'Open it by itself, with --url.';
+/**
+ * The URL to serve a saved page at: `url`, else the one its header
+ * records. Or why there is none: no URL anywhere, or one a route
+ * can't answer (`about:blank`, `file://`). `remedy` is a sentence
+ * saying how to give one where it was named.
+ */
+export function savedPageUrl(given, header, url, remedy) {
+    const at = url ?? header.url;
+    if (!at)
+        return { problem: `${given} does not say what URL it was saved from. ${remedy}` };
+    if (!/^https?:/i.test(at))
+        return { problem: `${given} can only be served at an http or https URL, not ${at}. ${remedy}` };
+    return { url: at };
+}
+/**
+ * With `--from-saved` (`fromSaved`): each word naming a local `.html`
+ * file is a saved page, at the URL it records or `--url`; the others
+ * stay URLs. Without, `--url` and `--offline` are refused. Throws a
+ * `UsageError` naming the file for any saved page that can't be opened,
+ * before anything opens.
+ */
+export async function pagesToOpen(words, opts, cwd = process.cwd()) {
+    if (!opts.fromSaved) {
+        if (opts.url !== undefined)
+            throw new UsageError(URL_NEEDS_ONE_SAVED);
+        if (opts.offline)
+            throw new UsageError(OFFLINE_NEEDS_SAVED);
+        return words.map(({ url }) => ({ url }));
+    }
+    const files = words.map((w) => savedPageFile(w, cwd));
+    const count = files.filter(Boolean).length;
+    if (count === 0)
+        throw new UsageError(NO_SAVED_FILE);
+    if (opts.url !== undefined && count > 1)
+        throw new UsageError(URL_NEEDS_ONE_SAVED);
+    return Promise.all(words.map(async ({ word, url }, i) => {
+        const file = files[i];
+        if (!file)
+            return { url };
+        let header;
+        try {
+            ({ header } = await loadSavedPage(file));
+        }
+        catch (err) {
+            // A name that's no file is a mistake in the command; one that
+            // can't be read for another reason isn't.
+            const code = err.code;
+            const message = savedReadMessage(word, err);
+            throw code === 'ENOENT' || code === 'EISDIR' ? new UsageError(message) : new Error(message);
+        }
+        const found = savedPageUrl(word, header, opts.url, GIVE_SAVED_URL);
+        if ('problem' in found)
+            throw new UsageError(found.problem);
+        return { url: found.url, saved: { file, given: word, url: found.url, offline: opts.offline, userscripts: header.userscripts } };
+    }));
+}
+// The file a page names, when it's a local `.html` file: what
+// `--from-saved` serves. A word ending `.html` with no `://` is one
+// even where it would read as a host (`pgae.html`), so a typo is
+// said to be no file rather than opened live; `localhost:8080/x.html`
+// keeps its port, and so its host.
+function savedPageFile({ word, url }, cwd) {
+    if (url.startsWith('file:'))
+        return /\.x?html?$/i.test(url) ? fileURLToPath(url) : null;
+    const first = word.split('/')[0];
+    if (word.includes('://') || /:\d+$/.test(first) || !/\.x?html?$/i.test(word))
+        return null;
+    return path.resolve(cwd, word);
+}
+// A site's service worker answers its requests before Playwright's
+// routes see them, so a site that has one would get its live page
+// instead of the saved one. Bypassing it takes the network domain
+// enabled on a session of our own, kept for the page's life. Best
+// effort: a browser that refuses still serves pages without one.
+const bypassed = new WeakMap();
+function bypassServiceWorker(page) {
+    let session = bypassed.get(page);
+    if (!session) {
+        session = (async () => {
+            try {
+                const cdp = await page.context().newCDPSession(page);
+                await cdp.send('Network.enable');
+                await cdp.send('Network.setBypassServiceWorker', { bypass: true });
+                return cdp;
+            }
+            catch {
+                return null;
+            }
+        })();
+        bypassed.set(page, session);
+    }
+    return session;
+}
+/** Reads a saved file for serving, with its header. */
+export async function loadSavedPage(file) {
+    const html = await readFile(file, 'utf8');
+    return { html, header: readSavedHeader(html) };
+}
+/** Why a saved page named with `--from-saved` could not be read. */
+export function savedReadMessage(given, err) {
+    if (err.code === 'ENOENT')
+        return noSuchFileMessage(given);
+    if (err.code === 'EISDIR')
+        return isDirectoryMessage(given, 'Name a saved .html file.');
+    if (err.code === 'EACCES')
+        return `The saved page ${given} could not be read: Permission denied`;
+    return `The saved page ${given} could not be read: ${err.message}`;
+}

package/lib/harness/script-mark.d.ts

@@ -0,0 +1,17 @@
+/** What the comment says. */
+export interface ScriptMark {
+    /** A run's script: the run's id (`D1`). */
+    run?: string;
+    /** A run's script: when the run started, which tells it from an older run with the same id. */
+    started?: string;
+    /** The file it was installed from. */
+    file?: string;
+}
+/** `text` with `mark` as its last line, in place of any it had. */
+export declare function markedText(text: string, mark: ScriptMark): string;
+/** What the comment in `text` says, or null when it has none. */
+export declare function readMark(text: string): ScriptMark | null;
+/** `text` without the comment, as it was before it was added. */
+export declare function withoutMark(text: string): string;
+/** Whether two texts are the same script, the comment and trailing white space aside. */
+export declare function sameScript(a: string, b: string): boolean;

package/lib/harness/script-mark.js

@@ -0,0 +1,56 @@
+// The comment sm-dev adds as the last line of a script it installs in
+// another manager (Violentmonkey, Tampermonkey), saying where
+// it came from, and for a run's script, which run:
+//
+//   // sm-dev: run=D1 started=2026-10-04T12:00:00.000Z file=/home/me/foo.user.js
+//
+// In the script's own text, since that's what every manager keeps as
+// given, so no manager's internals are relied on. Last, so it moves no
+// line numbers. See docs/sm-dev-violentmonkey.md.
+const PREFIX = '// sm-dev: ';
+/** `text` with `mark` as its last line, in place of any it had. */
+export function markedText(text, mark) {
+    const body = withoutMark(text);
+    // The file last, since a path can hold spaces.
+    const fields = [
+        ...(mark.run !== undefined ? [`run=${mark.run}`] : []),
+        ...(mark.started !== undefined ? [`started=${mark.started}`] : []),
+        ...(mark.file !== undefined ? [`file=${mark.file}`] : []),
+    ];
+    if (fields.length === 0)
+        return body;
+    return `${body}${body.endsWith('\n') || body === '' ? '' : '\n'}${PREFIX}${fields.join(' ')}\n`;
+}
+// The last line that has anything on it, and where it starts.
+function lastLine(text) {
+    const trimmed = text.replace(/\s+$/, '');
+    const start = trimmed.lastIndexOf('\n') + 1;
+    return { line: trimmed.slice(start), start };
+}
+/** What the comment in `text` says, or null when it has none. */
+export function readMark(text) {
+    const { line } = lastLine(text);
+    if (!line.startsWith(PREFIX))
+        return null;
+    const mark = {};
+    const rest = line.slice(PREFIX.length);
+    const file = /(?:^| )file=(.*)$/.exec(rest);
+    if (file)
+        mark.file = file[1];
+    for (const [, key, value] of (file ? rest.slice(0, file.index) : rest).matchAll(/(\w+)=(\S*)/g)) {
+        if (key === 'run')
+            mark.run = value;
+        else if (key === 'started')
+            mark.started = value;
+    }
+    return mark;
+}
+/** `text` without the comment, as it was before it was added. */
+export function withoutMark(text) {
+    const { line, start } = lastLine(text);
+    return line.startsWith(PREFIX) ? text.slice(0, start) : text;
+}
+/** Whether two texts are the same script, the comment and trailing white space aside. */
+export function sameScript(a, b) {
+    return withoutMark(a).trimEnd() === withoutMark(b).trimEnd();
+}