@blastlauncher/protocol 0.0.0-stage → 3.0.0-alpha.1

package/dist/embedder-schema.js

@@ -0,0 +1,314 @@
+// The JSON Schema description of the embedder protocol (decision 0009, point 5).
+// It is one exported structure that `scripts/protocol/generate-schema.ts`
+// serializes verbatim into `packages/protocol/schema/`; the checked-in file
+// must regenerate byte-identical (`bun run protocol:check`). Draft 2020-12
+// with a deliberately small keyword set: `type`, `properties`, `required`,
+// `additionalProperties`, `items`, `enum`, `const`, `oneOf`, `anyOf` and
+// `$ref` — the schema test ships its own validator for exactly those.
+import { CAPABILITIES } from "./capabilities.js";
+import { EMBEDDER_METHODS, EMBEDDER_PROTOCOL_VERSION } from "./embedder.js";
+const ref = (name) => ({ $ref: `#/$defs/${name}` });
+const json = ref("jsonValue");
+const string = { type: "string" };
+const integer = { type: "integer" };
+const embedderError = ref("embedderError");
+const nullResult = { type: "null" };
+const envelope = (required, properties) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+});
+const stringRecord = (item) => ({
+    type: "object",
+    additionalProperties: item,
+});
+/**
+ * The result each request method answers. Loose shapes stay JSON values: the
+ * engine forwards manifests, dependency reports and preference data without
+ * narrowing them here.
+ */
+const RESULTS = {
+    "extension.open": envelope(["extension"], { extension: string }),
+    "extension.launch": envelope(["session"], { session: string }),
+    "extension.manifest": json,
+    "extension.dependencies.check": json,
+    "extension.dependencies.install": json,
+    "extension.preferences": json,
+    "extension.savePreferences": nullResult,
+    "extension.watch": nullResult,
+    "extension.unwatch": nullResult,
+    "extension.close": nullResult,
+    "session.event": nullResult,
+    "session.input": nullResult,
+    "session.close": nullResult,
+    "engine.shutdown": nullResult,
+};
+/** Optional params per method, mirroring the `?` markers of the wire shapes. */
+const OPTIONAL_KEYS = {
+    "extension.launch": [
+        "argumentValues",
+        "launchContext",
+        "bundleTimeoutMs",
+        "installDependencies",
+        "views",
+    ],
+};
+const PARAMS = {
+    "extension.open": { dir: string },
+    "extension.manifest": { extension: string },
+    "extension.watch": { extension: string },
+    "extension.unwatch": { extension: string },
+    "extension.close": { extension: string },
+    "extension.dependencies.check": { extension: string },
+    "extension.dependencies.install": { extension: string },
+    "extension.preferences": { extension: string, command: string },
+    "extension.savePreferences": {
+        extension: string,
+        command: string,
+        values: stringRecord({ type: ["string", "number", "boolean"] }),
+    },
+    "extension.launch": {
+        extension: string,
+        command: string,
+        argumentValues: stringRecord(string),
+        launchContext: stringRecord(json),
+        bundleTimeoutMs: { type: "integer", minimum: 0, maximum: 2_147_483_647 },
+        installDependencies: { type: "boolean" },
+        views: envelope(["platform"], { platform: { enum: ["macOS", "Windows", "Linux"] } }),
+    },
+    "session.input": { session: string, input: ref("controllerInput") },
+    "session.event": {
+        session: string,
+        node: string,
+        handler: string,
+        args: { type: "array", items: json },
+    },
+    "session.close": { session: string },
+    "engine.shutdown": {},
+};
+// One `request/<method>` envelope def and one `result/<method>` def per
+// method, so an embedder can validate both halves of the exchange.
+const requestAndResultEntries = EMBEDDER_METHODS.flatMap((name) => {
+    const optional = OPTIONAL_KEYS[name] ?? [];
+    return [
+        [
+            `request.${name}`,
+            envelope(["type", "id", "method"], {
+                type: { const: "request" },
+                id: string,
+                method: { const: name },
+                params: {
+                    type: "object",
+                    properties: PARAMS[name],
+                    required: Object.keys(PARAMS[name]).filter((key) => !optional.includes(key)),
+                    additionalProperties: false,
+                },
+            }),
+        ],
+        [`result.${name}`, RESULTS[name]],
+    ];
+});
+const EVENT_PROPERTIES = {
+    "manifest.changed": { extension: string, manifest: json },
+    "manifest.error": { extension: string, error: embedderError },
+    "dependencies.log": { extension: string, message: string },
+    "session.scene": { session: string, scene: ref("sceneMessage") },
+    "session.view": { session: string, view: ref("controllerView") },
+    "session.log": { session: string, log: ref("logMessage") },
+    "session.exited": { session: string, code: integer, error: embedderError },
+};
+const eventVariants = Object.entries(EVENT_PROPERTIES).map(([name, props]) => envelope(["type", "event", ...(name === "session.view" ? ["session", "view"] : [])], {
+    type: { const: "event" },
+    event: { const: name },
+    ...props,
+}));
+// A capability-request variant per catalog entry: the `name` const pins the
+// received params to that capability's declared shape.
+const capabilityEntries = Object.entries(CAPABILITIES).map(([name, spec]) => [
+    `capabilities.${name}`,
+    {
+        scope: spec.scope,
+        summary: spec.summary,
+        params: spec.params,
+        result: spec.result,
+        api: [...spec.api],
+    },
+]);
+const capabilityRequestVariants = Object.keys(CAPABILITIES).map((name) => envelope(["type", "id", "session", "name"], {
+    type: { const: "capability.request" },
+    id: string,
+    session: string,
+    name: { const: name },
+    params: { $ref: `#/$defs/capabilities.${name}/params` },
+}));
+const sceneNode = {
+    type: "object",
+    properties: {
+        id: string,
+        type: string,
+        props: {
+            type: "object",
+            additionalProperties: { anyOf: [ref("handlerRef"), json] },
+        },
+        children: { type: "array", items: ref("sceneNode") },
+    },
+    required: ["id", "type", "props", "children"],
+    additionalProperties: false,
+};
+/** The whole embedder protocol schema, serialized verbatim by the generator. */
+export const EMBEDDER_PROTOCOL_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://blastlauncher.dev/schema/embedder-v1.schema.json",
+    title: `Blast embedder protocol v${EMBEDDER_PROTOCOL_VERSION}`,
+    description: "NDJSON messages of `blast serve` (decision 0011). Each validated instance " +
+        "is one line: an embedder -> server or a server -> embedder message.",
+    oneOf: [ref("embedderMessages"), ref("serverMessages")],
+    $defs: {
+        controllerInput: {
+            oneOf: [
+                ...["search", "actionsQuery", "dropdownQuery"].map((type) => envelope(["type", "text"], { type: { const: type }, text: string })),
+                envelope(["type", "direction"], {
+                    type: { const: "move" },
+                    direction: { enum: ["up", "down", "left", "right"] },
+                }),
+                ...["select", "focus", "toggle"].map((type) => envelope(["type", "id"], { type: { const: type }, id: string })),
+                envelope(["type", "id", "value"], {
+                    type: { const: "setValue" },
+                    id: string,
+                    value: string,
+                }),
+                envelope(["type", "delta"], { type: { const: "optionMove" }, delta: { type: "number" } }),
+                ...[
+                    "primary",
+                    "openActions",
+                    "closeActions",
+                    "back",
+                    "openDropdown",
+                    "chooseDropdown",
+                    "focusNext",
+                    "focusPrev",
+                    "optionChoose",
+                    "submit",
+                ].map((type) => envelope(["type"], { type: { const: type } })),
+                envelope(["type", "key"], {
+                    type: { const: "key" },
+                    key: envelope(["name"], {
+                        name: string,
+                        ...Object.fromEntries(["ctrl", "meta", "shift", "option", "super"].map((key) => [key, { type: "boolean" }])),
+                    }),
+                }),
+                envelope(["type", "index"], { type: { const: "toastAction" }, index: { type: "number" } }),
+                envelope(["type", "confirm"], {
+                    type: { const: "alert" },
+                    confirm: { type: "boolean" },
+                    remember: { type: "boolean" },
+                }),
+            ],
+        },
+        controllerView: {
+            $comment: "Opaque JSON view model: packages/client-core/src/controller.ts ControllerView.",
+            type: "object",
+            additionalProperties: json,
+        },
+        jsonValue: {
+            type: ["string", "number", "boolean", "null", "array", "object"],
+            items: json,
+            additionalProperties: json,
+        },
+        handlerRef: envelope(["$handler"], { $handler: string }),
+        embedderError: envelope(["code", "message"], { code: string, message: string, data: json }),
+        sceneNode,
+        sceneMessage: envelope(["type", "revision", "root"], {
+            type: { const: "scene" },
+            revision: integer,
+            root: { anyOf: [ref("sceneNode"), { type: "null" }] },
+        }),
+        logMessage: envelope(["type", "level", "message"], {
+            type: { const: "log" },
+            level: { type: "string", enum: ["debug", "info", "warn", "error"] },
+            message: string,
+        }),
+        ...Object.fromEntries(requestAndResultEntries),
+        request: {
+            oneOf: EMBEDDER_METHODS.map((name) => ref(`request.${name}`)),
+        },
+        "embedder.capability.result": {
+            oneOf: [
+                envelope(["type", "id", "ok", "value"], {
+                    type: { const: "capability.result" },
+                    id: string,
+                    ok: { const: true },
+                    value: json,
+                }),
+                envelope(["type", "id", "ok", "error"], {
+                    type: { const: "capability.result" },
+                    id: string,
+                    ok: { const: false },
+                    error: embedderError,
+                }),
+            ],
+        },
+        "embedder.capability.progress": envelope(["type", "id", "value"], {
+            type: { const: "capability.progress" },
+            id: string,
+            value: json,
+        }),
+        "embedder.hello": envelope(["type", "protocol", "capabilities"], {
+            type: { const: "hello" },
+            protocol: integer,
+            capabilities: { type: "array", items: string },
+        }),
+        embedderMessages: {
+            oneOf: [
+                ref("embedder.hello"),
+                ref("request"),
+                ref("embedder.capability.result"),
+                ref("embedder.capability.progress"),
+            ],
+        },
+        "server.welcome": envelope(["type", "protocol", "engine", "catalog"], {
+            type: { const: "welcome" },
+            protocol: integer,
+            engine: envelope(["version"], { version: string }),
+            catalog: { type: "object", additionalProperties: json },
+        }),
+        "server.error": envelope(["type", "error"], {
+            type: { const: "error" },
+            error: embedderError,
+        }),
+        response: {
+            oneOf: [
+                envelope(["type", "id", "ok", "result"], {
+                    type: { const: "response" },
+                    id: string,
+                    ok: { const: true },
+                    result: json,
+                }),
+                envelope(["type", "id", "ok", "error"], {
+                    type: { const: "response" },
+                    id: string,
+                    ok: { const: false },
+                    error: embedderError,
+                }),
+            ],
+        },
+        "server.event": { oneOf: eventVariants },
+        "server.capability.request": { oneOf: capabilityRequestVariants },
+        "server.capability.cancel": envelope(["type", "id"], {
+            type: { const: "capability.cancel" },
+            id: string,
+        }),
+        serverMessages: {
+            oneOf: [
+                ref("server.welcome"),
+                ref("server.error"),
+                ref("response"),
+                ref("server.event"),
+                ref("server.capability.request"),
+                ref("server.capability.cancel"),
+            ],
+        },
+        ...Object.fromEntries(capabilityEntries),
+    },
+};

package/dist/embedder.d.ts

@@ -0,0 +1,173 @@
+import type { JsonValue } from "./messages.js";
+export declare const EMBEDDER_PROTOCOL_VERSION = 1;
+export type EmbedderError = {
+    code: string;
+    message: string;
+    data?: JsonValue;
+};
+/** Structural wire counterpart of client-core's ControllerInput; no runtime dependency. */
+export type EmbedderControllerInput = {
+    type: "search" | "actionsQuery" | "dropdownQuery";
+    text: string;
+} | {
+    type: "move";
+    direction: "up" | "down" | "left" | "right";
+} | {
+    type: "select" | "focus" | "toggle";
+    id: string;
+} | {
+    type: "setValue";
+    id: string;
+    value: string;
+} | {
+    type: "optionMove";
+    delta: number;
+} | {
+    type: "primary" | "openActions" | "closeActions" | "back" | "openDropdown" | "chooseDropdown" | "focusNext" | "focusPrev" | "optionChoose" | "submit";
+} | {
+    type: "key";
+    key: {
+        name: string;
+        ctrl?: boolean;
+        meta?: boolean;
+        shift?: boolean;
+        option?: boolean;
+        super?: boolean;
+    };
+} | {
+    type: "toastAction";
+    index: number;
+} | {
+    type: "alert";
+    confirm: boolean;
+    remember?: boolean;
+};
+export type EmbedderParams = {
+    "extension.open": {
+        dir: string;
+    };
+    "extension.manifest": {
+        extension: string;
+    };
+    "extension.watch": {
+        extension: string;
+    };
+    "extension.unwatch": {
+        extension: string;
+    };
+    "extension.close": {
+        extension: string;
+    };
+    "extension.dependencies.check": {
+        extension: string;
+    };
+    "extension.dependencies.install": {
+        extension: string;
+    };
+    "extension.preferences": {
+        extension: string;
+        command: string;
+    };
+    "extension.savePreferences": {
+        extension: string;
+        command: string;
+        values: Record<string, string | number | boolean>;
+    };
+    "extension.launch": {
+        extension: string;
+        command: string;
+        argumentValues?: Record<string, string>;
+        launchContext?: Record<string, JsonValue>;
+        bundleTimeoutMs?: number;
+        installDependencies?: boolean;
+        views?: {
+            platform: "macOS" | "Windows" | "Linux";
+        };
+    };
+    "session.input": {
+        session: string;
+        input: EmbedderControllerInput;
+    };
+    "session.event": {
+        session: string;
+        node: string;
+        handler: string;
+        args: JsonValue[];
+    };
+    "session.close": {
+        session: string;
+    };
+    "engine.shutdown": Record<string, never>;
+};
+export type EmbedderRequest = {
+    [M in keyof EmbedderParams]: {
+        type: "request";
+        id: string;
+        method: M;
+        params: EmbedderParams[M];
+    };
+}[keyof EmbedderParams];
+export type EmbedderMessage = {
+    type: "hello";
+    protocol: number;
+    capabilities: string[];
+} | EmbedderRequest | {
+    type: "capability.result";
+    id: string;
+    ok: true;
+    value: JsonValue;
+} | {
+    type: "capability.result";
+    id: string;
+    ok: false;
+    error: EmbedderError;
+} | {
+    type: "capability.progress";
+    id: string;
+    value: JsonValue;
+};
+export type EmbedderServerMessage = {
+    type: "welcome";
+    protocol: number;
+    engine: {
+        version: string;
+    };
+    catalog: JsonValue;
+} | {
+    type: "error";
+    error: EmbedderError;
+} | {
+    type: "response";
+    id: string;
+    ok: true;
+    result: JsonValue;
+} | {
+    type: "response";
+    id: string;
+    ok: false;
+    error: EmbedderError;
+} | {
+    type: "event";
+    event: string;
+    [key: string]: JsonValue;
+} | {
+    type: "capability.request";
+    id: string;
+    session: string;
+    name: string;
+    params: JsonValue;
+} | {
+    type: "capability.cancel";
+    id: string;
+};
+/** Every request method name, in wire-table order; the schema generator and
+ * its test enumerate this instead of re-listing the methods. */
+export declare const EMBEDDER_METHODS: (keyof EmbedderParams & string)[];
+/** Total boundary validator; unknown fields and methods are rejected. */
+export declare function parseEmbedderMessage(value: unknown): {
+    ok: true;
+    message: EmbedderMessage;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/embedder.js

@@ -0,0 +1,151 @@
+export const EMBEDDER_PROTOCOL_VERSION = 1;
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const json = (v) => v === null ||
+    typeof v === "string" ||
+    typeof v === "boolean" ||
+    (typeof v === "number" && Number.isFinite(v)) ||
+    (Array.isArray(v) ? v.every(json) : object(v) && Object.values(v).every(json));
+const string = (v) => typeof v === "string";
+const record = (v, check) => object(v) && Object.values(v).every(check);
+const shapes = {
+    "extension.open": ["dir"],
+    "extension.manifest": ["extension"],
+    "extension.watch": ["extension"],
+    "extension.unwatch": ["extension"],
+    "extension.close": ["extension"],
+    "extension.dependencies.check": ["extension"],
+    "extension.dependencies.install": ["extension"],
+    "extension.preferences": ["extension", "command"],
+    "extension.savePreferences": ["extension", "command", "values"],
+    "extension.launch": [
+        "extension",
+        "command",
+        "argumentValues?",
+        "launchContext?",
+        "bundleTimeoutMs?",
+        "installDependencies?",
+        "views?",
+    ],
+    "session.input": ["session", "input"],
+    "session.event": ["session", "node", "handler", "args"],
+    "session.close": ["session"],
+    "engine.shutdown": [],
+};
+/** Every request method name, in wire-table order; the schema generator and
+ * its test enumerate this instead of re-listing the methods. */
+export const EMBEDDER_METHODS = Object.keys(shapes);
+function fields(v, names, check) {
+    return (Object.keys(v).every((k) => names.includes(k) || names.includes(`${k}?`)) &&
+        names.every((name) => {
+            const key = name.replace(/\?$/, "");
+            return (name.endsWith("?") && !(key in v)) || (key in v && check(key, v[key]));
+        }));
+}
+function valid(v) {
+    if (!object(v))
+        return false;
+    if (v.type === "hello")
+        return fields(v, ["type", "protocol", "capabilities"], (k, x) => k === "protocol"
+            ? Number.isSafeInteger(x)
+            : k === "capabilities"
+                ? Array.isArray(x) && x.every(string)
+                : string(x));
+    if (v.type === "capability.progress")
+        return fields(v, ["type", "id", "value"], (k, x) => (k === "value" ? json(x) : string(x)));
+    if (v.type === "capability.result")
+        return fields(v, ["type", "id", "ok", v.ok === true ? "value" : "error"], (k, x) => k === "ok"
+            ? typeof x === "boolean"
+            : k === "value"
+                ? json(x)
+                : k === "error"
+                    ? object(x) &&
+                        fields(x, ["code", "message", "data?"], (key, y) => key === "data" ? json(y) : string(y))
+                    : string(x));
+    if (v.type !== "request" || !string(v.method) || !Object.hasOwn(shapes, v.method))
+        return false;
+    return fields(v, ["type", "id", "method", "params"], (k, x) => k !== "params"
+        ? string(x)
+        : object(x) &&
+            fields(x, shapes[v.method], (key, y) => {
+                if (key === "args")
+                    return Array.isArray(y) && y.every(json);
+                if (key === "argumentValues")
+                    return record(y, string);
+                if (key === "bundleTimeoutMs")
+                    return typeof y === "number" && Number.isSafeInteger(y) && y >= 0 && y <= 2_147_483_647;
+                if (key === "installDependencies")
+                    return typeof y === "boolean";
+                if (key === "launchContext")
+                    return record(y, json);
+                if (key === "views")
+                    return (object(y) &&
+                        fields(y, ["platform"], (_, z) => ["macOS", "Windows", "Linux"].includes(z)));
+                if (key === "input")
+                    return controllerInput(y);
+                if (key === "values")
+                    return record(y, (z) => typeof z === "string" ||
+                        typeof z === "boolean" ||
+                        (typeof z === "number" && Number.isFinite(z)));
+                return string(y);
+            }));
+}
+function controllerInput(v) {
+    if (!object(v))
+        return false;
+    const shape = ["search", "actionsQuery", "dropdownQuery"].includes(v.type)
+        ? ["type", "text"]
+        : v.type === "move"
+            ? ["type", "direction"]
+            : v.type === "setValue"
+                ? ["type", "id", "value"]
+                : v.type === "optionMove"
+                    ? ["type", "delta"]
+                    : ["select", "focus", "toggle"].includes(v.type)
+                        ? ["type", "id"]
+                        : v.type === "key"
+                            ? ["type", "key"]
+                            : v.type === "toastAction"
+                                ? ["type", "index"]
+                                : v.type === "alert"
+                                    ? ["type", "confirm", "remember?"]
+                                    : [
+                                        "focusNext",
+                                        "focusPrev",
+                                        "optionChoose",
+                                        "submit",
+                                        "primary",
+                                        "openActions",
+                                        "closeActions",
+                                        "back",
+                                        "openDropdown",
+                                        "chooseDropdown",
+                                    ].includes(v.type)
+                                        ? ["type"]
+                                        : undefined;
+    return (!!shape &&
+        fields(v, shape, (key, value) => {
+            if (key === "direction")
+                return ["up", "down", "left", "right"].includes(value);
+            if (key === "delta")
+                return typeof value === "number" && Number.isFinite(value);
+            if (key === "index")
+                return typeof value === "number" && Number.isFinite(value);
+            if (key === "confirm" || key === "remember")
+                return typeof value === "boolean";
+            if (key === "key")
+                return (object(value) &&
+                    fields(value, ["name", "ctrl?", "meta?", "shift?", "option?", "super?"], (name, x) => name === "name" ? string(x) : typeof x === "boolean"));
+            return string(value);
+        }));
+}
+/** Total boundary validator; unknown fields and methods are rejected. */
+export function parseEmbedderMessage(value) {
+    try {
+        if (valid(value))
+            return { ok: true, message: value };
+    }
+    catch {
+        /* Cyclic/non-JSON input is invalid too. */
+    }
+    return { ok: false, error: "Invalid embedder message or request params" };
+}

package/dist/framing.d.ts

@@ -0,0 +1,20 @@
+import type { HostMessage, RuntimeMessage } from "./messages.js";
+/** 8 MiB, per docs/decisions/0001: lines have a size cap. */
+export declare const DEFAULT_MAX_LINE_BYTES: number;
+export type WireMessage = HostMessage | RuntimeMessage;
+/** One message as one JSON line, ready to write to the stream. */
+export declare function encodeMessage(message: WireMessage): string;
+export type LineDecoderOptions = {
+    /** Longest accepted line in bytes, terminator excluded. */
+    maxLineBytes?: number;
+    /** Called once per non-blank line with the parsed JSON value, unvalidated. */
+    onLine: (value: unknown) => void;
+    /** Called once when the stream is unusable; no callback follows. */
+    onError: (error: string) => void;
+};
+export type LineDecoder = {
+    push(chunk: string | Uint8Array): void;
+    /** Closes the stream; a line left without its newline is an error. */
+    end(): void;
+};
+export declare function createLineDecoder(options: LineDecoderOptions): LineDecoder;