@kb-labs/core-workspace 1.7.0 → 1.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @kb-labs/core-workspace
 
-> **Core workspace utilities for KB Labs, including root directory resolution and workspace detection.** Provides utilities for locating the KB Labs workspace umbrella directory for internal tooling consumption.
+> **Core workspace utilities for KB Labs, including platform/project root resolution.** Provides utilities for locating the KB Labs platform installation and the user's project directory for internal tooling consumption (CLI, services, dev tools).
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-18.18.0+-green.svg)](https://nodejs.org/)
@@ -8,32 +8,65 @@
 
 ## 🎯 Vision & Purpose
 
-**@kb-labs/core-workspace** provides workspace utilities for KB Labs internal tooling (CLI, REST, Studio). It resolves the workspace root directory by detecting workspace markers (`.git`, `pnpm-workspace.yaml`, `package.json`) and provides workspace metadata.
+**@kb-labs/core-workspace** provides root-directory resolution utilities shared by CLI, services, and `kb-dev`.
 
-## 🏗️ Architecture
+KB Labs distinguishes **two** logical roots, which may coincide (dev mode) or differ (installed mode):
 
-### Core Components
+| Root            | What it is                                                                                       | Where it lives                                      |
+| --------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
+| **platformRoot** | Directory that contains the installed KB Labs platform code (parent of `node_modules/@kb-labs/*`) | `/opt/kb-labs` (installed), workspace root (dev)    |
+| **projectRoot**  | Directory that contains the user's `.kb/kb.config.json` and all per-project plugin state         | `~/work/my-app` (installed), workspace root (dev)   |
 
-#### Workspace Root Resolver
+**Why two roots?** Plugin discovery needs to scan the platform's `node_modules`, while platform state (`.kb/qa`, `.kb/mind`, `.kb/marketplace.lock`, adapter storage paths like `.kb/database/kb.sqlite`) belongs to the user's project. Until the platform moved out of the workspace, both assumptions resolved to the same `cwd` — and the codebase silently conflated them. This package makes the distinction explicit.
 
-- **Purpose**: Resolve workspace root directory
-- **Responsibilities**: Detect workspace markers, return root path
-- **Dependencies**: `core-sys` for repository utilities
+## 🏗️ Architecture
 
-### Design Patterns
+### Core Functions
 
-- **Utility Pattern**: Pure utility functions
-- **Strategy Pattern**: Multiple detection strategies
+#### `resolveRoots(options)` — main entry point
 
-### Data Flow
+Resolves both `platformRoot` and `projectRoot` in a single call. This is what the CLI bootstrap, service bootstrap, and `kb-dev` should use.
 
+```typescript
+const { platformRoot, projectRoot, sameLocation, sources } = await resolveRoots({
+  moduleUrl: import.meta.url, // from the caller's binary/entry
+  startDir: process.cwd(),
+})
 ```
-resolveWorkspaceRoot({ startDir, stopDir })
-    │
-    ├──► Walk up directory tree
-    ├──► Check for markers (.git, pnpm-workspace.yaml, package.json)
-    ├──► Return workspace root
-```
+
+- `sameLocation: true` ⇒ dev mode (both roots are the same directory).
+- `sources.platform` / `sources.project` describe how each root was discovered (`'explicit' | 'env' | 'module' | 'marker' | 'config' | 'repo' | 'fallback'`).
+
+#### `resolvePlatformRoot(options)`
+
+Finds the directory that contains the installed KB Labs platform (parent of `node_modules/@kb-labs/*`).
+
+Priority chain:
+
+1. Explicit `cwd` option.
+2. `KB_PLATFORM_ROOT` env var (set by the installer wrapper in installed mode).
+3. Walk up from `moduleUrl` (`import.meta.url` of the caller). This walks all the way up and:
+   - Prefers the **top-most** `pnpm-workspace.yaml` if one exists (handles KB Labs "workspace of workspaces" dev layout).
+   - Falls back to the first directory whose `node_modules` contains a known platform marker (`@kb-labs/cli-bin`, `@kb-labs/core-runtime`) — this is the normal installed-mode path.
+4. Walk up from `startDir` looking for the same markers or `pnpm-workspace.yaml`.
+5. Repository root via `findRepoRoot`.
+6. Fallback to `startDir`.
+
+#### `resolveProjectRoot(options)`
+
+Finds the user's project root — the directory containing `.kb/kb.config.json`.
+
+Priority chain:
+
+1. Explicit `cwd` option.
+2. Env vars: `KB_PROJECT_ROOT` (preferred) or legacy `KB_LABS_WORKSPACE_ROOT` / `KB_LABS_REPO_ROOT`.
+3. Nearest `.kb/kb.config.json` ancestor walking up from `startDir`.
+4. Repository root via `findRepoRoot`.
+5. Fallback to `startDir`.
+
+#### `resolveWorkspaceRoot(options)` — deprecated alias
+
+Kept as an alias of `resolveProjectRoot` for backwards compatibility. Prefer the explicit name.
 
 ## 🚀 Quick Start
 
@@ -46,32 +79,51 @@ pnpm add @kb-labs/core-workspace
 ### Basic Usage
 
 ```typescript
-import { resolveWorkspaceRoot } from '@kb-labs/core-workspace';
+import { resolveRoots } from '@kb-labs/core-workspace'
 
-const { root, found } = await resolveWorkspaceRoot({
-  startDir: process.cwd()
-});
+// In a CLI entrypoint (bin.ts):
+const { platformRoot, projectRoot, sameLocation } = await resolveRoots({
+  moduleUrl: import.meta.url,
+  startDir: process.cwd(),
+})
 
-if (found) {
-  console.log('Workspace root:', root);
-}
+console.log({ platformRoot, projectRoot, sameLocation })
 ```
 
-## ✨ Features
+### In dev mode (monorepo workspace)
 
-- **Multiple Markers**: Detects workspace via `.git`, `pnpm-workspace.yaml`, `package.json`
-- **Flexible Resolution**: Supports start and stop directories
-- **Workspace Metadata**: Provides workspace filesystem information
+```text
+platformRoot === projectRoot === <workspace-root>
+sameLocation:   true
+sources:        { platform: 'module', project: 'config' }
+```
 
-## 🔧 Configuration
+### In installed mode
 
-### Configuration Options
+```text
+platformRoot:  /opt/kb-labs                    (from KB_PLATFORM_ROOT or moduleUrl walk-up)
+projectRoot:   /home/user/work/my-project      (from .kb/kb.config.json walk-up)
+sameLocation:  false
+```
+
+## ✨ Features
 
-No configuration needed (utilities only).
+- **Two-root resolution**: clearly distinguishes platform code location from project state location.
+- **Multiple discovery signals**: explicit options, env vars, `import.meta.url` walk-up, marker walk-up, repo root.
+- **Dev/installed parity**: same API works in workspace dev mode and in deployed/installed mode; callers don't need to branch.
+- **Nested-workspace aware**: handles the KB Labs "workspace of workspaces" layout where sub-repos each have their own `pnpm-workspace.yaml`.
+- **Backwards compatible**: legacy `resolveWorkspaceRoot` and `KB_LABS_WORKSPACE_ROOT` / `KB_LABS_REPO_ROOT` env vars still work.
+
+## 🔧 Configuration
 
 ### Environment Variables
 
-None.
+| Variable                  | Purpose                                                                       |
+| ------------------------- | ----------------------------------------------------------------------------- |
+| `KB_PLATFORM_ROOT`        | Override platform root (installer wrapper, CI).                                |
+| `KB_PROJECT_ROOT`         | Override project root.                                                         |
+| `KB_LABS_WORKSPACE_ROOT`  | Legacy alias for `KB_PROJECT_ROOT` (kept for backwards compatibility).         |
+| `KB_LABS_REPO_ROOT`       | Legacy alias for `KB_PROJECT_ROOT` (kept for backwards compatibility).         |
 
 ## 🤝 Contributing
 

package/dist/index.d.ts

@@ -1,8 +1,38 @@
-interface WorkspaceRootResolution {
+/**
+ * @module @kb-labs/core-workspace/types
+ *
+ * Types for workspace/platform/project root resolution.
+ *
+ * KB Labs distinguishes **two** logical roots:
+ *
+ * - **platformRoot** — the directory that contains the installed KB Labs
+ *   platform code (i.e. the parent of `node_modules/@kb-labs/*`). This is the
+ *   place from which plugin discovery should scan `node_modules`, and where
+ *   cloud/CI deployments may place per-installation platform defaults.
+ *
+ * - **projectRoot** — the directory that contains the user's `.kb/` folder,
+ *   including `.kb/kb.config.json` and any runtime state written by plugins
+ *   (`.kb/qa`, `.kb/mind`, `.kb/release`, `.kb/marketplace.lock`, etc.).
+ *   This is *where the user is working*.
+ *
+ * In development (monorepo workspace) mode these two roots typically resolve
+ * to the same directory. In installed mode they are different — the platform
+ * lives under e.g. `/opt/kb-labs` while the project lives under
+ * `~/work/my-app`.
+ */
+/**
+ * Minimal filesystem façade used by the resolvers. Allows tests to inject a
+ * virtual filesystem without touching `node:fs` directly.
+ */
+interface WorkspaceFs {
+    exists(path: string): Promise<boolean>;
+}
+type ProjectRootSource = 'explicit' | 'env' | 'config' | 'repo' | 'fallback';
+interface ProjectRootResolution {
     rootDir: string;
-    source: 'explicit' | 'env' | 'config' | 'repo' | 'fallback';
+    source: ProjectRootSource;
 }
-interface ResolveWorkspaceRootOptions {
+interface ResolveProjectRootOptions {
     /**
      * Explicit root directory to use (e.g. from CLI flag). Highest priority.
      */
@@ -24,20 +54,135 @@ interface ResolveWorkspaceRootOptions {
      */
     verbose?: boolean;
 }
-interface WorkspaceFs {
-    exists(path: string): Promise<boolean>;
+/**
+ * @deprecated Use {@link ResolveProjectRootOptions}. Alias kept for backwards
+ * compatibility with `resolveWorkspaceRoot`.
+ */
+type ResolveWorkspaceRootOptions = ResolveProjectRootOptions;
+/**
+ * @deprecated Use {@link ProjectRootResolution}.
+ */
+type WorkspaceRootResolution = ProjectRootResolution;
+type PlatformRootSource = 'explicit' | 'env' | 'module' | 'marker' | 'repo' | 'fallback';
+interface PlatformRootResolution {
+    rootDir: string;
+    source: PlatformRootSource;
+}
+interface ResolvePlatformRootOptions {
+    /**
+     * Explicit root directory to use (e.g. from CLI flag). Highest priority.
+     */
+    cwd?: string;
+    /**
+     * `import.meta.url` of the calling module (typically the CLI entrypoint or
+     * a service bootstrap file). Used to locate the installed
+     * `node_modules/@kb-labs/*` tree by walking up from the module's physical
+     * location. This is the **most reliable** signal in installed mode because
+     * it does not depend on process cwd or directory layout assumptions.
+     */
+    moduleUrl?: string;
+    /**
+     * Starting directory for marker-based discovery. Defaults to process.cwd().
+     */
+    startDir?: string;
+    /**
+     * Environment variables map. Defaults to process.env.
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * Optionally inject custom filesystem helpers for testing.
+     */
+    fs?: WorkspaceFs;
+    /**
+     * When true, includes additional metadata in errors/logs.
+     */
+    verbose?: boolean;
+}
+interface ResolveRootsOptions extends ResolvePlatformRootOptions, ResolveProjectRootOptions {
+}
+interface RootsResolution {
+    /** Where `node_modules/@kb-labs/*` lives. */
+    platformRoot: string;
+    /** Where `.kb/kb.config.json` and per-project state live. */
+    projectRoot: string;
+    /**
+     * `true` when both roots resolve to the same physical directory — this is
+     * the normal case in the KB Labs monorepo dev mode.
+     */
+    sameLocation: boolean;
+    /** How each root was resolved (for diagnostics). */
+    sources: {
+        platform: PlatformRootSource;
+        project: ProjectRootSource;
+    };
 }
 
 /**
- * Resolve the workspace root for kb-labs tooling.
+ * Resolve the project root — the directory that contains the user's
+ * `.kb/kb.config.json` and plugin state.
  *
  * Priority order:
- * 1. Explicit `cwd` option (e.g. CLI flag)
- * 2. Environment variables (`KB_LABS_WORKSPACE_ROOT`, `KB_LABS_REPO_ROOT`)
- * 3. Nearest `.kb/kb-labs.config.json` ancestor
- * 4. Repository root discovered via `findRepoRoot`
- * 5. Fallback to provided `startDir` / process cwd
+ *
+ * 1. Explicit `cwd` option (e.g. CLI flag).
+ * 2. Environment variables: `KB_PROJECT_ROOT` (preferred), then the legacy
+ *    `KB_LABS_WORKSPACE_ROOT` / `KB_LABS_REPO_ROOT`.
+ * 3. Nearest `.kb/kb.config.json` ancestor walking up from `startDir`.
+ * 4. Repository root discovered via `findRepoRoot` (pnpm workspace, `.git`,
+ *    `package.json`).
+ * 5. Fallback to `startDir` / `process.cwd()`.
+ *
+ * In monorepo dev mode this typically returns the workspace root. In installed
+ * mode it returns the user's project directory.
+ */
+declare function resolveProjectRoot(options?: ResolveProjectRootOptions): Promise<ProjectRootResolution>;
+/**
+ * @deprecated Use {@link resolveProjectRoot}. This alias is kept for
+ * backwards compatibility; semantics are identical.
+ *
+ * The name "workspace root" is ambiguous — in KB Labs terminology, what it
+ * actually refers to is the project root (where `.kb/kb.config.json` lives),
+ * not the KB Labs platform installation. Prefer the explicit name.
  */
 declare function resolveWorkspaceRoot(options?: ResolveWorkspaceRootOptions): Promise<WorkspaceRootResolution>;
+/**
+ * Resolve the platform root — the directory that contains the installed
+ * KB Labs platform code (i.e. the parent of `node_modules/@kb-labs/*`).
+ *
+ * Priority order:
+ *
+ * 1. Explicit `cwd` option (e.g. CLI flag).
+ * 2. Environment variable `KB_PLATFORM_ROOT` (typically set by the installer
+ *    wrapper script in installed mode).
+ * 3. Walk up from `moduleUrl` (e.g. `import.meta.url` of the CLI `bin.ts`),
+ *    looking for a directory whose `node_modules` contains a known platform
+ *    package. This is the most reliable signal in installed mode because it
+ *    does not depend on `process.cwd()`.
+ * 4. Walk up from `startDir` looking for either a platform marker or
+ *    `pnpm-workspace.yaml` (the latter covers monorepo dev mode).
+ * 5. Repository root discovered via `findRepoRoot`.
+ * 6. Fallback to `startDir` / `process.cwd()`.
+ *
+ * In monorepo dev mode steps 4 or 5 will typically match the workspace root,
+ * so `platformRoot` and `projectRoot` resolve to the same directory.
+ */
+declare function resolvePlatformRoot(options?: ResolvePlatformRootOptions): Promise<PlatformRootResolution>;
+/**
+ * Resolve both the platform root and the project root in a single call. This
+ * is the main entry point for the CLI, service bootstrap, and `kb-dev`.
+ *
+ * @example
+ * ```ts
+ * // In bin.ts (the CLI entrypoint):
+ * const { platformRoot, projectRoot } = await resolveRoots({
+ *   moduleUrl: import.meta.url,
+ *   startDir: process.cwd(),
+ * })
+ * ```
+ *
+ * In dev mode `platformRoot === projectRoot` and `sameLocation` is `true`.
+ * In installed mode they differ: `platformRoot` points at the platform
+ * installation while `projectRoot` points at the user's project directory.
+ */
+declare function resolveRoots(options?: ResolveRootsOptions): Promise<RootsResolution>;
 
-export { type ResolveWorkspaceRootOptions, type WorkspaceRootResolution, resolveWorkspaceRoot };
+export { type PlatformRootResolution, type PlatformRootSource, type ProjectRootResolution, type ProjectRootSource, type ResolvePlatformRootOptions, type ResolveProjectRootOptions, type ResolveRootsOptions, type ResolveWorkspaceRootOptions, type RootsResolution, type WorkspaceFs, type WorkspaceRootResolution, resolvePlatformRoot, resolveProjectRoot, resolveRoots, resolveWorkspaceRoot };

package/dist/index.js

@@ -1,9 +1,14 @@
 import path from 'path';
 import { promises } from 'fs';
+import { fileURLToPath } from 'url';
 import { findRepoRoot } from '@kb-labs/core-sys';
 
 // src/workspace/root-resolver.ts
 var WORKSPACE_CONFIG_RELATIVE = path.join(".kb", "kb.config.json");
+var PLATFORM_PACKAGE_MARKERS = [
+  "@kb-labs/cli-bin",
+  "@kb-labs/core-runtime"
+];
 var defaultFs = {
   async exists(target) {
     try {
@@ -14,11 +19,11 @@ var defaultFs = {
     }
   }
 };
-function resolveEnvRoot(env) {
+function resolveProjectEnvRoot(env) {
   if (!env) {
     return void 0;
   }
-  return env.KB_LABS_WORKSPACE_ROOT ?? env.KB_LABS_REPO_ROOT;
+  return env.KB_PROJECT_ROOT ?? env.KB_LABS_WORKSPACE_ROOT ?? env.KB_LABS_REPO_ROOT;
 }
 async function findConfigRoot(startDir, fs) {
   let current = path.resolve(startDir);
@@ -34,7 +39,7 @@ async function findConfigRoot(startDir, fs) {
     current = parent;
   }
 }
-async function resolveWorkspaceRoot(options = {}) {
+async function resolveProjectRoot(options = {}) {
   const {
     cwd,
     env = process.env,
@@ -47,7 +52,7 @@ async function resolveWorkspaceRoot(options = {}) {
       source: "explicit"
     };
   }
-  const envRoot = resolveEnvRoot(env);
+  const envRoot = resolveProjectEnvRoot(env);
   if (envRoot) {
     return {
       rootDir: path.resolve(envRoot),
@@ -78,7 +83,128 @@ async function resolveWorkspaceRoot(options = {}) {
     source: "fallback"
   };
 }
+async function resolveWorkspaceRoot(options = {}) {
+  return resolveProjectRoot(options);
+}
+async function hasPlatformMarker(candidate, fs) {
+  for (const marker of PLATFORM_PACKAGE_MARKERS) {
+    const markerPath = path.join(candidate, "node_modules", marker);
+    if (await fs.exists(markerPath)) {
+      return true;
+    }
+  }
+  return false;
+}
+async function walkUpForPlatformMarker(startDir, fs) {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (await hasPlatformMarker(current, fs)) {
+      return current;
+    }
+    if (await fs.exists(path.join(current, "pnpm-workspace.yaml"))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return void 0;
+    }
+    current = parent;
+  }
+}
+async function resolvePlatformRootFromModuleUrl(moduleUrl, fs) {
+  let modulePath;
+  try {
+    modulePath = fileURLToPath(moduleUrl);
+  } catch {
+    return void 0;
+  }
+  let current = path.dirname(modulePath);
+  let firstMarkerHit;
+  let topMostWorkspace;
+  while (true) {
+    if (!firstMarkerHit && await hasPlatformMarker(current, fs)) {
+      firstMarkerHit = current;
+    }
+    if (await fs.exists(path.join(current, "pnpm-workspace.yaml"))) {
+      topMostWorkspace = current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return topMostWorkspace ?? firstMarkerHit;
+    }
+    current = parent;
+  }
+}
+async function resolvePlatformRoot(options = {}) {
+  const {
+    cwd,
+    moduleUrl,
+    env = process.env,
+    fs = defaultFs,
+    startDir = process.cwd()
+  } = options;
+  if (cwd) {
+    return {
+      rootDir: path.resolve(cwd),
+      source: "explicit"
+    };
+  }
+  const envRoot = env?.KB_PLATFORM_ROOT;
+  if (envRoot) {
+    return {
+      rootDir: path.resolve(envRoot),
+      source: "env"
+    };
+  }
+  if (moduleUrl) {
+    const fromModule = await resolvePlatformRootFromModuleUrl(moduleUrl, fs);
+    if (fromModule) {
+      return {
+        rootDir: fromModule,
+        source: "module"
+      };
+    }
+  }
+  const fromMarker = await walkUpForPlatformMarker(startDir, fs);
+  if (fromMarker) {
+    return {
+      rootDir: fromMarker,
+      source: "marker"
+    };
+  }
+  try {
+    const repoRoot = await findRepoRoot(startDir);
+    const resolvedRepo = path.resolve(repoRoot);
+    const fsRoot = path.parse(resolvedRepo).root;
+    if (resolvedRepo !== fsRoot) {
+      return {
+        rootDir: resolvedRepo,
+        source: "repo"
+      };
+    }
+  } catch {
+  }
+  return {
+    rootDir: path.resolve(startDir),
+    source: "fallback"
+  };
+}
+async function resolveRoots(options = {}) {
+  const [platform, project] = await Promise.all([
+    resolvePlatformRoot(options),
+    resolveProjectRoot(options)
+  ]);
+  return {
+    platformRoot: platform.rootDir,
+    projectRoot: project.rootDir,
+    sameLocation: path.resolve(platform.rootDir) === path.resolve(project.rootDir),
+    sources: {
+      platform: platform.source,
+      project: project.source
+    }
+  };
+}
 
-export { resolveWorkspaceRoot };
+export { resolvePlatformRoot, resolveProjectRoot, resolveRoots, resolveWorkspaceRoot };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/workspace/root-resolver.ts"],"names":["fsp"],"mappings":";;;;;AAWA,IAAM,yBAAA,GAA4B,IAAA,CAAK,IAAA,CAAK,KAAA,EAAO,gBAAgB,CAAA;AAEnE,IAAM,SAAA,GAAyB;AAAA,EAC7B,MAAM,OAAO,MAAA,EAAkC;AAC7C,IAAA,IAAI;AACF,MAAA,MAAMA,QAAA,CAAI,OAAO,MAAM,CAAA;AACvB,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AACF,CAAA;AAEA,SAAS,eACP,GAAA,EACoB;AACpB,EAAA,IAAI,CAAC,GAAA,EAAK;AAAC,IAAA,OAAO,MAAA;AAAA,EAAS;AAC3B,EAAA,OAAO,GAAA,CAAI,0BAA0B,GAAA,CAAI,iBAAA;AAC3C;AAEA,eAAe,cAAA,CACb,UACA,EAAA,EAC6B;AAC7B,EAAA,IAAI,OAAA,GAAU,IAAA,CAAK,OAAA,CAAQ,QAAQ,CAAA;AAEnC,EAAA,OAAO,IAAA,EAAM;AACX,IAAA,MAAM,UAAA,GAAa,IAAA,CAAK,IAAA,CAAK,OAAA,EAAS,yBAAyB,CAAA;AAE/D,IAAA,IAAI,MAAM,EAAA,CAAG,MAAA,CAAO,UAAU,CAAA,EAAG;AAC/B,MAAA,OAAO,OAAA;AAAA,IACT;AAEA,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,OAAA,CAAQ,OAAO,CAAA;AACnC,IAAA,IAAI,WAAW,OAAA,EAAS;AACtB,MAAA,OAAO,MAAA;AAAA,IACT;AAEA,IAAA,OAAA,GAAU,MAAA;AAAA,EACZ;AACF;AAYA,eAAsB,oBAAA,CACpB,OAAA,GAAuC,EAAC,EACN;AAClC,EAAA,MAAM;AAAA,IACJ,GAAA;AAAA,IACA,MAAM,OAAA,CAAQ,GAAA;AAAA,IACd,EAAA,GAAK,SAAA;AAAA,IACL,QAAA,GAAW,QAAQ,GAAA;AAAI,GACzB,GAAI,OAAA;AAEJ,EAAA,IAAI,GAAA,EAAK;AACP,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,IAAA,CAAK,OAAA,CAAQ,GAAG,CAAA;AAAA,MACzB,MAAA,EAAQ;AAAA,KACV;AAAA,EACF;AAEA,EAAA,MAAM,OAAA,GAAU,eAAe,GAAG,CAAA;AAClC,EAAA,IAAI,OAAA,EAAS;AACX,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,IAAA,CAAK,OAAA,CAAQ,OAAO,CAAA;AAAA,MAC7B,MAAA,EAAQ;AAAA,KACV;AAAA,EACF;AAEA,EAAA,MAAM,UAAA,GAAa,MAAM,cAAA,CAAe,QAAA,EAAU,EAAE,CAAA;AACpD,EAAA,IAAI,UAAA,EAAY;AACd,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,UAAA;AAAA,MACT,MAAA,EAAQ;AAAA,KACV;AAAA,EACF;AAEA,EAAA,IAAI;AACF,IAAA,MAAM,QAAA,GAAW,MAAM,YAAA,CAAa,QAAQ,CAAA;AAC5C,IAAA,MAAM,YAAA,GAAe,IAAA,CAAK,OAAA,CAAQ,QAAQ,CAAA;AAC1C,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,KAAA,CAAM,YAAY,CAAA,CAAE,IAAA;AAExC,IAAA,IAAI,iBAAiB,MAAA,EAAQ;AAC3B,MAAA,OAAO;AAAA,QACL,OAAA,EAAS,YAAA;AAAA,QACT,MAAA,EAAQ;AAAA,OACV;AAAA,IACF;AAAA,EACF,CAAA,CAAA,MAAQ;AAAA,EAER;AAEA,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,IAAA,CAAK,OAAA,CAAQ,QAAQ,CAAA;AAAA,IAC9B,MAAA,EAAQ;AAAA,GACV;AACF","file":"index.js","sourcesContent":["import path from 'node:path'\nimport { promises as fsp } from 'node:fs'\n\nimport { findRepoRoot } from '@kb-labs/core-sys'\n\nimport type {\n  ResolveWorkspaceRootOptions,\n  WorkspaceFs,\n  WorkspaceRootResolution,\n} from './types'\n\nconst WORKSPACE_CONFIG_RELATIVE = path.join('.kb', 'kb.config.json')\n\nconst defaultFs: WorkspaceFs = {\n  async exists(target: string): Promise<boolean> {\n    try {\n      await fsp.access(target)\n      return true\n    } catch {\n      return false\n    }\n  },\n}\n\nfunction resolveEnvRoot(\n  env: Record<string, string | undefined> | undefined,\n): string | undefined {\n  if (!env) {return undefined}\n  return env.KB_LABS_WORKSPACE_ROOT ?? env.KB_LABS_REPO_ROOT\n}\n\nasync function findConfigRoot(\n  startDir: string,\n  fs: WorkspaceFs,\n): Promise<string | undefined> {\n  let current = path.resolve(startDir)\n\n  while (true) {\n    const configPath = path.join(current, WORKSPACE_CONFIG_RELATIVE)\n    // eslint-disable-next-line no-await-in-loop -- Searching for workspace root: must check each directory sequentially\n    if (await fs.exists(configPath)) {\n      return current\n    }\n\n    const parent = path.dirname(current)\n    if (parent === current) {\n      return undefined\n    }\n\n    current = parent\n  }\n}\n\n/**\n * Resolve the workspace root for kb-labs tooling.\n *\n * Priority order:\n * 1. Explicit `cwd` option (e.g. CLI flag)\n * 2. Environment variables (`KB_LABS_WORKSPACE_ROOT`, `KB_LABS_REPO_ROOT`)\n * 3. Nearest `.kb/kb-labs.config.json` ancestor\n * 4. Repository root discovered via `findRepoRoot`\n * 5. Fallback to provided `startDir` / process cwd\n */\nexport async function resolveWorkspaceRoot(\n  options: ResolveWorkspaceRootOptions = {},\n): Promise<WorkspaceRootResolution> {\n  const {\n    cwd,\n    env = process.env,\n    fs = defaultFs,\n    startDir = process.cwd(),\n  } = options\n\n  if (cwd) {\n    return {\n      rootDir: path.resolve(cwd),\n      source: 'explicit',\n    }\n  }\n\n  const envRoot = resolveEnvRoot(env)\n  if (envRoot) {\n    return {\n      rootDir: path.resolve(envRoot),\n      source: 'env',\n    }\n  }\n\n  const configRoot = await findConfigRoot(startDir, fs)\n  if (configRoot) {\n    return {\n      rootDir: configRoot,\n      source: 'config',\n    }\n  }\n\n  try {\n    const repoRoot = await findRepoRoot(startDir)\n    const resolvedRepo = path.resolve(repoRoot)\n    const fsRoot = path.parse(resolvedRepo).root\n\n    if (resolvedRepo !== fsRoot) {\n      return {\n        rootDir: resolvedRepo,\n        source: 'repo',\n      }\n    }\n  } catch {\n    // swallow and fall through to fallback\n  }\n\n  return {\n    rootDir: path.resolve(startDir),\n    source: 'fallback',\n  }\n}\n\n"]}
+{"version":3,"sources":["../src/workspace/root-resolver.ts"],"names":["fsp"],"mappings":"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","file":"index.js","sourcesContent":["import path from 'node:path'\nimport { promises as fsp } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\n\nimport { findRepoRoot } from '@kb-labs/core-sys'\n\nimport type {\n  PlatformRootResolution,\n  ProjectRootResolution,\n  ResolvePlatformRootOptions,\n  ResolveProjectRootOptions,\n  ResolveRootsOptions,\n  ResolveWorkspaceRootOptions,\n  RootsResolution,\n  WorkspaceFs,\n  WorkspaceRootResolution,\n} from './types'\n\nconst WORKSPACE_CONFIG_RELATIVE = path.join('.kb', 'kb.config.json')\n\n/**\n * Package markers used to recognise an installed KB Labs platform. Any one of\n * these, when present as `<root>/node_modules/<marker>`, indicates that\n * `<root>` is a platform installation.\n */\nconst PLATFORM_PACKAGE_MARKERS = [\n  '@kb-labs/cli-bin',\n  '@kb-labs/core-runtime',\n] as const\n\nconst defaultFs: WorkspaceFs = {\n  async exists(target: string): Promise<boolean> {\n    try {\n      await fsp.access(target)\n      return true\n    } catch {\n      return false\n    }\n  },\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Project root (previously \"workspace root\")\n// ──────────────────────────────────────────────────────────────────────────\n\nfunction resolveProjectEnvRoot(\n  env: Record<string, string | undefined> | undefined,\n): string | undefined {\n  if (!env) {\n    return undefined\n  }\n  return (\n    env.KB_PROJECT_ROOT ??\n    env.KB_LABS_WORKSPACE_ROOT ??\n    env.KB_LABS_REPO_ROOT\n  )\n}\n\nasync function findConfigRoot(\n  startDir: string,\n  fs: WorkspaceFs,\n): Promise<string | undefined> {\n  let current = path.resolve(startDir)\n\n  while (true) {\n    const configPath = path.join(current, WORKSPACE_CONFIG_RELATIVE)\n    // eslint-disable-next-line no-await-in-loop -- Searching for project root: must check each directory sequentially\n    if (await fs.exists(configPath)) {\n      return current\n    }\n\n    const parent = path.dirname(current)\n    if (parent === current) {\n      return undefined\n    }\n\n    current = parent\n  }\n}\n\n/**\n * Resolve the project root — the directory that contains the user's\n * `.kb/kb.config.json` and plugin state.\n *\n * Priority order:\n *\n * 1. Explicit `cwd` option (e.g. CLI flag).\n * 2. Environment variables: `KB_PROJECT_ROOT` (preferred), then the legacy\n *    `KB_LABS_WORKSPACE_ROOT` / `KB_LABS_REPO_ROOT`.\n * 3. Nearest `.kb/kb.config.json` ancestor walking up from `startDir`.\n * 4. Repository root discovered via `findRepoRoot` (pnpm workspace, `.git`,\n *    `package.json`).\n * 5. Fallback to `startDir` / `process.cwd()`.\n *\n * In monorepo dev mode this typically returns the workspace root. In installed\n * mode it returns the user's project directory.\n */\nexport async function resolveProjectRoot(\n  options: ResolveProjectRootOptions = {},\n): Promise<ProjectRootResolution> {\n  const {\n    cwd,\n    env = process.env,\n    fs = defaultFs,\n    startDir = process.cwd(),\n  } = options\n\n  if (cwd) {\n    return {\n      rootDir: path.resolve(cwd),\n      source: 'explicit',\n    }\n  }\n\n  const envRoot = resolveProjectEnvRoot(env)\n  if (envRoot) {\n    return {\n      rootDir: path.resolve(envRoot),\n      source: 'env',\n    }\n  }\n\n  const configRoot = await findConfigRoot(startDir, fs)\n  if (configRoot) {\n    return {\n      rootDir: configRoot,\n      source: 'config',\n    }\n  }\n\n  try {\n    const repoRoot = await findRepoRoot(startDir)\n    const resolvedRepo = path.resolve(repoRoot)\n    const fsRoot = path.parse(resolvedRepo).root\n\n    if (resolvedRepo !== fsRoot) {\n      return {\n        rootDir: resolvedRepo,\n        source: 'repo',\n      }\n    }\n  } catch {\n    // swallow and fall through to fallback\n  }\n\n  return {\n    rootDir: path.resolve(startDir),\n    source: 'fallback',\n  }\n}\n\n/**\n * @deprecated Use {@link resolveProjectRoot}. This alias is kept for\n * backwards compatibility; semantics are identical.\n *\n * The name \"workspace root\" is ambiguous — in KB Labs terminology, what it\n * actually refers to is the project root (where `.kb/kb.config.json` lives),\n * not the KB Labs platform installation. Prefer the explicit name.\n */\nexport async function resolveWorkspaceRoot(\n  options: ResolveWorkspaceRootOptions = {},\n): Promise<WorkspaceRootResolution> {\n  return resolveProjectRoot(options)\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Platform root\n// ──────────────────────────────────────────────────────────────────────────\n\n/**\n * Check whether `<candidate>/node_modules/<marker>` exists for any of the\n * known platform package markers.\n */\nasync function hasPlatformMarker(\n  candidate: string,\n  fs: WorkspaceFs,\n): Promise<boolean> {\n  for (const marker of PLATFORM_PACKAGE_MARKERS) {\n    const markerPath = path.join(candidate, 'node_modules', marker)\n    // eslint-disable-next-line no-await-in-loop -- Sequential probe is intentional\n    if (await fs.exists(markerPath)) {\n      return true\n    }\n  }\n  return false\n}\n\n/**\n * Walk up from `startDir` looking for either a platform marker\n * (`node_modules/@kb-labs/*`) or a pnpm workspace marker\n * (`pnpm-workspace.yaml`). Returns the first match.\n */\nasync function walkUpForPlatformMarker(\n  startDir: string,\n  fs: WorkspaceFs,\n): Promise<string | undefined> {\n  let current = path.resolve(startDir)\n\n  while (true) {\n    // eslint-disable-next-line no-await-in-loop -- Sequential walk is intentional\n    if (await hasPlatformMarker(current, fs)) {\n      return current\n    }\n\n    // eslint-disable-next-line no-await-in-loop -- Sequential walk is intentional\n    if (await fs.exists(path.join(current, 'pnpm-workspace.yaml'))) {\n      return current\n    }\n\n    const parent = path.dirname(current)\n    if (parent === current) {\n      return undefined\n    }\n    current = parent\n  }\n}\n\n/**\n * Given a `file://` URL (typically `import.meta.url` from a CLI entry or\n * service bootstrap), walk up through its directory ancestors to locate the\n * platform installation root.\n *\n * Two signals are collected on the way up:\n *\n * 1. **First platform-package marker hit** — a directory whose `node_modules`\n *    contains `@kb-labs/cli-bin` (or another known platform marker). In\n *    installed mode this is the platform installation directory.\n *\n * 2. **Top-most `pnpm-workspace.yaml`** — we keep walking past inner workspace\n *    markers and record the *outermost* one. This is important in the\n *    KB Labs \"workspace of workspaces\" dev layout, where individual sub-repos\n *    (`platform/kb-labs-cli`, `plugins/kb-labs-*`, etc.) each have their own\n *    `pnpm-workspace.yaml` while the true monorepo root lives at the very top.\n *\n * Precedence after walking: the outermost `pnpm-workspace.yaml` wins if one\n * exists (dev mode); otherwise we return the first marker hit (installed\n * mode). This way a naive walk-up can never stop prematurely at a nested\n * workspace or at a package with its own hoisting symlink.\n */\nasync function resolvePlatformRootFromModuleUrl(\n  moduleUrl: string,\n  fs: WorkspaceFs,\n): Promise<string | undefined> {\n  let modulePath: string\n  try {\n    modulePath = fileURLToPath(moduleUrl)\n  } catch {\n    return undefined\n  }\n\n  let current = path.dirname(modulePath)\n  let firstMarkerHit: string | undefined\n  let topMostWorkspace: string | undefined\n\n  while (true) {\n    // eslint-disable-next-line no-await-in-loop -- Sequential walk is intentional\n    if (!firstMarkerHit && (await hasPlatformMarker(current, fs))) {\n      firstMarkerHit = current\n    }\n\n    // Keep overwriting: we want the *outermost* (highest-up) workspace root,\n    // not the innermost. This handles the KB Labs nested-workspaces layout.\n    // eslint-disable-next-line no-await-in-loop -- Sequential walk is intentional\n    if (await fs.exists(path.join(current, 'pnpm-workspace.yaml'))) {\n      topMostWorkspace = current\n    }\n\n    const parent = path.dirname(current)\n    if (parent === current) {\n      // Reached filesystem root. Prefer top-most workspace (dev mode);\n      // otherwise return first marker hit (installed mode).\n      return topMostWorkspace ?? firstMarkerHit\n    }\n    current = parent\n  }\n}\n\n/**\n * Resolve the platform root — the directory that contains the installed\n * KB Labs platform code (i.e. the parent of `node_modules/@kb-labs/*`).\n *\n * Priority order:\n *\n * 1. Explicit `cwd` option (e.g. CLI flag).\n * 2. Environment variable `KB_PLATFORM_ROOT` (typically set by the installer\n *    wrapper script in installed mode).\n * 3. Walk up from `moduleUrl` (e.g. `import.meta.url` of the CLI `bin.ts`),\n *    looking for a directory whose `node_modules` contains a known platform\n *    package. This is the most reliable signal in installed mode because it\n *    does not depend on `process.cwd()`.\n * 4. Walk up from `startDir` looking for either a platform marker or\n *    `pnpm-workspace.yaml` (the latter covers monorepo dev mode).\n * 5. Repository root discovered via `findRepoRoot`.\n * 6. Fallback to `startDir` / `process.cwd()`.\n *\n * In monorepo dev mode steps 4 or 5 will typically match the workspace root,\n * so `platformRoot` and `projectRoot` resolve to the same directory.\n */\nexport async function resolvePlatformRoot(\n  options: ResolvePlatformRootOptions = {},\n): Promise<PlatformRootResolution> {\n  const {\n    cwd,\n    moduleUrl,\n    env = process.env,\n    fs = defaultFs,\n    startDir = process.cwd(),\n  } = options\n\n  if (cwd) {\n    return {\n      rootDir: path.resolve(cwd),\n      source: 'explicit',\n    }\n  }\n\n  const envRoot = env?.KB_PLATFORM_ROOT\n  if (envRoot) {\n    return {\n      rootDir: path.resolve(envRoot),\n      source: 'env',\n    }\n  }\n\n  if (moduleUrl) {\n    const fromModule = await resolvePlatformRootFromModuleUrl(moduleUrl, fs)\n    if (fromModule) {\n      return {\n        rootDir: fromModule,\n        source: 'module',\n      }\n    }\n  }\n\n  const fromMarker = await walkUpForPlatformMarker(startDir, fs)\n  if (fromMarker) {\n    return {\n      rootDir: fromMarker,\n      source: 'marker',\n    }\n  }\n\n  try {\n    const repoRoot = await findRepoRoot(startDir)\n    const resolvedRepo = path.resolve(repoRoot)\n    const fsRoot = path.parse(resolvedRepo).root\n\n    if (resolvedRepo !== fsRoot) {\n      return {\n        rootDir: resolvedRepo,\n        source: 'repo',\n      }\n    }\n  } catch {\n    // swallow and fall through to fallback\n  }\n\n  return {\n    rootDir: path.resolve(startDir),\n    source: 'fallback',\n  }\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Composite resolver\n// ──────────────────────────────────────────────────────────────────────────\n\n/**\n * Resolve both the platform root and the project root in a single call. This\n * is the main entry point for the CLI, service bootstrap, and `kb-dev`.\n *\n * @example\n * ```ts\n * // In bin.ts (the CLI entrypoint):\n * const { platformRoot, projectRoot } = await resolveRoots({\n *   moduleUrl: import.meta.url,\n *   startDir: process.cwd(),\n * })\n * ```\n *\n * In dev mode `platformRoot === projectRoot` and `sameLocation` is `true`.\n * In installed mode they differ: `platformRoot` points at the platform\n * installation while `projectRoot` points at the user's project directory.\n */\nexport async function resolveRoots(\n  options: ResolveRootsOptions = {},\n): Promise<RootsResolution> {\n  const [platform, project] = await Promise.all([\n    resolvePlatformRoot(options),\n    resolveProjectRoot(options),\n  ])\n\n  return {\n    platformRoot: platform.rootDir,\n    projectRoot: project.rootDir,\n    sameLocation:\n      path.resolve(platform.rootDir) === path.resolve(project.rootDir),\n    sources: {\n      platform: platform.source,\n      project: project.source,\n    },\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kb-labs/core-workspace",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Core workspace utilities for KB Labs, including root directory resolution and workspace detection",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@kb-labs/core-sys": "^1.7.0"
+    "@kb-labs/core-sys": "^1.8.0"
   },
   "devDependencies": {
     "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",