kibi-cli 1.0.1 → 2.1.0

package/dist/plugins/load-plugin.js

@@ -0,0 +1,59 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { PluginValidationError, validateKibiPlugin, } from "kibi-plugin-sdk";
+import { PluginResolutionError, resolveProjectLocalPackage, } from "./resolve-package.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Dynamically import a project-local plugin package and validate the named
+ * `kibiPlugin` export against kibi.plugin.v1.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export async function loadPluginPackage(workspaceRoot, packageName, options = {}) {
+    const resolvePackage = options.resolvePackage ?? resolveProjectLocalPackage;
+    const importModule = options.importModule ?? ((url) => import(url));
+    const resolved = resolvePackage(workspaceRoot, packageName);
+    let moduleExports;
+    try {
+        moduleExports = await importModule(resolved.entryUrl);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PluginResolutionError("PLUGIN_IMPORT_FAILED", `Failed to import plugin package '${packageName}': ${message}`);
+    }
+    if (!isRecord(moduleExports) || !("kibiPlugin" in moduleExports)) {
+        throw new PluginValidationError("MISSING_KIBI_PLUGIN_EXPORT", `Package '${packageName}' must export a named 'kibiPlugin' binding`);
+    }
+    const plugin = validateKibiPlugin(moduleExports.kibiPlugin);
+    const packageVersion = typeof resolved.packageJson.version === "string"
+        ? resolved.packageJson.version.trim()
+        : "";
+    if (!packageVersion) {
+        throw new PluginValidationError("MISSING_PACKAGE_VERSION", `Package '${packageName}' package.json must declare a version for provider provenance`);
+    }
+    if (plugin.version !== packageVersion) {
+        throw new PluginValidationError("PLUGIN_VERSION_MISMATCH", `Plugin '${plugin.id}' export version '${plugin.version}' does not match resolved package.json version '${packageVersion}'`);
+    }
+    // Host provenance always uses the resolved package manifest version.
+    const stamped = {
+        ...plugin,
+        version: packageVersion,
+    };
+    return { packageName, resolved, plugin: stamped };
+}

package/dist/plugins/project-config.d.ts

@@ -0,0 +1,28 @@
+import { type ProjectKibiConfig } from "kibi-plugin-sdk";
+export type ProjectPackageManifest = Readonly<{
+    name?: string;
+    dependencies?: Readonly<Record<string, string>>;
+    devDependencies?: Readonly<Record<string, string>>;
+    optionalDependencies?: Readonly<Record<string, string>>;
+    peerDependencies?: Readonly<Record<string, string>>;
+    kibi?: unknown;
+}>;
+export declare function readProjectPackageJson(workspaceRoot: string): ProjectPackageManifest;
+/**
+ * Read and validate `package.json#kibi` for capability-plugin activation.
+ * Missing package.json, `kibi`, or `kibi.plugins` yields empty config
+ * (builtin-only), matching historical workspaces without a package manifest.
+ */
+export declare function readProjectKibiConfig(workspaceRoot: string): ProjectKibiConfig;
+export type ConfiguredCapabilityPluginDiagnostic = Readonly<{
+    package: string;
+    capability: string;
+    mode: string;
+    /** True when the package is listed in dependencies, devDependencies, or optionalDependencies. */
+    declared: boolean;
+}>;
+/**
+ * Parsed `package.json#kibi.plugins` rows. Does not import plugin modules.
+ */
+export declare function describeConfiguredCapabilityPlugins(workspaceRoot: string): readonly ConfiguredCapabilityPluginDiagnostic[];
+//# sourceMappingURL=project-config.d.ts.map

package/dist/plugins/project-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-config.d.ts","sourceRoot":"","sources":["../../src/plugins/project-config.ts"],"names":[],"mappings":"AAoBA,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC,CAAC;AAGH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,GACpB,sBAAsB,CAyBxB;AAED;;;;GAIG;AAEH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,GACpB,iBAAiB,CAOnB;AAED,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAkBH;;GAEG;AAGH,wBAAgB,mCAAmC,CACjD,aAAa,EAAE,MAAM,GACpB,SAAS,oCAAoC,EAAE,CAsBjD"}

package/dist/plugins/project-config.js

@@ -0,0 +1,90 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import * as fs from "node:fs";
+import { join } from "node:path";
+import { PluginValidationError, validateProjectKibiConfig, } from "kibi-plugin-sdk";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function readProjectPackageJson(workspaceRoot) {
+    const packageJsonPath = join(workspaceRoot, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        throw new PluginValidationError("MISSING_PACKAGE_JSON", `No package.json found at ${packageJsonPath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PluginValidationError("INVALID_PACKAGE_JSON", `Failed to parse package.json: ${message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PluginValidationError("INVALID_PACKAGE_JSON", "package.json must be a JSON object");
+    }
+    return parsed;
+}
+/**
+ * Read and validate `package.json#kibi` for capability-plugin activation.
+ * Missing package.json, `kibi`, or `kibi.plugins` yields empty config
+ * (builtin-only), matching historical workspaces without a package manifest.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export function readProjectKibiConfig(workspaceRoot) {
+    const packageJsonPath = join(workspaceRoot, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return {};
+    }
+    const manifest = readProjectPackageJson(workspaceRoot);
+    return validateProjectKibiConfig(manifest.kibi);
+}
+// implements REQ-capability-plugin-activation-disclosure-v1
+function dependencyDeclared(manifest, packageName) {
+    return [
+        manifest.dependencies,
+        manifest.devDependencies,
+        manifest.optionalDependencies,
+    ].some((dependencies) => Boolean(dependencies) &&
+        Object.prototype.hasOwnProperty.call(dependencies, packageName));
+}
+/**
+ * Parsed `package.json#kibi.plugins` rows. Does not import plugin modules.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+// covered_by TEST-e2e-capability-plugins
+export function describeConfiguredCapabilityPlugins(workspaceRoot) {
+    const config = readProjectKibiConfig(workspaceRoot);
+    const plugins = config.plugins ?? [];
+    if (plugins.length === 0)
+        return [];
+    const manifest = readProjectPackageJson(workspaceRoot);
+    const rows = [];
+    for (const plugin of plugins) {
+        const declared = dependencyDeclared(manifest, plugin.package);
+        for (const capability of Object.keys(plugin.capabilities)) {
+            const entry = plugin.capabilities[capability];
+            if (!entry)
+                continue;
+            rows.push({
+                package: plugin.package,
+                capability,
+                mode: entry.mode,
+                declared,
+            });
+        }
+    }
+    return rows;
+}

package/dist/plugins/registry.d.ts

@@ -0,0 +1,93 @@
+import { type CapabilityId, type KibiPluginV1, type OntologyPackV1, type PluginMode, type PluginPermissions, type PluginProviderStamp, type ProjectKibiConfig, type SemanticClassifierV1, type SymbolExtractorV1 } from "kibi-plugin-sdk";
+import { type LoadPluginOptions, loadPluginPackage } from "./load-plugin.js";
+export type BuiltinPluginFactory = () => KibiPluginV1 | Promise<KibiPluginV1>;
+export type CapabilityProviderBinding<T> = Readonly<{
+    pluginId: string;
+    pluginVersion: string;
+    packageName: string | null;
+    mode: PluginMode | "builtin";
+    permissions: PluginPermissions;
+    external: boolean;
+    capability: T;
+    stamp: PluginProviderStamp;
+}>;
+export type CapabilityModeResolution<T> = Readonly<{
+    builtin: CapabilityProviderBinding<T>;
+    /** At most one replace provider for this capability. */
+    replace: CapabilityProviderBinding<T> | null;
+    /** Augment providers in package.json activation order. */
+    augment: readonly CapabilityProviderBinding<T>[];
+    /** Shadow providers never participate in canonical results. */
+    shadow: readonly CapabilityProviderBinding<T>[];
+}>;
+export type CapabilityRegistryOptions = Readonly<{
+    workspaceRoot: string;
+    /** Injected builtin plugin; defaults to a local stub. */
+    builtinFactory?: BuiltinPluginFactory;
+    /** Pre-validated project config; skips package.json when provided. */
+    projectConfig?: ProjectKibiConfig;
+    /** Injectable project-config reader for tests. */
+    readConfig?: (workspaceRoot: string) => ProjectKibiConfig;
+    /** Injectable plugin loader for tests. */
+    loadPlugin?: (workspaceRoot: string, packageName: string, options?: LoadPluginOptions) => Promise<Awaited<ReturnType<typeof loadPluginPackage>>>;
+    loadPluginOptions?: LoadPluginOptions;
+}>;
+/**
+ * Minimal builtin used when no factory is injected and the builtin package is
+ * not yet wired. Satisfies kibi.plugin.v1 validation.
+ */
+export declare function createStubBuiltinPlugin(): KibiPluginV1;
+/**
+ * Per-workspace capability registry. Builtin providers are always present;
+ * configured packages load lazily the first time a capability is resolved.
+ * Not a process-wide singleton — inject or construct per test/runtime.
+ */
+export declare class CapabilityRegistry {
+    readonly workspaceRoot: string;
+    private readonly builtinFactory;
+    private readonly readConfig;
+    private readonly loadPlugin;
+    private readonly loadPluginOptions;
+    private readonly injectedConfig;
+    private builtinPluginPromise;
+    private configPromise;
+    private readonly loadedPackages;
+    private readonly capabilityCache;
+    constructor(options: CapabilityRegistryOptions);
+    getBuiltinPlugin(): Promise<KibiPluginV1>;
+    getProjectConfig(): Promise<ProjectKibiConfig>;
+    resolveSemanticClassifiers(): Promise<CapabilityModeResolution<SemanticClassifierV1>>;
+    resolveOntologyPacks(): Promise<CapabilityModeResolution<OntologyPackV1>>;
+    resolveSymbolExtractors(): Promise<CapabilityModeResolution<SymbolExtractorV1>>;
+    resolveCapability(capabilityId: CapabilityId): Promise<CapabilityModeResolution<unknown>>;
+    /**
+     * Canonical providers only (builtin + optional replace + augment).
+     * Shadow bindings are excluded.
+     */
+    canonicalProviders<T>(resolution: CapabilityModeResolution<T>): readonly CapabilityProviderBinding<T>[];
+    private buildCapabilityResolution;
+    private ensurePackageLoaded;
+}
+/**
+ * Explicit cache keyed by workspace root. Injectable — not a hidden global.
+ */
+export declare class CapabilityRegistryCache {
+    private readonly registries;
+    get(workspaceRoot: string): CapabilityRegistry | undefined;
+    getOrCreate(workspaceRoot: string, options?: Omit<CapabilityRegistryOptions, "workspaceRoot">): CapabilityRegistry;
+    set(workspaceRoot: string, registry: CapabilityRegistry): void;
+    clear(): void;
+}
+export declare function createCapabilityRegistry(options: CapabilityRegistryOptions): CapabilityRegistry;
+export declare function createCapabilityRegistryCache(): CapabilityRegistryCache;
+export type EnsureCapabilityRegistryOptions = CapabilityRegistryOptions & {
+    readonly cache?: CapabilityRegistryCache;
+};
+/**
+ * Lazily construct and cache a registry per workspace root.
+ * Callers should supply a cache instance — there is no process-global store.
+ */
+export declare function ensureCapabilityRegistry(workspaceRootOrOptions: string | EnsureCapabilityRegistryOptions, options?: Omit<CapabilityRegistryOptions, "workspaceRoot"> & {
+    readonly cache?: CapabilityRegistryCache;
+}): CapabilityRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/plugins/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/plugins/registry.ts"],"names":[],"mappings":"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"}

package/dist/plugins/registry.js

@@ -0,0 +1,338 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { KIBI_PLUGIN_API_VERSION, ONTOLOGY_PACK_CAPABILITY_ID, SEMANTIC_CLASSIFIER_CAPABILITY_ID, SYMBOL_EXTRACTOR_CAPABILITY_ID, defineKibiPlugin, validateKibiPlugin, } from "kibi-plugin-sdk";
+import { loadPluginPackage } from "./load-plugin.js";
+import { readProjectKibiConfig } from "./project-config.js";
+import { PluginResolutionError } from "./resolve-package.js";
+const CAPABILITY_SLOT = {
+    [SEMANTIC_CLASSIFIER_CAPABILITY_ID]: "semanticClassifier",
+    [ONTOLOGY_PACK_CAPABILITY_ID]: "ontologyPack",
+    [SYMBOL_EXTRACTOR_CAPABILITY_ID]: "symbolExtractor",
+};
+/**
+ * Minimal builtin used when no factory is injected and the builtin package is
+ * not yet wired. Satisfies kibi.plugin.v1 validation.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function createStubBuiltinPlugin() {
+    return validateKibiPlugin(defineKibiPlugin({
+        apiVersion: KIBI_PLUGIN_API_VERSION,
+        id: "kibi-plugin-builtin-stub",
+        version: "0.0.0-stub",
+        permissions: {
+            network: false,
+            metered: false,
+            secrets: [],
+        },
+        capabilities: {
+            semanticClassifier: {
+                id: "kibi-plugin-builtin-stub.classifier",
+                classify: () => ({ decisions: [] }),
+            },
+            ontologyPack: {
+                id: "kibi-plugin-builtin-stub.ontology",
+                schemas: () => [],
+                match: () => [],
+            },
+            symbolExtractor: {
+                id: "kibi-plugin-builtin-stub.symbols",
+                supports: () => false,
+                analyze: (input) => ({
+                    sourceFile: input.path,
+                    language: "unknown",
+                    module: {
+                        title: "stub",
+                        language: "unknown",
+                        analysisMode: "fallback",
+                        fallbackReason: "builtin_stub",
+                    },
+                    symbols: [],
+                }),
+            },
+        },
+    }));
+}
+/** Default host builtin from the published kibi-plugin-builtin package. */
+async function defaultBuiltinFactory() {
+    const mod = (await import("kibi-plugin-builtin"));
+    const plugin = mod.kibiPlugin;
+    if (!plugin) {
+        throw new Error("kibi-plugin-builtin did not export kibiPlugin");
+    }
+    const validated = validateKibiPlugin(plugin);
+    let packageVersion = validated.version;
+    try {
+        const { createRequire } = await import("node:module");
+        const require = createRequire(import.meta.url);
+        const builtinPackageJson = require("kibi-plugin-builtin/package.json");
+        if (typeof builtinPackageJson.version === "string" &&
+            builtinPackageJson.version.trim()) {
+            packageVersion = builtinPackageJson.version.trim();
+        }
+    }
+    catch {
+        // Fall back to the export version when package.json is not resolvable.
+    }
+    if (validated.version !== packageVersion) {
+        throw new Error(`kibi-plugin-builtin export version '${validated.version}' does not match package.json version '${packageVersion}'`);
+    }
+    return { ...validated, version: packageVersion };
+}
+// implements REQ-capability-plugin-activation-disclosure-v1
+function stampFor(plugin, capability, mode, external, model) {
+    return {
+        pluginId: plugin.id,
+        pluginVersion: plugin.version,
+        capability,
+        mode: mode === "builtin" ? "augment" : mode,
+        external,
+        network: plugin.permissions.network,
+        metered: plugin.permissions.metered,
+        ...(model !== undefined ? { model } : {}),
+    };
+}
+// implements REQ-capability-plugin-activation-disclosure-v1
+function disclosedModel(capability) {
+    if (typeof capability !== "object" || capability === null)
+        return undefined;
+    if (!("model" in capability))
+        return undefined;
+    const model = capability.model;
+    return typeof model === "string" && model.trim() !== ""
+        ? model.trim()
+        : undefined;
+}
+function bindingFor(plugin, packageName, mode, capabilityId, capability) {
+    const external = packageName !== null;
+    return {
+        pluginId: plugin.id,
+        pluginVersion: plugin.version,
+        packageName,
+        mode,
+        permissions: plugin.permissions,
+        external,
+        capability,
+        stamp: stampFor(plugin, capabilityId, mode, external, disclosedModel(capability)),
+    };
+}
+function capabilityFromPlugin(plugin, capabilityId) {
+    const slot = CAPABILITY_SLOT[capabilityId];
+    return plugin.capabilities[slot];
+}
+/**
+ * Per-workspace capability registry. Builtin providers are always present;
+ * configured packages load lazily the first time a capability is resolved.
+ * Not a process-wide singleton — inject or construct per test/runtime.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export class CapabilityRegistry {
+    workspaceRoot;
+    builtinFactory;
+    readConfig;
+    loadPlugin;
+    loadPluginOptions;
+    injectedConfig;
+    builtinPluginPromise;
+    configPromise;
+    loadedPackages = new Map();
+    capabilityCache = new Map();
+    constructor(options) {
+        this.workspaceRoot = options.workspaceRoot;
+        this.builtinFactory = options.builtinFactory ?? defaultBuiltinFactory;
+        this.readConfig = options.readConfig ?? readProjectKibiConfig;
+        this.loadPlugin = options.loadPlugin ?? loadPluginPackage;
+        this.loadPluginOptions = options.loadPluginOptions;
+        this.injectedConfig = options.projectConfig;
+    }
+    async getBuiltinPlugin() {
+        this.builtinPluginPromise ??= Promise.resolve(this.builtinFactory()).then((plugin) => validateKibiPlugin(plugin));
+        return this.builtinPluginPromise;
+    }
+    async getProjectConfig() {
+        if (this.injectedConfig !== undefined) {
+            return this.injectedConfig;
+        }
+        this.configPromise ??= Promise.resolve(this.readConfig(this.workspaceRoot));
+        return this.configPromise;
+    }
+    async resolveSemanticClassifiers() {
+        return this.resolveCapability(SEMANTIC_CLASSIFIER_CAPABILITY_ID);
+    }
+    async resolveOntologyPacks() {
+        return this.resolveCapability(ONTOLOGY_PACK_CAPABILITY_ID);
+    }
+    async resolveSymbolExtractors() {
+        return this.resolveCapability(SYMBOL_EXTRACTOR_CAPABILITY_ID);
+    }
+    async resolveCapability(capabilityId) {
+        const cached = this.capabilityCache.get(capabilityId);
+        if (cached)
+            return cached;
+        const promise = this.buildCapabilityResolution(capabilityId);
+        this.capabilityCache.set(capabilityId, promise);
+        try {
+            return await promise;
+        }
+        catch (error) {
+            this.capabilityCache.delete(capabilityId);
+            throw error;
+        }
+    }
+    /**
+     * Canonical providers only (builtin + optional replace + augment).
+     * Shadow bindings are excluded.
+     */
+    canonicalProviders(resolution) {
+        if (resolution.replace) {
+            return [resolution.replace, ...resolution.augment];
+        }
+        return [resolution.builtin, ...resolution.augment];
+    }
+    async buildCapabilityResolution(capabilityId) {
+        const builtinPlugin = await this.getBuiltinPlugin();
+        const builtinCapability = capabilityFromPlugin(builtinPlugin, capabilityId);
+        if (!builtinCapability) {
+            throw new PluginResolutionError("BUILTIN_MISSING_CAPABILITY", `Builtin plugin '${builtinPlugin.id}' does not provide ${capabilityId}`);
+        }
+        const builtin = bindingFor(builtinPlugin, null, "builtin", capabilityId, builtinCapability);
+        const config = await this.getProjectConfig();
+        const entries = config.plugins ?? [];
+        const relevant = entries.filter((entry) => entry.capabilities[capabilityId] !== undefined);
+        let replace = null;
+        const augment = [];
+        const shadow = [];
+        const pluginIds = new Map([
+            [builtinPlugin.id, "kibi-plugin-builtin"],
+        ]);
+        const providerIds = new Set([
+            capabilityFromPlugin(builtinPlugin, capabilityId)?.id ?? builtinPlugin.id,
+        ]);
+        for (const entry of relevant) {
+            const modeConfig = entry.capabilities[capabilityId];
+            if (!modeConfig)
+                continue;
+            const loaded = await this.ensurePackageLoaded(entry);
+            const owner = pluginIds.get(loaded.plugin.id);
+            if (owner !== undefined && owner !== entry.package) {
+                throw new PluginResolutionError("DUPLICATE_PLUGIN_ID", `Plugin id '${loaded.plugin.id}' is claimed by both '${owner}' and '${entry.package}'`);
+            }
+            pluginIds.set(loaded.plugin.id, entry.package);
+            const capability = capabilityFromPlugin(loaded.plugin, capabilityId);
+            if (!capability) {
+                throw new PluginResolutionError("PLUGIN_MISSING_CAPABILITY", `Plugin package '${entry.package}' is activated for ${capabilityId} but does not export that capability`);
+            }
+            if ("id" in capability && typeof capability.id === "string") {
+                if (providerIds.has(capability.id)) {
+                    throw new PluginResolutionError("DUPLICATE_PROVIDER_ID", `Provider id '${capability.id}' for ${capabilityId} is not unique`);
+                }
+                providerIds.add(capability.id);
+            }
+            const binding = bindingFor(loaded.plugin, entry.package, modeConfig.mode, capabilityId, capability);
+            if (modeConfig.mode === "replace") {
+                if (replace !== null) {
+                    throw new PluginResolutionError("MULTIPLE_REPLACE_PROVIDERS", `At most one replace provider is allowed for ${capabilityId}; both '${replace.packageName}' and '${entry.package}' requested replace`);
+                }
+                replace = binding;
+            }
+            else if (modeConfig.mode === "augment") {
+                augment.push(binding);
+            }
+            else {
+                shadow.push(binding);
+            }
+        }
+        return { builtin, replace, augment, shadow };
+    }
+    async ensurePackageLoaded(entry) {
+        const existing = this.loadedPackages.get(entry.package);
+        if (existing)
+            return existing;
+        const loadOptions = this.loadPluginOptions;
+        const promise = this.loadPlugin(this.workspaceRoot, entry.package, loadOptions);
+        this.loadedPackages.set(entry.package, promise);
+        try {
+            return await promise;
+        }
+        catch (error) {
+            if (this.loadedPackages.get(entry.package) === promise) {
+                this.loadedPackages.delete(entry.package);
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * Explicit cache keyed by workspace root. Injectable — not a hidden global.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1
+export class CapabilityRegistryCache {
+    registries = new Map();
+    get(workspaceRoot) {
+        return this.registries.get(workspaceRoot);
+    }
+    getOrCreate(workspaceRoot, options) {
+        const existing = this.registries.get(workspaceRoot);
+        if (existing)
+            return existing;
+        const registry = new CapabilityRegistry({
+            workspaceRoot,
+            ...options,
+        });
+        this.registries.set(workspaceRoot, registry);
+        return registry;
+    }
+    set(workspaceRoot, registry) {
+        this.registries.set(workspaceRoot, registry);
+    }
+    clear() {
+        this.registries.clear();
+    }
+}
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function createCapabilityRegistry(options) {
+    return new CapabilityRegistry(options);
+}
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function createCapabilityRegistryCache() {
+    return new CapabilityRegistryCache();
+}
+/**
+ * Lazily construct and cache a registry per workspace root.
+ * Callers should supply a cache instance — there is no process-global store.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function ensureCapabilityRegistry(workspaceRootOrOptions, options) {
+    if (typeof workspaceRootOrOptions === "string") {
+        const { cache, ...registryOptions } = options ?? {};
+        if (cache) {
+            return cache.getOrCreate(workspaceRootOrOptions, registryOptions);
+        }
+        return new CapabilityRegistry({
+            workspaceRoot: workspaceRootOrOptions,
+            ...registryOptions,
+        });
+    }
+    const { workspaceRoot, cache, ...registryOptions } = workspaceRootOrOptions;
+    if (cache) {
+        return cache.getOrCreate(workspaceRoot, registryOptions);
+    }
+    return new CapabilityRegistry({
+        workspaceRoot,
+        ...registryOptions,
+    });
+}

package/dist/plugins/resolve-package.d.ts

@@ -0,0 +1,47 @@
+import { PluginValidationError } from "kibi-plugin-sdk";
+import { type ProjectPackageManifest } from "./project-config.js";
+export declare class PluginResolutionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type ResolvedProjectPackage = Readonly<{
+    packageName: string;
+    packageRoot: string;
+    packageJsonPath: string;
+    packageJson: ProjectPackageManifest & Readonly<Record<string, unknown>>;
+    /** Absolute filesystem path of the package entry used for dynamic import. */
+    entryPath: string;
+    /** file:// URL for dynamic import. */
+    entryUrl: string;
+}>;
+/**
+ * Bare npm package names only. Paths, URLs, subpaths, and aliases are rejected.
+ */
+export declare function isBarePackageName(packageName: string): boolean;
+export declare function assertBarePackageName(packageName: string): void;
+export declare function hasDeclaredProjectDependency(workspaceRoot: string, packageName: string, manifest?: ProjectPackageManifest): boolean;
+export declare function hasConsumerNodeModulesLink(workspaceRoot: string, packageName: string, packageRoot: string): boolean;
+/**
+ * Same project-scope policy as packages/cursor/bin/launch-kibi-mcp.mjs:
+ * within workspace OR node_modules symlink OR Yarn PnP active resolver.
+ * Rejects NODE_PATH / global / ambient packages.
+ */
+export declare function isProjectScopedPackage(workspaceRoot: string, packageName: string, packageRoot: string): boolean;
+export declare function packageJsonForResolvedFile(startPath: string, expectedPackageName: string): {
+    packageJsonPath: string;
+    packageRoot: string;
+    packageJson: ProjectPackageManifest & Readonly<Record<string, unknown>>;
+} | null;
+/**
+ * Confine a resolved entry to the realpath'd package root. Rejects
+ * `exports`/`main` traversal and symlink escapes.
+ */
+export declare function assertResolvedEntryInsidePackageRoot(packageRoot: string, entryPath: string): string;
+/**
+ * Resolve a declared project-local plugin package through the workspace
+ * package.json require graph. NODE_PATH / global / path / URL references fail.
+ */
+export declare function resolveProjectLocalPackage(workspaceRoot: string, packageName: string): ResolvedProjectPackage;
+/** Re-export for callers that catch SDK validation failures as resolution errors. */
+export { PluginValidationError };
+//# sourceMappingURL=resolve-package.d.ts.map

package/dist/plugins/resolve-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-package.d.ts","sourceRoot":"","sources":["../../src/plugins/resolve-package.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,qBAAqB,CAAC;AAG7B,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAGD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,sBAAsB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxE,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAmBH;;GAEG;AAEH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAoB9D;AAGD,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAO/D;AAGD,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,OAAO,CAaT;AAGD,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAeT;AAED;;;;GAIG;AAEH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAMT;AAGD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,mBAAmB,EAAE,MAAM,GAC1B;IACD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,sBAAsB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzE,GAAG,IAAI,CA0BP;AAED;;;GAGG;AAEH,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,MAAM,CAoCR;AA0DD;;;GAGG;AAEH,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,sBAAsB,CAgExB;AAED,qFAAqF;AACrF,OAAO,EAAE,qBAAqB,EAAE,CAAC"}