@kb-labs/cli-commands 2.30.0 → 2.32.0

package/dist/{discover-DhqYgS-M.d.ts → discover-Cz7X5bQp.d.ts}

@@ -46,6 +46,7 @@ interface RegisteredCommand {
     unavailableReason?: string;
     hint?: string;
     source: 'workspace' | 'node_modules' | 'linked' | 'builtin';
+    scope?: 'platform' | 'project';
     shadowed: boolean;
     pkgRoot?: string;
     packageName?: string;
@@ -55,6 +56,13 @@ interface CommandModule {
 }
 interface DiscoveryResult {
     source: 'workspace' | 'node_modules' | 'linked' | 'builtin';
+    /**
+     * Scope this result came from. Platform-wide discovery (monorepo workspace,
+     * platform node_modules) reports `platform`; discovery from
+     * `<projectRoot>/.kb/plugins/` reports `project`. On collision (same
+     * packageName in both scopes) the platform entry wins — see ADR-0012.
+     */
+    scope: 'platform' | 'project';
     packageName: string;
     manifestPath: string;
     pkgRoot: string;
@@ -88,7 +96,14 @@ interface CacheFile {
     lockfileHash?: string;
     configHash?: string;
     pluginsStateHash?: string;
-    marketplaceLockHash?: string;
+    /** Hash of <platformRoot>/.kb/marketplace.lock. Invalidates when global plugins change. */
+    platformMarketplaceLockHash?: string;
+    /** Hash of <projectRoot>/.kb/marketplace.lock. Invalidates when project-scoped plugins change. */
+    projectMarketplaceLockHash?: string;
+    /** Absolute platform root at the time of caching — cache is invalid if it differs on next run. */
+    platformRoot?: string;
+    /** Absolute project root at the time of caching. */
+    projectRoot?: string;
     packages: Record<string, PackageCacheEntry>;
 }
 type AvailabilityCheck = {
@@ -261,6 +276,7 @@ declare function resetInProcCache(): void;
  */
 declare function discoverManifests(cwd: string, noCache?: boolean, options?: {
     platformRoot?: string;
+    projectRoot?: string;
 }): Promise<DiscoveryResult[]>;
 /**
  * Lazy load manifests for a specific namespace

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CommandGroup, P as ProductGroup, a as Command, R as RegisteredCommand } from './discover-DhqYgS-M.js';
-export { A as AvailabilityCheck, b as CacheFile, c as CommandLookupResult, d as CommandManifest, e as CommandModule, f as CommandType, D as DiscoveryResult, F as FlagDefinition, G as GlobalFlags, g as PackageCacheEntry, h as discoverManifests, i as discoverManifestsByNamespace, j as findCommand, k as findCommandWithType, r as registry } from './discover-DhqYgS-M.js';
+import { C as CommandGroup, P as ProductGroup, a as Command, R as RegisteredCommand } from './discover-Cz7X5bQp.js';
+export { A as AvailabilityCheck, b as CacheFile, c as CommandLookupResult, d as CommandManifest, e as CommandModule, f as CommandType, D as DiscoveryResult, F as FlagDefinition, G as GlobalFlags, g as PackageCacheEntry, h as discoverManifests, i as discoverManifestsByNamespace, j as findCommand, k as findCommandWithType, r as registry } from './discover-Cz7X5bQp.js';
 import { ILogger } from '@kb-labs/core-platform';
 export { TimingTracker } from '@kb-labs/shared-cli-ui';
 import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
@@ -17,6 +17,13 @@ interface RegisterBuiltinCommandsInput {
      * dev-mode behavior unchanged.
      */
     platformRoot?: string;
+    /**
+     * The user's project root (directory containing `.kb/kb.config.{json,jsonc}`).
+     * Discovery uses this to pick up project-scope plugins from
+     * `<projectRoot>/.kb/plugins/` and to invalidate the cache when the
+     * project's `marketplace.lock` changes. When omitted, falls back to `cwd`.
+     */
+    projectRoot?: string;
 }
 declare function registerBuiltinCommands(input?: RegisterBuiltinCommandsInput): Promise<void>;
 

package/dist/index.js

@@ -249,8 +249,8 @@ async function computePluginsStateHash(cwd) {
     return "";
   }
 }
-async function computeMarketplaceLockHash(cwd) {
-  const lockPath = path.join(cwd, ".kb", "marketplace.lock");
+async function computeMarketplaceLockHashAt(root) {
+  const lockPath = path.join(root, ".kb", "marketplace.lock");
   try {
     const content = await promises.readFile(lockPath, "utf8");
     return createHash("sha256").update(content).digest("hex");
@@ -479,22 +479,19 @@ async function discoverWorkspace(cwd) {
       }
     }
   }
-  const localPluginPattern = path.join(
-    ".kb",
-    "plugins",
-    "*",
-    "packages",
-    "*-entry",
-    PACKAGE_JSON
-  );
-  const localPluginFiles = await glob(localPluginPattern, {
-    cwd,
+  return loadManifestsForPackages(packageInfos, "workspace", "platform");
+}
+async function discoverProjectLocalPlugins(projectRoot) {
+  const pattern = path.join(".kb", "plugins", "*", "packages", "*-entry", PACKAGE_JSON);
+  const files = await glob(pattern, {
+    cwd: projectRoot,
     absolute: false,
     ignore: ["**/node_modules/**"]
   });
-  for (const pkgFile of localPluginFiles) {
-    const pkgRoot = path.dirname(path.join(cwd, pkgFile));
-    const pkg = await readPackageJson(path.join(cwd, pkgFile));
+  const packageInfos = [];
+  for (const pkgFile of files) {
+    const pkgRoot = path.dirname(path.join(projectRoot, pkgFile));
+    const pkg = await readPackageJson(path.join(projectRoot, pkgFile));
     if (!pkg) {
       continue;
     }
@@ -503,6 +500,9 @@ async function discoverWorkspace(cwd) {
       packageInfos.push({ pkgRoot, pkg, manifestPath: manifestInfo.path });
     }
   }
+  return loadManifestsForPackages(packageInfos, "linked", "project");
+}
+async function loadManifestsForPackages(packageInfos, source, scope) {
   const loadPromises = packageInfos.map(async ({ pkgRoot, pkg, manifestPath }) => {
     const pkgStart = Date.now();
     try {
@@ -515,7 +515,8 @@ async function discoverWorkspace(cwd) {
         validateUniqueIds(manifests, pkg.name);
         return {
           manifests,
-          source: "workspace",
+          source,
+          scope,
           packageName: pkg.name,
           manifestPath: toPosixPath(manifestPath),
           pkgRoot: toPosixPath(pkgRoot)
@@ -536,7 +537,8 @@ async function discoverWorkspace(cwd) {
       const synthetic = createUnavailableManifest(pkg.name, err);
       return {
         manifests: [synthetic],
-        source: "workspace",
+        source,
+        scope,
         packageName: pkg.name,
         manifestPath: toPosixPath(manifestPath),
         pkgRoot: toPosixPath(pkgRoot)
@@ -570,6 +572,9 @@ async function discoverCurrentPackage(cwd) {
         return {
           manifests,
           source: "workspace",
+          // Current-package fallback fires in installed mode when the user's
+          // project itself exposes a manifest. That maps to the project scope.
+          scope: "project",
           packageName: pkg.name,
           manifestPath: toPosixPath(manifestInfo.path),
           pkgRoot: toPosixPath(cwd)
@@ -674,6 +679,10 @@ async function discoverNodeModules(cwd) {
           return {
             manifests,
             source: isLinked ? "linked" : "node_modules",
+            // node_modules discovery runs at the platform root. In dev mode
+            // platformRoot === projectRoot so either label is correct; we use
+            // platform to reflect where the manifest physically lives.
+            scope: "platform",
             packageName: pkg.name,
             manifestPath: toPosixPath(manifestPath),
             pkgRoot: toPosixPath(pkgRoot)
@@ -693,6 +702,7 @@ async function discoverNodeModules(cwd) {
         return {
           manifests: [synthetic],
           source: isLinked ? "linked" : "node_modules",
+          scope: "platform",
           packageName: pkg.name,
           manifestPath: toPosixPath(manifestPath),
           pkgRoot: toPosixPath(pkgRoot)
@@ -724,17 +734,35 @@ function deduplicateManifests(all) {
     const existing = byPackageName.get(result.packageName);
     if (!existing) {
       byPackageName.set(result.packageName, result);
-    } else {
-      const existingPriority = priority[existing.source] || 0;
-      const newPriority = priority[result.source] || 0;
-      if (newPriority > existingPriority) {
-        byPackageName.set(result.packageName, result);
+      continue;
+    }
+    if (existing.scope !== result.scope) {
+      if (existing.pkgRoot === result.pkgRoot) {
+        const projectEntry = existing.scope === "project" ? existing : result;
+        byPackageName.set(result.packageName, projectEntry);
+        continue;
       }
+      const winner = existing.scope === "platform" ? existing : result;
+      const loser = existing.scope === "platform" ? result : existing;
+      log("warn", JSON.stringify({
+        code: "DISCOVERY_SCOPE_COLLISION",
+        packageName: result.packageName,
+        platformPath: winner.pkgRoot,
+        projectPath: loser.pkgRoot,
+        message: "Package exists in both platform and project scopes \u2014 platform wins."
+      }));
+      byPackageName.set(result.packageName, winner);
+      continue;
+    }
+    const existingPriority = priority[existing.source] ?? 0;
+    const newPriority = priority[result.source] ?? 0;
+    if (newPriority > existingPriority) {
+      byPackageName.set(result.packageName, result);
     }
   }
   return Array.from(byPackageName.values());
 }
-async function loadCache(cwd) {
+async function loadCache(cwd, roots) {
   const cachePath = path.join(cwd, ".kb", "cache", "cli-manifests.json");
   try {
     const content = await promises.readFile(cachePath, "utf8");
@@ -771,11 +799,26 @@ async function loadCache(cwd) {
       log("debug", "Cache invalidated: .kb/plugins.json changed");
       return null;
     }
-    const currentMarketplaceLockHash = await computeMarketplaceLockHash(cwd);
-    if (currentMarketplaceLockHash && cache.marketplaceLockHash && cache.marketplaceLockHash !== currentMarketplaceLockHash) {
-      log("debug", "Cache invalidated: .kb/marketplace.lock changed");
+    if (cache.platformRoot && cache.platformRoot !== roots.platformRoot) {
+      log("debug", `Cache invalidated: platformRoot changed (${cache.platformRoot} \u2192 ${roots.platformRoot})`);
+      return null;
+    }
+    if (cache.projectRoot && cache.projectRoot !== roots.projectRoot) {
+      log("debug", `Cache invalidated: projectRoot changed (${cache.projectRoot} \u2192 ${roots.projectRoot})`);
+      return null;
+    }
+    const currentPlatformLockHash = await computeMarketplaceLockHashAt(roots.platformRoot);
+    if (currentPlatformLockHash && cache.platformMarketplaceLockHash && cache.platformMarketplaceLockHash !== currentPlatformLockHash) {
+      log("debug", `Cache invalidated: ${roots.platformRoot}/.kb/marketplace.lock changed`);
       return null;
     }
+    if (roots.projectRoot !== roots.platformRoot) {
+      const currentProjectLockHash = await computeMarketplaceLockHashAt(roots.projectRoot);
+      if (currentProjectLockHash && cache.projectMarketplaceLockHash && cache.projectMarketplaceLockHash !== currentProjectLockHash) {
+        log("debug", `Cache invalidated: ${roots.projectRoot}/.kb/marketplace.lock changed`);
+        return null;
+      }
+    }
     const parsedCache = cache;
     parsedCache.ttlMs = parsedCache.ttlMs ?? DISK_CACHE_TTL_MS;
     for (const entry of Object.values(parsedCache.packages)) {
@@ -827,7 +870,7 @@ async function isPackageCacheStale(entry, options) {
   }
   return false;
 }
-async function saveCache(cwd, results) {
+async function saveCache(cwd, results, roots) {
   const cachePath = path.join(cwd, ".kb", "cache", "cli-manifests.json");
   await promises.mkdir(path.dirname(cachePath), { recursive: true });
   const packages = {};
@@ -873,7 +916,8 @@ async function saveCache(cwd, results) {
   const lockfileHash = await computeLockfileHash(cwd);
   const configHash = await computeConfigHash(cwd);
   const pluginsStateHash = await computePluginsStateHash(cwd);
-  const marketplaceLockHash = await computeMarketplaceLockHash(cwd);
+  const platformMarketplaceLockHash = await computeMarketplaceLockHashAt(roots.platformRoot);
+  const projectMarketplaceLockHash = roots.projectRoot !== roots.platformRoot ? await computeMarketplaceLockHashAt(roots.projectRoot) : "";
   if (lockfileHash) {
     stateHasher.update(lockfileHash);
   }
@@ -883,9 +927,14 @@ async function saveCache(cwd, results) {
   if (pluginsStateHash) {
     stateHasher.update(pluginsStateHash);
   }
-  if (marketplaceLockHash) {
-    stateHasher.update(marketplaceLockHash);
+  if (platformMarketplaceLockHash) {
+    stateHasher.update(platformMarketplaceLockHash);
+  }
+  if (projectMarketplaceLockHash) {
+    stateHasher.update(projectMarketplaceLockHash);
   }
+  stateHasher.update(roots.platformRoot);
+  stateHasher.update(roots.projectRoot);
   const cache = {
     version: process.version,
     cliVersion: process.env.CLI_VERSION || "0.1.0",
@@ -895,7 +944,10 @@ async function saveCache(cwd, results) {
     lockfileHash: lockfileHash || void 0,
     configHash: configHash || void 0,
     pluginsStateHash: pluginsStateHash || void 0,
-    marketplaceLockHash: marketplaceLockHash || void 0,
+    platformMarketplaceLockHash: platformMarketplaceLockHash || void 0,
+    projectMarketplaceLockHash: projectMarketplaceLockHash || void 0,
+    platformRoot: roots.platformRoot,
+    projectRoot: roots.projectRoot,
     packages
   };
   try {
@@ -907,6 +959,9 @@ async function saveCache(cwd, results) {
 async function discoverManifests(cwd, noCache = false, options = {}) {
   const startTime = Date.now();
   const timings = {};
+  const platformRoot = options.platformRoot ?? cwd;
+  const projectRoot = options.projectRoot ?? cwd;
+  const roots = { platformRoot, projectRoot };
   if (noCache) {
     inProcDiscoveryCache = null;
   } else if (inProcDiscoveryCache) {
@@ -923,7 +978,7 @@ async function discoverManifests(cwd, noCache = false, options = {}) {
   }
   if (!noCache) {
     const cacheStart = Date.now();
-    const cached = await loadCache(cwd);
+    const cached = await loadCache(cwd, roots);
     timings.cacheLoad = Date.now() - cacheStart;
     if (cached) {
       log("debug", "Using cached manifests");
@@ -966,7 +1021,7 @@ async function discoverManifests(cwd, noCache = false, options = {}) {
   let workspace = [];
   try {
     const wsStart = Date.now();
-    workspace = await discoverWorkspace(cwd);
+    workspace = await discoverWorkspace(platformRoot);
     timings.workspace = Date.now() - wsStart;
     log("info", `Discovered ${workspace.length} workspace packages with CLI manifests`);
   } catch (_err) {
@@ -980,17 +1035,22 @@ async function discoverManifests(cwd, noCache = false, options = {}) {
     }
   }
   const nmStart = Date.now();
-  const nodeModulesRoot = options.platformRoot ?? cwd;
-  const installed = await discoverNodeModules(nodeModulesRoot);
+  const installed = await discoverNodeModules(platformRoot);
   timings.nodeModules = Date.now() - nmStart;
   if (installed.length > 0) {
     log("info", `Discovered ${installed.length} installed packages with CLI manifests`);
   }
+  const plStart = Date.now();
+  const projectLocal = await discoverProjectLocalPlugins(projectRoot);
+  timings.projectLocal = Date.now() - plStart;
+  if (projectLocal.length > 0) {
+    log("info", `Discovered ${projectLocal.length} project-local plugins`);
+  }
   const dedupStart = Date.now();
-  const results = deduplicateManifests([...workspace, ...installed]);
+  const results = deduplicateManifests([...workspace, ...installed, ...projectLocal]);
   timings.deduplicate = Date.now() - dedupStart;
   const saveStart = Date.now();
-  await saveCache(cwd, results);
+  await saveCache(cwd, results, roots);
   timings.cacheSave = Date.now() - saveStart;
   const totalTime = Date.now() - startTime;
   const sourceCounts = results.reduce((acc, r) => {
@@ -1690,7 +1750,8 @@ var diag = defineSystemCommand({
     });
     try {
       const platformRoot = process.env.KB_PLATFORM_ROOT;
-      const discovered = await discoverManifests(cwd, false, { platformRoot });
+      const projectRoot = process.env.KB_PROJECT_ROOT;
+      const discovered = await discoverManifests(cwd, false, { platformRoot, projectRoot });
       const manifests = registry.listManifests();
       const enabled = manifests.filter((m) => m.available && !m.shadowed).length;
       const disabled = manifests.filter((m) => !m.available).length;
@@ -3981,7 +4042,8 @@ async function registerBuiltinCommands(input = {}) {
     const noCache = process.argv.includes("--no-cache") || env.KB_PLUGIN_NO_CACHE === "1";
     const { discoverManifests: discoverManifests2 } = await Promise.resolve().then(() => (init_discover(), discover_exports));
     const discovered = await discoverManifests2(cwd, noCache, {
-      platformRoot: input.platformRoot
+      platformRoot: input.platformRoot,
+      projectRoot: input.projectRoot
     });
     if (discovered.length > 0) {
       log3.info(`Discovered ${discovered.length} packages with CLI manifests`);