@alisio/core 0.9.0 → 0.10.0

package/dist/application.d.ts

@@ -148,6 +148,11 @@ export interface PluginCatalogEntry {
     enabled: boolean;
     manageable: boolean;
     diagnostic?: string;
+    /**
+     * The npm package name an external plugin was loaded from. Never a path: the catalog stays
+     * path-safe, so file and directory plugins carry no `spec`.
+     */
+    spec?: string;
 }
 export interface ConfiguredProviderCatalog {
     profile: string;

package/dist/application.js

@@ -332,6 +332,7 @@ export async function createApplication(options = {}) {
                         status: enabled ? "active" : "inactive",
                         enabled,
                         manageable: entry.manageable,
+                        ...(isPathSpec(entry.spec) ? {} : { spec: entry.spec }),
                     });
                     runtimePluginEnabled.set(candidate.plugin.id, enabled);
                 }
@@ -349,6 +350,7 @@ export async function createApplication(options = {}) {
                             enabled: true,
                             manageable: entry.manageable,
                             diagnostic: "Activation failed; registrations were rolled back",
+                            ...(isPathSpec(entry.spec) ? {} : { spec: entry.spec }),
                         });
                         continue;
                     }
@@ -364,6 +366,7 @@ export async function createApplication(options = {}) {
                         enabled: true,
                         manageable: false,
                         diagnostic: "Load failed; no path or credential details are shown here",
+                        ...(isPathSpec(entry.spec) ? {} : { spec: entry.spec }),
                     });
                 }
             }

package/dist/changelog/data.js

@@ -2,6 +2,26 @@
 export const CHANGELOG_DATA = {
     schema: 1,
     entries: [
+        {
+            version: "0.10.0",
+            date: "2026-11-07",
+            sections: [
+                {
+                    title: "Added",
+                    items: [
+                        "Settings → Plugins → **Plugin catalog**: browse the published plugins with search, category and tag filters and pages of 10, and install one with a click. The catalog is cached for 24 hours and only downloaded again when it changed; **Check for updates** checks now.",
+                        "**Install from file**: install a private plugin from a `.tgz` made with `npm pack` or `pnpm pack`. The file is validated first (an Alisio plugin, its SDK range, install scripts), the install shows its progress step by step, and temporary files are removed. The package is kept under `~/.config/alisio/plugins/local-packages`, so the original file can be moved or deleted.",
+                        "**Installed plugins**: uninstall a plugin, see when a catalog plugin has a newer version, and update one or all of them. Installing a plugin that is already there updates it in place.",
+                    ],
+                },
+                {
+                    title: "Improved",
+                    items: [
+                        "When `npm` is missing, installing a plugin says so clearly instead of failing with a spawn error. Alisio Desktop bundles its own `npm`, so plugins install without Node.js on the system.",
+                    ],
+                },
+            ],
+        },
         {
             version: "0.9.0",
             date: "2026-11-07",

package/dist/index.d.ts

@@ -73,8 +73,12 @@ export { describePermissionStatus, type EffectState, effectState, FULL_ACCESS_WA
 export { DIAGRAM_MAX_BYTES, DIAGRAM_MAX_NODES, DIAGRAM_SYNTAXES, DIAGRAMS_MAX_ALLOWED, mermaidProblem, type PlanDiagram, validateDiagrams, } from "./plan/diagrams.ts";
 export { buildPlanManifest, parsePlanHeadings, slugifyHeading, } from "./plan/manifest.ts";
 export { claimApprovedPlan, currentPlan, discardApprovedPlan, IMPLEMENTATION_AGENT_ID, implementationPrompt, PLAN_CONTEXT_MAX_CHARS, PLAN_CRITERIA_KEY, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, type PlanFollowUp, type PlanState, type PlanStatus, planHash, readPlanState, settlePlanRun, withdrawPendingPlan, } from "./plan/state.ts";
-export { discoverPlugins, type PluginEnvironment, PluginHost, type PluginHostOptions, pluginPrefix, type ViewInfo, ViewRunError, } from "./plugins/host.ts";
-export { type CliInstallOptions, cliInstall, cliUpdateAll, INSTALL_TIMEOUT_MS, type InstallPluginInput, type InstallPluginResult, type InstallRunner, installedGlobalPluginPackages, installedNpmPlugins, installPlugin, isPeerConflict, npmInstallTarget, type PluginSpec, parsePluginSpec, pluginTrustRemark, printInstallResult, registerPluginInstallTool, sanitizeNpmError, updateAllPlugins, } from "./plugins/install.ts";
+export { discoverPlugins, type PluginEnvironment, PluginHost, type PluginHostOptions, pluginCodeImportedFrom, pluginPrefix, type ViewInfo, ViewRunError, } from "./plugins/host.ts";
+export { type CliInstallOptions, cliInstall, cliUpdateAll, INSTALL_TIMEOUT_MS, type InstallPluginInput, type InstallPluginResult, type InstallRunner, installedGlobalPluginPackages, installedGlobalPlugins, installedNpmPlugins, installPlugin, isPeerConflict, npmInstallTarget, type PluginSpec, parsePluginSpec, pluginDependencySpec, pluginTrustRemark, printInstallResult, registerPluginInstallTool, sanitizeNpmError, type UninstallPluginInput, type UninstallPluginResult, uninstallPlugin, updateAllPlugins, } from "./plugins/install.ts";
+export { type InstallLocalPluginInput, type InstallLocalPluginResult, installLocalPluginTarball, LocalInstallError, type LocalInstallPhase, storedTarballName, } from "./plugins/local-install.ts";
+export { NPM_NOT_FOUND_MESSAGE, type NpmInvocation, resolveNpmInvocation, runNpm, } from "./plugins/npm-runner.ts";
+export { inspectPluginTarball, MAX_TARBALL_BYTES, type PluginTarballInfo, readTarballPackageJson, type TarballLimits, } from "./plugins/tarball.ts";
+export { type CatalogPluginState, type CatalogPluginStateInput, catalogPluginState, comparePluginVersions, satisfiesRange, } from "./plugins/version-compat.ts";
 export * from "./proof/index.ts";
 export { ActiveProvider, ProviderRegistry, UnconfiguredProvider } from "./providers/registry.ts";
 export { availableProviderModels, type ProviderModelCatalog, resolveProviderModel, } from "./providers/routing.ts";

package/dist/index.js

@@ -72,8 +72,12 @@ export { describePermissionStatus, effectState, FULL_ACCESS_WARNING, modeFromFla
 export { DIAGRAM_MAX_BYTES, DIAGRAM_MAX_NODES, DIAGRAM_SYNTAXES, DIAGRAMS_MAX_ALLOWED, mermaidProblem, validateDiagrams, } from "./plan/diagrams.js";
 export { buildPlanManifest, parsePlanHeadings, slugifyHeading, } from "./plan/manifest.js";
 export { claimApprovedPlan, currentPlan, discardApprovedPlan, IMPLEMENTATION_AGENT_ID, implementationPrompt, PLAN_CONTEXT_MAX_CHARS, PLAN_CRITERIA_KEY, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, planHash, readPlanState, settlePlanRun, withdrawPendingPlan, } from "./plan/state.js";
-export { discoverPlugins, PluginHost, pluginPrefix, ViewRunError, } from "./plugins/host.js";
-export { cliInstall, cliUpdateAll, INSTALL_TIMEOUT_MS, installedGlobalPluginPackages, installedNpmPlugins, installPlugin, isPeerConflict, npmInstallTarget, parsePluginSpec, pluginTrustRemark, printInstallResult, registerPluginInstallTool, sanitizeNpmError, updateAllPlugins, } from "./plugins/install.js";
+export { discoverPlugins, PluginHost, pluginCodeImportedFrom, pluginPrefix, ViewRunError, } from "./plugins/host.js";
+export { cliInstall, cliUpdateAll, INSTALL_TIMEOUT_MS, installedGlobalPluginPackages, installedGlobalPlugins, installedNpmPlugins, installPlugin, isPeerConflict, npmInstallTarget, parsePluginSpec, pluginDependencySpec, pluginTrustRemark, printInstallResult, registerPluginInstallTool, sanitizeNpmError, uninstallPlugin, updateAllPlugins, } from "./plugins/install.js";
+export { installLocalPluginTarball, LocalInstallError, storedTarballName, } from "./plugins/local-install.js";
+export { NPM_NOT_FOUND_MESSAGE, resolveNpmInvocation, runNpm, } from "./plugins/npm-runner.js";
+export { inspectPluginTarball, MAX_TARBALL_BYTES, readTarballPackageJson, } from "./plugins/tarball.js";
+export { catalogPluginState, comparePluginVersions, satisfiesRange, } from "./plugins/version-compat.js";
 export * from "./proof/index.js";
 export { ActiveProvider, ProviderRegistry, UnconfiguredProvider } from "./providers/registry.js";
 export { availableProviderModels, resolveProviderModel, } from "./providers/routing.js";

package/dist/plugins/host.d.ts

@@ -37,6 +37,11 @@ export interface ViewInfo {
     description: string;
     params: Record<string, unknown>;
 }
+/**
+ * Whether any plugin file under `dir` was already imported in this process. Such code stays cached
+ * after the package is updated on disk, so the new version only loads after a restart.
+ */
+export declare function pluginCodeImportedFrom(dir: string): boolean;
 export declare class PluginHost implements RunnerExtensions {
     private registry;
     private state;

package/dist/plugins/host.js

@@ -9,7 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createHash } from "node:crypto";
 import { mkdirSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import Ajv from "ajv";
 import { z } from "zod";
@@ -53,6 +53,19 @@ export class ViewRunError extends Error {
     }
 }
 const message = (error) => (error instanceof Error ? error.message : String(error));
+/** Entry files of plugins imported by this process (Node caches an ES module for its lifetime). */
+const importedPluginFiles = new Set();
+/**
+ * Whether any plugin file under `dir` was already imported in this process. Such code stays cached
+ * after the package is updated on disk, so the new version only loads after a restart.
+ */
+export function pluginCodeImportedFrom(dir) {
+    const prefix = dir.endsWith(sep) ? dir : `${dir}${sep}`;
+    for (const file of importedPluginFiles)
+        if (file.startsWith(prefix))
+            return true;
+    return false;
+}
 export class PluginHost {
     registry;
     state;
@@ -222,6 +235,7 @@ export class PluginHost {
         let module;
         try {
             module = await import(__rewriteRelativeImportExtension(pathToFileURL(path).href));
+            importedPluginFiles.add(path);
         }
         catch (error) {
             if (error.code === "ERR_UNKNOWN_FILE_EXTENSION")

package/dist/plugins/install.d.ts

@@ -1,5 +1,5 @@
 import type { ToolRegistry } from "../core/registry.ts";
-import { type ProcessResult } from "../runtime/process.ts";
+import type { ProcessResult } from "../runtime/process.ts";
 export interface PluginSpec {
     name: string;
     version?: string;
@@ -22,6 +22,7 @@ export type InstallRunner = (command: string, args: string[], options: {
     env?: Record<string, string>;
 }) => Promise<ProcessResult>;
 export declare const INSTALL_TIMEOUT_MS = 300000;
+export declare const defaultInstallRunner: InstallRunner;
 export interface InstallPluginInput {
     /** `npm:<package>[@<version>]` or a bare package name. */
     spec: string;
@@ -29,6 +30,11 @@ export interface InstallPluginInput {
     configHome?: string;
     /** Refresh an already-installed package to `@latest`, keeping the npm name in the config. */
     update?: boolean;
+    /**
+     * Run npm even when the package is already installed, at exactly `spec`'s version (an explicit
+     * reinstall or downgrade from the catalog). `update` instead takes `@latest`.
+     */
+    force?: boolean;
     /** Refuse immediately; loading and installing executable plugins is disabled under --read-only. */
     readOnly?: boolean;
     signal?: AbortSignal;
@@ -48,7 +54,9 @@ export interface InstallPluginResult {
     pluginsDir: string;
     /** Already present in the global plugins directory before this call (no npm run performed). */
     alreadyInstalled: boolean;
-    /** Refreshed to `@latest` by this call. */
+    /** Version that was installed before this call, when there was one. */
+    previousVersion?: string;
+    /** Refreshed (to `@latest`, or reinstalled at the requested version) by this call. */
     updated: boolean;
     /** Plain-text remark about where the plugin loads and how project trust applies. */
     trustRemark: string;
@@ -65,8 +73,48 @@ export declare function isPeerConflict(output: string): boolean;
  * `<pluginsDir>/node_modules` (names only; file/directory entries are ignored).
  */
 export declare function installedGlobalPluginPackages(home: string): Promise<string[]>;
+/** Atomically adds `packageName` to the global configuration `plugins` array, preserving all other fields. */
+export declare function persistGlobalPluginEntry(configHomeDir: string, packageName: string): Promise<string>;
+/** Atomically removes `packageName` from the global configuration `plugins` array. */
+export declare function removeGlobalPluginEntry(configHomeDir: string, packageName: string): Promise<boolean>;
+/** The dependency spec npm recorded for `name` in `<pluginsDir>/package.json`, if any. */
+export declare function pluginDependencySpec(pluginsDir: string, name: string): Promise<string | undefined>;
+export declare const LOCAL_PACKAGES_DIR = "local-packages";
+/**
+ * The stored tarball a `file:` dependency spec points at, only when it lives inside
+ * `<pluginsDir>/local-packages` (anything else, including `..` escapes, is never deleted by us).
+ */
+export declare function storedTarballOf(pluginsDir: string, spec: string | undefined): string | undefined;
 /** The shared install routine used by both the CLI command and the `plugin_install` tool. */
 export declare function installPlugin(input: InstallPluginInput): Promise<InstallPluginResult>;
+/** Globally installed plugin packages (configured and present on disk) with their versions. */
+export declare function installedGlobalPlugins(home: string): Promise<Array<{
+    name: string;
+    version: string;
+}>>;
+export interface UninstallPluginInput {
+    /** The npm package name (no `npm:` prefix, no version). */
+    packageName: string;
+    /** Defaults to `configHome()` (ALISIO_CONFIG_HOME, else ~/.config/alisio). */
+    configHome?: string;
+    readOnly?: boolean;
+    signal?: AbortSignal;
+    /** Injected npm for tests; defaults to the real (or bundled) npm. */
+    runner?: InstallRunner;
+}
+export interface UninstallPluginResult {
+    packageName: string;
+    /** The package was installed or configured before this call (false = nothing to do). */
+    removed: boolean;
+    pluginsDir: string;
+    configFile: string;
+}
+/**
+ * Removes a package from the global plugins directory (`npm uninstall --prefix`) and its name from
+ * the global configuration `plugins` array. Idempotent: an absent package only cleans a stale
+ * config entry. The config is untouched when npm fails.
+ */
+export declare function uninstallPlugin(input: UninstallPluginInput): Promise<UninstallPluginResult>;
 export interface UpdateAllPluginsInput {
     configHome?: string;
     readOnly?: boolean;

package/dist/plugins/install.js

@@ -9,13 +9,13 @@
  * still follows the existing executable-plugin policy: it runs in-process wherever it is loaded and
  * is disabled entirely under `--read-only`.
  */
-import { chmod, mkdir, open, readdir, rename, unlink } from "node:fs/promises";
+import { chmod, mkdir, open, readdir, rename, rm, unlink } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { textResult } from "@alisio/sdk";
 import { configHome } from "../config.js";
 import { readJson } from "../runtime/fs.js";
 import { PLUGIN_KEYWORD } from "../runtime/modules.js";
-import { runProcess } from "../runtime/process.js";
+import { runNpm } from "./npm-runner.js";
 /** npm package name: scope (optional) followed by the name; both start with an alphanumeric. */
 const PACKAGE_PART = "[A-Za-z0-9][A-Za-z0-9._-]*";
 const NAME_RE = new RegExp(`^(?:@${PACKAGE_PART}\\/)?${PACKAGE_PART}$`);
@@ -67,7 +67,7 @@ export function npmInstallTarget(name, version, update = false) {
     return update ? `${name}@latest` : version ? `${name}@${version}` : name;
 }
 export const INSTALL_TIMEOUT_MS = 300_000;
-const defaultRunner = (command, args, options) => runProcess(command, args, { ...options, timeoutMs: INSTALL_TIMEOUT_MS, maxBytes: 64_000 });
+export const defaultInstallRunner = (command, args, options) => runNpm(command, args, options, { timeoutMs: INSTALL_TIMEOUT_MS, maxBytes: 64_000 });
 /**
  * Redacts probable secrets from npm output (auth tokens, JWTs, bearer credentials, userinfo in
  * URLs) and caps the size, so a failing install never echoes credentials to the user.
@@ -124,20 +124,29 @@ single) {
     return new Error(`${head}Retry with: ${retry}` +
         (single ? `\n(or: alisio install npm:${single})` : "\n(or: alisio install --update)"));
 }
-/** Atomically adds `packageName` to the global configuration `plugins` array, preserving all other fields. */
-async function persistGlobalPluginEntry(configHomeDir, packageName) {
+/**
+ * Atomically rewrites the global configuration `plugins` array through `update`, preserving every
+ * other field. Returns the file path and whether the array changed (no write when it did not).
+ */
+async function updateGlobalPluginEntries(configHomeDir, update, options) {
     const file = join(configHomeDir, "config.json");
     const existing = await readJson(file);
     let raw;
-    if (existing === undefined)
+    if (existing === undefined) {
+        if (!options.createIfMissing)
+            return { file, changed: false };
         raw = {};
+    }
     else if (typeof existing === "object" && !Array.isArray(existing))
         raw = existing;
     else
         throw new Error(`Global Alisio configuration must be a JSON object: ${file}`);
     const current = Array.isArray(raw.plugins) ? raw.plugins : [];
-    if (!current.includes(packageName))
-        raw.plugins = [...current, packageName];
+    const next = update(current);
+    const changed = next.length !== current.length || next.some((entry, i) => entry !== current[i]);
+    if (!changed && existing !== undefined)
+        return { file, changed: false };
+    raw.plugins = next;
     raw.schemaVersion ??= 1;
     await mkdir(dirname(file), { recursive: true, mode: 0o700 });
     const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
@@ -157,8 +166,38 @@ async function persistGlobalPluginEntry(configHomeDir, packageName) {
         await unlink(temporary).catch(() => { });
         throw error;
     }
+    return { file, changed: true };
+}
+/** Atomically adds `packageName` to the global configuration `plugins` array, preserving all other fields. */
+export async function persistGlobalPluginEntry(configHomeDir, packageName) {
+    const { file } = await updateGlobalPluginEntries(configHomeDir, (current) => (current.includes(packageName) ? current : [...current, packageName]), { createIfMissing: true });
     return file;
 }
+/** Atomically removes `packageName` from the global configuration `plugins` array. */
+export async function removeGlobalPluginEntry(configHomeDir, packageName) {
+    const { changed } = await updateGlobalPluginEntries(configHomeDir, (current) => current.filter((entry) => entry !== packageName), { createIfMissing: false });
+    return changed;
+}
+/** The dependency spec npm recorded for `name` in `<pluginsDir>/package.json`, if any. */
+export async function pluginDependencySpec(pluginsDir, name) {
+    const manifest = (await readJson(join(pluginsDir, "package.json")).catch(() => undefined));
+    const spec = manifest?.dependencies?.[name];
+    return typeof spec === "string" ? spec : undefined;
+}
+export const LOCAL_PACKAGES_DIR = "local-packages";
+/**
+ * The stored tarball a `file:` dependency spec points at, only when it lives inside
+ * `<pluginsDir>/local-packages` (anything else, including `..` escapes, is never deleted by us).
+ */
+export function storedTarballOf(pluginsDir, spec) {
+    if (!spec?.startsWith("file:"))
+        return undefined;
+    const target = resolve(pluginsDir, spec.slice(5));
+    const root = join(pluginsDir, LOCAL_PACKAGES_DIR);
+    if (dirname(target) !== root || !/\.(tgz|tar\.gz)$/.test(target))
+        return undefined;
+    return target;
+}
 /** The shared install routine used by both the CLI command and the `plugin_install` tool. */
 export async function installPlugin(input) {
     const parsed = parsePluginSpec(input.spec);
@@ -172,9 +211,9 @@ export async function installPlugin(input) {
     const installedManifest = (await readJson(join(packageDir, "package.json")));
     const alreadyInstalled = !!installedManifest?.version;
     let updated = false;
-    if (!alreadyInstalled || input.update) {
+    if (!alreadyInstalled || input.update || input.force) {
         const signal = input.signal ?? AbortSignal.timeout(INSTALL_TIMEOUT_MS);
-        const run = input.runner ?? defaultRunner;
+        const run = input.runner ?? defaultInstallRunner;
         const npmResult = await run("npm", [
             "install",
             "--prefix",
@@ -183,7 +222,7 @@ export async function installPlugin(input) {
         ], { cwd: pluginsDir, signal });
         if (npmResult.exitCode !== 0)
             throw npmInstallError(`plugin "${parsed.name}"`, [npmInstallTarget(parsed.name, parsed.version, input.update)], pluginsDir, npmResult, await installedGlobalPluginPackages(home), npmInstallTarget(parsed.name, parsed.version));
-        updated = !!input.update && alreadyInstalled;
+        updated = (!!input.update || !!input.force) && alreadyInstalled;
     }
     const manifest = (await readJson(join(packageDir, "package.json")));
     const installedVersion = manifest?.version ?? "unknown";
@@ -196,10 +235,61 @@ export async function installPlugin(input) {
         configFile,
         pluginsDir,
         alreadyInstalled,
+        ...(installedManifest?.version ? { previousVersion: installedManifest.version } : {}),
         updated,
         trustRemark: pluginTrustRemark(parsed.name),
     };
 }
+/** Globally installed plugin packages (configured and present on disk) with their versions. */
+export async function installedGlobalPlugins(home) {
+    const result = [];
+    for (const name of await installedGlobalPluginPackages(home)) {
+        const manifest = (await readJson(join(home, "plugins", "node_modules", name, "package.json")));
+        result.push({ name, version: manifest?.version ?? "unknown" });
+    }
+    return result;
+}
+/**
+ * Removes a package from the global plugins directory (`npm uninstall --prefix`) and its name from
+ * the global configuration `plugins` array. Idempotent: an absent package only cleans a stale
+ * config entry. The config is untouched when npm fails.
+ */
+export async function uninstallPlugin(input) {
+    const parsed = parsePluginSpec(input.packageName);
+    if (parsed.version !== undefined || input.packageName.trim().startsWith("npm:"))
+        throw new Error(`Invalid package name "${input.packageName}": pass the bare npm package name, without "npm:" or a version`);
+    if (input.readOnly)
+        throw new Error(`Uninstalling npm plugin "${parsed.name}" is unavailable under --read-only: it runs npm and writes your global configuration. Run without --read-only.`);
+    const home = resolve(input.configHome ?? configHome());
+    const pluginsDir = join(home, "plugins");
+    const packageDir = join(pluginsDir, "node_modules", parsed.name);
+    const manifest = (await readJson(join(packageDir, "package.json")));
+    const present = manifest !== undefined;
+    const dependency = await pluginDependencySpec(pluginsDir, parsed.name);
+    const stored = storedTarballOf(pluginsDir, dependency);
+    if (present || dependency !== undefined) {
+        const signal = input.signal ?? AbortSignal.timeout(INSTALL_TIMEOUT_MS);
+        const run = input.runner ?? defaultInstallRunner;
+        const result = await run("npm", ["uninstall", "--prefix", pluginsDir, parsed.name], {
+            cwd: pluginsDir,
+            signal,
+        });
+        if (result.exitCode !== 0) {
+            const detail = sanitizeNpmError([result.stdout, result.stderr].filter(Boolean).join("\n"));
+            throw new Error(`npm uninstall failed for plugin "${parsed.name}" (exit ${result.exitCode}).\n${detail || "no output"}`);
+        }
+    }
+    const { file, changed } = await updateGlobalPluginEntries(home, (current) => current.filter((entry) => entry !== parsed.name), { createIfMissing: false });
+    // The copy kept for a local-file install goes with the package.
+    if (stored)
+        await rm(stored, { force: true });
+    return {
+        packageName: parsed.name,
+        removed: present || changed || stored !== undefined,
+        pluginsDir,
+        configFile: file,
+    };
+}
 /**
  * Refreshes every plugin package installed in the global plugins directory in ONE
  * `npm install --prefix <plugins> <pkg>@latest ...` call, which lets npm resolve all peer ranges
@@ -214,7 +304,7 @@ export async function updateAllPlugins(input) {
     if (names.length === 0)
         return { packages: [], pluginsDir };
     const signal = input.signal ?? AbortSignal.timeout(INSTALL_TIMEOUT_MS);
-    const run = input.runner ?? defaultRunner;
+    const run = input.runner ?? defaultInstallRunner;
     const targets = names.map((name) => npmInstallTarget(name, undefined, true));
     const npmResult = await run("npm", ["install", "--prefix", pluginsDir, ...targets], {
         cwd: pluginsDir,

package/dist/plugins/local-install.d.ts

@@ -0,0 +1,33 @@
+import { type InstallRunner } from "./install.ts";
+import { type PluginTarballInfo } from "./tarball.ts";
+export type LocalInstallPhase = "validating" | "copying" | "installing" | "registering";
+export interface InstallLocalPluginInput {
+    tarballPath: string;
+    configHome?: string;
+    readOnly?: boolean;
+    signal?: AbortSignal;
+    runner?: InstallRunner;
+    /** Called as each phase starts. */
+    onPhase?: (phase: LocalInstallPhase) => void;
+}
+export interface InstallLocalPluginResult {
+    packageName: string;
+    installedVersion: string;
+    previousVersion?: string;
+    /** A version of the package was installed before this call. */
+    alreadyInstalled: boolean;
+    updated: boolean;
+    storedPath: string;
+    /** The dependency spec npm records, relative to the plugins directory. */
+    spec: string;
+    pluginsDir: string;
+    configFile: string;
+    info: PluginTarballInfo;
+}
+/** An install failure that carries the tail of npm's output for the UI. */
+export declare class LocalInstallError extends Error {
+    readonly logTail?: string | undefined;
+    constructor(message: string, logTail?: string | undefined);
+}
+export declare const storedTarballName: (name: string, version: string) => string;
+export declare function installLocalPluginTarball(input: InstallLocalPluginInput): Promise<InstallLocalPluginResult>;

package/dist/plugins/local-install.js

@@ -0,0 +1,121 @@
+/**
+ * Installs a plugin from a local `.tgz` (`npm pack` / `pnpm pack`): private plugins that are never
+ * published. The validated tarball is copied into `<pluginsDir>/local-packages/` and npm installs
+ * FROM THAT COPY, so the `file:` dependency npm records in `<pluginsDir>/package.json` is stable
+ * and self-contained: moving or deleting the original file cannot break a later install of
+ * another plugin. Any failure rolls back (stored copy, partial package, config entry).
+ */
+import { chmod, copyFile, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { configHome } from "../config.js";
+import { readJson } from "../runtime/fs.js";
+import { defaultInstallRunner, INSTALL_TIMEOUT_MS, LOCAL_PACKAGES_DIR, persistGlobalPluginEntry, pluginDependencySpec, removeGlobalPluginEntry, sanitizeNpmError, storedTarballOf, } from "./install.js";
+import { inspectPluginTarball } from "./tarball.js";
+/** An install failure that carries the tail of npm's output for the UI. */
+export class LocalInstallError extends Error {
+    logTail;
+    constructor(message, logTail) {
+        super(message);
+        this.logTail = logTail;
+    }
+}
+const TAIL_CHARS = 1500;
+const safePart = (text) => text.replace(/[^A-Za-z0-9._-]/g, "_");
+export const storedTarballName = (name, version) => `${safePart(name.replace(/^@/, "").replace(/\//g, "-"))}-${safePart(version)}.tgz`;
+export async function installLocalPluginTarball(input) {
+    if (input.readOnly)
+        throw new Error("Installing a plugin from a file is unavailable under --read-only: it runs npm and writes your global configuration. Run without --read-only.");
+    input.onPhase?.("validating");
+    const info = await inspectPluginTarball(input.tarballPath);
+    if (!info.isAlisioPlugin || !info.name || !info.version)
+        throw new Error(`This file is not a valid Alisio plugin package: ${info.reasons.join("; ")}`);
+    const name = info.name;
+    const version = info.version;
+    const home = resolve(input.configHome ?? configHome());
+    const pluginsDir = join(home, "plugins");
+    const localDir = join(pluginsDir, LOCAL_PACKAGES_DIR);
+    const packageDir = join(pluginsDir, "node_modules", name);
+    const run = input.runner ?? defaultInstallRunner;
+    const signal = input.signal ?? AbortSignal.timeout(INSTALL_TIMEOUT_MS);
+    const previous = (await readJson(join(packageDir, "package.json")));
+    const previousSpec = await pluginDependencySpec(pluginsDir, name);
+    const previousStored = storedTarballOf(pluginsDir, previousSpec);
+    // What to reinstall from if an update fails half-way: our stored copy, or the external file a
+    // plugin installed by hand still points at.
+    const previousSource = previousStored ??
+        (previousSpec?.startsWith("file:") ? resolve(pluginsDir, previousSpec.slice(5)) : undefined);
+    const snapshot = async (file) => readFile(file, "utf8").catch(() => undefined);
+    const manifestFiles = ["package.json", "package-lock.json"].map((f) => join(pluginsDir, f));
+    const snapshots = await Promise.all(manifestFiles.map(snapshot));
+    const configBefore = (await readJson(join(home, "config.json")));
+    const inConfig = Array.isArray(configBefore?.plugins) && configBefore.plugins.includes(name);
+    input.onPhase?.("copying");
+    await mkdir(localDir, { recursive: true, mode: 0o700 });
+    const storedPath = join(localDir, storedTarballName(name, version));
+    const backup = `${storedPath}.bak`;
+    const hadStored = await rename(storedPath, backup).then(() => true, () => false);
+    try {
+        await copyFile(input.tarballPath, storedPath);
+        await chmod(storedPath, 0o600);
+        input.onPhase?.("installing");
+        const result = await run("npm", ["install", "--prefix", pluginsDir, storedPath], {
+            cwd: pluginsDir,
+            signal,
+        });
+        if (result.exitCode !== 0) {
+            const tail = sanitizeNpmError([result.stdout, result.stderr].filter(Boolean).join("\n"), 100_000).slice(-TAIL_CHARS);
+            throw new LocalInstallError(`npm install failed for plugin "${name}" (exit ${result.exitCode}).\n${tail || "no output"}`, tail || undefined);
+        }
+        input.onPhase?.("registering");
+        const configFile = await persistGlobalPluginEntry(home, name);
+        await rm(backup, { force: true });
+        if (previousStored && previousStored !== storedPath)
+            await rm(previousStored, { force: true });
+        const manifest = (await readJson(join(packageDir, "package.json")));
+        return {
+            packageName: name,
+            installedVersion: manifest?.version ?? version,
+            ...(previous?.version ? { previousVersion: previous.version } : {}),
+            alreadyInstalled: previous !== undefined,
+            updated: previous !== undefined,
+            storedPath,
+            spec: `file:${LOCAL_PACKAGES_DIR}/${storedTarballName(name, version)}`,
+            pluginsDir,
+            configFile,
+            info,
+        };
+    }
+    catch (error) {
+        await rm(storedPath, { force: true }).catch(() => { });
+        if (hadStored)
+            await rename(backup, storedPath).catch(() => { });
+        if (previous !== undefined && previousSource) {
+            // An update that broke the package: put the previous version back.
+            const current = (await readJson(join(packageDir, "package.json")).catch(() => undefined));
+            if (current?.version !== previous.version)
+                await run("npm", ["install", "--prefix", pluginsDir, previousSource], {
+                    cwd: pluginsDir,
+                    signal: AbortSignal.timeout(INSTALL_TIMEOUT_MS),
+                }).catch(() => undefined);
+        }
+        // npm rewrites the dependency spec; a spec pointing at the copy we just removed would break
+        // every later install.
+        await Promise.all(manifestFiles.map((file, i) => {
+            const before = snapshots[i];
+            return before === undefined ? rm(file, { force: true }) : writeFile(file, before);
+        })).catch(() => { });
+        if (previous === undefined) {
+            // A package that was not there before must not be left half-installed.
+            if (await readJson(join(packageDir, "package.json")).catch(() => undefined)) {
+                await run("npm", ["uninstall", "--prefix", pluginsDir, name], {
+                    cwd: pluginsDir,
+                    signal: AbortSignal.timeout(60_000),
+                }).catch(() => undefined);
+                await rm(packageDir, { recursive: true, force: true }).catch(() => { });
+            }
+            if (!inConfig)
+                await removeGlobalPluginEntry(home, name).catch(() => false);
+        }
+        throw error;
+    }
+}

package/dist/plugins/npm-runner.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How Alisio spawns npm for plugin install and uninstall.
+ *
+ * A system npm is the default. The desktop app ships without Node.js on the user's PATH, so it
+ * bundles npm and points `ALISIO_NPM_CLI` at its `bin/npm-cli.js`: npm then runs through the
+ * executable that is already running (Node, or the Electron binary acting as Node), with no
+ * system npm needed.
+ */
+import { type ProcessResult } from "../runtime/process.ts";
+export declare const NPM_NOT_FOUND_MESSAGE = "npm was not found: install Node.js, or use the desktop app, which bundles it";
+export interface NpmInvocation {
+    command: string;
+    args: string[];
+    /** Present only when the child needs an explicit environment (bundled npm). */
+    env?: Record<string, string>;
+}
+/**
+ * Maps `npm <args>` to the process to spawn. With `ALISIO_NPM_CLI` set, that script runs through
+ * `execPath`, and `ELECTRON_RUN_AS_NODE=1` is added when that executable is Electron.
+ */
+export declare function resolveNpmInvocation(command: string, args: string[], env?: NodeJS.ProcessEnv, versions?: Record<string, string | undefined>, execPath?: string): NpmInvocation;
+/** The default install runner: bounded time and output, bundled npm aware, clear ENOENT error. */
+export declare function runNpm(command: string, args: string[], options: {
+    cwd: string;
+    signal: AbortSignal;
+    env?: Record<string, string>;
+}, limits?: {
+    timeoutMs?: number;
+    maxBytes?: number;
+}): Promise<ProcessResult>;

package/dist/plugins/npm-runner.js

@@ -0,0 +1,66 @@
+/**
+ * How Alisio spawns npm for plugin install and uninstall.
+ *
+ * A system npm is the default. The desktop app ships without Node.js on the user's PATH, so it
+ * bundles npm and points `ALISIO_NPM_CLI` at its `bin/npm-cli.js`: npm then runs through the
+ * executable that is already running (Node, or the Electron binary acting as Node), with no
+ * system npm needed.
+ */
+import { isMissingCommand, runProcess } from "../runtime/process.js";
+export const NPM_NOT_FOUND_MESSAGE = "npm was not found: install Node.js, or use the desktop app, which bundles it";
+/** Env keys the npm child inherits (the default runner env plus what npm needs for its cache/proxy). */
+const NPM_ENV_KEYS = [
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "SystemRoot",
+    "COMSPEC",
+    "LANG",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+    "NODE_EXTRA_CA_CERTS",
+];
+/**
+ * Maps `npm <args>` to the process to spawn. With `ALISIO_NPM_CLI` set, that script runs through
+ * `execPath`, and `ELECTRON_RUN_AS_NODE=1` is added when that executable is Electron.
+ */
+export function resolveNpmInvocation(command, args, env = process.env, versions = process.versions, execPath = process.execPath) {
+    const cli = env.ALISIO_NPM_CLI;
+    if (command !== "npm" || !cli)
+        return { command, args };
+    const childEnv = {};
+    for (const key of NPM_ENV_KEYS) {
+        const value = env[key];
+        if (value)
+            childEnv[key] = value;
+    }
+    if (versions.electron)
+        childEnv.ELECTRON_RUN_AS_NODE = "1";
+    return { command: execPath, args: [cli, ...args], env: childEnv };
+}
+/** The default install runner: bounded time and output, bundled npm aware, clear ENOENT error. */
+export async function runNpm(command, args, options, limits = {}) {
+    const spec = resolveNpmInvocation(command, args);
+    try {
+        return await runProcess(spec.command, spec.args, {
+            cwd: options.cwd,
+            signal: options.signal,
+            ...(spec.env || options.env ? { env: { ...spec.env, ...options.env } } : {}),
+            ...limits,
+        });
+    }
+    catch (error) {
+        if (command === "npm" && isMissingCommand(error))
+            throw new Error(NPM_NOT_FOUND_MESSAGE);
+        throw error;
+    }
+}

package/dist/plugins/tarball.d.ts

@@ -0,0 +1,39 @@
+import type { Readable } from "node:stream";
+export declare const MAX_TARBALL_BYTES: number;
+export declare const MAX_PACKAGE_JSON_BYTES: number;
+export declare const MAX_TARBALL_ENTRIES = 20000;
+export declare const MAX_EXPANDED_BYTES: number;
+export interface TarballLimits {
+    maxPackageJsonBytes?: number;
+    maxEntries?: number;
+    maxExpandedBytes?: number;
+}
+export declare class TarballError extends Error {
+}
+/**
+ * Reads `package/package.json` from a gzip ustar stream. Throws `TarballError` with a user-facing
+ * reason for anything unusable (not gzip, corrupt, unsafe path, over a limit, no manifest).
+ */
+export declare function readTarballPackageJson(source: Readable, limits?: TarballLimits): Promise<{
+    packageJson: unknown;
+    entries: number;
+}>;
+export interface PluginTarballInfo {
+    name?: string;
+    version?: string;
+    description?: string;
+    author?: string;
+    license?: string;
+    /** `peerDependencies["@alisio/sdk"]`. */
+    sdkRange?: string;
+    /** True when every check passed; `reasons` lists what failed otherwise. */
+    isAlisioPlugin: boolean;
+    reasons: string[];
+    /** Declared `preinstall`/`install`/`postinstall` scripts (npm runs them on install). */
+    lifecycleScripts: string[];
+    size: number;
+}
+/** Validates a tarball on disk as an Alisio plugin package; never throws for bad content. */
+export declare function inspectPluginTarball(path: string, limits?: TarballLimits & {
+    maxBytes?: number;
+}): Promise<PluginTarballInfo>;

package/dist/plugins/tarball.js

@@ -0,0 +1,277 @@
+/**
+ * Inspection of a plugin tarball (`.tgz` from `npm pack`/`pnpm pack`) without extracting it and
+ * without any external `tar`: a streaming gzip + ustar reader that only keeps `package/package.json`.
+ * Everything is bounded (compressed size, expanded size, entry count, manifest size) and any entry
+ * path that could escape the package directory rejects the whole archive.
+ */
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createGunzip } from "node:zlib";
+import { PLUGIN_KEYWORD } from "../runtime/modules.js";
+import { parsePluginSpec } from "./install.js";
+import { comparePluginVersions } from "./version-compat.js";
+export const MAX_TARBALL_BYTES = 50 * 1024 * 1024;
+export const MAX_PACKAGE_JSON_BYTES = 1024 * 1024;
+export const MAX_TARBALL_ENTRIES = 20_000;
+export const MAX_EXPANDED_BYTES = 1024 * 1024 * 1024;
+const MAX_META_BYTES = 64 * 1024;
+const LIFECYCLE = ["preinstall", "install", "postinstall"];
+export class TarballError extends Error {
+}
+const str = (block, start, length) => {
+    const slice = block.subarray(start, start + length);
+    const end = slice.indexOf(0);
+    return slice.subarray(0, end < 0 ? slice.length : end).toString("utf8");
+};
+function parseSize(block) {
+    if ((block[124] ?? 0) & 0x80)
+        throw new TarballError("The archive has an entry that is too large");
+    const value = Number.parseInt(str(block, 124, 12).trim() || "0", 8);
+    if (!Number.isFinite(value) || value < 0)
+        throw new TarballError("The archive is corrupt");
+    return value;
+}
+function checksumOk(block) {
+    const stored = Number.parseInt(str(block, 148, 8).trim() || "x", 8);
+    let sum = 0;
+    for (let i = 0; i < 512; i++)
+        sum += i >= 148 && i < 156 ? 0x20 : (block[i] ?? 0);
+    return stored === sum;
+}
+/** Path of the `path=` record of a pax extended header, if any. */
+function paxPath(data) {
+    let offset = 0;
+    while (offset < data.length) {
+        const space = data.indexOf(0x20, offset);
+        if (space < 0)
+            return undefined;
+        const length = Number.parseInt(data.subarray(offset, space).toString("utf8"), 10);
+        if (!Number.isFinite(length) || length <= 0)
+            return undefined;
+        const record = data.subarray(space + 1, offset + length - 1).toString("utf8");
+        if (record.startsWith("path="))
+            return record.slice(5);
+        offset += length;
+    }
+    return undefined;
+}
+/** Normalized entry name; throws for anything that is absolute or climbs out with `..`. */
+function safeName(raw) {
+    const name = raw.replace(/\/+$/, "");
+    if (name.startsWith("/") || name.includes("\\") || /^[A-Za-z]:/.test(name))
+        throw new TarballError(`The archive has an unsafe path: ${raw.slice(0, 80)}`);
+    if (name.split("/").some((part) => part === ".."))
+        throw new TarballError(`The archive has an unsafe path: ${raw.slice(0, 80)}`);
+    return name;
+}
+/**
+ * Reads `package/package.json` from a gzip ustar stream. Throws `TarballError` with a user-facing
+ * reason for anything unusable (not gzip, corrupt, unsafe path, over a limit, no manifest).
+ */
+export async function readTarballPackageJson(source, limits = {}) {
+    const maxJson = limits.maxPackageJsonBytes ?? MAX_PACKAGE_JSON_BYTES;
+    const maxEntries = limits.maxEntries ?? MAX_TARBALL_ENTRIES;
+    const maxExpanded = limits.maxExpandedBytes ?? MAX_EXPANDED_BYTES;
+    const gunzip = createGunzip();
+    source.on("error", (error) => gunzip.destroy(error));
+    source.pipe(gunzip);
+    let state = "header";
+    let buf = Buffer.alloc(0);
+    let remaining = 0;
+    let mode = "skip";
+    let collected = [];
+    let pendingName;
+    let entries = 0;
+    let expanded = 0;
+    let manifest;
+    let padding = 0;
+    const finishData = () => {
+        const data = Buffer.concat(collected);
+        collected = [];
+        if (mode === "manifest")
+            manifest = data;
+        else if (mode === "pax")
+            pendingName = paxPath(data) ?? pendingName;
+        else if (mode === "longname")
+            pendingName = str(data, 0, data.length);
+        mode = "skip";
+    };
+    const header = (block) => {
+        if (block.every((byte) => byte === 0)) {
+            state = "end";
+            return;
+        }
+        if (!checksumOk(block))
+            throw new TarballError("The file is not a valid tar archive (corrupt header checksum)");
+        const prefix = str(block, 345, 155);
+        const own = str(block, 0, 100);
+        const size = parseSize(block);
+        const type = String.fromCharCode(block[156] || 0x30);
+        padding = (512 - (size % 512)) % 512;
+        if (type === "x" || type === "L" || type === "g") {
+            if (size > MAX_META_BYTES)
+                throw new TarballError("The archive has an oversized header record");
+            mode = type === "x" ? "pax" : type === "L" ? "longname" : "skip";
+        }
+        else {
+            entries++;
+            if (entries > maxEntries)
+                throw new TarballError("The archive has too many entries");
+            const name = safeName(pendingName ?? (prefix ? `${prefix}/${own}` : own));
+            pendingName = undefined;
+            mode = "skip";
+            if (name === "package/package.json" && (type === "0" || type === "7")) {
+                if (size > maxJson)
+                    throw new TarballError("package.json is too large");
+                mode = "manifest";
+            }
+        }
+        remaining = size;
+        state = remaining > 0 ? "data" : padding > 0 ? "pad" : "header";
+        if (remaining === 0 && mode !== "skip")
+            finishData();
+    };
+    const pump = () => {
+        for (;;) {
+            if (state === "end")
+                return;
+            if (state === "header") {
+                if (buf.length < 512)
+                    return;
+                const block = buf.subarray(0, 512);
+                buf = buf.subarray(512);
+                header(block);
+                continue;
+            }
+            const take = Math.min(remaining, buf.length);
+            if (take === 0)
+                return;
+            if (state === "data" && mode !== "skip") {
+                collected.push(buf.subarray(0, take));
+            }
+            buf = buf.subarray(take);
+            remaining -= take;
+            if (remaining > 0)
+                return;
+            if (state === "data") {
+                if (mode !== "skip")
+                    finishData();
+                remaining = padding;
+                state = padding > 0 ? "pad" : "header";
+            }
+            else
+                state = "header";
+        }
+    };
+    try {
+        for await (const chunk of gunzip) {
+            expanded += chunk.length;
+            if (expanded > maxExpanded)
+                throw new TarballError("The archive expands beyond the allowed size");
+            buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+            pump();
+        }
+    }
+    catch (error) {
+        if (error instanceof TarballError)
+            throw error;
+        throw new TarballError("The file is not a gzip archive (.tgz)");
+    }
+    finally {
+        source.unpipe(gunzip);
+        source.destroy();
+    }
+    const last = state;
+    if (last !== "end" && last !== "header")
+        throw new TarballError("The archive is truncated");
+    if (entries === 0 && last !== "end")
+        throw new TarballError("The file is not a valid tar archive");
+    if (!manifest)
+        throw new TarballError("The archive has no package/package.json");
+    let packageJson;
+    try {
+        packageJson = JSON.parse(manifest.toString("utf8"));
+    }
+    catch {
+        throw new TarballError("package/package.json is not valid JSON");
+    }
+    return { packageJson, entries };
+}
+const text = (value, max = 500) => typeof value === "string" && value.trim() && value.length <= max ? value.trim() : undefined;
+/** Validates a tarball on disk as an Alisio plugin package; never throws for bad content. */
+export async function inspectPluginTarball(path, limits = {}) {
+    const size = (await stat(path)).size;
+    const info = {
+        isAlisioPlugin: false,
+        reasons: [],
+        lifecycleScripts: [],
+        size,
+    };
+    const maxBytes = limits.maxBytes ?? MAX_TARBALL_BYTES;
+    if (size > maxBytes) {
+        info.reasons.push(`The file is larger than ${Math.round(maxBytes / (1024 * 1024))} MB`);
+        return info;
+    }
+    let json;
+    try {
+        json = (await readTarballPackageJson(createReadStream(path), limits)).packageJson;
+    }
+    catch (error) {
+        info.reasons.push(error instanceof TarballError ? error.message : "The file could not be read");
+        return info;
+    }
+    if (!json || typeof json !== "object" || Array.isArray(json)) {
+        info.reasons.push("package/package.json is not an object");
+        return info;
+    }
+    const pkg = json;
+    const name = text(pkg.name, 214);
+    const version = text(pkg.version, 64);
+    let nameOk = false;
+    if (name) {
+        try {
+            const parsed = parsePluginSpec(name);
+            nameOk = parsed.version === undefined && parsed.name === name;
+        }
+        catch {
+            nameOk = false;
+        }
+    }
+    if (nameOk)
+        info.name = name;
+    else
+        info.reasons.push("The package name is missing or not a valid npm package name");
+    if (version && comparePluginVersions(version, version) !== undefined)
+        info.version = version;
+    else
+        info.reasons.push("The package version is missing or not a valid semver version");
+    const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : [];
+    if (!keywords.includes(PLUGIN_KEYWORD))
+        info.reasons.push(`Not an Alisio plugin: package.json keywords must include "${PLUGIN_KEYWORD}"`);
+    const hasExports = (typeof pkg.exports === "string" && pkg.exports.length > 0) ||
+        (!!pkg.exports && typeof pkg.exports === "object" && Object.keys(pkg.exports).length > 0);
+    if (!hasExports && !text(pkg.main))
+        info.reasons.push('The package has no entry point ("exports" or "main" in package.json)');
+    const description = text(pkg.description, 600);
+    if (description)
+        info.description = description;
+    const author = text(pkg.author) ??
+        (pkg.author && typeof pkg.author === "object"
+            ? text(pkg.author.name)
+            : undefined);
+    if (author)
+        info.author = author;
+    const license = text(pkg.license, 80);
+    if (license)
+        info.license = license;
+    const peers = pkg.peerDependencies;
+    const range = peers && typeof peers === "object"
+        ? text(peers["@alisio/sdk"], 80)
+        : undefined;
+    if (range)
+        info.sdkRange = range;
+    const scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+    info.lifecycleScripts = LIFECYCLE.filter((key) => typeof scripts[key] === "string");
+    info.isAlisioPlugin = info.reasons.length === 0;
+    return info;
+}

package/dist/plugins/version-compat.d.ts

@@ -0,0 +1,20 @@
+/** Negative, zero or positive like a comparator; `undefined` when either version is malformed. */
+export declare function comparePluginVersions(a: string, b: string): number | undefined;
+/** Whether `version` satisfies `range`. An unparseable range or version never satisfies. */
+export declare function satisfiesRange(version: string, range: string): boolean;
+export interface CatalogPluginStateInput {
+    catalogVersion: string;
+    installedVersion?: string;
+    /** The plugin's declared `@alisio/sdk` range. */
+    sdkRange?: string;
+    /** The installed `@alisio/sdk` version, when known. */
+    sdkVersion?: string;
+}
+export interface CatalogPluginState {
+    installedVersion?: string;
+    /** False only when both the range and the SDK version are known and do not match. */
+    compatible: boolean;
+    updateAvailable: boolean;
+}
+/** Install state of one catalog entry against what is installed and the running SDK. */
+export declare function catalogPluginState(input: CatalogPluginStateInput): CatalogPluginState;

package/dist/plugins/version-compat.js

@@ -0,0 +1,154 @@
+function parse(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version.trim());
+    if (!match)
+        return undefined;
+    return {
+        triple: [Number(match[1]), Number(match[2]), Number(match[3])],
+        pre: match[4] ? match[4].split(".") : [],
+    };
+}
+function compareTriples(a, b) {
+    for (let i = 0; i < 3; i++) {
+        const diff = a[i] - b[i];
+        if (diff)
+            return diff;
+    }
+    return 0;
+}
+/** Negative, zero or positive like a comparator; `undefined` when either version is malformed. */
+export function comparePluginVersions(a, b) {
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return undefined;
+    const core = compareTriples(left.triple, right.triple);
+    if (core)
+        return core;
+    if (!left.pre.length || !right.pre.length)
+        return right.pre.length - left.pre.length;
+    const length = Math.max(left.pre.length, right.pre.length);
+    for (let i = 0; i < length; i++) {
+        const x = left.pre[i];
+        const y = right.pre[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xn = /^\d+$/.test(x);
+        const yn = /^\d+$/.test(y);
+        if (xn && yn) {
+            if (Number(x) !== Number(y))
+                return Number(x) - Number(y);
+        }
+        else if (xn !== yn)
+            return xn ? -1 : 1;
+        else if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/** A partial version (`1`, `1.2`, `1.x`, `*`) as its numeric parts (`undefined` = wildcard). */
+function partial(text) {
+    const parts = text.replace(/^v/, "").split(".");
+    if (parts.length > 3 || parts[0] === "")
+        return undefined;
+    const out = [];
+    for (const part of parts) {
+        if (part === "x" || part === "X" || part === "*")
+            out.push(undefined);
+        else if (/^\d+$/.test(part))
+            out.push(Number(part));
+        else
+            return undefined;
+    }
+    while (out.length < 3)
+        out.push(undefined);
+    return out;
+}
+function comparator(token) {
+    const match = /^(\^|~|>=|<=|>|<|=)?\s*(.+)$/.exec(token);
+    if (!match)
+        return undefined;
+    const op = match[1] ?? "";
+    const nums = partial(match[2]);
+    if (!nums)
+        return undefined;
+    const [maj, min, pat] = nums;
+    const floor = [maj ?? 0, min ?? 0, pat ?? 0];
+    const ge = (v) => compareTriples(v, floor) >= 0;
+    if (maj === undefined)
+        return () => true;
+    switch (op) {
+        case "^": {
+            const upper = maj > 0
+                ? [maj + 1, 0, 0]
+                : min === undefined
+                    ? [1, 0, 0]
+                    : min > 0 || pat === undefined
+                        ? [0, min + 1, 0]
+                        : [0, 0, pat + 1];
+            return (v) => ge(v) && compareTriples(v, upper) < 0;
+        }
+        case "~": {
+            const upper = min === undefined ? [maj + 1, 0, 0] : [maj, min + 1, 0];
+            return (v) => ge(v) && compareTriples(v, upper) < 0;
+        }
+        case ">=":
+            return ge;
+        case ">": {
+            const next = pat !== undefined
+                ? [maj, min ?? 0, pat]
+                : min !== undefined
+                    ? [maj, min + 1, 0]
+                    : [maj + 1, 0, 0];
+            return pat !== undefined
+                ? (v) => compareTriples(v, next) > 0
+                : (v) => compareTriples(v, next) >= 0;
+        }
+        case "<":
+            return (v) => compareTriples(v, floor) < 0;
+        case "<=": {
+            const top = pat !== undefined
+                ? [maj, min ?? 0, pat + 1]
+                : min !== undefined
+                    ? [maj, min + 1, 0]
+                    : [maj + 1, 0, 0];
+            return (v) => compareTriples(v, top) < 0;
+        }
+        default: {
+            // Exact or wildcard (`1.2.x`, `1`).
+            if (pat !== undefined)
+                return (v) => compareTriples(v, floor) === 0;
+            const upper = min === undefined ? [maj + 1, 0, 0] : [maj, min + 1, 0];
+            return (v) => ge(v) && compareTriples(v, upper) < 0;
+        }
+    }
+}
+/** Whether `version` satisfies `range`. An unparseable range or version never satisfies. */
+export function satisfiesRange(version, range) {
+    const parsed = parse(version);
+    if (!parsed)
+        return false;
+    const alternatives = range.split("||").map((part) => part.trim());
+    return alternatives.some((alt) => {
+        const tokens = alt
+            .replace(/(\^|~|>=|<=|>|<|=)\s+/g, "$1")
+            .split(/\s+/)
+            .filter(Boolean);
+        if (tokens.length === 0)
+            return false;
+        const checks = tokens.map(comparator);
+        return checks.every((check) => check?.(parsed.triple) === true);
+    });
+}
+/** Install state of one catalog entry against what is installed and the running SDK. */
+export function catalogPluginState(input) {
+    const compatible = !input.sdkRange || !input.sdkVersion ? true : satisfiesRange(input.sdkVersion, input.sdkRange);
+    const updateAvailable = input.installedVersion !== undefined &&
+        (comparePluginVersions(input.catalogVersion, input.installedVersion) ?? 0) > 0;
+    return {
+        compatible,
+        updateAvailable,
+        ...(input.installedVersion !== undefined ? { installedVersion: input.installedVersion } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Embeddable provider-agnostic Alisio agent core: tool loop, context compaction, local tools, MCP, plugin host and SQLite session store. Runs on Node >=22.16 and Bun.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@alisio/sdk": "0.9.0",
+    "@alisio/sdk": "0.10.0",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",