browxai 0.7.0

package/dist/plugin/resolver.d.ts

@@ -0,0 +1,85 @@
+import { type ResolvedManifest, type TrustTier } from "./manifest.js";
+/** Per-entry overrides in the object form of `plugins.json`. */
+export interface PluginEntryOverride {
+    readonly enabled?: boolean;
+    readonly trust?: TrustTier;
+}
+/**
+ * `plugins.json` declaration. Two equivalent shapes accepted for
+ * ergonomics:
+ *
+ *   Array form:
+ *     { "plugins": ["@browxai/plugin-example", ...] }
+ *
+ *   Object form (lets the operator pin trust tier overrides per entry):
+ *     {
+ *       "plugins": {
+ *         "@browxai/plugin-example": { "enabled": true },
+ *         "my-local-plugin": { "enabled": false, "trust": "local" }
+ *       }
+ *     }
+ *
+ * `enabled: false` means "declared but skipped at server start" — used
+ * to disable a plugin without uninstalling it.
+ */
+export interface PluginsJsonFile {
+    readonly plugins: ReadonlyArray<string> | Readonly<Record<string, PluginEntryOverride>>;
+}
+export interface DeclaredPlugin {
+    /** npm package name. */
+    readonly name: string;
+    /** Whether the operator wants it active. */
+    readonly enabled: boolean;
+    /** Optional operator-supplied trust override. */
+    readonly trust?: TrustTier;
+}
+/** Workspace path conventions — single source of truth. The workspace
+ *  root is whatever `resolveWorkspace().root` returns (default
+ *  `~/.browxai/`); the plugin file conventions live directly under it
+ *  so adopters with a custom BROWX_WORKSPACE keep everything in one
+ *  tree. */
+export interface PluginPaths {
+    /** Workspace root — same as `resolveWorkspace().root`. */
+    readonly root: string;
+    /** `<workspace>/plugins.json` — declarative truth. */
+    readonly declarationFile: string;
+    /** `<workspace>/plugins-lock.json` — auto-generated pin. */
+    readonly lockFile: string;
+    /** `<workspace>/plugins/` — install dir for pnpm. */
+    readonly installDir: string;
+    /** `<workspace>/plugins/node_modules/` — pnpm install target. */
+    readonly nodeModulesDir: string;
+}
+export declare function pluginPaths(workspaceRoot: string): PluginPaths;
+/**
+ * Read + normalise the `plugins.json` file. Returns an empty list when
+ * the file is missing or malformed (with a warning) — server start
+ * never aborts on a bad config file.
+ */
+export declare function readDeclaration(paths: PluginPaths): ReadonlyArray<DeclaredPlugin>;
+/**
+ * Result of trying to resolve one declared plugin's manifest off disk.
+ * `kind` discriminates: a `not-installed` entry surfaces as a load
+ * error in the runtime; an `invalid-manifest` entry too. Both keep
+ * server start running.
+ */
+export type ResolveResult = {
+    readonly kind: "resolved";
+    readonly manifest: ResolvedManifest;
+} | {
+    readonly kind: "not-installed";
+    readonly name: string;
+} | {
+    readonly kind: "invalid-manifest";
+    readonly name: string;
+    readonly error: string;
+};
+/**
+ * Resolve one plugin's manifest. Side-effect free — reads `package.json`
+ * and the `browxai` field, validates the field, returns a typed result.
+ *
+ * `trustOverride` (from `plugins.json`) wins; otherwise the trust tier
+ * comes from the manifest itself, defaulting to `community` (the safe
+ * assumption for an externally-sourced plugin).
+ */
+export declare function resolveDeclaredPlugin(paths: PluginPaths, decl: DeclaredPlugin): ResolveResult;

package/dist/plugin/resolver.js

@@ -0,0 +1,166 @@
+// Plugin manifest resolver — reads `<workspace>/plugins.json`
+// and the installed-package manifests under
+// `<workspace>/plugins/node_modules/<pkg>/package.json`.
+//
+// The declarative file (`plugins.json`) is the source of truth for
+// "which plugins should the server load". The lock file
+// (`plugins-lock.json`) carries the resolved version + content-hash
+// pin for reproducibility. The lock is only written / consulted by the
+// CLI install/remove/upgrade/sync commands — the runtime only reads
+// `plugins.json`.
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import { ZodError } from "zod";
+import { log } from "../util/logging.js";
+import { parseManifestField } from "./manifest.js";
+export function pluginPaths(workspaceRoot) {
+    return {
+        root: workspaceRoot,
+        declarationFile: join(workspaceRoot, "plugins.json"),
+        lockFile: join(workspaceRoot, "plugins-lock.json"),
+        installDir: join(workspaceRoot, "plugins"),
+        nodeModulesDir: join(workspaceRoot, "plugins", "node_modules"),
+    };
+}
+/**
+ * Read + normalise the `plugins.json` file. Returns an empty list when
+ * the file is missing or malformed (with a warning) — server start
+ * never aborts on a bad config file.
+ */
+export function readDeclaration(paths) {
+    if (!existsSync(paths.declarationFile))
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(paths.declarationFile, "utf8"));
+    }
+    catch (e) {
+        log.warn(`plugin runtime: ${paths.declarationFile} is malformed — ignoring`, {
+            error: e instanceof Error ? e.message : String(e),
+        });
+        return [];
+    }
+    if (!raw || typeof raw !== "object")
+        return [];
+    const decl = raw.plugins;
+    if (!decl)
+        return [];
+    // `isArrayForm` narrows the union to its array member here and —
+    // crucially — subtracts that member in the `else` branch. The built-in
+    // `Array.isArray` only guards `any[]`, which can't subtract the
+    // `readonly string[]` branch, leaving the `Object.entries` values below
+    // typed as `any`.
+    if (isArrayForm(decl)) {
+        return decl
+            .filter((s) => typeof s === "string" && s.length > 0)
+            .map((name) => ({ name, enabled: true }));
+    }
+    if (typeof decl === "object") {
+        const out = [];
+        for (const [name, entry] of Object.entries(decl)) {
+            if (!entry || typeof entry !== "object")
+                continue;
+            out.push({
+                name,
+                enabled: entry.enabled !== false,
+                ...(entry.trust ? { trust: entry.trust } : {}),
+            });
+        }
+        return out;
+    }
+    return [];
+}
+/**
+ * Resolve one plugin's manifest. Side-effect free — reads `package.json`
+ * and the `browxai` field, validates the field, returns a typed result.
+ *
+ * `trustOverride` (from `plugins.json`) wins; otherwise the trust tier
+ * comes from the manifest itself, defaulting to `community` (the safe
+ * assumption for an externally-sourced plugin).
+ */
+export function resolveDeclaredPlugin(paths, decl) {
+    const pkgRoot = join(paths.nodeModulesDir, decl.name);
+    const pkgJsonPath = join(pkgRoot, "package.json");
+    if (!existsSync(pkgJsonPath)) {
+        return { kind: "not-installed", name: decl.name };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+    }
+    catch (e) {
+        return {
+            kind: "invalid-manifest",
+            name: decl.name,
+            error: `package.json is malformed: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    if (!raw.browxai) {
+        return {
+            kind: "invalid-manifest",
+            name: decl.name,
+            error: `package.json#browxai field is missing — not a browxai plugin`,
+        };
+    }
+    let manifest;
+    try {
+        manifest = parseManifestField(raw.browxai);
+    }
+    catch (e) {
+        if (e instanceof ZodError) {
+            return {
+                kind: "invalid-manifest",
+                name: decl.name,
+                error: e.issues
+                    .map((iss) => `${iss.path.join(".") || "<root>"}: ${iss.message}`)
+                    .join("; "),
+            };
+        }
+        return {
+            kind: "invalid-manifest",
+            name: decl.name,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+    const entryPath = resolvePath(pkgRoot, manifest.register);
+    if (!existsSync(entryPath)) {
+        return {
+            kind: "invalid-manifest",
+            name: decl.name,
+            error: `browxai.register points at ${manifest.register} but resolved path ${entryPath} does not exist`,
+        };
+    }
+    const trust = decl.trust ?? manifest.trust ?? inferTrustFromName(decl.name);
+    return {
+        kind: "resolved",
+        manifest: {
+            name: raw.name ?? decl.name,
+            version: raw.version ?? "0.0.0",
+            ...(raw.description ? { description: raw.description } : {}),
+            path: pkgRoot,
+            entryPath,
+            trust,
+            browxai: manifest,
+        },
+    };
+}
+/**
+ * Heuristic when no explicit trust tier is set: `@browxai/*` is
+ * `kalebtec`; everything else is `community`. Local-path installs are
+ * tagged `local` by the CLI install command (sets the trust field in
+ * the plugins.json entry).
+ */
+function inferTrustFromName(name) {
+    if (name.startsWith("@browxai/"))
+        return "kalebtec";
+    return "community";
+}
+/**
+ * Narrows the `plugins.json` value to its array form. Unlike the built-in
+ * `Array.isArray` (which only guards `any[]`), this predicate is keyed to
+ * the declared union, so the `else` branch correctly leaves only the
+ * object form — keeping `Object.entries` strongly typed.
+ */
+function isArrayForm(decl) {
+    return Array.isArray(decl);
+}

package/dist/plugin/runtime.d.ts

@@ -0,0 +1,77 @@
+import type { z } from "zod";
+import type { Capability } from "../util/capabilities.js";
+import type { PluginRecord, PluginToolHandler, PluginToolResponse } from "./types.js";
+/** Error code emitted when a plugin's `api.callTool` violates the call graph. */
+export declare const PLUGIN_CALL_GRAPH_VIOLATION = "plugin-call-graph-violation";
+export interface RuntimeHostHooks {
+    /**
+     * Tools registered before the runtime engages — i.e. the core browxai
+     * surface (and any earlier plugin tools loaded by a previous batch).
+     * Used by call-graph enforcement: a plugin may always call a core
+     * tool (implicit-root). Core tool names are namespace-less.
+     */
+    isCoreTool(name: string): boolean;
+    /**
+     * Dispatch a tool by name. Routes through the host's wrapped handler
+     * (capability gate, diagnostics, metrics, secrets masking — all the
+     * usual chokepoints). Called by plugin tools through `api.callTool`
+     * AFTER the call-graph check passes.
+     */
+    dispatch(name: string, args: unknown): Promise<PluginToolResponse>;
+    /**
+     * Register a plugin-emitted tool into the host's MCP server +
+     * `toolHandlers` map. The host applies its standard wrapping
+     * (capability gate, metrics, diagnostics) so plugin tools behave
+     * identically to core tools at the dispatch boundary.
+     *
+     * `capability` is whatever the plugin declared for itself — passed
+     * through so the host's gate can refuse if the capability isn't
+     * active. `ownerPlugin` is the npm name of the plugin registering
+     * the tool — kept on the host side so `ownerOf` can answer cross-
+     * plugin lookups.
+     */
+    registerTool(name: string, def: {
+        description: string;
+        inputSchema?: Record<string, z.ZodTypeAny> | undefined;
+    }, handler: PluginToolHandler, capability: string | undefined, ownerPlugin: string): void;
+    /**
+     * Look up the owner of an already-registered plugin tool. Returns
+     * `undefined` for core tools or unknown names.
+     */
+    ownerOf(toolName: string): string | undefined;
+}
+export interface RuntimeStartOptions {
+    /** Absolute path of the workspace root (`resolveWorkspace().root`). */
+    readonly workspaceRoot: string;
+    /** The capability set the server resolved at boot. */
+    readonly enabledCapabilities: ReadonlySet<Capability>;
+    /** Host hooks (see {@link RuntimeHostHooks}). */
+    readonly host: RuntimeHostHooks;
+    /** Optional extra plugin names declared via the config store
+     *  (`set_config({plugins})`). Unioned with the `plugins.json`
+     *  declaration. */
+    readonly extraDeclared?: ReadonlyArray<string>;
+}
+export interface RuntimeStartResult {
+    /** Per-declared-plugin record (loaded OR disabled OR errored). */
+    readonly plugins: ReadonlyArray<PluginRecord>;
+    /** Total tools registered by loaded plugins. */
+    readonly toolCount: number;
+}
+/**
+ * Top-level entry point: read the declaration, resolve manifests,
+ * validate the graph, load each plugin in dep-order.
+ *
+ * Throws ONLY on cycle errors (server start aborts — the contract). All
+ * other failures (capability mismatch, missing dep, validation error,
+ * load-time exception) downgrade the affected plugin to a non-loaded
+ * status and continue.
+ */
+export declare function startPluginRuntime(opts: RuntimeStartOptions): Promise<RuntimeStartResult>;
+/**
+ * Lookup table accessor exposed for the `plugins_info` MCP tool. The
+ * runtime holds an internal `liveTools` map; the result of
+ * {@link startPluginRuntime} is the structured surface — this helper is
+ * just for callers wanting the tool registry view on a plugin.
+ */
+export declare function toolsForPlugin(records: ReadonlyArray<PluginRecord>, pluginName: string): ReadonlyArray<string>;