browxai 0.7.0

package/dist/plugin/depgraph.js

@@ -0,0 +1,186 @@
+// Dependency-graph machinery for the plugin runtime.
+//
+// At server start, the resolver materialises each plugin's manifest and
+// hands the runtime a `{plugin -> dependsOn[].plugin}` adjacency. This
+// module:
+//   - Composes those edges into a directed graph.
+//   - Detects cycles via Tarjan's SCC pass (loudly: every plugin in any
+//     non-trivial SCC is named in the error so an adopter can fix it
+//     without re-running with verbose logs).
+//   - Topo-sorts the rest so the runtime loads deps before dependents.
+//   - Exposes per-plugin transitive `dependsOn` closures used by the
+//     runtime's call-graph enforcement (a plugin may call any tool
+//     belonging to a plugin in its TRANSITIVELY-resolved dep set,
+//     plus any core browxai tool).
+//
+// Kept dep-free — node:built-ins only.
+export class DepGraphCycleError extends Error {
+    cycles;
+    constructor(cycles) {
+        const summary = cycles.map((c) => c.join(" → ")).join("; ");
+        super(`plugin runtime: dep-graph contains ${cycles.length} cycle(s) — refusing to load any plugin. ` +
+            `Cycles: ${summary}. Resolve by removing one direction of each cycle from the offending plugin manifest(s).`);
+        this.cycles = cycles;
+        this.name = "DepGraphCycleError";
+    }
+}
+/**
+ * Build the dep graph result. Throws {@link DepGraphCycleError} if any
+ * non-trivial strongly-connected component is found. The error names
+ * every plugin in every cycle.
+ *
+ * Self-edges (`pluginA -> pluginA`) are tolerated and ignored — a
+ * self-edge encodes "this plugin can call its own tools" which is
+ * always-true and harmless.
+ *
+ * Edges pointing at plugins that aren't in `directDeps.keys()` are
+ * tolerated at this layer; the runtime separately validates that
+ * dependsOn targets exist + satisfy their semver range. We only model
+ * what's in the graph here.
+ */
+export function buildDepGraph(input) {
+    const nodes = [...input.directDeps.keys()];
+    // Filter edges to self-edges-out + missing-target-out, since either
+    // poses no cycle risk + is reported elsewhere.
+    const edges = new Map();
+    for (const node of nodes) {
+        const deps = input.directDeps.get(node) ?? [];
+        const filtered = deps.filter((d) => d !== node && input.directDeps.has(d));
+        edges.set(node, filtered);
+    }
+    const cycles = findCycles(nodes, edges);
+    if (cycles.length > 0)
+        throw new DepGraphCycleError(cycles);
+    const loadOrder = topoSort(nodes, edges);
+    const transitiveDeps = computeTransitiveDeps(loadOrder, edges);
+    return { loadOrder, transitiveDeps };
+}
+/**
+ * Tarjan's strongly-connected-components algorithm. A non-trivial SCC
+ * (size > 1) is a cycle; a self-edge in a single-node SCC would also
+ * count but we strip those above so a single-node SCC is always trivial.
+ *
+ * Output is the list of cycles, each cycle being its members in the
+ * order they appear in the SCC.
+ */
+function findCycles(nodes, edges) {
+    let index = 0;
+    const indexOf = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const cycles = [];
+    const strongconnect = (v) => {
+        indexOf.set(v, index);
+        lowlink.set(v, index);
+        index += 1;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of edges.get(v) ?? []) {
+            if (!indexOf.has(w)) {
+                strongconnect(w);
+                lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
+            }
+            else if (onStack.has(w)) {
+                lowlink.set(v, Math.min(lowlink.get(v), indexOf.get(w)));
+            }
+        }
+        if (lowlink.get(v) === indexOf.get(v)) {
+            const component = [];
+            // pop until we pop v
+            while (true) {
+                const w = stack.pop();
+                onStack.delete(w);
+                component.push(w);
+                if (w === v)
+                    break;
+            }
+            if (component.length > 1)
+                cycles.push(component.reverse());
+        }
+    };
+    for (const v of nodes) {
+        if (!indexOf.has(v))
+            strongconnect(v);
+    }
+    return cycles;
+}
+/**
+ * Stable topological sort (Kahn-style). The input is assumed acyclic
+ * (the caller ran `findCycles` first). Within each "indegree==0" cohort
+ * we sort lexicographically so the load order is deterministic across
+ * runs / hosts.
+ */
+function topoSort(nodes, edges) {
+    const indegree = new Map();
+    for (const n of nodes)
+        indegree.set(n, 0);
+    for (const [, deps] of edges) {
+        for (const d of deps) {
+            // Edge n -> d means "n depends on d" — d must load first, so d
+            // gets an outgoing edge to n in the LOAD graph. Equivalently:
+            // each n we visit increments its OWN indegree by the count of
+            // not-yet-loaded deps it has. Cleaner: walk in reverse — process
+            // a node once all its deps have been processed.
+            void d;
+        }
+    }
+    // Compute indegree from the dependency direction. A node's "indegree"
+    // for load purposes is the number of deps that haven't loaded yet.
+    for (const [n, deps] of edges)
+        indegree.set(n, deps.length);
+    const ready = [];
+    for (const [n, deg] of indegree) {
+        if (deg === 0)
+            ready.push(n);
+    }
+    ready.sort();
+    const result = [];
+    // Reverse-edge map so we can decrement dependents when a node loads.
+    const dependents = new Map();
+    for (const n of nodes)
+        dependents.set(n, []);
+    for (const [n, deps] of edges) {
+        for (const d of deps) {
+            dependents.get(d)?.push(n);
+        }
+    }
+    while (ready.length > 0) {
+        const next = ready.shift();
+        result.push(next);
+        for (const dep of dependents.get(next) ?? []) {
+            const left = (indegree.get(dep) ?? 0) - 1;
+            indegree.set(dep, left);
+            if (left === 0) {
+                // Insert sorted.
+                let i = 0;
+                while (i < ready.length && ready[i] < dep)
+                    i += 1;
+                ready.splice(i, 0, dep);
+            }
+        }
+    }
+    if (result.length !== nodes.length) {
+        // Shouldn't happen — cycles would have been caught above. Defensive.
+        throw new Error(`plugin runtime: topo-sort failed (loaded ${result.length} of ${nodes.length}). Re-run with diagnostics on.`);
+    }
+    return result;
+}
+/**
+ * For each plugin, compute the FULL transitive set of plugins it
+ * depends on. Walks the load order (deps-first) so each plugin can
+ * look up its already-computed dep closures.
+ */
+function computeTransitiveDeps(loadOrder, edges) {
+    const result = new Map();
+    for (const n of loadOrder) {
+        const closure = new Set();
+        for (const d of edges.get(n) ?? []) {
+            closure.add(d);
+            for (const t of result.get(d) ?? new Set())
+                closure.add(t);
+        }
+        result.set(n, closure);
+    }
+    return result;
+}

package/dist/plugin/manifest.d.ts

@@ -0,0 +1,182 @@
+import { z } from "zod";
+/**
+ * Trust tiers. The host operator is the only party who can configure which
+ * plugins to enable (via plugins.json), so trust is an advisory signal —
+ * the runtime treats `kalebtec` / `community` / `local` identically at
+ * capability-gate / call-graph-enforcement time. Surfaced on `plugins_list`
+ * so the operator can audit.
+ *
+ *  - `kalebtec`  — published by Kalebtec under `@browxai/plugin-*`.
+ *                  Reference plugins; same release/CI hygiene as the host.
+ *  - `community` — third-party npm packages (`browxai-plugin-*` or
+ *                  `@<org>/browxai-plugin-*`). Adopter installs by name.
+ *  - `local`     — file-path-installed plugins. Used during plugin
+ *                  development (`browxai plugin install file:./my-plugin/`).
+ */
+export declare const TRUST_TIERS: readonly ["kalebtec", "community", "local"];
+export type TrustTier = (typeof TRUST_TIERS)[number];
+/**
+ * Inter-plugin dependency. `plugin` is the npm package name of another
+ * browxai plugin this one composes with. `version` is a semver range the
+ * dep must satisfy (e.g. `^1.0.0`). Matched against the dep plugin's
+ * `package.json#version` at load-time.
+ */
+export declare const dependsOnEntrySchema: z.ZodObject<{
+    plugin: z.ZodString;
+    version: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    plugin: string;
+}, {
+    version: string;
+    plugin: string;
+}>;
+export type DependsOnEntry = z.infer<typeof dependsOnEntrySchema>;
+/**
+ * The full plugin manifest, as embedded under `package.json#browxai`.
+ *
+ *   apiVersion       semver of the plugin-runtime contract the plugin codes
+ *                    against. The runtime advertises its own supported range
+ *                    (see RUNTIME_API_VERSION below); a plugin whose
+ *                    apiVersion does not satisfy is rejected at load-time.
+ *
+ *   browxaiVersion   semver range of the host browxai package the plugin
+ *                    was tested against. Advisory — surfaced in
+ *                    plugins_list, but a mismatch only warns (so a
+ *                    conservative range doesn't lock out a known-good
+ *                    host that already shipped). Authors can tighten this
+ *                    if needed.
+ *
+ *   namespace        MANDATORY tool prefix. Every tool a plugin registers
+ *                    is `<namespace>.<tool>`. The runtime rejects any
+ *                    other shape. Namespaces must be globally unique
+ *                    across the loaded plugin set — two plugins claiming
+ *                    `figma` both fail with a clear error.
+ *
+ *   register         Relative path to the JS module the runtime imports.
+ *                    The module must export a `register(api)` function
+ *                    (default export OR named `register`).
+ *
+ *   capabilities     Capabilities the plugin's tools need. Subset of the
+ *                    server's enabled set at load time. Mismatch →
+ *                    plugin disabled (status: disabled-by-capability-mismatch),
+ *                    server still starts. Empty array means "no
+ *                    capability-gated tools" — perfectly fine.
+ *
+ *   trust            Trust tier. The CLI tags this based on the install
+ *                    source; authors may set it on `kalebtec` packages but
+ *                    the CLI overrides on community / local installs.
+ *
+ *   dependsOn        Other browxai plugins this one calls into. The
+ *                    runtime composes these into a directed graph;
+ *                    cycles abort startup; call-graph enforcement at
+ *                    runtime refuses calls outside the declared
+ *                    transitive set.
+ */
+export declare const browxaiManifestSchema: z.ZodObject<{
+    apiVersion: z.ZodString;
+    browxaiVersion: z.ZodOptional<z.ZodString>;
+    namespace: z.ZodString;
+    register: z.ZodString;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    trust: z.ZodOptional<z.ZodEnum<["kalebtec", "community", "local"]>>;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        plugin: z.ZodString;
+        version: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        plugin: string;
+    }, {
+        version: string;
+        plugin: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    capabilities: string[];
+    register: string;
+    apiVersion: string;
+    namespace: string;
+    dependsOn: {
+        version: string;
+        plugin: string;
+    }[];
+    browxaiVersion?: string | undefined;
+    trust?: "kalebtec" | "community" | "local" | undefined;
+}, {
+    register: string;
+    apiVersion: string;
+    namespace: string;
+    capabilities?: string[] | undefined;
+    browxaiVersion?: string | undefined;
+    trust?: "kalebtec" | "community" | "local" | undefined;
+    dependsOn?: {
+        version: string;
+        plugin: string;
+    }[] | undefined;
+}>;
+export type BrowxaiManifestData = z.infer<typeof browxaiManifestSchema>;
+/**
+ * Fully-resolved plugin manifest the runtime works with. Composes the
+ * Zod-validated `browxai` field with metadata read off the rest of
+ * `package.json` (name, version, description), the absolute path the
+ * plugin was loaded from, and the resolved trust tier (CLI-overridden
+ * for community / local installs).
+ */
+export interface ResolvedManifest {
+    /** npm package name (`package.json#name`). */
+    readonly name: string;
+    /** npm semver of the installed version (`package.json#version`). */
+    readonly version: string;
+    /** Optional human-readable description. */
+    readonly description?: string;
+    /** Absolute path the plugin was loaded from. */
+    readonly path: string;
+    /** Absolute path to the JS entry file (resolved from `register`). */
+    readonly entryPath: string;
+    /** Resolved trust tier (CLI tags community / local installs). */
+    readonly trust: TrustTier;
+    /** Parsed + validated `package.json#browxai` field. */
+    readonly browxai: BrowxaiManifestData;
+}
+/**
+ * The plugin-runtime API contract version. Plugin manifests declare
+ * `apiVersion`; the runtime checks plugin.apiVersion startsWith the
+ * runtime's major.
+ *
+ *  ships 1.0 — the first stable runtime contract. Breaking
+ * changes here are deferred to a major-version bump.
+ */
+export declare const RUNTIME_API_VERSION = "1.0.0";
+/**
+ * Reserved namespaces a plugin may NOT claim. Core browxai tools live in
+ * the implicit-root namespace; reserving the obvious aliases here
+ * prevents an early plugin from squatting them.
+ */
+export declare const RESERVED_NAMESPACES: ReadonlySet<string>;
+/**
+ * Validate a parsed `package.json#browxai` field. Returns the typed
+ * manifest data on success; throws on validation failure. Caller maps
+ * the throw to a `load-error` status (so server start continues).
+ */
+export declare function parseManifestField(raw: unknown): BrowxaiManifestData;
+/**
+ * Lightweight semver-major compatibility check used at apiVersion time.
+ *
+ * The runtime advertises {@link RUNTIME_API_VERSION}; a plugin manifest
+ * carries an apiVersion. We don't pull in a full semver lib — the check
+ * is "the plugin's apiVersion has the same MAJOR as the runtime, and the
+ * plugin's MINOR is ≤ runtime's MINOR". This is the standard semver
+ * "library guarantees backwards compat within a major" assumption and
+ * is enough for the contract.
+ *
+ * A plugin built for `1.0.0` works under runtime `1.5.0`; a plugin built
+ * for `1.5.0` does NOT work under runtime `1.0.0` (newer API surface).
+ * A plugin built for `2.0.0` does NOT work under runtime `1.x` (major
+ * gap).
+ */
+export declare function isApiVersionCompatible(pluginApiVersion: string, runtimeApiVersion?: string): boolean;
+/**
+ * Match a plugin's installed version against a semver range from a
+ * `dependsOn[].version` entry. Kept dep-free; supports the common
+ * shapes (`^x.y.z`, `~x.y.z`, exact, `>=x.y.z`, `*`).
+ */
+export declare function satisfiesRange(version: string, range: string): boolean;

package/dist/plugin/manifest.js

@@ -0,0 +1,219 @@
+// Plugin manifest shape + validator.
+//
+// Every browxai plugin ships a `"browxai"` field on its `package.json`
+// (the standard npm package-metadata file). That field carries the
+// machine-readable contract the runtime resolves against — entry point,
+// tool namespace, declared capabilities, declared dependencies on other
+// plugins, trust tier, the API version range the plugin was built for.
+//
+// Why a sub-field on package.json rather than a sidecar JSON file?
+//   - npm/pnpm already keep `package.json` honest at install time.
+//   - Adopters can `pnpm add` a plugin from npm without an out-of-band
+//     "browxai-config" download step.
+//   - The conventional `package.json` `version` + `name` fields are the
+//     canonical version + identity the runtime trusts.
+//
+// The runtime validates the field with the Zod schema in this module. A
+// failing validation marks the plugin `load-error` with a structured
+// message — server start does NOT abort because of one bad plugin.
+import { z } from "zod";
+/**
+ * Trust tiers. The host operator is the only party who can configure which
+ * plugins to enable (via plugins.json), so trust is an advisory signal —
+ * the runtime treats `kalebtec` / `community` / `local` identically at
+ * capability-gate / call-graph-enforcement time. Surfaced on `plugins_list`
+ * so the operator can audit.
+ *
+ *  - `kalebtec`  — published by Kalebtec under `@browxai/plugin-*`.
+ *                  Reference plugins; same release/CI hygiene as the host.
+ *  - `community` — third-party npm packages (`browxai-plugin-*` or
+ *                  `@<org>/browxai-plugin-*`). Adopter installs by name.
+ *  - `local`     — file-path-installed plugins. Used during plugin
+ *                  development (`browxai plugin install file:./my-plugin/`).
+ */
+export const TRUST_TIERS = ["kalebtec", "community", "local"];
+/**
+ * Inter-plugin dependency. `plugin` is the npm package name of another
+ * browxai plugin this one composes with. `version` is a semver range the
+ * dep must satisfy (e.g. `^1.0.0`). Matched against the dep plugin's
+ * `package.json#version` at load-time.
+ */
+export const dependsOnEntrySchema = z.object({
+    plugin: z.string().min(1, "dependsOn[].plugin: must be a non-empty npm package name"),
+    version: z
+        .string()
+        .min(1, "dependsOn[].version: must be a non-empty semver range, e.g. '^1.0.0'"),
+});
+/**
+ * The full plugin manifest, as embedded under `package.json#browxai`.
+ *
+ *   apiVersion       semver of the plugin-runtime contract the plugin codes
+ *                    against. The runtime advertises its own supported range
+ *                    (see RUNTIME_API_VERSION below); a plugin whose
+ *                    apiVersion does not satisfy is rejected at load-time.
+ *
+ *   browxaiVersion   semver range of the host browxai package the plugin
+ *                    was tested against. Advisory — surfaced in
+ *                    plugins_list, but a mismatch only warns (so a
+ *                    conservative range doesn't lock out a known-good
+ *                    host that already shipped). Authors can tighten this
+ *                    if needed.
+ *
+ *   namespace        MANDATORY tool prefix. Every tool a plugin registers
+ *                    is `<namespace>.<tool>`. The runtime rejects any
+ *                    other shape. Namespaces must be globally unique
+ *                    across the loaded plugin set — two plugins claiming
+ *                    `figma` both fail with a clear error.
+ *
+ *   register         Relative path to the JS module the runtime imports.
+ *                    The module must export a `register(api)` function
+ *                    (default export OR named `register`).
+ *
+ *   capabilities     Capabilities the plugin's tools need. Subset of the
+ *                    server's enabled set at load time. Mismatch →
+ *                    plugin disabled (status: disabled-by-capability-mismatch),
+ *                    server still starts. Empty array means "no
+ *                    capability-gated tools" — perfectly fine.
+ *
+ *   trust            Trust tier. The CLI tags this based on the install
+ *                    source; authors may set it on `kalebtec` packages but
+ *                    the CLI overrides on community / local installs.
+ *
+ *   dependsOn        Other browxai plugins this one calls into. The
+ *                    runtime composes these into a directed graph;
+ *                    cycles abort startup; call-graph enforcement at
+ *                    runtime refuses calls outside the declared
+ *                    transitive set.
+ */
+export const browxaiManifestSchema = z.object({
+    apiVersion: z.string().min(1, "browxai.apiVersion: missing"),
+    browxaiVersion: z.string().min(1, "browxai.browxaiVersion: missing").optional(),
+    namespace: z
+        .string()
+        .min(1, "browxai.namespace: missing")
+        // Lowercase identifier — must not collide with reserved core
+        // namespaces. `_` allowed; no `.`/`:` (those are tool-name separators).
+        .regex(/^[a-z][a-z0-9_]*$/, "browxai.namespace: must match /^[a-z][a-z0-9_]*$/ (lowercase, alphanumeric + underscore, starts with a letter)"),
+    register: z.string().min(1, "browxai.register: missing entry-point path"),
+    capabilities: z.array(z.string()).default([]),
+    trust: z.enum(TRUST_TIERS).optional(),
+    dependsOn: z.array(dependsOnEntrySchema).default([]),
+});
+/**
+ * The plugin-runtime API contract version. Plugin manifests declare
+ * `apiVersion`; the runtime checks plugin.apiVersion startsWith the
+ * runtime's major.
+ *
+ *  ships 1.0 — the first stable runtime contract. Breaking
+ * changes here are deferred to a major-version bump.
+ */
+export const RUNTIME_API_VERSION = "1.0.0";
+/**
+ * Reserved namespaces a plugin may NOT claim. Core browxai tools live in
+ * the implicit-root namespace; reserving the obvious aliases here
+ * prevents an early plugin from squatting them.
+ */
+export const RESERVED_NAMESPACES = new Set([
+    "browxai",
+    "browx",
+    "core",
+    "system",
+    "plugins",
+]);
+/**
+ * Validate a parsed `package.json#browxai` field. Returns the typed
+ * manifest data on success; throws on validation failure. Caller maps
+ * the throw to a `load-error` status (so server start continues).
+ */
+export function parseManifestField(raw) {
+    const parsed = browxaiManifestSchema.parse(raw);
+    if (RESERVED_NAMESPACES.has(parsed.namespace)) {
+        throw new Error(`browxai.namespace: "${parsed.namespace}" is reserved for the core surface. ` +
+            `Pick a project-unique namespace (e.g. "${parsed.namespace}_${Math.floor(Math.random() * 1000)}").`);
+    }
+    return parsed;
+}
+/**
+ * Lightweight semver-major compatibility check used at apiVersion time.
+ *
+ * The runtime advertises {@link RUNTIME_API_VERSION}; a plugin manifest
+ * carries an apiVersion. We don't pull in a full semver lib — the check
+ * is "the plugin's apiVersion has the same MAJOR as the runtime, and the
+ * plugin's MINOR is ≤ runtime's MINOR". This is the standard semver
+ * "library guarantees backwards compat within a major" assumption and
+ * is enough for the contract.
+ *
+ * A plugin built for `1.0.0` works under runtime `1.5.0`; a plugin built
+ * for `1.5.0` does NOT work under runtime `1.0.0` (newer API surface).
+ * A plugin built for `2.0.0` does NOT work under runtime `1.x` (major
+ * gap).
+ */
+export function isApiVersionCompatible(pluginApiVersion, runtimeApiVersion = RUNTIME_API_VERSION) {
+    const a = parseVersion(pluginApiVersion);
+    const b = parseVersion(runtimeApiVersion);
+    if (!a || !b)
+        return false;
+    if (a.major !== b.major)
+        return false;
+    if (a.minor > b.minor)
+        return false;
+    return true;
+}
+function parseVersion(s) {
+    // Tolerate leading `^` / `~` / `>=` / `=` so adopters can paste a
+    // semver-range string into apiVersion. The runtime ignores the operator
+    // and treats the rest as a concrete version.
+    const stripped = s.replace(/^(\^|~|>=|<=|=|>|<)/, "").trim();
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(stripped);
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+/**
+ * Match a plugin's installed version against a semver range from a
+ * `dependsOn[].version` entry. Kept dep-free; supports the common
+ * shapes (`^x.y.z`, `~x.y.z`, exact, `>=x.y.z`, `*`).
+ */
+export function satisfiesRange(version, range) {
+    const trimmed = range.trim();
+    if (trimmed === "*" || trimmed === "")
+        return true;
+    const v = parseVersion(version);
+    if (!v)
+        return false;
+    if (trimmed.startsWith("^")) {
+        const r = parseVersion(trimmed.slice(1));
+        if (!r)
+            return false;
+        if (v.major !== r.major)
+            return false;
+        if (v.major === 0) {
+            // ^0.x.y locks minor too (npm convention).
+            if (v.minor !== r.minor)
+                return false;
+            return v.patch >= r.patch || (v.patch === r.patch && true);
+        }
+        return v.minor > r.minor || (v.minor === r.minor && v.patch >= r.patch);
+    }
+    if (trimmed.startsWith("~")) {
+        const r = parseVersion(trimmed.slice(1));
+        if (!r)
+            return false;
+        if (v.major !== r.major || v.minor !== r.minor)
+            return false;
+        return v.patch >= r.patch;
+    }
+    if (trimmed.startsWith(">=")) {
+        const r = parseVersion(trimmed.slice(2).trim());
+        if (!r)
+            return false;
+        return (v.major > r.major ||
+            (v.major === r.major && v.minor > r.minor) ||
+            (v.major === r.major && v.minor === r.minor && v.patch >= r.patch));
+    }
+    // Exact (with or without leading `=`).
+    const r = parseVersion(trimmed.replace(/^=/, ""));
+    if (!r)
+        return false;
+    return v.major === r.major && v.minor === r.minor && v.patch === r.patch;
+}

package/dist/plugin/package-manager.d.ts

@@ -0,0 +1,22 @@
+/** Package managers the plugin CLI can drive. */
+export type PackageManager = "pnpm" | "npm";
+/** The pnpm-flavoured operations the CLI performs, mapped per manager. */
+export type PmOperation = "add" | "remove" | "update" | "install";
+/** One package manager's integration surface. */
+export interface PackageManagerAdapter {
+    /** The CLI binary name (also the probe target and the spawn command). */
+    readonly name: PackageManager;
+    /** Probe order — the lowest priority that is on PATH wins. pnpm (0) is the
+     *  project's declared manager; npm (1) is the adopter fallback. */
+    readonly priority: number;
+    /** The manager's verb for each browxai plugin operation. */
+    readonly verbs: Record<PmOperation, string>;
+}
+/** Register a package-manager adapter. Add-only: a new manager is one
+ *  `registerPackageManager(...)` call. */
+export declare function registerPackageManager(adapter: PackageManagerAdapter): void;
+/** The registered adapter for a manager, or `undefined` when none is registered. */
+export declare function packageManagerAdapter(name: PackageManager): PackageManagerAdapter | undefined;
+/** All registered adapters, in ascending probe priority — the order
+ *  `detectPackageManager` walks when probing PATH. */
+export declare function packageManagerAdaptersByPriority(): PackageManagerAdapter[];

package/dist/plugin/package-manager.js

@@ -0,0 +1,40 @@
+// Package-manager adapters (RFC 0004 P4 / D6) — the add-only registry that
+// replaces the `PM_VERBS` record (`Record<PackageManager, Record<PmOperation,
+// string>>`). Each supported manager is ONE `PackageManagerAdapter`: its CLI
+// name, its probe priority (lower wins when several are on PATH), and the verb
+// it uses for each browxai plugin operation. Adding `yarn` is one adapter
+// registered here — no edit to `pmArgs` / `detectPackageManager` / the CLI.
+//
+// Behavior-preservation: the pnpm/npm adapters carry the EXACT verb strings the
+// old `PM_VERBS` did, and the probe priority preserves the old
+// "pnpm wins, npm is the fallback" order — so `pmArgs(...)` and
+// `detectPackageManager(...)` return identical results.
+const ADAPTERS = new Map();
+/** Register a package-manager adapter. Add-only: a new manager is one
+ *  `registerPackageManager(...)` call. */
+export function registerPackageManager(adapter) {
+    ADAPTERS.set(adapter.name, adapter);
+}
+/** The registered adapter for a manager, or `undefined` when none is registered. */
+export function packageManagerAdapter(name) {
+    return ADAPTERS.get(name);
+}
+/** All registered adapters, in ascending probe priority — the order
+ *  `detectPackageManager` walks when probing PATH. */
+export function packageManagerAdaptersByPriority() {
+    return [...ADAPTERS.values()].sort((a, b) => a.priority - b.priority);
+}
+// pnpm — the project's native manager (wins detection). Verbs are the canonical
+// pnpm spelling the CLI was written against.
+registerPackageManager({
+    name: "pnpm",
+    priority: 0,
+    verbs: { add: "add", remove: "remove", update: "update", install: "install" },
+});
+// npm — the fallback for `npm install -g browxai` adopters with no pnpm on PATH.
+// `add`→`install`, `remove`→`uninstall`; `update`/`install` keep their names.
+registerPackageManager({
+    name: "npm",
+    priority: 1,
+    verbs: { add: "install", remove: "uninstall", update: "update", install: "install" },
+});