sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/manager-actions.js

@@ -0,0 +1,129 @@
+// The `manager` verbs: `fetch` a manager into sm-dev's cache, `install`
+// it into a browser, and `enable` or `disable` it there. sm-dev runs
+// them itself, never in a run: they act on the browser's extensions,
+// which a run doesn't hold.
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { allowUserScripts, installedManagers, loadUnpacked, otherManagersWarning, setExtensionEnabled, } from './browser-extensions.js';
+import { withTilde } from './browser-launch.js';
+import { EXTENSION_DIR } from './extension-launch.js';
+import { fetchManager, fetchedDir, fetchedVersion } from './manager-fetch.js';
+import { MANAGERS, managerFlag } from './managers.js';
+import { cmd, id as idRole, message, quoted, SM_DEV_PREFIX, ui, url } from './output-style.js';
+import { rebuildAdvice } from './rebuild-advice.js';
+// A line of sm-dev's own, as a note, without its `[sm-dev] ` prefix.
+const withoutPrefix = (line) => (line.startsWith(SM_DEV_PREFIX) ? line.slice(SM_DEV_PREFIX.length) : line);
+/** A failure the person made in asking, rather than one doing it. */
+export class ManagerUsageError extends Error {
+}
+/** Does one verb. Returns false when it failed, having said why. */
+export async function managerAction(o) {
+    const { label } = MANAGERS[o.manager];
+    if (o.verb === 'fetch') {
+        if (o.manager === 'sourcemonkey')
+            throw new ManagerUsageError(`${label} comes with sm-dev, so there is nothing to fetch. Use ${quoted('--manager')} to name another.`);
+        const fetched = await fetchManager(o.manager, (line) => o.note(withoutPrefix(line)));
+        if (!fetched.downloaded) {
+            o.out(ui `${label} ${fetched.version} is the newest version, and is already in ${url(withTilde(fetched.dir))}`);
+            return true;
+        }
+        o.out(ui `Fetched ${label} ${fetched.version} into ${url(withTilde(fetched.dir))}${fetched.replaced ? `, replacing ${fetched.replaced}` : ''}`);
+        if (fetched.replaced)
+            o.out(message(`A browser with it installed from there gets the new version with ${quoted(`sm-dev ${managerFlag(o.manager)} manager install`)}.`));
+        return true;
+    }
+    const endpoint = o.endpoint;
+    const managers = await browserManagers(endpoint);
+    const copies = managers.filter((m) => m.manager === o.manager);
+    if (o.verb === 'install') {
+        if (!await install(o, managers, copies))
+            return false;
+    }
+    else {
+        if (copies.length === 0) {
+            o.note(message(`${label} is not installed in this browser. Install it with ${quoted(`sm-dev${o.browserArg ?? ''} ${managerFlag(o.manager)} manager install`)}`));
+            return false;
+        }
+        const enable = o.verb === 'enable';
+        if (!enable && o.manager === 'sourcemonkey' && (o.runsUsing ?? []).length > 0) {
+            const runs = o.runsUsing;
+            const ids = runs.map((run) => idRole(run)).join(', ');
+            o.note(ui `SourceMonkey can't be turned off while ${runs.length === 1 ? ui `run ${ids} uses` : ui `runs ${ids} use`} it. Stop ${runs.length === 1 ? 'that run' : 'them'} first.`);
+            return false;
+        }
+        for (const copy of copies) {
+            if (copy.enabled === enable) {
+                o.out(`${copy.name} ${copy.version} is already ${enable ? 'enabled' : 'disabled'}`);
+                continue;
+            }
+            await setExtensionEnabled(endpoint, copy.id, enable);
+            copy.enabled = enable;
+            o.out(`${enable ? 'Enabled' : 'Disabled'} ${copy.name} ${copy.version}`);
+        }
+        if (enable && copies.some((c) => !c.userScripts)) {
+            o.note(message(`Its Allow User Scripts is off, so it can't run scripts. ${quoted(`sm-dev${o.browserArg ?? ''} ${managerFlag(o.manager)} manager install`)} turns it on.`));
+        }
+    }
+    // Not after turning it off, when it's no longer in use either.
+    if (o.verb !== 'disable')
+        for (const line of otherManagersWarning(managers, o.manager, o.browserArg))
+            o.note(line);
+    return true;
+}
+// `manager install`: loads the manager unpacked, from sm-dev's copy of
+// SourceMonkey or the fetched copy of another, with "Allow User
+// Scripts" on. One there already is left as it is, but for turning
+// that on, and for a fetched copy, updating it to the version fetched
+// since.
+async function install(o, managers, copies) {
+    const { label } = MANAGERS[o.manager];
+    const endpoint = o.endpoint;
+    let dir;
+    let version;
+    if (o.manager === 'sourcemonkey') {
+        dir = EXTENSION_DIR;
+        if (!existsSync(path.join(dir, 'manifest.json'))) {
+            o.note(ui `The built extension is missing from ${url(dir)}. ${message(rebuildAdvice())}`);
+            return false;
+        }
+        version = null;
+    }
+    else {
+        // Fetched the first time it's wanted, as `manager fetch` would.
+        version = fetchedVersion(o.manager) ?? (await fetchManager(o.manager, (line) => o.note(withoutPrefix(line)))).version;
+        dir = fetchedDir(o.manager);
+    }
+    const ours = copies.find((m) => m.path !== undefined && path.resolve(m.path) === path.resolve(dir));
+    const copy = ours ?? copies[0];
+    if (copy) {
+        if (ours && version !== null && ours.version !== version) {
+            await loadUnpacked(endpoint, dir);
+            o.out(ui `Updated ${copy.name} from ${copy.version} to ${version}, from ${url(withTilde(dir))}`);
+        }
+        else {
+            // Where Chrome says it came from, when it says.
+            const from = copy.path ? ui `, from ${url(withTilde(copy.path))}` : copy.fromStore ? ', from the Chrome Web Store' : '';
+            o.out(ui `${copy.name} ${copy.version} is already installed${from}${copy.enabled ? '' : ui `, but disabled. Turn it on with ${cmd(`sm-dev${o.browserArg ?? ''} ${managerFlag(o.manager)} manager enable`)}.`}`);
+        }
+        if (!copy.userScripts) {
+            await allowUserScripts(endpoint, copy.id);
+            o.out('Turned on its Allow User Scripts');
+        }
+        return true;
+    }
+    const id = await loadUnpacked(endpoint, dir);
+    await allowUserScripts(endpoint, id);
+    const loaded = (await browserManagers(endpoint)).find((m) => m.id === id);
+    managers.push(...(loaded ? [loaded] : []));
+    o.out(ui `Installed ${label}${loaded ? ` ${loaded.version}` : ''} from ${url(withTilde(dir))}, with Allow User Scripts on`);
+    return true;
+}
+// The managers in the browser, or a failure naming it.
+async function browserManagers(endpoint) {
+    try {
+        return await installedManagers(endpoint);
+    }
+    catch (err) {
+        throw new Error(`Could not read the extensions of the browser at ${endpoint.replace(/^https?:\/\//, '')}: ${err.message}`);
+    }
+}

package/lib/harness/manager-commands.d.ts

@@ -0,0 +1,142 @@
+import { type CollectionRefresh, type ManagedCollection, type ManagedFileContent, type ManagedOnDisk, type ManagedScript, type ManagedScriptDetails, type ManagedScriptIcons, type ManagedSiteIcon, type ScriptEnable, type ScriptIconsLoad, type ScriptInstall, type ScriptRefresh } from '../sm-dev-protocol.js';
+import { type TabActivity } from './json-output.js';
+/**
+ * The calls these commands make into the manager: SourceMonkey's
+ * (managed-changes.ts), or another's (external-manager.ts).
+ */
+export interface ManagerControl {
+    /** The manager's name, for what the commands say (`SourceMonkey`). */
+    readonly label: string;
+    collections(): Promise<ManagedCollection[]>;
+    scripts(): Promise<ManagedScript[]>;
+    /** What the disk says of local scripts and collections; null for an extension older than 1.5. */
+    onDisk(): Promise<ManagedOnDisk | null>;
+    setScriptEnabled(id: string, enabled: boolean): Promise<ScriptEnable>;
+    setCollectionEnabled(id: string, enabled: boolean): Promise<ManagedCollection>;
+    refreshScript(id: string): Promise<ScriptRefresh>;
+    refreshCollection(id: string): Promise<CollectionRefresh>;
+    /**
+     * `replace`: another manager may replace a script of the person's own
+     * with the same name and namespace; else it refuses (`ReplaceRefused`).
+     */
+    installScript(location: string, collectionId: string | null, replace?: boolean): Promise<ScriptInstall>;
+    uninstallScript(id: string): Promise<ManagedScript>;
+    moveScript(id: string, collectionId: string): Promise<ScriptEnable>;
+    renameCollection(id: string, name: string): Promise<ManagedCollection>;
+    scriptDetails(id: string): Promise<ManagedScriptDetails | null>;
+    scriptText(id: string): Promise<string | null>;
+    /** A script's `@require` and `@resource` files as installed; null for no script. Absent when the manager doesn't give them. */
+    scriptFiles?(id: string): Promise<ManagedFileContent[] | null>;
+    /** A script's `@icon` and site icons; null for no script. Absent when the manager doesn't give them. */
+    scriptIcons?(id: string, load: ScriptIconsLoad): Promise<ManagedScriptIcons | null>;
+}
+/**
+ * A run's id in the extension (`D1-ab12`, see `linkRunId`) as sm-dev
+ * names the run (`D1`).
+ */
+export declare function runOfLinkId(id: string): string;
+/** In a run, what it knows of the scripts `script list` shows. */
+export interface RunView {
+    /** The run's own scripts' numbers (`2`), by the extension's id. */
+    own: Map<string, string>;
+    /** The selected script: by the extension's id, or by its E-id. */
+    selected?: {
+        internalId: string;
+    } | {
+        label: string;
+    };
+}
+/** `1 script`, `2 scripts`. */
+export declare function count(n: number, noun: string): string;
+/** The verbs each command takes. `script` without one picks a script instead. */
+export declare const MANAGER_VERBS: {
+    readonly collection: readonly ["list", "show", "enable", "disable", "refresh", "rename"];
+    readonly script: readonly ["list", "show", "print", "save", "enable", "disable", "refresh", "install", "uninstall", "move"];
+};
+/** Said for `collection <words>` with no verb it takes: `C3 frob`, or one word alone. */
+export declare function noSuchVerb(words: readonly string[]): string;
+/** `collection list`: each collection, numbered ones first. */
+export declare function collectionList(manager: ManagerControl, out: (line: string) => void, json: boolean): Promise<void>;
+/**
+ * The collection `name` names: `C3`, `id=<id>`, a run's (`D1`), or its
+ * name, whole or a part only it has, in any case. For none or several,
+ * throws an error with the reason.
+ */
+export declare function pickCollection(collections: readonly ManagedCollection[], name: string): ManagedCollection;
+/**
+ * `script list [collection]`: the installed scripts, under their
+ * collections, or one collection's. Throws for a collection it can't
+ * find.
+ */
+export declare function scriptList(manager: ManagerControl, name: string | undefined, out: (line: string) => void, json: boolean, view?: RunView): Promise<void>;
+/** What a run adds to the commands that show and change things. */
+export interface ManagerRun extends RunView {
+    /** Re-reads one of the run's own scripts from disk, as `update` does. */
+    updateOwn(internalId: string): Promise<void>;
+    /** What a script does on each of the run's tabs, with the words `scripts` uses for it. */
+    tabsOf(script: ManagedScript, label: string | undefined): Promise<{
+        activity: TabActivity;
+        text: string;
+    }[]>;
+}
+/** Where the commands that show and change things run. */
+export interface ManagerContext {
+    manager: ManagerControl;
+    out: (line: string) => void;
+    json: boolean;
+    /** In a run. */
+    run?: ManagerRun;
+    /**
+     * The collections and scripts are the person's own (not a
+     * a temp browser's), so a change that takes something away needs
+     * `--force`.
+     */
+    guarded: boolean;
+    /** Where a relative path given to `script install` is from. */
+    cwd: string;
+}
+/**
+ * The script `name` names: a run's own by its number (`2`), `E12`,
+ * `id=<id>`, or its name, whole or a part only it has, in any case. For
+ * none or several, throws an error with the reason.
+ */
+export declare function pickManagedScript(scripts: readonly ManagedScript[], name: string, view?: RunView): ManagedScript;
+/** Another manager won't replace the person's own script `shown` (`E3: Name`) without `replace`. */
+export declare class ReplaceRefused extends Error {
+    readonly shown: string;
+    constructor(shown: string);
+}
+/** Said for a script name that names none. */
+export declare function noSuchScript(name: string): string;
+/**
+ * `collection <C> <verb>`, `script [script] <verb>` and `script
+ * install`. `subject`: what it acts on, named before the verb; a script
+ * left out is the selected one. `args`: the words after the verb;
+ * `flags`: the command's own. Returns false when it failed, having said
+ * why.
+ */
+export declare function managerVerb(ctx: ManagerContext, command: 'collection' | 'script', verb: string, subject: string | undefined, args: string[], flags: Record<string, string | true>): Promise<boolean>;
+/** A site icon as sm-dev gives it: `path` absent for the globe. */
+interface SiteIconFile {
+    path?: string;
+    source?: ManagedSiteIcon['source'];
+    sites: string[];
+    bytes?: Buffer;
+}
+/**
+ * The file of `files` that `name` names: a `@resource`'s name, exactly,
+ * or a part of its URL only it has; `script` for the script itself;
+ * `icon` for the `@icon`. For none or multiple, throws a failure
+ * listing them. `shown`: the script, marked up.
+ */
+export declare function pickScriptFile(files: readonly ManagedFileContent[], name: string, shown: string): ManagedFileContent | 'script';
+/**
+ * The site icon that `name` (`site-icons/github.com`) names: the one
+ * whose name has the part after `site-icons/`. For none or multiple,
+ * throws a failure listing them.
+ */
+export declare function pickSiteIcon(files: readonly SiteIconFile[], name: string, shown: string): SiteIconFile & {
+    path: string;
+    bytes: Buffer;
+};
+export {};