@blastlauncher/web 0.0.0-stage → 3.0.0-alpha.0

package/dist/browser-install.js

@@ -0,0 +1,326 @@
+import { maxSatisfying, satisfies } from "semver";
+import { supplied } from "@blastlauncher/protocol/dependency-policy";
+export class BrowserInstallError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "BrowserInstallError";
+        this.code = code;
+    }
+}
+export class BrowserIntegrityError extends BrowserInstallError {
+    packageName;
+    expected;
+    actual;
+    constructor(packageName, expected, actual) {
+        super("BROWSER_INTEGRITY", `Integrity check failed for ${packageName}`);
+        this.name = "BrowserIntegrityError";
+        this.packageName = packageName;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+export class BrowserSizeLimitError extends BrowserInstallError {
+    limit;
+    actual;
+    constructor(limit, actual) {
+        super("BROWSER_SIZE_LIMIT", `Browser dependency size limit exceeded (${actual} > ${limit} bytes)`);
+        this.name = "BrowserSizeLimitError";
+        this.limit = limit;
+        this.actual = actual;
+    }
+}
+export class BrowserPackageLimitError extends BrowserInstallError {
+    limit;
+    constructor(limit) {
+        super("BROWSER_PACKAGE_LIMIT", `Browser dependency package limit exceeded (${limit})`);
+        this.name = "BrowserPackageLimitError";
+        this.limit = limit;
+    }
+}
+export class BrowserNativePackageError extends BrowserInstallError {
+    packageName;
+    constructor(packageName) {
+        super("BROWSER_NATIVE_MODULE", `Native package is not supported in the browser: ${packageName}`);
+        this.name = "BrowserNativePackageError";
+        this.packageName = packageName;
+    }
+}
+export class BrowserResolutionError extends BrowserInstallError {
+    packageName;
+    constructor(packageName, range) {
+        super("BROWSER_RESOLUTION", `Unable to resolve ${packageName}@${range} from the npm registry`);
+        this.name = "BrowserResolutionError";
+        this.packageName = packageName;
+    }
+}
+const DEFAULT_MAX_BYTES = 32 * 1024 * 1024;
+const DEFAULT_MAX_PACKAGES = 128;
+function packagePath(name) {
+    return `node_modules/${name}`;
+}
+function ancestorCandidates(parentPath, name) {
+    if (!parentPath)
+        return [packagePath(name)];
+    // Nearest first, exactly the order Node and bundleForBrowser resolve in: the
+    // parent's own node_modules, then each enclosing node_modules up to the root.
+    const result = [`${parentPath}/node_modules/${name}`];
+    let packageDirectory = parentPath;
+    while (packageDirectory && packageDirectory !== ".") {
+        const nodeModulesDirectory = packageDirectory.slice(0, packageDirectory.lastIndexOf("/"));
+        if (!nodeModulesDirectory)
+            break;
+        result.push(`${nodeModulesDirectory}/${name}`);
+        const separator = nodeModulesDirectory.lastIndexOf("/");
+        if (separator < 0)
+            break;
+        packageDirectory = nodeModulesDirectory.slice(0, separator);
+    }
+    result.push(packagePath(name));
+    return [...new Set(result)];
+}
+function lockedVersion(lock, path) {
+    return lock?.packages?.[path]?.version;
+}
+/** npm v1 lockfiles only nest dependency records, so only the root has a path here. */
+function legacyLockVersion(lock, name) {
+    return lock?.dependencies?.[name]?.version;
+}
+function parseLockfile(lockfile) {
+    if (lockfile === undefined)
+        return undefined;
+    if (typeof lockfile === "string")
+        return JSON.parse(lockfile);
+    return lockfile;
+}
+function decode(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+function readString(bytes) {
+    return decode(bytes).replace(/\0.*$/, "").trim();
+}
+function octal(bytes) {
+    const value = readString(bytes).replace(/[^0-7].*$/, "");
+    return value ? Number.parseInt(value, 8) : 0;
+}
+export class BrowserTarPathError extends BrowserInstallError {
+    path;
+    constructor(path) {
+        super("BROWSER_TAR_PATH", `Unsafe path in npm archive: ${path}`);
+        this.name = "BrowserTarPathError";
+        this.path = path;
+    }
+}
+function normalTarPath(path) {
+    if (path.includes("\\") || path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path))
+        throw new BrowserTarPathError(path);
+    const parts = path.split("/");
+    if (parts.some((part) => part === ".."))
+        throw new BrowserTarPathError(path);
+    return parts.filter((part) => part !== "" && part !== ".").join("/");
+}
+/** Parses the small subset of POSIX tar needed for npm archives, including pax and ustar names. */
+export function unpackTar(archive) {
+    const files = new Map();
+    let offset = 0;
+    let paxPath;
+    while (offset + 512 <= archive.length) {
+        const header = archive.subarray(offset, offset + 512);
+        offset += 512;
+        if (header.every((byte) => byte === 0))
+            break;
+        const size = octal(header.subarray(124, 136));
+        const type = header[156];
+        let name = readString(header.subarray(0, 100));
+        const prefix = readString(header.subarray(345, 500));
+        if (prefix)
+            name = `${prefix}/${name}`;
+        const body = archive.subarray(offset, offset + size);
+        offset += Math.ceil(size / 512) * 512;
+        if (type === 120) {
+            for (const record of decode(body).split("\n")) {
+                const equals = record.indexOf("=");
+                if (equals > 0) {
+                    const key = record.slice(record.indexOf(" ") + 1, equals);
+                    if (key === "path")
+                        paxPath = record.slice(equals + 1);
+                }
+            }
+            continue;
+        }
+        name = normalTarPath(paxPath ?? name);
+        paxPath = undefined;
+        if (!name || type === 53 || type === 1 || type === 2 || name.endsWith("/"))
+            continue;
+        if (type === 0 || type === 48 || type === undefined)
+            files.set(name, body.slice());
+    }
+    return files;
+}
+async function gunzip(bytes) {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    const stream = new Blob([copy.buffer]).stream().pipeThrough(new DecompressionStream("gzip"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+async function integrity(bytes) {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    const digest = await globalThis.crypto.subtle.digest("SHA-512", copy.buffer);
+    let binary = "";
+    for (const byte of new Uint8Array(digest))
+        binary += String.fromCharCode(byte);
+    return `sha512-${btoa(binary)}`;
+}
+export async function installForBrowser(options) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxPackages = options.maxPackages ?? DEFAULT_MAX_PACKAGES;
+    const lock = parseLockfile(options.lockfile);
+    const registry = (options.registry ?? "https://registry.npmjs.org").replace(/\/$/, "");
+    const packages = new Map();
+    const versions = new Map();
+    const records = new Map();
+    let bytes = 0;
+    const addBytes = (count) => {
+        bytes += count;
+        if (bytes > maxBytes)
+            throw new BrowserSizeLimitError(maxBytes, bytes);
+    };
+    // One registry request per package name, however many dependents ask for it.
+    const packuments = new Map();
+    const packumentFor = (name, range) => {
+        let pending = packuments.get(name);
+        if (!pending) {
+            pending = options
+                .fetch(`${registry}/${name}`, {
+                headers: { Accept: "application/vnd.npm.install-v1+json" },
+            })
+                .then((response) => {
+                if (!response.ok)
+                    throw new BrowserResolutionError(name, range);
+                return response.json();
+            });
+            packuments.set(name, pending);
+        }
+        return pending;
+    };
+    async function install(name, range, parentPath) {
+        if (supplied(name))
+            return;
+        const packument = (await packumentFor(name, range));
+        // The nearest existing copy is the one the importer will load, so it alone
+        // decides: reuse it when it satisfies, otherwise nest a copy under the parent.
+        // A farther matching copy must not count; it would be shadowed at runtime.
+        const candidates = ancestorCandidates(parentPath, name);
+        const shadow = candidates.find((candidate) => records.has(candidate));
+        if (shadow) {
+            const record = records.get(shadow);
+            if (satisfies(record.version, range)) {
+                if (!record.active)
+                    await record.promise;
+                return;
+            }
+        }
+        // Nothing is loaded yet, so follow the layout npm resolved for this
+        // extension. The nearest locked copy that satisfies the range is where Node
+        // would find it, including a nested copy when the root holds another major.
+        let path = shadow
+            ? undefined
+            : candidates.find((candidate) => {
+                const version = lockedVersion(lock, candidate);
+                return version !== undefined && satisfies(version, range) && !records.has(candidate);
+            });
+        if (!path) {
+            if (shadow) {
+                // A shadowing copy forces nesting below the importer; a top-level
+                // duplicate range conflict nests below the root copy itself.
+                path = `${parentPath ?? packagePath(name)}/node_modules/${name}`;
+            }
+            else if (parentPath === undefined) {
+                path = packagePath(name);
+            }
+            else {
+                const root = packagePath(name);
+                const rootVersion = lockedVersion(lock, root);
+                // The lockfile's root version is the copy npm hoisted for this importer;
+                // when it does not satisfy the range, nest instead of overwriting it.
+                path =
+                    rootVersion !== undefined && !satisfies(rootVersion, range)
+                        ? `${parentPath}/node_modules/${name}`
+                        : root;
+            }
+        }
+        while (records.has(path)) {
+            const record = records.get(path);
+            if (satisfies(record.version, range)) {
+                if (!record.active)
+                    await record.promise;
+                return;
+            }
+            path = `${path}/node_modules/${name}`;
+        }
+        const locked = lockedVersion(lock, path) ??
+            (path === packagePath(name) ? legacyLockVersion(lock, name) : undefined);
+        const version = locked !== undefined && satisfies(locked, range)
+            ? locked
+            : maxSatisfying(Object.keys(packument.versions ?? {}), range);
+        if (!version || !satisfies(version, range))
+            throw new BrowserResolutionError(name, range);
+        const metadata = packument.versions?.[version];
+        const tarball = metadata?.dist?.tarball;
+        if (!metadata || !tarball)
+            throw new BrowserResolutionError(name, range);
+        if (records.size >= maxPackages)
+            throw new BrowserPackageLimitError(maxPackages);
+        let finish;
+        let fail;
+        const promise = new Promise((resolve, reject) => {
+            finish = resolve;
+            fail = reject;
+        });
+        const record = { name, version, promise, active: true };
+        records.set(path, record);
+        const task = (async () => {
+            try {
+                const archiveResponse = await options.fetch(tarball);
+                if (!archiveResponse.ok)
+                    throw new BrowserResolutionError(name, version);
+                const archive = new Uint8Array(await archiveResponse.arrayBuffer());
+                addBytes(archive.byteLength);
+                const actual = await integrity(archive);
+                const expected = metadata.dist?.integrity;
+                const expectedSha512 = expected?.split(/\s+/).find((entry) => entry.startsWith("sha512-"));
+                if (expectedSha512 && expectedSha512 !== actual)
+                    throw new BrowserIntegrityError(name, expectedSha512, actual);
+                const files = unpackTar(await gunzip(archive));
+                if ([...files.keys()].some((file) => file.endsWith(".node") || file === "binding.gyp" || file.endsWith("/binding.gyp")))
+                    throw new BrowserNativePackageError(name);
+                for (const [file, content] of files) {
+                    const clean = file.replace(/^package\/?/, "");
+                    if (clean)
+                        packages.set(`${path}/${clean}`, content);
+                }
+                if (!packages.has(`${path}/package.json`))
+                    packages.set(`${path}/package.json`, JSON.stringify({ name, version }));
+                if (!versions.has(name) || path === packagePath(name))
+                    versions.set(name, version);
+                const optionalPeers = new Set(Object.entries(metadata.peerDependenciesMeta ?? {})
+                    .filter(([, value]) => value?.optional === true)
+                    .map(([dependency]) => dependency));
+                const dependencies = Object.fromEntries(Object.entries({ ...metadata.dependencies, ...metadata.peerDependencies }).filter(([dependency]) => !optionalPeers.has(dependency)));
+                await Promise.all(Object.entries(dependencies).map(([dependency, dependencyRange]) => install(dependency, dependencyRange, path)));
+                record.active = false;
+                finish();
+            }
+            catch (error) {
+                record.active = false;
+                fail(error);
+            }
+        })();
+        // Keep the promise exposed by the record independent of the async executor's return value.
+        void task;
+        return promise;
+    }
+    await Promise.all(Object.entries(options.manifest.dependencies ?? {}).map(([name, range]) => install(name, range)));
+    return { packages, versions, bytes };
+}

package/dist/bundle-config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Browser bundling configuration shared by the prebuild and the in-browser
+ * path. Both must resolve the same runtime modules to the same in-memory
+ * files; keeping one list means a prebuilt bundle and a bundle the browser
+ * builds on demand cannot disagree about what is external.
+ */
+/** Runtime modules supplied once and shared by every prebuilt command bundle. */
+export declare const sharedModules: string[];
+/** In-memory paths for the same runtime modules. */
+export declare const aliases: Record<string, string>;

package/dist/bundle-config.js

@@ -0,0 +1,31 @@
+/**
+ * Browser bundling configuration shared by the prebuild and the in-browser
+ * path. Both must resolve the same runtime modules to the same in-memory
+ * files; keeping one list means a prebuilt bundle and a bundle the browser
+ * builds on demand cannot disagree about what is external.
+ */
+/** Runtime modules supplied once and shared by every prebuilt command bundle. */
+export const sharedModules = [
+    "react",
+    "react/jsx-runtime",
+    "react/jsx-dev-runtime",
+    "@raycast/api",
+    "react-reconciler",
+    "scheduler",
+    "@blastlauncher/protocol",
+];
+/** In-memory paths for the same runtime modules. */
+export const aliases = {
+    "@raycast/api": "/packages/runtime/src/api/index.ts",
+    "@blastlauncher/protocol": "/packages/protocol/src/index.ts",
+    react: "/node_modules/react/index.js",
+    "react/jsx-runtime": "/node_modules/react/jsx-runtime.js",
+    "react/jsx-dev-runtime": "/node_modules/react/jsx-dev-runtime.js",
+    "react-reconciler": "/node_modules/react-reconciler/index.js",
+    "react-reconciler/constants.js": "/node_modules/react-reconciler/constants.js",
+    scheduler: "/node_modules/scheduler/index.js",
+    "stream/promises": "/packages/web/sandbox/stream-promises.ts",
+    "node:stream/promises": "/packages/web/sandbox/stream-promises.ts",
+    "util/types": "/packages/web/sandbox/util-types.ts",
+    "node:util/types": "/packages/web/sandbox/util-types.ts",
+};

package/dist/bundles.d.ts

@@ -0,0 +1,29 @@
+import { type Preference } from "@blastlauncher/protocol/preference-fields";
+import type { CommandMode } from "@blastlauncher/protocol";
+export type CatalogArgument = {
+    name: string;
+    required: boolean;
+};
+export type CatalogManifest = {
+    name: string;
+    preferences: Preference[];
+    commands: Record<string, Preference[]>;
+    arguments?: Record<string, CatalogArgument[]>;
+    modes?: Record<string, CommandMode>;
+};
+export type CatalogBundle = {
+    path: string;
+    bytes: number;
+    sha256: string;
+    files?: Record<string, CatalogBundle>;
+    manifest?: CatalogManifest;
+};
+export type BundleIndex = {
+    buildSha: string;
+    bundles: Record<string, CatalogBundle>;
+    runtime?: CatalogBundle;
+};
+export declare function bundleKey(extension: string, command: string): string;
+export declare function parseBundleIndex(value: unknown): BundleIndex;
+export declare function sha256Hex(value: ArrayBuffer): Promise<string>;
+export declare function bundleMatches(index: BundleIndex | undefined, buildSha: string | undefined, key: string, bytes: ArrayBuffer): Promise<boolean>;

package/dist/bundles.js

@@ -0,0 +1,126 @@
+import { parsePreferences } from "@blastlauncher/protocol/preference-fields";
+export function bundleKey(extension, command) {
+    return `${extension}/${command}`;
+}
+export function parseBundleIndex(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Invalid browser bundle index");
+    const input = value;
+    if (typeof input.buildSha !== "string" || !input.bundles || typeof input.bundles !== "object")
+        throw new Error("Invalid browser bundle index shape");
+    const runtimeValue = input.runtime;
+    let runtime;
+    if (runtimeValue !== undefined) {
+        if (!runtimeValue || typeof runtimeValue !== "object")
+            throw new Error("Invalid runtime bundle");
+        const item = runtimeValue;
+        if (item.path !== "bundles/runtime.js" ||
+            typeof item.bytes !== "number" ||
+            !Number.isInteger(item.bytes) ||
+            typeof item.sha256 !== "string" ||
+            !/^[0-9a-f]{64}$/.test(item.sha256))
+            throw new Error("Invalid runtime bundle");
+        runtime = { path: item.path, bytes: item.bytes, sha256: item.sha256 };
+    }
+    const bundles = {};
+    for (const [key, entryValue] of Object.entries(input.bundles)) {
+        if (!entryValue || typeof entryValue !== "object")
+            throw new Error(`Invalid bundle entry: ${key}`);
+        const item = entryValue;
+        if (typeof item.path !== "string" ||
+            !/^bundles\/[^/]+\/[^/]+\.js$/.test(item.path) ||
+            typeof item.bytes !== "number" ||
+            !Number.isInteger(item.bytes) ||
+            item.bytes < 0 ||
+            typeof item.sha256 !== "string" ||
+            !/^[0-9a-f]{64}$/.test(item.sha256))
+            throw new Error(`Invalid bundle entry shape: ${key}`);
+        const files = {};
+        if (item.files !== undefined) {
+            if (!item.files || typeof item.files !== "object")
+                throw new Error(`Invalid bundle files: ${key}`);
+            for (const [name, fileValue] of Object.entries(item.files)) {
+                if (!fileValue || typeof fileValue !== "object")
+                    throw new Error(`Invalid bundle file: ${key}/${name}`);
+                const file = fileValue;
+                if (typeof file.path !== "string" ||
+                    !file.path.startsWith("bundles/") ||
+                    typeof file.bytes !== "number" ||
+                    !Number.isInteger(file.bytes) ||
+                    file.bytes < 0 ||
+                    typeof file.sha256 !== "string" ||
+                    !/^[0-9a-f]{64}$/.test(file.sha256))
+                    throw new Error(`Invalid bundle file shape: ${key}/${name}`);
+                files[name] = { path: file.path, bytes: file.bytes, sha256: file.sha256 };
+            }
+        }
+        let manifest;
+        if (item.manifest !== undefined) {
+            if (!item.manifest || typeof item.manifest !== "object")
+                throw new Error(`Invalid bundle manifest: ${key}`);
+            const declared = item.manifest;
+            if (typeof declared.name !== "string" ||
+                !declared.commands ||
+                typeof declared.commands !== "object")
+                throw new Error(`Invalid bundle manifest shape: ${key}`);
+            const commands = {};
+            const modes = {};
+            const declaredModes = declared.modes;
+            if (declaredModes !== undefined && (!declaredModes || typeof declaredModes !== "object"))
+                throw new Error(`Invalid bundle manifest modes: ${key}`);
+            for (const [name, mode] of Object.entries((declaredModes ?? {}))) {
+                if (mode !== "view" &&
+                    mode !== "no-view" &&
+                    mode !== "menu-bar" &&
+                    mode !== "model-provider")
+                    throw new Error(`Invalid bundle manifest mode: ${key}/${name}`);
+                modes[name] = mode;
+            }
+            for (const [name, preferences] of Object.entries(declared.commands))
+                commands[name] = parsePreferences(preferences, `Bundle ${key} command ${name} preferences`);
+            for (const name of Object.keys(commands))
+                modes[name] ??= "view";
+            const argumentsByCommand = {};
+            const declaredArguments = declared.arguments;
+            if (declaredArguments !== undefined &&
+                (!declaredArguments || typeof declaredArguments !== "object"))
+                throw new Error(`Invalid bundle manifest arguments: ${key}`);
+            for (const [name, argumentsFor] of Object.entries((declaredArguments ?? {}))) {
+                if (!Array.isArray(argumentsFor))
+                    throw new Error(`Invalid bundle manifest arguments: ${key}/${name}`);
+                argumentsByCommand[name] = argumentsFor.map((argument) => {
+                    const entry = argument;
+                    if (!entry || typeof entry.name !== "string" || typeof entry.required !== "boolean")
+                        throw new Error(`Invalid bundle manifest argument: ${key}/${name}`);
+                    return { name: entry.name, required: entry.required };
+                });
+            }
+            manifest = {
+                name: declared.name,
+                preferences: parsePreferences(declared.preferences, `Bundle ${key} preferences`),
+                commands,
+                ...(Object.keys(argumentsByCommand).length ? { arguments: argumentsByCommand } : {}),
+                ...(Object.keys(modes).length ? { modes } : {}),
+            };
+        }
+        bundles[key] = {
+            path: item.path,
+            bytes: item.bytes,
+            sha256: item.sha256,
+            ...(Object.keys(files).length ? { files } : {}),
+            ...(manifest ? { manifest } : {}),
+        };
+    }
+    return { buildSha: input.buildSha, bundles, ...(runtime ? { runtime } : {}) };
+}
+export async function sha256Hex(value) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", value);
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export async function bundleMatches(index, buildSha, key, bytes) {
+    const entry = index?.bundles[key];
+    return Boolean(entry &&
+        buildSha === index?.buildSha &&
+        entry.bytes === bytes.byteLength &&
+        (await sha256Hex(bytes)) === entry.sha256);
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,66 @@
+/** The slice of the host catalog the capability handlers consult. */
+export type CapabilityCatalog = {
+    extensions: {
+        name: string;
+        commands: {
+            name: string;
+        }[];
+    }[];
+};
+export type BrowserStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    key(index: number): string | null;
+    readonly length: number;
+};
+export type ClipboardBridge = {
+    readText?: () => Promise<string>;
+    writeText?: (text: string) => Promise<void>;
+};
+export type CapabilityRequest = {
+    name: string;
+    params: unknown;
+};
+export type CapabilityResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: {
+        code: "DENIED";
+        message: string;
+    };
+};
+export type CapabilityContext = {
+    extensionName: string;
+    commandName: string;
+    source: string;
+};
+export type BrowserCapabilityOptions = {
+    catalog: CapabilityCatalog;
+    storage?: BrowserStorage;
+    clipboard?: ClipboardBridge;
+    openUrl?: (url: string) => void;
+    launchCommand?: (source: string, command: string) => Promise<void>;
+    status?: (message: string, error?: boolean) => void;
+    openPreferences?: (scope: "extension" | "command", context: CapabilityContext) => void;
+};
+export type BrowserPreferences = {
+    extension: Record<string, JsonValue>;
+    commands: Record<string, Record<string, JsonValue>>;
+};
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function createBrowserPreferenceStore(extension: string, storage?: BrowserStorage): {
+    read: () => BrowserPreferences;
+    save: (next: BrowserPreferences) => void;
+    values(command: string): {
+        [x: string]: JsonValue;
+    };
+    update(extensionValues: Record<string, JsonValue>, command: string, commandValues: Record<string, JsonValue>): void;
+};
+/** Browser-backed capability handlers. All browser effects are injected for unit tests. */
+export declare function createBrowserCapabilities(options: BrowserCapabilityOptions): (request: CapabilityRequest, context: CapabilityContext) => Promise<CapabilityResult>;
+export {};