kibi-cli 2.0.0 → 2.2.0

package/dist/plugins/registry.js

@@ -0,0 +1,359 @@
+/*
+ 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, VOCABULARY_ALIGNMENT_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",
+    [VOCABULARY_ALIGNMENT_CAPABILITY_ID]: "vocabularyAlignment",
+};
+/**
+ * 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: [],
+                }),
+            },
+            vocabularyAlignment: {
+                id: "kibi-plugin-builtin-stub.vocabulary",
+                rankSubjects: (input) => ({
+                    decisions: input.clauses.map((clause) => ({
+                        claimKey: clause.claimKey,
+                        choice: "new_subject",
+                        confidence: 0,
+                    })),
+                }),
+                compareClaims: (input) => ({
+                    judgments: input.pairs.map((pair) => ({
+                        pairKey: pair.pairKey,
+                        sameObligation: false,
+                        confidence: 0,
+                    })),
+                }),
+            },
+        },
+    }));
+}
+/** 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 resolveVocabularyAlignment() {
+        return this.resolveCapability(VOCABULARY_ALIGNMENT_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"}

package/dist/plugins/resolve-package.js

@@ -0,0 +1,262 @@
+/*
+ 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 { createRequire } from "node:module";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PluginValidationError } from "kibi-plugin-sdk";
+import { readProjectPackageJson, } from "./project-config.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export class PluginResolutionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PluginResolutionError";
+        this.code = code;
+    }
+}
+function readJson(path) {
+    return JSON.parse(fs.readFileSync(path, "utf8"));
+}
+function nextAncestorDirectory(current) {
+    const parent = dirname(current);
+    return parent === current ? undefined : parent;
+}
+function isWithinRoot(rootPath, candidatePath) {
+    const relativePath = relative(resolve(rootPath), resolve(candidatePath));
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !isAbsolute(relativePath)));
+}
+/**
+ * Bare npm package names only. Paths, URLs, subpaths, and aliases are rejected.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function isBarePackageName(packageName) {
+    const trimmed = packageName.trim();
+    if (!trimmed || trimmed !== packageName)
+        return false;
+    if (trimmed.startsWith(".") ||
+        trimmed.startsWith("/") ||
+        trimmed.includes(":") ||
+        trimmed.includes("\\") ||
+        trimmed.includes("..")) {
+        return false;
+    }
+    // Reject subpath imports (`pkg/sub`) and Windows drive paths.
+    if (trimmed.includes("/") && !trimmed.startsWith("@"))
+        return false;
+    if (trimmed.startsWith("@")) {
+        const parts = trimmed.split("/");
+        if (parts.length !== 2 || !parts[0] || !parts[1])
+            return false;
+        if (parts[1].includes("/"))
+            return false;
+    }
+    return true;
+}
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export function assertBarePackageName(packageName) {
+    if (!isBarePackageName(packageName)) {
+        throw new PluginResolutionError("INVALID_PACKAGE_REFERENCE", `Plugin package '${packageName}' must be a bare package name; paths, URLs, and subpaths are rejected`);
+    }
+}
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export function hasDeclaredProjectDependency(workspaceRoot, packageName, manifest) {
+    const packageJson = manifest ?? readProjectPackageJson(workspaceRoot);
+    return [
+        packageJson.dependencies,
+        packageJson.devDependencies,
+        packageJson.optionalDependencies,
+    ].some((dependencies) => Boolean(dependencies &&
+        typeof dependencies === "object" &&
+        dependencies[packageName]));
+}
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function hasConsumerNodeModulesLink(workspaceRoot, packageName, packageRoot) {
+    try {
+        const linkPath = join(workspaceRoot, "node_modules", ...packageName.split("/"));
+        const linkedRoot = fs.realpathSync(linkPath);
+        return (isWithinRoot(linkedRoot, packageRoot) ||
+            isWithinRoot(packageRoot, linkedRoot));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1, REQ-capability-plugin-observable-behavior-v1
+export function isProjectScopedPackage(workspaceRoot, packageName, packageRoot) {
+    if (isWithinRoot(workspaceRoot, packageRoot))
+        return true;
+    return (hasConsumerNodeModulesLink(workspaceRoot, packageName, packageRoot) ||
+        Boolean(process.versions.pnp));
+}
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function packageJsonForResolvedFile(startPath, expectedPackageName) {
+    let current = resolve(startPath);
+    try {
+        if (!fs.statSync(current).isDirectory())
+            current = dirname(current);
+    }
+    catch {
+        current = dirname(current);
+    }
+    let cursor = current;
+    while (cursor !== undefined) {
+        const packageJsonPath = join(cursor, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            try {
+                const packageJson = readJson(packageJsonPath);
+                if (packageJson.name === expectedPackageName) {
+                    return { packageJsonPath, packageRoot: cursor, packageJson };
+                }
+            }
+            catch {
+                // Keep walking if a parent package manifest is malformed.
+            }
+        }
+        cursor = nextAncestorDirectory(cursor);
+    }
+    return null;
+}
+/**
+ * Confine a resolved entry to the realpath'd package root. Rejects
+ * `exports`/`main` traversal and symlink escapes.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function assertResolvedEntryInsidePackageRoot(packageRoot, entryPath) {
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync(packageRoot);
+    }
+    catch {
+        throw new PluginResolutionError("PACKAGE_NOT_FOUND", `Plugin package root '${packageRoot}' is not readable`);
+    }
+    let realEntry;
+    try {
+        const stats = fs.statSync(entryPath);
+        if (!stats.isFile()) {
+            throw new PluginResolutionError("PACKAGE_ENTRY_NOT_FILE", `Plugin package entry '${entryPath}' is not a regular file`);
+        }
+        realEntry = fs.realpathSync(entryPath);
+    }
+    catch (error) {
+        if (error instanceof PluginResolutionError)
+            throw error;
+        throw new PluginResolutionError("PACKAGE_ENTRY_NOT_FOUND", `Plugin package entry '${entryPath}' does not exist`);
+    }
+    if (!isWithinRoot(realRoot, realEntry)) {
+        throw new PluginResolutionError("PACKAGE_ENTRY_OUTSIDE_ROOT", `Resolved plugin entry '${realEntry}' is outside package root '${realRoot}'`);
+    }
+    return realEntry;
+}
+function candidateFromManifest(packageJson) {
+    const exportsField = packageJson.exports;
+    if (typeof exportsField === "string")
+        return exportsField;
+    if (exportsField &&
+        typeof exportsField === "object" &&
+        !Array.isArray(exportsField)) {
+        const rootExport = exportsField["."];
+        if (typeof rootExport === "string")
+            return rootExport;
+        if (rootExport &&
+            typeof rootExport === "object" &&
+            !Array.isArray(rootExport)) {
+            const conditional = rootExport;
+            if (typeof conditional.import === "string")
+                return conditional.import;
+            if (typeof conditional.default === "string")
+                return conditional.default;
+            if (typeof conditional.require === "string")
+                return conditional.require;
+        }
+    }
+    if (typeof packageJson.module === "string")
+        return packageJson.module;
+    if (typeof packageJson.main === "string")
+        return packageJson.main;
+    return undefined;
+}
+function resolvePackageEntryWithNode(packageRoot, packageJson, packageName, consumerRequire) {
+    let resolved;
+    try {
+        resolved = consumerRequire.resolve(packageName);
+    }
+    catch {
+        resolved = undefined;
+    }
+    if (resolved === undefined) {
+        const candidate = candidateFromManifest(packageJson);
+        if (candidate) {
+            resolved = resolve(packageRoot, candidate);
+        }
+    }
+    if (resolved === undefined) {
+        throw new PluginResolutionError("PACKAGE_ENTRY_NOT_FOUND", `Node could not resolve the root export of '${packageName}' from ${packageRoot}`);
+    }
+    const entryPath = assertResolvedEntryInsidePackageRoot(packageRoot, resolved);
+    return { entryPath, entryUrl: pathToFileURL(entryPath).href };
+}
+/**
+ * Resolve a declared project-local plugin package through the workspace
+ * package.json require graph. NODE_PATH / global / path / URL references fail.
+ */
+// implements REQ-capability-plugin-activation-disclosure-v1
+export function resolveProjectLocalPackage(workspaceRoot, packageName) {
+    assertBarePackageName(packageName);
+    const root = resolve(workspaceRoot);
+    const manifest = readProjectPackageJson(root);
+    if (!hasDeclaredProjectDependency(root, packageName, manifest)) {
+        throw new PluginResolutionError("UNDECLARED_DEPENDENCY", `Plugin package '${packageName}' must be listed in dependencies, devDependencies, or optionalDependencies of ${join(root, "package.json")}`);
+    }
+    const consumerRequire = createRequire(join(root, "package.json"));
+    let packageInfo = null;
+    try {
+        packageInfo = packageJsonForResolvedFile(consumerRequire.resolve(`${packageName}/package.json`), packageName);
+    }
+    catch {
+        try {
+            packageInfo = packageJsonForResolvedFile(consumerRequire.resolve(packageName), packageName);
+        }
+        catch {
+            packageInfo = null;
+        }
+    }
+    if (!packageInfo) {
+        throw new PluginResolutionError("PACKAGE_NOT_FOUND", `No project-local package '${packageName}' was found for ${root}. Install it in that workspace and retry.`);
+    }
+    if (!isProjectScopedPackage(root, packageName, packageInfo.packageRoot)) {
+        throw new PluginResolutionError("PACKAGE_OUTSIDE_WORKSPACE", `Resolved '${packageName}' outside the consumer workspace: ${packageInfo.packageRoot}. Install it in ${root}; global, NODE_PATH, and ambient packages are not supported.`);
+    }
+    const { entryPath, entryUrl } = resolvePackageEntryWithNode(packageInfo.packageRoot, packageInfo.packageJson, packageName, consumerRequire);
+    return {
+        packageName,
+        packageRoot: packageInfo.packageRoot,
+        packageJsonPath: packageInfo.packageJsonPath,
+        packageJson: packageInfo.packageJson,
+        entryPath,
+        entryUrl,
+    };
+}
+/** Re-export for callers that catch SDK validation failures as resolution errors. */
+export { PluginValidationError };