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

package/dist/engine.d.ts

@@ -0,0 +1,39 @@
+import type { CapabilityHandler } from "./broker.js";
+import { type OpenExtensionOptions } from "./extension.js";
+import type { DependencyInstaller } from "./install-dependencies.js";
+/** Shared defaults and capability registrations for a group of extensions. */
+export declare function createEngine(options?: {
+    timeoutMs?: number;
+    dataDir?: string;
+    installer?: DependencyInstaller;
+    watcher?: OpenExtensionOptions["watcher"];
+    debounce?: OpenExtensionOptions["debounce"];
+    dependencies?: "manual" | "auto";
+    handlers?: Record<string, CapabilityHandler>;
+}): {
+    /** Later registrations win; changes apply to future launches. */
+    register(handlers: Record<string, CapabilityHandler>): () => void;
+    openExtension(extensionOptions: OpenExtensionOptions): {
+        manifest: () => Promise<import("./extension-manifest.js").ExtensionManifest>;
+        watch(listener: (update: import("./extension-manifest.js").ExtensionManifest | Error) => void): () => void;
+        dependencies: {
+            check: () => Promise<import("./install-dependencies.js").DependencyInstallStatus>;
+            install: (installOptions?: {
+                onLog?: (message: string) => void;
+            }) => Promise<import("./install-dependencies.js").DependencyInstallStatus>;
+        };
+        preferences: (name: string, scope?: "extension" | "command") => Promise<{
+            extension: import("./bundle.js").Preference[];
+            command: import("./bundle.js").Preference[];
+            values: import("./storage.js").StorageItems;
+            missing: import("./bundle.js").Preference[];
+        }>;
+        savePreferences(name: string, values: import("./storage.js").StorageItems, scope?: "extension" | "command"): Promise<void>;
+        launch(name: string, launchOptions?: import("./extension.js").ExtensionLaunchOptions): Promise<{
+            session: import("./session.js").Session;
+            close: () => Promise<void>;
+        }>;
+        close(): Promise<void>;
+    };
+    close(): Promise<void>;
+};

package/dist/engine.js

@@ -0,0 +1,53 @@
+import { createExtensionHandle, } from "./extension.js";
+/** Shared defaults and capability registrations for a group of extensions. */
+export function createEngine(options = {}) {
+    const registrations = new Set();
+    const extensions = new Set();
+    let closing;
+    const ensureOpen = () => {
+        if (closing)
+            throw new Error("Engine is closed");
+    };
+    const registeredHandlers = () => Object.assign({}, ...registrations);
+    if (options.handlers)
+        registrations.add({ ...options.handlers });
+    return {
+        /** Later registrations win; changes apply to future launches. */
+        register(handlers) {
+            ensureOpen();
+            const registration = { ...handlers };
+            registrations.add(registration);
+            return () => {
+                registrations.delete(registration);
+            };
+        },
+        openExtension(extensionOptions) {
+            ensureOpen();
+            const extension = createExtensionHandle({
+                ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+                ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+                ...(options.installer === undefined ? {} : { installer: options.installer }),
+                ...(options.watcher === undefined ? {} : { watcher: options.watcher }),
+                ...(options.debounce === undefined ? {} : { debounce: options.debounce }),
+                ...extensionOptions,
+            }, registeredHandlers, options.dependencies === "auto");
+            const close = extension.close;
+            extension.close = async () => {
+                try {
+                    await close();
+                }
+                finally {
+                    extensions.delete(extension);
+                }
+            };
+            extensions.add(extension);
+            return extension;
+        },
+        close() {
+            return (closing ??= Promise.resolve().then(async () => {
+                registrations.clear();
+                await Promise.all([...extensions].map((extension) => extension.close()));
+            }));
+        },
+    };
+}

package/dist/extension-manifest.d.ts

@@ -0,0 +1,34 @@
+import { type Preference } from "./bundle.js";
+export type ExtensionMode = "view" | "no-view" | "menu-bar";
+export type ExtensionOption = {
+    title: string;
+    value: string;
+};
+export type ExtensionArgument = {
+    name: string;
+    type: "text" | "password" | "dropdown";
+    /** A required argument must be filled before Enter launches the command. */
+    required: boolean;
+    placeholder: string;
+    /** A dropdown argument's options, in declaration order. */
+    data: ExtensionOption[];
+};
+export type ExtensionCommand = {
+    name: string;
+    title: string;
+    subtitle: string;
+    description: string;
+    mode: ExtensionMode;
+    arguments: ExtensionArgument[];
+    preferences: Preference[];
+};
+export type ExtensionManifest = {
+    name: string;
+    title: string;
+    preferences: Preference[];
+    commands: ExtensionCommand[];
+};
+/** Validates manifest metadata shared by embedders and reference clients. */
+export declare function parseManifest(value: unknown): ExtensionManifest;
+/** Required argument names that the form has not filled yet. */
+export declare function missingRequired(args: ExtensionArgument[], values: Record<string, string>): string[];

package/dist/extension-manifest.js

@@ -0,0 +1,79 @@
+import { parsePreferences } from "./bundle.js";
+const MODES = ["view", "no-view", "menu-bar"];
+const ARGUMENT_TYPES = ["text", "password", "dropdown"];
+function string(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Validates manifest metadata shared by embedders and reference clients. */
+export function parseManifest(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("manifest must be an object");
+    const manifest = value;
+    const name = string(manifest.name);
+    if (!name)
+        throw new Error('manifest needs a string "name"');
+    if (!Array.isArray(manifest.commands))
+        throw new Error('manifest needs a "commands" array');
+    return {
+        name,
+        title: string(manifest.title) || name,
+        preferences: parsePreferences(manifest.preferences),
+        commands: manifest.commands.map(parseCommand),
+    };
+}
+function parseCommand(value, index) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`command ${index + 1} must be an object`);
+    const command = value;
+    const name = string(command.name);
+    if (!name)
+        throw new Error(`command ${index + 1} needs a name`);
+    const mode = command.mode === undefined ? "view" : command.mode;
+    if (typeof mode !== "string" || !MODES.includes(mode))
+        throw new Error(`command ${JSON.stringify(name)} has an unknown mode`);
+    return {
+        name,
+        title: string(command.title) || name,
+        subtitle: string(command.subtitle),
+        description: string(command.description),
+        mode: mode,
+        preferences: parsePreferences(command.preferences),
+        arguments: Array.isArray(command.arguments) ? command.arguments.map(parseArgument) : [],
+    };
+}
+function parseArgument(value, index) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`argument ${index + 1} must be an object`);
+    const argument = value;
+    const name = string(argument.name);
+    if (!name)
+        throw new Error(`argument ${index + 1} needs a name`);
+    const type = string(argument.type);
+    if (!ARGUMENT_TYPES.includes(type))
+        throw new Error(`argument ${JSON.stringify(name)} has an unknown type ${JSON.stringify(type)}`);
+    const data = Array.isArray(argument.data)
+        ? argument.data.map(parseOption).filter((option) => option !== undefined)
+        : [];
+    return {
+        name,
+        type: type,
+        required: argument.required === true,
+        placeholder: string(argument.placeholder),
+        data,
+    };
+}
+function parseOption(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const option = value;
+    const optionValue = string(option.value);
+    if (!optionValue)
+        return undefined;
+    return { title: string(option.title) || optionValue, value: optionValue };
+}
+/** Required argument names that the form has not filled yet. */
+export function missingRequired(args, values) {
+    return args
+        .filter((argument) => argument.required && (values[argument.name] ?? "") === "")
+        .map((argument) => argument.name);
+}

package/dist/extension.d.ts

@@ -0,0 +1,93 @@
+import { type Preference } from "./bundle.js";
+import { type ExtensionManifest } from "./extension-manifest.js";
+import { type DependencyInstallStatus, type DependencyInstaller } from "./install-dependencies.js";
+import { type StartOptions } from "./session.js";
+import { type StorageItems } from "./storage.js";
+import type { CapabilityHandler } from "./broker.js";
+export type ExtensionLaunchOptions = Pick<StartOptions, "argumentValues" | "launchContext" | "fallbackText"> & {
+    /** Install unresolved manifest dependencies before bundling this launch. */
+    installDependencies?: boolean;
+    /** Receives installer output when this launch performs an install. */
+    onDependencyLog?: (message: string) => void;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    handlers?: Record<string, CapabilityHandler>;
+};
+export declare class MissingLaunchValuesError extends Error {
+    readonly code = "MISSING_LAUNCH_VALUES";
+    readonly preferences: Preference[];
+    readonly arguments: string[];
+    constructor(preferences: Preference[], args: string[]);
+}
+export declare class DependenciesRequiredError extends Error {
+    readonly code = "DEPENDENCIES_REQUIRED";
+    readonly unresolved: string[];
+    readonly installable: boolean;
+    readonly pinned: boolean;
+    constructor(status: Pick<DependencyInstallStatus, "unresolved" | "installable" | "pinned">);
+}
+export type OpenExtensionOptions = {
+    timeoutMs?: number;
+    extensionDir: string;
+    dataDir?: string;
+    installer?: DependencyInstaller;
+    handlers?: Record<string, CapabilityHandler>;
+    watcher?: ExtensionWatcherFactory;
+    debounce?: DebounceScheduler;
+};
+export type ExtensionWatcher = {
+    on(event: "error", listener: (error: Error) => void): ExtensionWatcher;
+    close(): void;
+};
+export type ExtensionWatcherFactory = (path: string, listener: (event: string, filename: string | Buffer | null) => void) => ExtensionWatcher;
+export type DebounceScheduler = {
+    schedule(callback: () => void, delayMs: number): unknown;
+    cancel(handle: unknown): void;
+};
+/** Opens an extension without starting a command or installing dependencies. */
+export declare function openExtension(options: OpenExtensionOptions): {
+    manifest: () => Promise<ExtensionManifest>;
+    watch(listener: (update: ExtensionManifest | Error) => void): () => void;
+    dependencies: {
+        check: () => Promise<DependencyInstallStatus>;
+        install: (installOptions?: {
+            onLog?: (message: string) => void;
+        }) => Promise<DependencyInstallStatus>;
+    };
+    preferences: (name: string, scope?: "extension" | "command") => Promise<{
+        extension: Preference[];
+        command: Preference[];
+        values: StorageItems;
+        missing: Preference[];
+    }>;
+    savePreferences(name: string, values: StorageItems, scope?: "extension" | "command"): Promise<void>;
+    launch(name: string, launchOptions?: ExtensionLaunchOptions): Promise<{
+        session: import("./session.js").Session;
+        close: () => Promise<void>;
+    }>;
+    close(): Promise<void>;
+};
+/** Internal constructor shared with the engine's live handler registry. */
+export declare function createExtensionHandle(options: OpenExtensionOptions, engineHandlers?: () => Record<string, CapabilityHandler>, defaultInstallDependencies?: boolean): {
+    manifest: () => Promise<ExtensionManifest>;
+    watch(listener: (update: ExtensionManifest | Error) => void): () => void;
+    dependencies: {
+        check: () => Promise<DependencyInstallStatus>;
+        install: (installOptions?: {
+            onLog?: (message: string) => void;
+        }) => Promise<DependencyInstallStatus>;
+    };
+    preferences: (name: string, scope?: "extension" | "command") => Promise<{
+        extension: Preference[];
+        command: Preference[];
+        values: StorageItems;
+        missing: Preference[];
+    }>;
+    savePreferences(name: string, values: StorageItems, scope?: "extension" | "command"): Promise<void>;
+    launch(name: string, launchOptions?: ExtensionLaunchOptions): Promise<{
+        session: import("./session.js").Session;
+        close: () => Promise<void>;
+    }>;
+    close(): Promise<void>;
+};
+export type ExtensionHandle = ReturnType<typeof createExtensionHandle>;

package/dist/extension.js

@@ -0,0 +1,295 @@
+import { watch as watchDirectory } from "node:fs";
+import { readFile, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { bundleCommand, MissingDependencyError } from "./bundle.js";
+import { createSessionBroker } from "./client.js";
+import { parseManifest, missingRequired } from "./extension-manifest.js";
+import { checkExtensionDependencies, installExtensionDependencies, } from "./install-dependencies.js";
+import { createPreferenceStore } from "./preferences.js";
+import { startCommand } from "./session.js";
+import { defaultDataDir } from "./storage.js";
+export class MissingLaunchValuesError extends Error {
+    code = "MISSING_LAUNCH_VALUES";
+    preferences;
+    arguments;
+    constructor(preferences, args) {
+        super(`Missing required values: ${[...preferences.map((p) => p.name), ...args].join(", ")}`);
+        this.name = "MissingLaunchValuesError";
+        this.preferences = preferences;
+        this.arguments = args;
+    }
+}
+export class DependenciesRequiredError extends Error {
+    code = "DEPENDENCIES_REQUIRED";
+    unresolved;
+    installable;
+    pinned;
+    constructor(status) {
+        const names = [...new Set(status.unresolved)].toSorted();
+        super(`Missing dependencies: ${names.join(", ")}. Run blast deps <extensionDir> to install them before launching.`);
+        this.name = "DependenciesRequiredError";
+        this.unresolved = names;
+        this.installable = status.installable;
+        this.pinned = status.pinned;
+    }
+}
+/** Opens an extension without starting a command or installing dependencies. */
+export function openExtension(options) {
+    return createExtensionHandle(options);
+}
+/** Internal constructor shared with the engine's live handler registry. */
+export function createExtensionHandle(options, engineHandlers = () => ({}), defaultInstallDependencies = false) {
+    const extensionDir = resolve(options.extensionDir);
+    const dataDir = options.dataDir ?? defaultDataDir();
+    const dependencyOptions = { extensionDir, dataDir };
+    const watcherFactory = options.watcher ?? ((path, listener) => watchDirectory(path, listener));
+    const debounce = options.debounce ??
+        {
+            schedule: (callback, delayMs) => setTimeout(callback, delayMs),
+            cancel: (handle) => clearTimeout(handle),
+        };
+    let closed = false;
+    let closing;
+    let queue = Promise.resolve();
+    const subscriptions = new Set();
+    const sessions = new Set();
+    const launches = new Set();
+    const ensureOpen = () => {
+        if (closed)
+            throw new Error("Extension handle is closed");
+    };
+    const manifest = async () => {
+        ensureOpen();
+        try {
+            return parseManifest(JSON.parse(await readFile(join(extensionDir, "package.json"), "utf8")));
+        }
+        catch (error) {
+            throw new Error(`Invalid extension manifest: ${error instanceof Error ? error.message : error}`, {
+                cause: error,
+            });
+        }
+    };
+    const commandManifest = async (name) => {
+        const extension = await manifest();
+        const command = extension.commands.find((c) => c.name === name);
+        if (!command)
+            throw new Error(`Unknown extension command: ${name}`);
+        return { extension, command };
+    };
+    const preferences = async (name, scope) => {
+        const { extension, command } = await commandManifest(name);
+        const store = createPreferenceStore({ extensionName: extension.name, dataDir });
+        const stored = await store.read();
+        const values = scope === "extension" ? stored.extension : { ...stored.extension, ...stored.commands[name] };
+        const fields = [
+            ...new Map([...extension.preferences, ...command.preferences].map((p) => [p.name, p])).values(),
+        ];
+        return {
+            extension: extension.preferences,
+            command: command.preferences,
+            values,
+            missing: fields.filter((p) => p.required &&
+                p.default === undefined &&
+                (values[p.name] === undefined || values[p.name] === "")),
+        };
+    };
+    // A failed install remains observable to its caller but does not poison the
+    // queue: commands may still bundle against the shared dependency fallback.
+    const serialize = (operation) => {
+        ensureOpen();
+        const next = queue.then(() => {
+            ensureOpen();
+            return operation();
+        });
+        queue = next.catch(() => { });
+        return next;
+    };
+    const launch = async (name, launchOptions = {}) => {
+        ensureOpen();
+        await queue;
+        const { command } = await commandManifest(name);
+        const prefs = await preferences(name);
+        const args = missingRequired(command.arguments, launchOptions.argumentValues ?? {});
+        if (prefs.missing.length || args.length)
+            throw new MissingLaunchValuesError(prefs.missing, args);
+        let dependencyStatus = await checkExtensionDependencies({
+            ...dependencyOptions,
+        });
+        const installDependencies = launchOptions.installDependencies ?? defaultInstallDependencies;
+        if (dependencyStatus.unresolved.length && installDependencies) {
+            await installExtensionDependencies({
+                ...dependencyOptions,
+                ...(options.installer ? { installer: options.installer } : {}),
+                ...(launchOptions.onDependencyLog ? { onLog: launchOptions.onDependencyLog } : {}),
+            });
+            dependencyStatus = await checkExtensionDependencies({
+                ...dependencyOptions,
+            });
+        }
+        // A successful installer publishes its key before the bundle runs. Some
+        // installers provision packages lazily, so an installable manifest is no
+        // longer launch-blocking once that key is current; undeclared imports are
+        // never installable and remain an immediate typed failure.
+        if (dependencyStatus.unresolved.length &&
+            (dependencyStatus.needed || !dependencyStatus.installable))
+            throw new DependenciesRequiredError(dependencyStatus);
+        ensureOpen();
+        const timeoutMs = launchOptions.timeoutMs ?? options.timeoutMs;
+        const bundle = () => bundleCommand({
+            extensionDir,
+            command: name,
+            dataDir,
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            ...(launchOptions.signal === undefined ? {} : { signal: launchOptions.signal }),
+        });
+        let bundled;
+        try {
+            bundled = await bundle();
+        }
+        catch (error) {
+            if (!(error instanceof MissingDependencyError))
+                throw error;
+            const declared = new Set(Object.keys(JSON.parse(await readFile(join(extensionDir, "package.json"), "utf8")).dependencies ?? {}));
+            const status = {
+                unresolved: error.packages,
+                installable: error.packages.every((packageName) => declared.has(packageName)),
+                pinned: (await checkExtensionDependencies(dependencyOptions)).pinned,
+            };
+            if (!installDependencies || !status.installable)
+                throw new DependenciesRequiredError(status);
+            await installExtensionDependencies({
+                ...dependencyOptions,
+                ...(options.installer ? { installer: options.installer } : {}),
+                ...(launchOptions.onDependencyLog ? { onLog: launchOptions.onDependencyLog } : {}),
+            });
+            try {
+                bundled = await bundle();
+            }
+            catch (retryError) {
+                if (retryError instanceof MissingDependencyError) {
+                    throw new DependenciesRequiredError({
+                        unresolved: retryError.packages,
+                        installable: retryError.packages.every((packageName) => declared.has(packageName)),
+                        pinned: status.pinned,
+                    });
+                }
+                throw retryError;
+            }
+        }
+        const cleanup = () => rm(dirname(bundled.entry), { recursive: true, force: true });
+        try {
+            ensureOpen();
+            const session = await startCommand({
+                ...bundled,
+                preferences: prefs.values,
+                dataDir,
+                ...(launchOptions.argumentValues === undefined
+                    ? {}
+                    : { argumentValues: launchOptions.argumentValues }),
+                ...(launchOptions.fallbackText === undefined
+                    ? {}
+                    : { fallbackText: launchOptions.fallbackText }),
+                ...(launchOptions.launchContext === undefined
+                    ? {}
+                    : { launchContext: launchOptions.launchContext }),
+                broker: createSessionBroker({ extensionName: bundled.extensionName, dataDir }, { handlers: { ...engineHandlers(), ...options.handlers, ...launchOptions.handlers } }),
+            });
+            let stopping;
+            const opened = {
+                session,
+                close: () => (stopping ??= (async () => {
+                    try {
+                        await session.shutdown({ timeoutMs: 5000 });
+                    }
+                    finally {
+                        await cleanup();
+                        sessions.delete(opened);
+                    }
+                })()),
+            };
+            sessions.add(opened);
+            if (closed) {
+                await opened.close();
+                ensureOpen();
+            }
+            return opened;
+        }
+        catch (error) {
+            await cleanup();
+            throw error;
+        }
+    };
+    return {
+        manifest,
+        watch(listener) {
+            ensureOpen();
+            let active = true;
+            let timer;
+            const reload = async () => {
+                let update;
+                try {
+                    update = await manifest();
+                }
+                catch (error) {
+                    update = error instanceof Error ? error : new Error(String(error));
+                }
+                if (active)
+                    listener(update);
+            };
+            // Directory watching also observes manifests replaced via atomic rename.
+            const watcher = watcherFactory(extensionDir, (_event, file) => {
+                if (file && file !== "package.json" && file !== "package-lock.json")
+                    return;
+                if (timer !== undefined)
+                    debounce.cancel(timer);
+                timer = debounce.schedule(() => {
+                    void reload();
+                }, 100);
+            });
+            watcher.on("error", (error) => {
+                if (active)
+                    listener(error);
+            });
+            const unsubscribe = () => {
+                active = false;
+                if (timer !== undefined)
+                    debounce.cancel(timer);
+                watcher.close();
+                subscriptions.delete(unsubscribe);
+            };
+            subscriptions.add(unsubscribe);
+            return unsubscribe;
+        },
+        dependencies: {
+            check: () => serialize(() => checkExtensionDependencies(dependencyOptions)),
+            install: (installOptions = {}) => serialize(() => installExtensionDependencies({
+                ...dependencyOptions,
+                ...installOptions,
+                ...(options.installer ? { installer: options.installer } : {}),
+            })),
+        },
+        preferences,
+        async savePreferences(name, values, scope) {
+            const { extension, command } = await commandManifest(name);
+            const isExtension = (key) => scope === "extension" ||
+                (extension.preferences.some((p) => p.name === key) &&
+                    !command.preferences.some((p) => p.name === key));
+            await createPreferenceStore({ extensionName: extension.name, dataDir }).save(Object.fromEntries(Object.entries(values).filter(([key]) => isExtension(key))), name, Object.fromEntries(Object.entries(values).filter(([key]) => !isExtension(key))));
+        },
+        launch(name, launchOptions) {
+            const pending = launch(name, launchOptions);
+            launches.add(pending);
+            void pending.finally(() => launches.delete(pending)).catch(() => { });
+            return pending;
+        },
+        close() {
+            return (closing ??= (async () => {
+                closed = true;
+                for (const unsubscribe of subscriptions)
+                    unsubscribe();
+                await Promise.allSettled([queue, ...launches]);
+                await Promise.all([...sessions].map((session) => session.close()));
+            })());
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./broker.js";
+export * from "./bundle.js";
+export * from "./session.js";
+export * from "./storage.js";
+export * from "./oauth.js";
+export * from "./provider.js";
+export * from "./dependencies.js";
+export * from "./client.js";
+export * from "./install-dependencies.js";
+export * from "./preferences.js";
+export { openExtension, MissingLaunchValuesError, DependenciesRequiredError, type OpenExtensionOptions, type ExtensionHandle, type ExtensionLaunchOptions, type DebounceScheduler, type ExtensionWatcher, type ExtensionWatcherFactory, } from "./extension.js";
+export * from "./extension-manifest.js";
+export * from "./engine.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from "./broker.js";
+export * from "./bundle.js";
+export * from "./session.js";
+export * from "./storage.js";
+export * from "./oauth.js";
+export * from "./provider.js";
+export * from "./dependencies.js";
+export * from "./client.js";
+export * from "./install-dependencies.js";
+export * from "./preferences.js";
+export { openExtension, MissingLaunchValuesError, DependenciesRequiredError, } from "./extension.js";
+export * from "./extension-manifest.js";
+export * from "./engine.js";

package/dist/install-dependencies.d.ts

@@ -0,0 +1,30 @@
+import { type SharedDependencyLoader } from "./dependencies.js";
+export type DependencyInstallOptions = {
+    extensionDir: string;
+    dataDir?: string;
+    sharedDependencies?: SharedDependencyLoader;
+};
+export type DependencyInstallStatus = {
+    directory: string;
+    key: string;
+    needed: boolean;
+    pinned: boolean;
+    /** Declared packages unavailable from a matching install or shared fallback. */
+    unresolved: string[];
+    /** Whether the manifest declares every unresolved package and can be installed. */
+    installable: boolean;
+};
+export type DependencyInstaller = (request: {
+    command: string;
+    args: string[];
+    cwd: string;
+    onLog?: (message: string) => void;
+}) => Promise<void>;
+export declare const npmDependencyInstaller: DependencyInstaller;
+/** Cheap disk-only check; a key is published only after a successful install. */
+export declare function checkExtensionDependencies(options: DependencyInstallOptions): Promise<DependencyInstallStatus>;
+/** Installs only production dependencies; never writes to the extension. */
+export declare function installExtensionDependencies(options: DependencyInstallOptions & {
+    installer?: DependencyInstaller;
+    onLog?: (message: string) => void;
+}): Promise<DependencyInstallStatus>;