@blastlauncher/runtime 1.0.5 → 3.0.0-alpha.1

package/dist/api/applications.js

@@ -0,0 +1,48 @@
+import { requestCapability } from "./capability.js";
+/** Fields other than the required `name` and `path`. */
+const OPTIONAL_FIELDS = ["localizedName", "bundleId", "windowsAppId"];
+export function pathParam(path, api) {
+    if (typeof path !== "string" && !(path instanceof URL) && !Buffer.isBuffer(path)) {
+        throw new TypeError(`${api}: path must be a string, Buffer or URL`);
+    }
+    const value = String(path);
+    if (value === "")
+        throw new TypeError(`${api}: path must not be empty`);
+    return value;
+}
+// The host is another process: rebuild each application from the declared
+// fields rather than trusting whatever shape arrived on the wire.
+export function toApplication(value, api = "getApplications") {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        typeof value.name !== "string" ||
+        typeof value.path !== "string") {
+        throw new TypeError(`${api}: the host returned an invalid Application`);
+    }
+    const application = { name: value.name, path: value.path };
+    for (const field of OPTIONAL_FIELDS) {
+        const fieldValue = value[field];
+        if (typeof fieldValue === "string")
+            application[field] = fieldValue;
+    }
+    return application;
+}
+export async function getApplications(path) {
+    const params = path === undefined ? {} : { path: pathParam(path, "getApplications") };
+    const value = await requestCapability("applications.list", params);
+    if (!Array.isArray(value)) {
+        throw new TypeError("getApplications: the host returned a non-array");
+    }
+    return value.map((item) => toApplication(item));
+}
+/**
+ * `getDefaultApplication(path)`: the application the machine would open the
+ * path with. Rejects when there is none, exactly as the declarations promise
+ * and as a headless host without an application database always does.
+ */
+export async function getDefaultApplication(path) {
+    return toApplication(await requestCapability("applications.default", {
+        path: pathParam(path, "getDefaultApplication"),
+    }), "getDefaultApplication");
+}

package/dist/api/cache.d.ts

@@ -0,0 +1,27 @@
+export type CacheOptions = {
+    namespace?: string;
+    directory?: string;
+    capacity?: number;
+};
+export type CacheSubscriber = (key: string | undefined, data: string | undefined) => void;
+export type CacheSubscription = () => void;
+export declare class Cache {
+    static get STORAGE_DIRECTORY_NAME(): string;
+    static get DEFAULT_CAPACITY(): number;
+    private directory;
+    private capacity;
+    constructor(options?: CacheOptions);
+    get storageDirectory(): string;
+    private read;
+    private write;
+    private notify;
+    get(key: string): string | undefined;
+    has(key: string): boolean;
+    get isEmpty(): boolean;
+    set(key: string, data: string): void;
+    remove(key: string): boolean;
+    clear(options?: {
+        notifySubscribers: boolean;
+    }): void;
+    subscribe: (subscriber: CacheSubscriber) => CacheSubscription;
+}

package/dist/api/cache.js

@@ -0,0 +1,126 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { environment } from "./environment.js";
+const subscribers = new Map();
+let writes = 0;
+// Namespaces are single segments even when supplied by an extension.
+function segment(value) {
+    return encodeURIComponent(value).replaceAll(".", "%2E");
+}
+export class Cache {
+    static get STORAGE_DIRECTORY_NAME() {
+        return "cache";
+    }
+    static get DEFAULT_CAPACITY() {
+        // Cache.Options.capacity in the public declarations specifies 10 MB.
+        return 10 * 1024 * 1024;
+    }
+    directory;
+    capacity;
+    constructor(options = {}) {
+        const parent = options.directory ?? environment.supportPath;
+        if (!parent)
+            throw new Error("Cache requires an assigned support directory");
+        this.capacity = options.capacity ?? Cache.DEFAULT_CAPACITY;
+        if (!Number.isFinite(this.capacity) || this.capacity < 0)
+            throw new Error("Cache capacity must be a finite non-negative number");
+        this.directory = resolve(parent, Cache.STORAGE_DIRECTORY_NAME);
+        if (options.namespace)
+            this.directory = join(this.directory, segment(options.namespace));
+        mkdirSync(this.directory, { recursive: true });
+    }
+    get storageDirectory() {
+        return this.directory;
+    }
+    read() {
+        let text;
+        try {
+            text = readFileSync(join(this.directory, "entries.json"), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return new Map();
+            throw error;
+        }
+        const entries = JSON.parse(text);
+        if (!Array.isArray(entries) ||
+            !entries.every((entry) => Array.isArray(entry) &&
+                entry.length === 2 &&
+                entry.every((value) => typeof value === "string")))
+            throw new Error("Invalid Cache entries");
+        return new Map(entries);
+    }
+    write(entries) {
+        const file = join(this.directory, "entries.json");
+        const temporary = `${file}.${process.pid}-${++writes}.tmp`;
+        try {
+            writeFileSync(temporary, JSON.stringify([...entries]), "utf8");
+            renameSync(temporary, file);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    }
+    notify(key, data) {
+        // Callbacks may subscribe or unsubscribe while notifications are delivered.
+        const snapshot = [...(subscribers.get(this.directory) ?? [])];
+        for (const subscriber of snapshot)
+            subscriber(key, data);
+    }
+    get(key) {
+        const entries = this.read();
+        const data = entries.get(key);
+        if (data !== undefined) {
+            entries.delete(key);
+            entries.set(key, data);
+            this.write(entries);
+        }
+        return data;
+    }
+    has(key) {
+        return this.read().has(key);
+    }
+    get isEmpty() {
+        return this.read().size === 0;
+    }
+    set(key, data) {
+        if (typeof key !== "string" || typeof data !== "string")
+            throw new Error("Cache keys and data must be strings");
+        const entries = this.read();
+        entries.delete(key);
+        entries.set(key, data);
+        let bytes = [...entries.values()].reduce((sum, value) => sum + Buffer.byteLength(value), 0);
+        for (const [oldKey, value] of entries) {
+            if (bytes <= this.capacity)
+                break;
+            entries.delete(oldKey);
+            bytes -= Buffer.byteLength(value);
+        }
+        this.write(entries);
+        this.notify(key, data);
+    }
+    remove(key) {
+        const entries = this.read();
+        const removed = entries.delete(key);
+        if (removed)
+            this.write(entries);
+        this.notify(key);
+        return removed;
+    }
+    clear(options) {
+        this.write(new Map());
+        if (options?.notifySubscribers !== false)
+            this.notify();
+    }
+    subscribe = (subscriber) => {
+        let listeners = subscribers.get(this.directory);
+        if (!listeners)
+            subscribers.set(this.directory, (listeners = new Set()));
+        listeners.add(subscriber);
+        return () => {
+            listeners.delete(subscriber);
+            if (!listeners.size)
+                subscribers.delete(this.directory);
+        };
+    };
+}

package/dist/api/capability.d.ts

@@ -0,0 +1,14 @@
+import type { JsonValue } from "../reconciler/index.js";
+/**
+ * Bridge used by privileged APIs to ask the host for a capability, e.g.
+ * `("clipboard.copy", { text })`. Installed by the runtime entry, never by
+ * extension code.
+ */
+export type CapabilityOptions = {
+    signal?: AbortSignal;
+    onProgress?: (value: JsonValue) => void;
+};
+export type CapabilityRequester = (name: string, params: Record<string, JsonValue>, options?: CapabilityOptions) => Promise<JsonValue>;
+/** Installs (or, with `undefined`, removes) the host bridge for privileged APIs. */
+export declare function setCapabilityRequester(next: CapabilityRequester | undefined): void;
+export declare function requestCapability(name: string, params: Record<string, JsonValue>, options?: CapabilityOptions): Promise<JsonValue>;

package/dist/api/capability.js

@@ -0,0 +1,30 @@
+let requester;
+/** Installs (or, with `undefined`, removes) the host bridge for privileged APIs. */
+export function setCapabilityRequester(next) {
+    requester = next;
+}
+export function requestCapability(name, params, options) {
+    if (options?.signal?.aborted)
+        return Promise.reject(new DOMException("The operation was aborted", "AbortError"));
+    if (!requester) {
+        return Promise.reject(new Error(`Cannot request capability '${name}': no capability requester is installed. ` +
+            "Call setCapabilityRequester() before using privileged APIs."));
+    }
+    const signal = options?.signal;
+    if (!signal)
+        return requester(name, params, options);
+    const dispatch = requester;
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(new DOMException("The operation was aborted", "AbortError"));
+        signal.addEventListener("abort", abort, { once: true });
+        try {
+            void dispatch(name, params, options)
+                .then(resolve, reject)
+                .finally(() => signal.removeEventListener("abort", abort));
+        }
+        catch (error) {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        }
+    });
+}

package/dist/api/clipboard.d.ts

@@ -0,0 +1,57 @@
+import type { JsonValue } from "../reconciler/index.js";
+import { type ApplicationPath } from "./applications.js";
+/** `Clipboard.Content`: the text, file and HTML forms the declarations define. */
+export type ClipboardContent = {
+    text: string;
+} | {
+    file: ApplicationPath;
+} | {
+    html: string;
+    text?: string;
+};
+/** `Clipboard.CopyOptions`. */
+export interface CopyOptions {
+    /** @deprecated Use `concealed` instead. */
+    transient?: boolean;
+    /** Indicates whether the content should be treated as confidential. */
+    concealed?: boolean;
+}
+/** `Clipboard.PasteOptions`. */
+export interface PasteOptions {
+    /** Whether the host should close its main window after pasting. */
+    closeMainWindow?: boolean;
+}
+/** Options shared by `Clipboard.read` and `Clipboard.readText`. */
+export interface ReadOptions {
+    /** Reaches back through the clipboard history; 0 is the current content. */
+    offset?: number;
+}
+/** `Clipboard.ReadContent`. */
+export interface ReadContent {
+    /** The text representation of the content. */
+    text: string;
+    /** The file representation of the content. */
+    file?: string;
+    /** The HTML representation of the content. */
+    html?: string;
+}
+/**
+ * `Clipboard.Content` as capability params: exactly one representation per
+ * request, so a client can tell a file copy from an HTML copy. `concealed` is
+ * a host-side concern (history elision) and travels alongside, never inside.
+ */
+export declare function contentParams(content: string | number | ClipboardContent, api: string): Record<string, JsonValue>;
+export declare function copy(content: string | number | ClipboardContent, options?: CopyOptions): Promise<void>;
+export declare function clear(): Promise<void>;
+export declare function paste(content: string | number | ClipboardContent, options?: PasteOptions): Promise<void>;
+/** Reads the clipboard at `offset`; the host answers with whatever it has. */
+export declare function read(options?: ReadOptions): Promise<ReadContent>;
+export declare function readText(options?: ReadOptions): Promise<string | undefined>;
+/** Members in the order the declarations list them. */
+export declare const Clipboard: {
+    copy: typeof copy;
+    clear: typeof clear;
+    paste: typeof paste;
+    read: typeof read;
+    readText: typeof readText;
+};

package/dist/api/clipboard.js

@@ -0,0 +1,83 @@
+import { pathParam } from "./applications.js";
+import { requestCapability } from "./capability.js";
+/** The offsets the declarations allow into the clipboard history. */
+const MAX_OFFSET = 5;
+/**
+ * `Clipboard.Content` as capability params: exactly one representation per
+ * request, so a client can tell a file copy from an HTML copy. `concealed` is
+ * a host-side concern (history elision) and travels alongside, never inside.
+ */
+export function contentParams(content, api) {
+    if (typeof content === "string")
+        return { text: content };
+    if (typeof content === "number")
+        return { text: String(content) };
+    if (typeof content === "object" && content !== null && !Array.isArray(content)) {
+        if ("file" in content &&
+            (typeof content.file === "string" ||
+                Buffer.isBuffer(content.file) ||
+                content.file instanceof URL))
+            return { file: pathParam(content.file, api) };
+        if ("html" in content && typeof content.html === "string") {
+            if (content.text === undefined)
+                return { html: content.html };
+            if (typeof content.text === "string")
+                return { html: content.html, text: content.text };
+        }
+        else if ("text" in content && typeof content.text === "string")
+            return { text: content.text };
+    }
+    throw new TypeError(`${api}: unsupported content in Blast`);
+}
+export async function copy(content, options) {
+    const params = contentParams(content, "Clipboard.copy");
+    // Only a set flag crosses the wire: absent stays absent, like every prop.
+    if (options?.concealed !== undefined)
+        params["concealed"] = options.concealed;
+    // `transient` is the deprecated name of `concealed`; hosts that still know the
+    // old flag receive it as authored rather than silently dropped.
+    if (options?.transient !== undefined)
+        params["transient"] = options.transient;
+    await requestCapability("clipboard.copy", params);
+}
+export async function clear() {
+    await requestCapability("clipboard.clear", {});
+}
+export async function paste(content, options) {
+    const params = contentParams(content, "Clipboard.paste");
+    // Raycast closes its main window by default; preserve an explicit false and
+    // make the default visible to hosts so every embedder can apply the policy.
+    params.closeMainWindow = options?.closeMainWindow ?? true;
+    await requestCapability("clipboard.paste", params);
+}
+function readParams(options, api) {
+    const offset = options?.offset;
+    if (offset === undefined)
+        return {};
+    if (!Number.isInteger(offset) || offset < 0 || offset > MAX_OFFSET) {
+        throw new TypeError(`${api}: offset must be an integer between 0 and ${MAX_OFFSET}`);
+    }
+    return { offset };
+}
+/** Reads the clipboard at `offset`; the host answers with whatever it has. */
+export async function read(options) {
+    const value = await requestCapability("clipboard.read", readParams(options, "Clipboard.read"));
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("Clipboard.read: the host returned a non-object clipboard content");
+    }
+    // The declarations make `text` required, so a host without text answers empty.
+    const content = { text: typeof value.text === "string" ? value.text : "" };
+    if (typeof value.file === "string")
+        content.file = value.file;
+    if (typeof value.html === "string")
+        content.html = value.html;
+    return content;
+}
+export async function readText(options) {
+    const { text } = await read(options);
+    // The wire cannot tell "no text" apart from an empty string; Raycast reports
+    // the former as undefined, so an empty text maps to that.
+    return text === "" ? undefined : text;
+}
+/** Members in the order the declarations list them. */
+export const Clipboard = { copy, clear, paste, read, readText };

package/dist/api/detail.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode } from "react";
+export interface DetailProps {
+    markdown?: string | null;
+    /** A `Detail.Metadata`; rendered as a `Slot` child named `metadata`. */
+    metadata?: ReactNode;
+    /** An ActionPanel; rendered as a `Slot` child named `actions`. */
+    actions?: ReactNode;
+    navigationTitle?: string;
+    isLoading?: boolean;
+}
+export interface ListItemDetailProps {
+    /** Indicates whether a loading bar should be shown above the detail. */
+    isLoading?: boolean;
+    /** The CommonMark string rendered when the parent item is selected. */
+    markdown?: string | null;
+    /** A `List.Item.Detail.Metadata`; rendered as a `Slot` child named `metadata`. */
+    metadata?: ReactNode;
+}
+export declare const Detail: ((props: DetailProps) => import("react").ReactElement<{
+    markdown?: string | null;
+    navigationTitle?: string;
+    isLoading?: boolean;
+}, string | import("react").JSXElementConstructor<any>>) & {
+    Metadata: import("./metadata.js").MetadataComponents;
+};
+export declare const ListItemDetail: ((props: ListItemDetailProps) => import("react").ReactElement<{
+    /** Indicates whether a loading bar should be shown above the detail. */
+    isLoading?: boolean;
+    /** The CommonMark string rendered when the parent item is selected. */
+    markdown?: string | null;
+}, string | import("react").JSXElementConstructor<any>>) & {
+    Metadata: import("./metadata.js").MetadataComponents;
+};

package/dist/api/detail.js

@@ -0,0 +1,11 @@
+import { createElement } from "react";
+import { createMetadata } from "./metadata.js";
+import { slot } from "./slot.js";
+export const Detail = Object.assign(function Detail(props) {
+    const { actions, metadata, ...rest } = props;
+    return createElement("Detail", rest, slot("actions", actions), slot("metadata", metadata));
+}, { Metadata: createMetadata("Detail") });
+export const ListItemDetail = Object.assign(function ListItemDetail(props) {
+    const { metadata, ...rest } = props;
+    return createElement("List.Item.Detail", rest, slot("metadata", metadata));
+}, { Metadata: createMetadata("List.Item.Detail") });

package/dist/api/diagnostics.d.ts

@@ -0,0 +1,16 @@
+/** The log levels the protocol's `log` message carries. */
+export type RuntimeLogLevel = "debug" | "info" | "warn" | "error";
+export type RuntimeLogSink = (level: RuntimeLogLevel, message: string) => void;
+/** Installs (or, with `undefined`, removes) the runtime log sink. */
+export declare function setRuntimeLogSink(next: RuntimeLogSink | undefined): void;
+/**
+ * Reports an exception. Without a sink (a bare module import in a test) this is
+ * a no-op: reporting must never be the reason a command fails.
+ */
+export declare function captureException(exception: unknown): void;
+/**
+ * Records heap statistics with a label. Raycast only records when memory
+ * reporting is enabled, so this stays at `debug` level: a client decides what
+ * to keep, and nothing is returned to the extension.
+ */
+export declare function captureMemorySnapshot(label: string): void;

package/dist/api/diagnostics.js

@@ -0,0 +1,26 @@
+// `captureException` and `captureMemorySnapshot` from the declarations. Raycast
+// reports both to the Developer Hub; Blast has no network and writes to the
+// runtime's log channel instead, which the host already collects per session.
+// The sink is installed by the runtime entry, never by extension code.
+import { format } from "node:util";
+let sink;
+/** Installs (or, with `undefined`, removes) the runtime log sink. */
+export function setRuntimeLogSink(next) {
+    sink = next;
+}
+/**
+ * Reports an exception. Without a sink (a bare module import in a test) this is
+ * a no-op: reporting must never be the reason a command fails.
+ */
+export function captureException(exception) {
+    sink?.("error", `captureException: ${format(exception)}`);
+}
+/**
+ * Records heap statistics with a label. Raycast only records when memory
+ * reporting is enabled, so this stays at `debug` level: a client decides what
+ * to keep, and nothing is returned to the extension.
+ */
+export function captureMemorySnapshot(label) {
+    const { heapUsed, heapTotal } = process.memoryUsage();
+    sink?.("debug", `captureMemorySnapshot: ${label} heapUsed=${heapUsed} heapTotal=${heapTotal}`);
+}

package/dist/api/dropdown.d.ts

@@ -0,0 +1,17 @@
+import type { ListDropdownProps } from "./list.js";
+export declare function useDropdown(type: string, props: ListDropdownProps): import("react").ReactElement<{
+    children?: import("react").ReactNode;
+    id?: string;
+    tooltip: string;
+    placeholder?: string;
+    storeValue?: boolean;
+    defaultValue?: string;
+    filtering?: boolean | {
+        keepSectionOrder: boolean;
+    };
+    isLoading?: boolean;
+    throttle?: boolean;
+    onSearchTextChange?: (text: string) => void;
+    value: string | undefined;
+    onChange: ((value: string) => void | undefined) | undefined;
+}, string | import("react").JSXElementConstructor<any>>;

package/dist/api/dropdown.js

@@ -0,0 +1,48 @@
+import { Children, createElement, isValidElement, useEffect, useRef, useState } from "react";
+import { requestCapability } from "./capability.js";
+import { environment } from "./environment.js";
+// Search/filtering/throttle are client presentation requests, like List/Grid's.
+export function useDropdown(type, props) {
+    const [selection, setSelection] = useState(props.defaultValue);
+    const edited = useRef(false);
+    const callback = useRef(props.onChange);
+    callback.current = props.onChange;
+    const key = `blast:dropdown:${JSON.stringify([environment.commandName, type, props.id ?? "default"])}`;
+    useEffect(() => {
+        if (!props.storeValue || props.value !== undefined)
+            return;
+        let mounted = true;
+        void requestCapability("storage.get", { scope: "blast:internal", key })
+            .then((value) => {
+            if (!mounted || edited.current || typeof value !== "string")
+                return;
+            const contains = (children) => Children.toArray(children).some((child) => {
+                if (!isValidElement(child))
+                    return false;
+                return child.props.value === value || contains(child.props.children);
+            });
+            if (contains(props.children)) {
+                setSelection(value);
+                callback.current?.(value);
+            }
+        })
+            .catch((error) => console.error("Dropdown restore failed", error));
+        return () => {
+            mounted = false;
+        };
+    }, [key, props.storeValue, props.value]);
+    const onChange = (value) => {
+        edited.current = true;
+        if (props.value === undefined)
+            setSelection(value);
+        if (props.storeValue) {
+            void requestCapability("storage.set", { scope: "blast:internal", key, value }).catch((error) => console.error("Dropdown save failed", error));
+        }
+        return props.onChange?.(value);
+    };
+    return createElement(type, {
+        ...props,
+        value: props.value ?? selection,
+        onChange: props.onChange || props.value === undefined || props.storeValue ? onChange : undefined,
+    });
+}