@kb-labs/core-workspace 1.0.0

package/LICENSE

@@ -0,0 +1,2 @@
+See root LICENSE file.
+

package/README.md

@@ -0,0 +1,82 @@
+# @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.
+
+[![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/)
+[![pnpm](https://img.shields.io/badge/pnpm-9.0.0+-orange.svg)](https://pnpm.io/)
+
+## 🎯 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.
+
+## 🏗️ Architecture
+
+### Core Components
+
+#### Workspace Root Resolver
+
+- **Purpose**: Resolve workspace root directory
+- **Responsibilities**: Detect workspace markers, return root path
+- **Dependencies**: `core-sys` for repository utilities
+
+### Design Patterns
+
+- **Utility Pattern**: Pure utility functions
+- **Strategy Pattern**: Multiple detection strategies
+
+### Data Flow
+
+```
+resolveWorkspaceRoot({ startDir, stopDir })
+    │
+    ├──► Walk up directory tree
+    ├──► Check for markers (.git, pnpm-workspace.yaml, package.json)
+    ├──► Return workspace root
+```
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pnpm add @kb-labs/core-workspace
+```
+
+### Basic Usage
+
+```typescript
+import { resolveWorkspaceRoot } from '@kb-labs/core-workspace';
+
+const { root, found } = await resolveWorkspaceRoot({
+  startDir: process.cwd()
+});
+
+if (found) {
+  console.log('Workspace root:', root);
+}
+```
+
+## ✨ Features
+
+- **Multiple Markers**: Detects workspace via `.git`, `pnpm-workspace.yaml`, `package.json`
+- **Flexible Resolution**: Supports start and stop directories
+- **Workspace Metadata**: Provides workspace filesystem information
+
+## 🔧 Configuration
+
+### Configuration Options
+
+No configuration needed (utilities only).
+
+### Environment Variables
+
+None.
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+KB Public License v1.1 © KB Labs

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+interface WorkspaceRootResolution {
+    rootDir: string;
+    source: 'explicit' | 'env' | 'config' | 'repo' | 'fallback';
+}
+interface ResolveWorkspaceRootOptions {
+    /**
+     * Explicit root directory to use (e.g. from CLI flag). Highest priority.
+     */
+    cwd?: string;
+    /**
+     * Starting directory for 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 WorkspaceFs {
+    exists(path: string): Promise<boolean>;
+}
+
+/**
+ * Resolve the workspace root for kb-labs tooling.
+ *
+ * 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
+ */
+declare function resolveWorkspaceRoot(options?: ResolveWorkspaceRootOptions): Promise<WorkspaceRootResolution>;
+
+export { type ResolveWorkspaceRootOptions, type WorkspaceRootResolution, resolveWorkspaceRoot };

package/dist/index.js

@@ -0,0 +1,84 @@
+import path from 'path';
+import { promises } from 'fs';
+import { findRepoRoot } from '@kb-labs/core-sys';
+
+// src/workspace/root-resolver.ts
+var WORKSPACE_CONFIG_RELATIVE = path.join(".kb", "kb.config.json");
+var defaultFs = {
+  async exists(target) {
+    try {
+      await promises.access(target);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+function resolveEnvRoot(env) {
+  if (!env) {
+    return void 0;
+  }
+  return env.KB_LABS_WORKSPACE_ROOT ?? env.KB_LABS_REPO_ROOT;
+}
+async function findConfigRoot(startDir, fs) {
+  let current = path.resolve(startDir);
+  while (true) {
+    const configPath = path.join(current, WORKSPACE_CONFIG_RELATIVE);
+    if (await fs.exists(configPath)) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return void 0;
+    }
+    current = parent;
+  }
+}
+async function resolveWorkspaceRoot(options = {}) {
+  const {
+    cwd,
+    env = process.env,
+    fs = defaultFs,
+    startDir = process.cwd()
+  } = options;
+  if (cwd) {
+    return {
+      rootDir: path.resolve(cwd),
+      source: "explicit"
+    };
+  }
+  const envRoot = resolveEnvRoot(env);
+  if (envRoot) {
+    return {
+      rootDir: path.resolve(envRoot),
+      source: "env"
+    };
+  }
+  const configRoot = await findConfigRoot(startDir, fs);
+  if (configRoot) {
+    return {
+      rootDir: configRoot,
+      source: "config"
+    };
+  }
+  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"
+  };
+}
+
+export { resolveWorkspaceRoot };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@kb-labs/core-workspace",
+  "version": "1.0.0",
+  "description": "Core workspace utilities for KB Labs, including root directory resolution and workspace detection",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@kb-labs/core-sys": "link:../core-sys"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "@typescript-eslint/eslint-plugin": "^8",
+    "@typescript-eslint/parser": "^8",
+    "eslint": "^9",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm clean && tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint . --ignore-pattern 'dist/**'",
+    "lint:fix": "eslint . --fix --ignore-pattern 'dist/**'",
+    "test:watch": "vitest"
+  }
+}