@vibe-agent-toolkit/utils 0.1.35 → 0.1.37

package/dist/asset-reference.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Resolve a VAT "asset reference" to an absolute filesystem path.
+ *
+ * An asset reference is either:
+ *   - A filesystem path (relative to baseDir, or absolute), OR
+ *   - An npm bare specifier (`@scope/pkg/subpath` or `pkg/subpath`),
+ *     resolved via Node module resolution from baseDir, honoring the
+ *     target package's `exports` map.
+ *
+ * Bare specifiers let VAT consumers reference schemas (and future
+ * config-supplied files) published as npm packages without hardcoding
+ * the package's internal layout. The publisher's `exports` field owns
+ * the layout; consumers stay portable.
+ *
+ * NOTE: this is a VAT-internal abstraction for locating files. It is NOT
+ * an RFC 3986 URI reference and is intentionally NOT used by markdown link
+ * walkers (including the `format: "uri-reference"` frontmatter checker) —
+ * bare specifiers are not valid URIs and would not resolve in a renderer.
+ *
+ * @example
+ *   resolveAssetReference('@scope/pkg/schemas/foo.json', '/proj')
+ *     // -> '/proj/node_modules/@scope/pkg/dist/schemas/foo.json' (per the
+ *     //    package's exports map)
+ *   resolveAssetReference('./schemas/foo.json', '/proj')
+ *     // -> '/proj/schemas/foo.json'
+ *   resolveAssetReference('/abs/foo.json', '/proj')
+ *     // -> '/abs/foo.json'
+ *
+ * @param specifier - The asset reference (path or bare npm specifier)
+ * @param baseDir - Absolute directory used as the resolution anchor
+ * @returns Absolute filesystem path to the asset
+ * @throws Error with actionable message and `cause` on resolution failure
+ */
+export declare function resolveAssetReference(specifier: string, baseDir: string): string;
+//# sourceMappingURL=asset-reference.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,138 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+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
+// specifiers.
+const BARE_SPECIFIER_RE = /^(?:@[^/]+\/[^/]+|[a-z0-9][a-z0-9._-]*)\/.+/i;
+/**
+ * Resolve a VAT "asset reference" to an absolute filesystem path.
+ *
+ * An asset reference is either:
+ *   - A filesystem path (relative to baseDir, or absolute), OR
+ *   - An npm bare specifier (`@scope/pkg/subpath` or `pkg/subpath`),
+ *     resolved via Node module resolution from baseDir, honoring the
+ *     target package's `exports` map.
+ *
+ * Bare specifiers let VAT consumers reference schemas (and future
+ * config-supplied files) published as npm packages without hardcoding
+ * the package's internal layout. The publisher's `exports` field owns
+ * the layout; consumers stay portable.
+ *
+ * NOTE: this is a VAT-internal abstraction for locating files. It is NOT
+ * an RFC 3986 URI reference and is intentionally NOT used by markdown link
+ * walkers (including the `format: "uri-reference"` frontmatter checker) —
+ * bare specifiers are not valid URIs and would not resolve in a renderer.
+ *
+ * @example
+ *   resolveAssetReference('@scope/pkg/schemas/foo.json', '/proj')
+ *     // -> '/proj/node_modules/@scope/pkg/dist/schemas/foo.json' (per the
+ *     //    package's exports map)
+ *   resolveAssetReference('./schemas/foo.json', '/proj')
+ *     // -> '/proj/schemas/foo.json'
+ *   resolveAssetReference('/abs/foo.json', '/proj')
+ *     // -> '/abs/foo.json'
+ *
+ * @param specifier - The asset reference (path or bare npm specifier)
+ * @param baseDir - Absolute directory used as the resolution anchor
+ * @returns Absolute filesystem path to the asset
+ * @throws Error with actionable message and `cause` on resolution failure
+ */
+export function resolveAssetReference(specifier, baseDir) {
+    if (!isBareSpecifier(specifier)) {
+        return safePath.resolve(baseDir, specifier);
+    }
+    const requireFn = createRequire(pathToFileURL(safePath.join(baseDir, 'package.json')).href);
+    try {
+        return requireFn.resolve(specifier);
+    }
+    catch (cause) {
+        // Unscoped bare specifiers can also be interpreted as relative paths
+        // (e.g., `dir/file.json` with no installed package "dir"). Fall back
+        // to path resolution. Scoped (`@scope/...`) has no such ambiguity —
+        // surface the error.
+        if (!specifier.startsWith('@') && isModuleNotFound(cause)) {
+            return safePath.resolve(baseDir, specifier);
+        }
+        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) {
+    return BARE_SPECIFIER_RE.test(value);
+}
+function isModuleNotFound(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'code' in err &&
+        err.code === 'MODULE_NOT_FOUND');
+}
+function formatResolutionError(err) {
+    if (err instanceof Error) {
+        // Node's MODULE_NOT_FOUND / ERR_PACKAGE_PATH_NOT_EXPORTED messages are
+        // long and noisy; first line is the actionable summary.
+        const firstLine = err.message.split('\n', 1)[0];
+        return firstLine ?? err.message;
+    }
+    return String(err);
+}
+//# sourceMappingURL=asset-reference.js.map

package/dist/asset-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-reference.js","sourceRoot":"","sources":["../src/asset-reference.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  */
 export * from './safe-exec.js';
 export * from './path-utils.js';
+export * from './asset-reference.js';
 export * from './fs-utils.js';
 export * from './file-crawler.js';
 export * from './gitignore-checker.js';

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,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;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"}

package/dist/index.js

@@ -8,6 +8,8 @@
 export * from './safe-exec.js';
 // Cross-platform path utilities
 export * from './path-utils.js';
+// Asset reference resolution (paths + npm bare specifiers)
+export * from './asset-reference.js';
 // Filesystem utilities
 export * from './fs-utils.js';
 // Directory crawling with glob patterns

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,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,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"}

package/package.json

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