@alisio/core 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export { BackgroundTaskStore, isLive as isTaskLive, isTerminal as isTaskTerminal
 export { changelogNews, compareVersions, formatChangelogMarkdown, isVersion, loadChangelog, type NewsDecision, parseChangelog, type SelectedEntries, selectEntries, UNRELEASED, } from "./changelog/index.ts";
 export { BUILTIN_COMMANDS, type BuiltinCommand, CommandCatalog, type CommandExecutionContext, type CommandHost, type CommandResult, type CommandSurface, } from "./commands/catalog.ts";
 export { type Config, type ConfigLoadResult, type ConfigProvenance, configFile, configHome, configSchema, isSettableSettingKey, type LoadedConfig, loadConfig, loadConfigWithProvenance, type McpServerSource, OCI_IMAGE_PATTERN, overridesSavedProviderProfile, type SettableSettingInfo, type SettableSettingKey, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.ts";
+export { formatContextGovernorStatsSection, formatContextReport, notableSegments, } from "./context/format.ts";
+export { buildContextReport, MAX_REPORT_SEGMENTS } from "./context/report.ts";
 export { type ContextBudget, checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.ts";
 export type { ApprovalDecision, ApprovalHandler, ApprovalRequest, ArtifactPublisherFactory, BeginRunInput, CapabilityGate, ContextSource, CoreArtifactPublisher, DecisionsFactory, EndRunInput, EventPage, HookFailure, MessagePage, PageOptions, Policy, PublishedArtifactInfo, RunnerExtensions, RunRecord, RunStatus, Session, SessionStore, StoredEvent, TerminalRunStatus, ToolCallMeta, } from "./core/contracts.ts";
 export { HumanWaits } from "./core/human-wait.ts";
@@ -71,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

@@ -32,6 +32,8 @@ export { BackgroundTaskStore, isLive as isTaskLive, isTerminal as isTaskTerminal
 export { changelogNews, compareVersions, formatChangelogMarkdown, isVersion, loadChangelog, parseChangelog, selectEntries, UNRELEASED, } from "./changelog/index.js";
 export { BUILTIN_COMMANDS, CommandCatalog, } from "./commands/catalog.js";
 export { configFile, configHome, configSchema, isSettableSettingKey, loadConfig, loadConfigWithProvenance, OCI_IMAGE_PATTERN, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.js";
+export { formatContextGovernorStatsSection, formatContextReport, notableSegments, } from "./context/format.js";
+export { buildContextReport, MAX_REPORT_SEGMENTS } from "./context/report.js";
 export { checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.js";
 export { HumanWaits } from "./core/human-wait.js";
 export { EXIT_PLAN_TOOL, GOAL_TOOLS, OPT_IN_TOOLS } from "./core/opt-in.js";
@@ -70,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;
+    }
+}