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

package/dist/session.js

@@ -0,0 +1,256 @@
+import { createLineDecoder, encodeMessage, parseHostMessage, parseRuntimeMessage, PROTOCOL_VERSION, } from "@blastlauncher/protocol";
+import { spawn } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAIRouter } from "./ai.js";
+import { createStorage, defaultDataDir, storageFile } from "./storage.js";
+// Variables a Node program needs to behave normally. Everything else in the
+// host environment (tokens, credentials) is withheld from extension code.
+const INHERITED_ENV = ["PATH", "HOME", "USER", "LANG", "LC_ALL", "TZ", "TMPDIR", "TEMP", "TMP"];
+export function runtimeEnvironment(source = process.env) {
+    const env = {};
+    for (const name of INHERITED_ENV) {
+        const value = source[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return env;
+}
+/** Resolves after the version handshake. Startup failures reject only after child cleanup. */
+export async function startCommand(options) {
+    const ai = options.mode === "model-provider" ? undefined : createAIRouter(options);
+    const capabilities = new Map();
+    const entry = resolve(options.entry);
+    const supportPath = options.environment?.supportPath ??
+        join(resolve(options.dataDir ?? defaultDataDir()), "support", basename(storageFile("", options.extensionName), ".json").replace(/^\.{1,2}$/, (name) => name.replaceAll(".", "%2e")));
+    await mkdir(supportPath, { recursive: true });
+    // A stored Form draft is read before spawning, like preferences, so the
+    // command's first render already has `LaunchProps.draftValues` — the
+    // runtime never blocks its first scene on a capability round trip for it.
+    let draftValues;
+    if (options.mode === "view") {
+        const internal = createStorage({
+            extensionName: options.extensionName,
+            dataDir: join(options.dataDir ?? defaultDataDir(), "internal"),
+        });
+        const stored = await internal.get(`blast:draft:${options.commandName}`);
+        if (typeof stored === "string") {
+            try {
+                const parsed = JSON.parse(stored);
+                if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                    draftValues = parsed;
+                }
+            }
+            catch {
+                // A corrupt draft must not block the launch; it is best-effort recall.
+            }
+        }
+    }
+    const init = {
+        type: "init",
+        protocol: PROTOCOL_VERSION,
+        command: {
+            entry,
+            extension: options.extensionName,
+            name: options.commandName,
+            mode: options.mode,
+            ...(options.argumentValues === undefined ? {} : { arguments: options.argumentValues }),
+            ...(options.fallbackText === undefined ? {} : { fallbackText: options.fallbackText }),
+            ...(options.launchContext === undefined ? {} : { launchContext: options.launchContext }),
+            ...(draftValues === undefined ? {} : { draftValues }),
+        },
+        preferences: { ...options.preferenceDefaults, ...options.preferences },
+        environment: options.environment ?? {
+            extensionName: options.extensionName,
+            commandName: options.commandName,
+            ownerOrAuthorName: options.ownerOrAuthorName ?? "",
+            assetsPath: options.assetsPath ?? join(dirname(entry), "assets"),
+            supportPath,
+            isDevelopment: true,
+            // The client can supply its UI theme.
+            appearance: "dark",
+            textSize: "medium",
+            availableAPIs: options.availableAPIs ?? [],
+        },
+    };
+    const checked = parseHostMessage(init);
+    if (!checked.ok)
+        throw new Error(checked.error);
+    const child = spawn(options.nodePath ?? "node", [fileURLToPath(import.meta.resolve("@blastlauncher/runtime/main"))], { stdio: ["pipe", "pipe", "pipe"], env: options.env ?? runtimeEnvironment() });
+    let ready = false;
+    let closed = false;
+    let failure;
+    let stderr = "";
+    let latestScene;
+    const logs = [];
+    const maxLogs = options.maxLogs ?? 1000;
+    const logListeners = new Set();
+    function addLog(log) {
+        logs.push(log);
+        if (logs.length > maxLogs)
+            logs.splice(0, logs.length - maxLogs);
+        for (const listener of logListeners)
+            listener(log);
+    }
+    const listeners = new Set();
+    const timers = new Set();
+    let resolveExit;
+    const exited = new Promise((done) => {
+        resolveExit = done;
+    });
+    let resolveReady;
+    const handshake = new Promise((done) => {
+        resolveReady = done;
+    });
+    function fail(error) {
+        failure ??= error;
+        child.kill("SIGKILL");
+    }
+    function protocolError(message) {
+        fail(Object.assign(new Error(message), { code: "PROTOCOL_ERROR" }));
+    }
+    function send(message) {
+        if (closed || child.stdin.destroyed)
+            return;
+        const parsed = parseHostMessage(message);
+        if (!parsed.ok)
+            throw new Error(parsed.error);
+        child.stdin.write(encodeMessage(parsed.message));
+    }
+    const decoder = createLineDecoder({
+        onError: protocolError,
+        onLine(value) {
+            if (failure)
+                return;
+            const parsed = parseRuntimeMessage(value);
+            if (!parsed.ok)
+                return protocolError(parsed.error);
+            const message = parsed.message;
+            if (!ready) {
+                if (message.type === "error")
+                    return fail(Object.assign(new Error(message.message), { code: message.code }));
+                if (message.type !== "ready" || message.protocol !== PROTOCOL_VERSION)
+                    return protocolError("Expected matching ready handshake");
+                ready = true;
+                clearTimeout(handshakeTimer);
+                resolveReady();
+                return;
+            }
+            switch (message.type) {
+                case "provider.models":
+                case "provider.part":
+                case "provider.end":
+                case "provider.error":
+                    if (options.mode !== "model-provider")
+                        return protocolError("Provider response in command session");
+                    options.providerResponse?.(message);
+                    break;
+                case "ready":
+                    return protocolError("Duplicate ready handshake");
+                case "scene":
+                    latestScene = message;
+                    for (const listener of listeners)
+                        listener(message);
+                    break;
+                case "log":
+                    addLog(message);
+                    break;
+                case "error":
+                    addLog({ type: "log", level: "error", message: `${message.code}: ${message.message}` });
+                    if (message.fatal)
+                        failure ??= Object.assign(new Error(message.message), { code: message.code });
+                    break;
+                case "capability.cancel":
+                    capabilities.get(message.id)?.abort();
+                    break;
+                case "capability.request": {
+                    const controller = new AbortController();
+                    capabilities.set(message.id, controller);
+                    void (ai?.broker ?? options.broker)(message, {
+                        signal: controller.signal,
+                        progress: (chunk) => {
+                            if (!controller.signal.aborted)
+                                send({ type: "capability.progress", id: message.id, value: chunk });
+                        },
+                    })
+                        .then(send)
+                        .catch((error) => fail(error instanceof Error ? error : new Error(String(error))))
+                        .finally(() => capabilities.delete(message.id));
+                    break;
+                }
+            }
+        },
+    });
+    const handshakeTimer = setTimeout(() => fail(new Error("Runtime handshake timed out")), options.handshakeTimeoutMs ?? 5000);
+    child.stdout.on("data", (chunk) => decoder.push(chunk));
+    child.stdout.on("end", () => decoder.end());
+    child.stderr.setEncoding("utf8").on("data", (message) => {
+        stderr += message;
+        addLog({ type: "log", level: "error", message });
+    });
+    child.stdin.on("error", fail);
+    child.on("error", fail);
+    child.on("close", async (code, signal) => {
+        closed = true;
+        clearTimeout(handshakeTimer);
+        for (const timer of timers)
+            clearTimeout(timer);
+        listeners.clear();
+        for (const controller of capabilities.values())
+            controller.abort();
+        await ai?.shutdown();
+        const startupError = failure ??
+            (!ready && stderr.trim() !== ""
+                ? new Error(`Runtime exited before ready: ${stderr.trim().slice(-1000)}`)
+                : undefined);
+        resolveExit({ code, signal, ...(startupError ? { error: startupError } : {}) });
+    });
+    send(init);
+    await Promise.race([
+        handshake,
+        exited.then((exit) => {
+            throw exit.error ?? new Error("Runtime exited before ready");
+        }),
+    ]);
+    let shutdown;
+    return {
+        get latestScene() {
+            return latestScene;
+        },
+        get logs() {
+            return logs;
+        },
+        onLog(callback) {
+            logListeners.add(callback);
+            return () => {
+                logListeners.delete(callback);
+            };
+        },
+        scenes(callback) {
+            if (!closed)
+                listeners.add(callback);
+            if (latestScene)
+                callback(latestScene);
+            return () => {
+                listeners.delete(callback);
+            };
+        },
+        sendProvider: send,
+        sendEvent(node, handler, args) {
+            send({ type: "event", node, handler, args });
+        },
+        shutdown({ timeoutMs = 1000 } = {}) {
+            if (shutdown || closed)
+                return shutdown ?? exited;
+            send({ type: "shutdown" });
+            timers.add(setTimeout(() => {
+                child.kill("SIGTERM");
+                timers.add(setTimeout(() => child.kill("SIGKILL"), timeoutMs));
+            }, timeoutMs));
+            shutdown = exited;
+            return shutdown;
+        },
+        exited,
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,31 @@
+import type { CapabilityHandler } from "./broker.js";
+/** The types `LocalStorage.Value` allows. */
+export type StorageValue = string | number | boolean;
+export type StorageItems = Record<string, StorageValue>;
+export type StorageOptions = {
+    /** Owning extension; the host takes it from the session's manifest name. */
+    extensionName: string;
+    /** Root of Blast's data directory; defaults to {@link defaultDataDir}. */
+    dataDir?: string;
+};
+export type Storage = {
+    get(key: string): Promise<StorageValue | undefined>;
+    set(key: string, value: StorageValue): Promise<void>;
+    remove(key: string): Promise<void>;
+    all(): Promise<StorageItems>;
+    clear(): Promise<void>;
+};
+/** `$XDG_DATA_HOME/blast`, or `~/.local/share/blast` when unset or relative. */
+export declare function defaultDataDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * The storage file of one extension. Names are untrusted, so anything outside
+ * the safe set is percent-encoded: a scoped or hostile name stays one path
+ * segment inside the storage directory.
+ */
+export declare function storageFile(dataDir: string, extensionName: string): string;
+export declare function isStorageValue(value: unknown): value is StorageValue;
+/** One store per session; the file is read on every call so two sessions of the
+ * same extension see each other's writes. */
+export declare function createStorage(options: StorageOptions): Storage;
+/** The `storage.*` capability handlers for one session. */
+export declare function createStorageHandlers(options: StorageOptions): Record<string, CapabilityHandler>;

package/dist/storage.js

@@ -0,0 +1,154 @@
+// Host-side local storage for `LocalStorage` (docs/decisions/0001). Values live
+// in one JSON file per extension below the host data directory. The extension
+// name comes from the session, never from capability params, so a command can
+// only reach its own namespace.
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+/** `$XDG_DATA_HOME/blast`, or `~/.local/share/blast` when unset or relative. */
+export function defaultDataDir(env = process.env) {
+    const xdg = env.XDG_DATA_HOME;
+    const root = xdg !== undefined && xdg !== "" && isAbsolute(xdg) ? xdg : join(homedir(), ".local", "share");
+    return join(root, "blast");
+}
+/**
+ * The storage file of one extension. Names are untrusted, so anything outside
+ * the safe set is percent-encoded: a scoped or hostile name stays one path
+ * segment inside the storage directory.
+ */
+export function storageFile(dataDir, extensionName) {
+    if (extensionName === "")
+        throw new Error("An extension name is required for local storage");
+    const encoded = extensionName.replace(/[^A-Za-z0-9._-]/g, (char) => {
+        return `%${char.codePointAt(0).toString(16)}`;
+    });
+    return join(dataDir, "storage", `${encoded}.json`);
+}
+export function isStorageValue(value) {
+    return (typeof value === "string" ||
+        (typeof value === "number" && Number.isFinite(value)) ||
+        typeof value === "boolean");
+}
+function isStorageItems(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every(isStorageValue));
+}
+function checkKey(key) {
+    if (typeof key !== "string" || key === "")
+        throw new Error("Local storage keys must be non-empty strings");
+    return key;
+}
+/** One store per session; the file is read on every call so two sessions of the
+ * same extension see each other's writes. */
+export function createStorage(options) {
+    const file = storageFile(options.dataDir ?? defaultDataDir(), options.extensionName);
+    // Mutations are read-modify-write, so they must not interleave; reads join the
+    // same queue and never observe a half-applied change.
+    let tail = Promise.resolve();
+    const serialize = (operation) => {
+        const next = tail.then(operation, operation);
+        tail = next.catch(() => undefined);
+        return next;
+    };
+    const read = async () => {
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+        const items = JSON.parse(text);
+        if (!isStorageItems(items)) {
+            throw new Error(`Local storage for ${options.extensionName} is not a JSON object of strings, numbers and booleans`);
+        }
+        return items;
+    };
+    let writes = 0;
+    const write = async (items) => {
+        await mkdir(dirname(file), { recursive: true });
+        // Atomic replace: a crash or a full disk must not leave a truncated file
+        // that the next session would read as corrupt.
+        const temporary = `${file}.${process.pid}-${++writes}.tmp`;
+        try {
+            await writeFile(temporary, `${JSON.stringify(items, null, 2)}\n`, "utf8");
+            await rename(temporary, file);
+        }
+        catch (error) {
+            await rm(temporary, { force: true });
+            throw error;
+        }
+    };
+    return {
+        get: (key) => serialize(async () => {
+            return (await read())[checkKey(key)];
+        }),
+        set: (key, value) => serialize(async () => {
+            if (!isStorageValue(value))
+                throw new Error("Local storage values must be strings, numbers or booleans");
+            const items = await read();
+            items[checkKey(key)] = value;
+            await write(items);
+        }),
+        remove: (key) => serialize(async () => {
+            const items = await read();
+            const name = checkKey(key);
+            if (!(name in items))
+                return;
+            delete items[name];
+            await write(items);
+        }),
+        all: () => serialize(read),
+        clear: () => serialize(async () => {
+            if (Object.keys(await read()).length === 0)
+                return;
+            await write({});
+        }),
+    };
+}
+function readParams(params, api) {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+        throw new Error(`${api}: params must be an object`);
+    }
+    return params;
+}
+// Params carry a key and a value only. Identity is never read from them: the
+// extension a request belongs to is fixed when the session starts.
+function requireKey(params, api) {
+    const key = readParams(params, api).key;
+    if (typeof key !== "string" || key === "")
+        throw new Error(`${api}: "key" must be a non-empty string`);
+    return key;
+}
+function requireValue(params, api) {
+    const value = readParams(params, api).value;
+    if (!isStorageValue(value))
+        throw new Error(`${api}: "value" must be a string, number or boolean`);
+    return value;
+}
+/** The `storage.*` capability handlers for one session. */
+export function createStorageHandlers(options) {
+    const storage = createStorage(options);
+    // A separate root makes internal keys disjoint from every LocalStorage key.
+    const internal = createStorage({
+        ...options,
+        dataDir: join(options.dataDir ?? defaultDataDir(), "internal"),
+    });
+    const store = (params, api) => readParams(params, api).scope === "blast:internal" ? internal : storage;
+    return {
+        // A missing key is `undefined` in the extension API; the wire says `null`.
+        "storage.get": async (params) => (await store(params, "storage.get").get(requireKey(params, "storage.get"))) ?? null,
+        "storage.set": async (params) => {
+            await store(params, "storage.set").set(requireKey(params, "storage.set"), requireValue(params, "storage.set"));
+        },
+        "storage.remove": async (params) => {
+            await store(params, "storage.remove").remove(requireKey(params, "storage.remove"));
+        },
+        "storage.all": () => storage.all(),
+        "storage.clear": () => storage.clear(),
+    };
+}

package/dist/tsconfig-paths.d.ts

@@ -0,0 +1,14 @@
+export type TsconfigAliasResolver = {
+    /**
+     * Absolute path of an existing file inside the extension directory that a
+     * bare specifier resolves to through `paths` or `baseUrl`, else `undefined`.
+     */
+    resolve(specifier: string): Promise<string | undefined>;
+    /** One line per non-fatal problem found while loading the tsconfig chain. */
+    warnings: string[];
+};
+/**
+ * Reads the extension's tsconfig chain and returns a resolver for bare
+ * specifiers, or `undefined` when the extension has no `baseUrl`/`paths`.
+ */
+export declare function loadTsconfigAliases(extensionDir: string): Promise<TsconfigAliasResolver | undefined>;