@vibe-agent-toolkit/utils 0.1.34 → 0.1.36

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":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAuBhF"}

package/dist/asset-reference.js

@@ -0,0 +1,80 @@
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { 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(`Failed to resolve asset reference '${specifier}': ${formatResolutionError(cause)}\n` +
+            `Check the package's "exports" field, or run install in ${baseDir}.`, { cause: cause });
+    }
+}
+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":"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"}

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.34",
+  "version": "0.1.36",
   "type": "module",
   "description": "Core utility functions with no external dependencies",
   "keywords": [