@vibe-agent-toolkit/utils 0.1.36 → 0.1.38

package/dist/asset-reference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asset-reference.d.ts","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAuBhF"}
+{"version":3,"file":"asset-reference.d.ts","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAmBhF"}

package/dist/asset-reference.js

@@ -1,6 +1,7 @@
+import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
-import { safePath } from './path-utils.js';
+import { isAbsolutePath, safePath } from './path-utils.js';
 // First segment must be a valid npm package name (scoped or unscoped),
 // followed by `/` and at least one subpath segment. Paths starting with
 // `.`, `/`, or a Windows drive letter are filesystem paths, never bare
@@ -55,8 +56,65 @@ export function resolveAssetReference(specifier, baseDir) {
         if (!specifier.startsWith('@') && isModuleNotFound(cause)) {
             return safePath.resolve(baseDir, specifier);
         }
-        throw new Error(`Failed to resolve asset reference '${specifier}': ${formatResolutionError(cause)}\n` +
-            `Check the package's "exports" field, or run install in ${baseDir}.`, { cause: cause });
+        throw new Error(formatActionableError(specifier, baseDir, cause), { cause: cause });
+    }
+}
+/**
+ * Build a message that distinguishes the three common failure modes so callers
+ * know where to look. Node's raw error often points at the resolved on-disk
+ * path, which adopters easily misread as a VAT path-handling bug.
+ */
+function formatActionableError(specifier, baseDir, cause) {
+    const headline = formatResolutionError(cause);
+    const code = cause?.code;
+    const missingPath = extractMissingModulePath(cause);
+    // Mode 1: Node walked the package's `exports` map, computed an absolute
+    // target path, and that file is not on disk. This is the most confusing
+    // case for adopters: the package IS installed, the exports map IS correct,
+    // but a build step in the target package didn't run (or produced different
+    // output). Name the missing file explicitly and point at the publisher.
+    if (code === 'MODULE_NOT_FOUND' && missingPath && missingPath !== specifier && isAbsolutePath(missingPath)) {
+        const fileExists = safeExistsSync(missingPath);
+        if (!fileExists) {
+            return (`Failed to resolve asset reference '${specifier}': ` +
+                `the package's "exports" map points to '${missingPath}', but that file does not exist on disk.\n` +
+                `Hint: the target package was found, but a build step did not produce this file. ` +
+                `Rebuild the publishing package (e.g., \`pnpm --filter <package> build\`) to generate the missing artifact, ` +
+                `or verify the package's "exports" subpath pattern matches what its build emits.\n` +
+                `Node error: ${headline}`);
+        }
+    }
+    // Mode 2: Exports map didn't expose the requested subpath at all.
+    if (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+        return (`Failed to resolve asset reference '${specifier}': ` +
+            `the target package does not expose this subpath in its "exports" map.\n` +
+            `Hint: check the package's package.json "exports" field — only paths declared there are reachable via bare specifier.\n` +
+            `Node error: ${headline}`);
+    }
+    // Mode 3: Package itself not installed / not reachable from baseDir.
+    return (`Failed to resolve asset reference '${specifier}': ${headline}\n` +
+        `Check the package's "exports" field, or run install in ${baseDir}.`);
+}
+/**
+ * Node's MODULE_NOT_FOUND message has the form: `Cannot find module 'X'`.
+ * Pull `X` out so we can decide whether the error refers to the original
+ * specifier (package not installed) or to a resolved on-disk path (file
+ * missing at exports target).
+ */
+const CANNOT_FIND_MODULE_RE = /Cannot find module '([^']+)'/;
+function extractMissingModulePath(cause) {
+    if (!(cause instanceof Error))
+        return undefined;
+    const match = CANNOT_FIND_MODULE_RE.exec(cause.message);
+    return match?.[1];
+}
+function safeExistsSync(filePath) {
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a Node-resolved exports target, used only to refine the error message
+        return existsSync(filePath);
+    }
+    catch {
+        return false;
     }
 }
 function isBareSpecifier(value) {

package/dist/asset-reference.js.map

@@ -1 +1 @@
-{"version":3,"file":"asset-reference.js","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,uEAAuE;AACvE,wEAAwE;AACxE,uEAAuE;AACvE,cAAc;AACd,MAAM,iBAAiB,GAAG,8CAA8C,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB,EAAE,OAAe;IACtE,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAE5F,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,qEAAqE;QACrE,qEAAqE;QACrE,oEAAoE;QACpE,qBAAqB;QACrB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1D,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,IAAI,KAAK,CACb,sCAAsC,SAAS,MAAM,qBAAqB,CAAC,KAAK,CAAC,IAAI;YACnF,0DAA0D,OAAO,GAAG,EACtE,EAAE,KAAK,EAAE,KAAc,EAAE,CAC1B,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAY;IACpC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACZ,GAAwB,CAAC,IAAI,KAAK,kBAAkB,CACtD,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAAC,GAAY;IACzC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,uEAAuE;QACvE,wDAAwD;QACxD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,OAAO,SAAS,IAAI,GAAG,CAAC,OAAO,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC"}
+{"version":3,"file":"asset-reference.js","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,eAAe,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,eAAe,CAAC;AAG9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,eAAe,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,gBAAgB,CAAC;AAI/B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,eAAe,CAAC;AAG9B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -18,7 +18,8 @@ export * from './file-crawler.js';
 export * from './gitignore-checker.js';
 // Git utilities (using git commands directly)
 export * from './git-utils.js';
-// Project root discovery (workspace root -> git root -> fallback)
+// Project root discovery (canonical: config → git → null).
+// CLI-boundary use only — see docs/concepts/roots-and-config.md.
 export * from './project-utils.js';
 // Git tracking cache (for efficient git-ignore checking)
 export * from './git-tracker.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,cAAc,gBAAgB,CAAC;AAE/B,gCAAgC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,2DAA2D;AAC3D,cAAc,sBAAsB,CAAC;AAErC,uBAAuB;AACvB,cAAc,eAAe,CAAC;AAE9B,wCAAwC;AACxC,cAAc,mBAAmB,CAAC;AAElC,sBAAsB;AACtB,cAAc,wBAAwB,CAAC;AAEvC,8CAA8C;AAC9C,cAAc,gBAAgB,CAAC;AAE/B,kEAAkE;AAClE,cAAc,oBAAoB,CAAC;AAEnC,yDAAyD;AACzD,cAAc,kBAAkB,CAAC;AAEjC,oDAAoD;AACpD,cAAc,mBAAmB,CAAC;AAElC,4CAA4C;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,2DAA2D;AAC3D,cAAc,eAAe,CAAC;AAE9B,oEAAoE;AACpE,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,cAAc,gBAAgB,CAAC;AAE/B,gCAAgC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,2DAA2D;AAC3D,cAAc,sBAAsB,CAAC;AAErC,uBAAuB;AACvB,cAAc,eAAe,CAAC;AAE9B,wCAAwC;AACxC,cAAc,mBAAmB,CAAC;AAElC,sBAAsB;AACtB,cAAc,wBAAwB,CAAC;AAEvC,8CAA8C;AAC9C,cAAc,gBAAgB,CAAC;AAE/B,2DAA2D;AAC3D,iEAAiE;AACjE,cAAc,oBAAoB,CAAC;AAEnC,yDAAyD;AACzD,cAAc,kBAAkB,CAAC;AAEjC,oDAAoD;AACpD,cAAc,mBAAmB,CAAC;AAElC,4CAA4C;AAC5C,cAAc,wBAAwB,CAAC;AAEvC,2DAA2D;AAC3D,cAAc,eAAe,CAAC;AAE9B,oEAAoE;AACpE,cAAc,oBAAoB,CAAC"}

package/dist/project-utils.d.ts

@@ -1,19 +1,58 @@
 /**
- * Project root discovery utilities.
+ * Canonical root-discovery primitives for VAT.
  *
- * Finds the project root directory using a layered detection strategy:
- * workspace root (monorepo) -> git root -> directory fallback.
+ * Per spec docs/superpowers/specs/2026-05-17-root-model-and-leading-slash-design.md §6,
+ * these are CLI-boundary functions: inner libraries take roots as parameters, not these.
+ * All return `string | null` with no internal fallbacks.
  */
 /**
- * Find the project root for boundary enforcement.
+ * Find the nearest vibe-agent-toolkit.config.yaml by walking up from startDir.
  *
- * Detection order:
- * 1. Walk up from startDir looking for package.json with "workspaces" (monorepo root)
- * 2. Fall back to git repository root
- * 3. Fall back to startDir itself (tests / standalone)
+ * Returns the path to the config file itself (not its directory). Returns null
+ * if no config exists in any ancestor.
  *
- * @param startDir - Directory to start searching from (e.g., dirname of SKILL.md)
- * @returns Project root directory
+ * @param startDir - Directory to start the walk from
+ * @returns Path to the config file, or null if not found
  */
-export declare function findProjectRoot(startDir: string): string;
+export declare function findConfigFile(startDir: string): string | null;
+/**
+ * Find the nearest package.json with a "workspaces" key by walking up.
+ *
+ * Used for Node-monorepo binary discovery and Node-specific tooling only.
+ * NOT a substitute for findProjectRoot — VAT projects are not required to be
+ * npm workspaces. Returns null when no workspaces-bearing package.json is found.
+ *
+ * @param startDir - Directory to start the walk from
+ * @returns Path to the workspace root directory, or null if not found
+ */
+export declare function findNodeWorkspaceRoot(startDir: string): string | null;
+/**
+ * Reset {@link findProjectRoot}'s module-level cache.
+ *
+ * Call at the start of each independent CLI invocation so in-process callers
+ * (and integration tests sharing a vitest worker) don't observe stale results.
+ */
+export declare function resetProjectRootCaches(): void;
+/**
+ * Find the VAT project root.
+ *
+ * Discovery ladder (checks startDir itself first, then each ancestor):
+ *   1. Directory containing vibe-agent-toolkit.config.yaml → that directory
+ *   2. Directory containing .git/                          → that directory
+ *   3. null
+ *
+ * The config-anchored ladder runs to completion first; only if no config is
+ * found anywhere up the tree do we walk a second time looking for .git/.
+ * This implements the "config wins over git, regardless of relative depth"
+ * semantic from spec §4 (config-file placement is a stronger declaration of
+ * intent than the git boundary).
+ *
+ * Cached at the module level via {@link walkUpCache}. The cache is keyed by
+ * each walked directory; entries are written for every dir touched on the
+ * walk so subsequent calls from siblings/descendants become Layer-1 hits.
+ *
+ * @param startDir - Directory to start the walk from
+ * @returns Project root directory, or null if neither config nor git root found
+ */
+export declare function findProjectRoot(startDir: string): string | null;
 //# sourceMappingURL=project-utils.d.ts.map

package/dist/project-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-utils.d.ts","sourceRoot":"","sources":["../src/project-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+BxD"}
+{"version":3,"file":"project-utils.d.ts","sourceRoot":"","sources":["../src/project-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBrE;AAkBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAoED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK/D"}

package/dist/project-utils.js

@@ -1,53 +1,181 @@
 /**
- * Project root discovery utilities.
+ * Canonical root-discovery primitives for VAT.
  *
- * Finds the project root directory using a layered detection strategy:
- * workspace root (monorepo) -> git root -> directory fallback.
+ * Per spec docs/superpowers/specs/2026-05-17-root-model-and-leading-slash-design.md §6,
+ * these are CLI-boundary functions: inner libraries take roots as parameters, not these.
+ * All return `string | null` with no internal fallbacks.
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { gitFindRoot } from './git-utils.js';
+import { dirname, parse } from 'node:path';
 import { safePath } from './path-utils.js';
+const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
 const PACKAGE_JSON_FILENAME = 'package.json';
 /**
- * Find the project root for boundary enforcement.
+ * Find the nearest vibe-agent-toolkit.config.yaml by walking up from startDir.
  *
- * Detection order:
- * 1. Walk up from startDir looking for package.json with "workspaces" (monorepo root)
- * 2. Fall back to git repository root
- * 3. Fall back to startDir itself (tests / standalone)
+ * Returns the path to the config file itself (not its directory). Returns null
+ * if no config exists in any ancestor.
  *
- * @param startDir - Directory to start searching from (e.g., dirname of SKILL.md)
- * @returns Project root directory
+ * @param startDir - Directory to start the walk from
+ * @returns Path to the config file, or null if not found
  */
-export function findProjectRoot(startDir) {
-    let currentDir = safePath.resolve(startDir);
-    const resolvedStartDir = currentDir;
-    // 1. Walk up looking for workspace root (package.json with "workspaces")
-    while (currentDir !== dirname(currentDir)) {
-        const packageJsonPath = safePath.join(currentDir, PACKAGE_JSON_FILENAME);
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Walking up from validated startDir
-        if (existsSync(packageJsonPath)) {
+export function findConfigFile(startDir) {
+    let current = safePath.resolve(startDir);
+    const root = parse(current).root;
+    while (true) {
+        const candidate = safePath.join(current, CONFIG_FILENAME);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- walk-up is intentional
+        if (existsSync(candidate))
+            return candidate;
+        if (current === root)
+            return null;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Find the nearest package.json with a "workspaces" key by walking up.
+ *
+ * Used for Node-monorepo binary discovery and Node-specific tooling only.
+ * NOT a substitute for findProjectRoot — VAT projects are not required to be
+ * npm workspaces. Returns null when no workspaces-bearing package.json is found.
+ *
+ * @param startDir - Directory to start the walk from
+ * @returns Path to the workspace root directory, or null if not found
+ */
+export function findNodeWorkspaceRoot(startDir) {
+    let current = safePath.resolve(startDir);
+    while (current !== dirname(current)) {
+        const pkgPath = safePath.join(current, PACKAGE_JSON_FILENAME);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- walk-up is intentional
+        if (existsSync(pkgPath)) {
             try {
-                // eslint-disable-next-line security/detect-non-literal-fs-filename -- Walking up from validated startDir
-                const content = readFileSync(packageJsonPath, 'utf-8');
-                const parsed = JSON.parse(content);
+                // eslint-disable-next-line security/detect-non-literal-fs-filename -- walk-up is intentional
+                const parsed = JSON.parse(readFileSync(pkgPath, 'utf-8'));
                 if (typeof parsed === 'object' && parsed !== null && 'workspaces' in parsed) {
-                    return currentDir;
+                    return current;
                 }
             }
             catch {
-                // Invalid JSON - skip this package.json
+                // Invalid JSON — skip and continue walking up.
             }
         }
-        currentDir = dirname(currentDir);
+        current = dirname(current);
+    }
+    return null;
+}
+/**
+ * Layer 1 cache for {@link findProjectRoot}.
+ *
+ * Each entry answers a property *of the keyed directory*: "what `projectRoot`
+ * governs files at or below this dir?" Because the answer is independent of
+ * where a walk-up started, entries can be safely shared across starting
+ * points.
+ *
+ * Tests that mutate fixtures between runs (or in-process callers that
+ * re-enter `vat audit` in the same process) must call
+ * {@link resetProjectRootCaches} to invalidate this cache.
+ *
+ * See spec docs/superpowers/specs/2026-05-17-root-model-and-leading-slash-design.md §8.
+ */
+const walkUpCache = new Map();
+/**
+ * Reset {@link findProjectRoot}'s module-level cache.
+ *
+ * Call at the start of each independent CLI invocation so in-process callers
+ * (and integration tests sharing a vitest worker) don't observe stale results.
+ */
+export function resetProjectRootCaches() {
+    walkUpCache.clear();
+}
+/** Write `entry` into walkUpCache for every dir in `visited`. */
+function propagateCache(visited, entry) {
+    for (const dir of visited)
+        walkUpCache.set(dir, entry);
+}
+/**
+ * Config-anchored walk-up phase. Walks ancestors of `startDir`, populating
+ * `visited` and consulting/writing the walk-up cache.
+ *
+ * Returns one of three results:
+ * - `{ kind: 'found', configRoot }` — a config or cache hit produced an
+ *   answer; cache has already been propagated to all visited dirs.
+ * - `{ kind: 'exhausted' }` — reached filesystem root without finding a
+ *   config; the caller should run the git-anchored phase.
+ *
+ * @returns walk result
+ */
+function configWalkPhase(startDir, visited) {
+    let current = safePath.resolve(startDir);
+    while (true) {
+        const cached = walkUpCache.get(current);
+        if (cached !== undefined) {
+            propagateCache(visited, cached);
+            return { kind: 'found', configRoot: cached.configRoot };
+        }
+        visited.push(current);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- walk-up is intentional
+        if (existsSync(safePath.join(current, CONFIG_FILENAME))) {
+            const entry = { configRoot: current };
+            propagateCache(visited, entry);
+            return { kind: 'found', configRoot: current };
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return { kind: 'exhausted' };
+        current = parent;
     }
-    // 2. Fall back to git root
-    const gitRoot = gitFindRoot(resolvedStartDir);
-    if (gitRoot !== null) {
-        return gitRoot;
+}
+/**
+ * Git-anchored walk-up phase. Only runs after `configWalkPhase` reports
+ * `exhausted`. Walks the same chain looking for `.git/` and writes the final
+ * answer (the .git dir or null) into walkUpCache for every visited dir.
+ */
+function gitWalkPhase(startDir, visited) {
+    let current = safePath.resolve(startDir);
+    while (true) {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- walk-up is intentional
+        if (existsSync(safePath.join(current, '.git'))) {
+            const entry = { configRoot: current };
+            propagateCache(visited, entry);
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            propagateCache(visited, { configRoot: null });
+            return null;
+        }
+        current = parent;
     }
-    // 3. Fall back to start directory
-    return resolvedStartDir;
+}
+/**
+ * Find the VAT project root.
+ *
+ * Discovery ladder (checks startDir itself first, then each ancestor):
+ *   1. Directory containing vibe-agent-toolkit.config.yaml → that directory
+ *   2. Directory containing .git/                          → that directory
+ *   3. null
+ *
+ * The config-anchored ladder runs to completion first; only if no config is
+ * found anywhere up the tree do we walk a second time looking for .git/.
+ * This implements the "config wins over git, regardless of relative depth"
+ * semantic from spec §4 (config-file placement is a stronger declaration of
+ * intent than the git boundary).
+ *
+ * Cached at the module level via {@link walkUpCache}. The cache is keyed by
+ * each walked directory; entries are written for every dir touched on the
+ * walk so subsequent calls from siblings/descendants become Layer-1 hits.
+ *
+ * @param startDir - Directory to start the walk from
+ * @returns Project root directory, or null if neither config nor git root found
+ */
+export function findProjectRoot(startDir) {
+    const visited = [];
+    const configPhase = configWalkPhase(startDir, visited);
+    if (configPhase.kind === 'found')
+        return configPhase.configRoot;
+    return gitWalkPhase(startDir, visited);
 }
 //# sourceMappingURL=project-utils.js.map

package/dist/project-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-utils.js","sourceRoot":"","sources":["../src/project-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAG3C,MAAM,qBAAqB,GAAG,cAAc,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,IAAI,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,gBAAgB,GAAG,UAAU,CAAC;IAEpC,yEAAyE;IACzE,OAAO,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1C,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC;QACzE,yGAAyG;QACzG,IAAI,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,yGAAyG;gBACzG,MAAM,OAAO,GAAG,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;gBACvD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC5C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,YAAY,IAAI,MAAM,EAAE,CAAC;oBAC5E,OAAO,UAAU,CAAC;gBACpB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,wCAAwC;YAC1C,CAAC;QACH,CAAC;QACD,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IAED,2BAA2B;IAC3B,MAAM,OAAO,GAAG,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAC9C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,kCAAkC;IAClC,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"project-utils.js","sourceRoot":"","sources":["../src/project-utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "type": "module",
   "description": "Core utility functions with no external dependencies",
   "keywords": [