@vibe-agent-toolkit/resources 0.1.36 → 0.1.38

package/dist/types.d.ts

@@ -20,7 +20,7 @@ export type { BaseResource, Heading, JsonResource, JsonSchemaResource, MarkdownR
 export { getResourceAbsolutePath, isValidProjectPath, normalizeProjectPath, } from './types/resource-path-utils.js';
 export { detectResourceType, parseJsonResource, parseJsonSchemaResource, parseMarkdownResource, parseYamlResource, } from './types/resource-parser.js';
 export type { ValidationMode, CollectionValidation, CollectionConfig, ResourcesConfig, ProjectConfig, SkillFileEntry, SkillPackagingConfig, SkillsConfig, ClaudeConfig, ClaudeMarketplaceConfig, ClaudeMarketplacePluginEntry, } from './schemas/project-config.js';
-export { findConfigFile, parseConfigFile, loadConfig, } from './config-parser.js';
+export { parseConfigFile, loadConfig, } from './config-parser.js';
 export { isGlobPattern, expandPattern, expandPatterns, } from './pattern-expander.js';
 export { matchesCollection, getCollectionsForFile, } from './collection-matcher.js';
 export type { ValidateLinkOptions } from './link-validator.js';

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,YAAY,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGrD,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AAGxC,YAAY,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AAGxC,YAAY,EACV,YAAY,EACZ,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,YAAY,EACZ,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,YAAY,GACb,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAGpC,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,8BAA8B,GAC/B,MAAM,6BAA6B,CAAC;AAGrC,YAAY,EACV,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,YAAY,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGrD,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AAGxC,YAAY,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AAGxC,YAAY,EACV,YAAY,EACZ,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,YAAY,EACZ,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,YAAY,GACb,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAGpC,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,8BAA8B,GAC/B,MAAM,6BAA6B,CAAC;AAGrC,YAAY,EACV,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/types.js

@@ -18,7 +18,7 @@ export { getResourceAbsolutePath, isValidProjectPath, normalizeProjectPath, } fr
 // Resource parsing
 export { detectResourceType, parseJsonResource, parseJsonSchemaResource, parseMarkdownResource, parseYamlResource, } from './types/resource-parser.js';
 // Config parsing
-export { findConfigFile, parseConfigFile, loadConfig, } from './config-parser.js';
+export { parseConfigFile, loadConfig, } from './config-parser.js';
 // Pattern expansion
 export { isGlobPattern, expandPattern, expandPatterns, } from './pattern-expander.js';
 // Collection matching

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AA2BrD,uBAAuB;AACvB,OAAO,EACL,YAAY,EACZ,YAAY,GACb,MAAM,sBAAsB,CAAC;AAY9B,0BAA0B;AAC1B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,mBAAmB;AACnB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAiBpC,iBAAiB;AACjB,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAE5B,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAE/B,sBAAsB;AACtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,oBAAoB;AACpB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAEhC,0BAA0B;AAC1B,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,8BAA8B,GAC/B,MAAM,6BAA6B,CAAC;AAOrC,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AA2BrD,uBAAuB;AACvB,OAAO,EACL,YAAY,EACZ,YAAY,GACb,MAAM,sBAAsB,CAAC;AAY9B,0BAA0B;AAC1B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,mBAAmB;AACnB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAiBpC,iBAAiB;AACjB,OAAO,EACL,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAE5B,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC;AAE/B,sBAAsB;AACtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,oBAAoB;AACpB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAEhC,0BAA0B;AAC1B,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,8BAA8B,GAC/B,MAAM,6BAA6B,CAAC;AAOrC,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/utils.d.ts

@@ -35,32 +35,60 @@ export declare function matchesGlobPattern(filePath: string, pattern: string): b
  */
 export declare function splitHrefAnchor(href: string): [string, string | undefined];
 /**
- * Resolve a markdown link href to an absolute filesystem path.
+ * Discriminated union returned by {@link resolveLocalHref}.
+ *
+ * - `anchor_only` — the href was `#fragment` only (no file component).
+ * - `resolved` — the href resolved to an absolute filesystem path.
+ * - `absolute_no_root` — the href is an RFC 3986 §4.2 absolute-path
+ *   reference (starts with `/`) but no `projectRoot` was supplied.
+ * - `absolute_escapes_root` — the absolute-path reference resolved to a
+ *   location outside `projectRoot` (e.g., via `..` traversal or a symlink
+ *   pointing outside the project).
+ */
+export type ResolveLocalHrefResult = {
+    kind: 'anchor_only';
+} | {
+    kind: 'resolved';
+    resolvedPath: string;
+    anchor: string | undefined;
+} | {
+    kind: 'absolute_no_root';
+    href: string;
+    anchor: string | undefined;
+} | {
+    kind: 'absolute_escapes_root';
+    href: string;
+    anchor: string | undefined;
+};
+/**
+ * Resolve a markdown link href to a filesystem path or a typed failure.
  *
  * Performs the standard href → path conversion used by both audit and validate:
  * 1. Strips anchor fragment (`#section`)
  * 2. Decodes URL-encoded characters (`%20` → space, `%26` → `&`)
- * 3. Resolves the path relative to the source file's directory
- *
- * Returns `null` for anchor-only links (e.g., `#heading`).
+ * 3. Resolves the path:
+ *    - Leading `/` (RFC 3986 §4.2 absolute-path reference) → resolve against
+ *      `projectRoot`. Requires a `projectRoot`; must not escape it.
+ *    - Otherwise → resolve relative to the source file's directory.
  *
  * @param href - Raw href from a markdown link
  * @param sourceFilePath - Absolute path of the file containing the link
- * @returns Resolved path info, or null for anchor-only links
+ * @param projectRoot - Optional project root for absolute-path references.
+ * @returns A {@link ResolveLocalHrefResult} discriminating success vs failure modes.
  *
  * @example
  * ```typescript
  * resolveLocalHref('My%20Folder/doc.md#intro', '/project/README.md')
- * // { resolvedPath: '/project/My Folder/doc.md', anchor: 'intro' }
+ * // { kind: 'resolved', resolvedPath: '/project/My Folder/doc.md', anchor: 'intro' }
  *
  * resolveLocalHref('#heading', '/project/README.md')
- * // null
+ * // { kind: 'anchor_only' }
+ *
+ * resolveLocalHref('/docs/foo.md', '/project/docs/sub/page.md', '/project')
+ * // { kind: 'resolved', resolvedPath: '/project/docs/foo.md', anchor: undefined }
  * ```
  */
-export declare function resolveLocalHref(href: string, sourceFilePath: string): {
-    resolvedPath: string;
-    anchor: string | undefined;
-} | null;
+export declare function resolveLocalHref(href: string, sourceFilePath: string, projectRoot?: string): ResolveLocalHrefResult;
 /**
  * Check if a file path is within a project directory.
  *
@@ -100,4 +128,5 @@ export declare function decodeJsonPointerSegment(segment: string): string;
  *   formatJsonPointerAsDotted('')                       // ''
  */
 export declare function formatJsonPointerAsDotted(pointer: string): string;
+export declare function isCanonicalArrayIndex(s: string): boolean;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAoB7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAS1E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACrB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,IAAI,CAiB7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAqB9E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAcjE"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAoB7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAS1E;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,sBAAsB,CA6BxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CA6B9E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAcjE;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAUxD"}

package/dist/utils.js

@@ -64,32 +64,37 @@ export function splitHrefAnchor(href) {
     return [filePath, anchor];
 }
 /**
- * Resolve a markdown link href to an absolute filesystem path.
+ * Resolve a markdown link href to a filesystem path or a typed failure.
  *
  * Performs the standard href → path conversion used by both audit and validate:
  * 1. Strips anchor fragment (`#section`)
  * 2. Decodes URL-encoded characters (`%20` → space, `%26` → `&`)
- * 3. Resolves the path relative to the source file's directory
- *
- * Returns `null` for anchor-only links (e.g., `#heading`).
+ * 3. Resolves the path:
+ *    - Leading `/` (RFC 3986 §4.2 absolute-path reference) → resolve against
+ *      `projectRoot`. Requires a `projectRoot`; must not escape it.
+ *    - Otherwise → resolve relative to the source file's directory.
  *
  * @param href - Raw href from a markdown link
  * @param sourceFilePath - Absolute path of the file containing the link
- * @returns Resolved path info, or null for anchor-only links
+ * @param projectRoot - Optional project root for absolute-path references.
+ * @returns A {@link ResolveLocalHrefResult} discriminating success vs failure modes.
  *
  * @example
  * ```typescript
  * resolveLocalHref('My%20Folder/doc.md#intro', '/project/README.md')
- * // { resolvedPath: '/project/My Folder/doc.md', anchor: 'intro' }
+ * // { kind: 'resolved', resolvedPath: '/project/My Folder/doc.md', anchor: 'intro' }
  *
  * resolveLocalHref('#heading', '/project/README.md')
- * // null
+ * // { kind: 'anchor_only' }
+ *
+ * resolveLocalHref('/docs/foo.md', '/project/docs/sub/page.md', '/project')
+ * // { kind: 'resolved', resolvedPath: '/project/docs/foo.md', anchor: undefined }
  * ```
  */
-export function resolveLocalHref(href, sourceFilePath) {
+export function resolveLocalHref(href, sourceFilePath, projectRoot) {
     const [fileHref, anchor] = splitHrefAnchor(href);
     if (fileHref === '') {
-        return null;
+        return { kind: 'anchor_only' };
     }
     let decodedHref;
     try {
@@ -98,9 +103,21 @@ export function resolveLocalHref(href, sourceFilePath) {
     catch {
         decodedHref = fileHref;
     }
+    // RFC 3986 §4.2 absolute-path reference — resolve against projectRoot.
+    if (decodedHref.startsWith('/')) {
+        if (!projectRoot) {
+            return { kind: 'absolute_no_root', href: fileHref, anchor };
+        }
+        const candidate = safePath.resolve(projectRoot, decodedHref.slice(1));
+        if (!isWithinProject(candidate, projectRoot)) {
+            return { kind: 'absolute_escapes_root', href: fileHref, anchor };
+        }
+        return { kind: 'resolved', resolvedPath: candidate, anchor };
+    }
+    // Relative reference — resolve against the source file's directory.
     const sourceDir = path.dirname(sourceFilePath);
     const resolvedPath = safePath.resolve(sourceDir, decodedHref);
-    return { resolvedPath, anchor };
+    return { kind: 'resolved', resolvedPath, anchor };
 }
 /**
  * Check if a file path is within a project directory.
@@ -120,7 +137,9 @@ export function resolveLocalHref(href, sourceFilePath) {
  * ```
  */
 export function isWithinProject(filePath, projectRoot) {
-    // Resolve symlinks to get real paths
+    // Canonicalize both sides symmetrically. Asymmetric handling (realpath one
+    // side, resolve the other) false-flags legitimate matches when projectRoot
+    // traverses a symlink — e.g. macOS /tmp → /private/tmp, bind mounts.
     let resolvedFilePath;
     try {
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is validated path parameter
@@ -130,7 +149,14 @@ export function isWithinProject(filePath, projectRoot) {
         // If realpath fails, file doesn't exist - use original path
         resolvedFilePath = safePath.resolve(filePath);
     }
-    const resolvedProjectRoot = safePath.resolve(projectRoot);
+    let resolvedProjectRoot;
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- projectRoot is validated path parameter
+        resolvedProjectRoot = fs.realpathSync(projectRoot);
+    }
+    catch {
+        resolvedProjectRoot = safePath.resolve(projectRoot);
+    }
     // Normalize to forward slashes for cross-platform comparison
     const normalizedFile = toForwardSlash(resolvedFilePath);
     const normalizedRoot = toForwardSlash(resolvedProjectRoot);
@@ -179,7 +205,7 @@ export function formatJsonPointerAsDotted(pointer) {
     }
     return out;
 }
-function isCanonicalArrayIndex(s) {
+export function isCanonicalArrayIndex(s) {
     // Canonical integer per RFC 6901 §4 + JSON canonical form: no leading zeros
     // except for "0" itself.
     if (s === '')

package/dist/utils.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/resources",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Markdown resource parsing, validation, and link integrity checking",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,11 +33,11 @@
   "author": "Jeff Dutton",
   "license": "MIT",
   "dependencies": {
-    "@vibe-agent-toolkit/agent-schema": "0.1.36",
-    "@vibe-agent-toolkit/utils": "0.1.36",
+    "@vibe-agent-toolkit/agent-schema": "0.1.38",
+    "@vibe-agent-toolkit/utils": "0.1.38",
     "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "github-slugger": "^2.0.0",
-    "js-yaml": "^4.1.1",
     "markdown-link-check": "^3.14.2",
     "picomatch": "^4.0.3",
     "remark-frontmatter": "^5.0.0",
@@ -46,10 +46,10 @@
     "semver": "^7.7.3",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
+    "yaml": "^2.6.1",
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.4",
     "@types/node": "^22.10.5",
     "@types/picomatch": "^4.0.2",

package/src/ajv-factory.ts

@@ -0,0 +1,56 @@
+/**
+ * Ajv factory for adopters consuming VAT-generated schemas.
+ *
+ * VAT's frontmatter walker treats `format: "uri-reference"` (plus `uri`,
+ * `iri`, `iri-reference`) as first-class URI families and validates the
+ * referenced files via {@link import('./utils.js').resolveLocalHref}, not via
+ * Ajv. But adopters consuming the same schemas with vanilla
+ * `new Ajv(...)` hit Ajv's default strict mode, which upgrades
+ * `unknown format "uri-reference" ignored` from a warning to a thrown error.
+ *
+ * This helper returns an Ajv instance with the standard JSON Schema format
+ * vocabulary registered (via `ajv-formats`) plus no-op shims for
+ * `iri` / `iri-reference` (which `ajv-formats` does not ship). All
+ * URI-family schemas compile cleanly under strict mode.
+ */
+
+import { Ajv, type Options as AjvOptions } from 'ajv';
+// ajv-formats is a CJS module published with `module.exports = formatsPlugin`
+// plus an `exports.default` alias. Under NodeNext module resolution the
+// default import is typed as the namespace object (not callable), even
+// though the runtime value IS the plugin function. The `.default ??
+// namespace` pattern below resolves both at type level and runtime.
+import * as ajvFormatsModule from 'ajv-formats';
+
+type AddFormatsFn = (ajv: Ajv) => Ajv;
+
+const addFormats: AddFormatsFn =
+  (ajvFormatsModule as unknown as { default?: AddFormatsFn }).default ??
+  (ajvFormatsModule as unknown as AddFormatsFn);
+
+/**
+ * Construct an Ajv instance pre-registered with the URI-family formats VAT
+ * schemas use. Use this anywhere downstream code compiles a schema that may
+ * reference `format: "uri-reference"` (or `uri`, `iri`, `iri-reference`).
+ *
+ * @param options - Ajv options. Passed through unchanged — caller controls
+ *   `allErrors`, `strict`, `allowUnionTypes`, `verbose`, etc.
+ *
+ * @example
+ * import { createAjvWithUriFormats } from '@vibe-agent-toolkit/resources';
+ *
+ * const ajv = createAjvWithUriFormats({ allErrors: true });
+ * const validate = ajv.compile(mySchemaWithUriReference);
+ * if (!validate(data)) console.error(validate.errors);
+ */
+export function createAjvWithUriFormats(options: AjvOptions = {}): Ajv {
+  const ajv = new Ajv(options);
+  addFormats(ajv);
+  // ajv-formats does not register `iri` / `iri-reference`. Adopters whose
+  // schemas declare those would still hit "unknown format" under strict
+  // mode. Register no-op validators — Ajv accepts the format token, and
+  // semantic validation happens through resolveLocalHref / equivalent.
+  ajv.addFormat('iri', true);
+  ajv.addFormat('iri-reference', true);
+  return ajv;
+}

package/src/config-parser.ts

@@ -5,58 +5,12 @@
  */
 
 import { readFile } from 'node:fs/promises';
-import path from 'node:path';
 
-import { safePath } from '@vibe-agent-toolkit/utils';
-import { load as loadYaml } from 'js-yaml';
+import { findConfigFile } from '@vibe-agent-toolkit/utils';
+import { parse as parseYaml } from 'yaml';
 
 import { ProjectConfigSchema, type ProjectConfig } from './schemas/project-config.js';
 
-const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
-
-/**
- * Find the config file by walking up the directory tree.
- *
- * Starts from the current directory and walks up until the config file is found
- * or the root directory is reached.
- *
- * @param startDir - Directory to start searching from (default: process.cwd())
- * @returns Absolute path to config file, or undefined if not found
- *
- * @example
- * ```typescript
- * const configPath = await findConfigFile();
- * if (configPath) {
- *   console.log(`Found config: ${configPath}`);
- * }
- * ```
- */
-export async function findConfigFile(startDir: string = process.cwd()): Promise<string | undefined> {
-  let currentDir = safePath.resolve(startDir);
-  const { root } = path.parse(currentDir);
-
-  while (true) {
-    const configPath = safePath.join(currentDir, CONFIG_FILENAME);
-
-    try {
-      // Check if file exists by attempting to read metadata
-      // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructing path during tree walk
-      await readFile(configPath, 'utf-8');
-      return configPath;
-    } catch {
-      // File doesn't exist, continue walking up
-    }
-
-    // Check if we've reached the root
-    if (currentDir === root) {
-      return undefined;
-    }
-
-    // Move up one directory
-    currentDir = path.dirname(currentDir);
-  }
-}
-
 /**
  * Parse a project configuration file.
  *
@@ -81,7 +35,7 @@ export async function parseConfigFile(configPath: string): Promise<ProjectConfig
   // Parse YAML
   let parsed: unknown;
   try {
-    parsed = loadYaml(content);
+    parsed = parseYaml(content);
   } catch (error) {
     throw new Error(`Invalid YAML in config file: ${error instanceof Error ? error.message : String(error)}`);
   }
@@ -117,7 +71,8 @@ export async function parseConfigFile(configPath: string): Promise<ProjectConfig
  * ```
  */
 export async function loadConfig(startDir: string = process.cwd()): Promise<ProjectConfig | undefined> {
-  const configPath = await findConfigFile(startDir);
+  // findConfigFile from utils is synchronous; awaiting a non-promise is a no-op.
+  const configPath = findConfigFile(startDir);
   if (!configPath) {
     return undefined;
   }

package/src/frontmatter-editor.ts

@@ -0,0 +1,214 @@
+/**
+ * FrontmatterEditor — round-trip-safe primitive for editing YAML frontmatter
+ * in markdown files.
+ *
+ * Public surface: openFrontmatter(markdown) → FrontmatterEditor.
+ *
+ * Round-trip identity contract: openFrontmatter(x).toString() === x for any
+ * well-formed input, byte-for-byte. Mutations preserve comments, blank lines,
+ * key ordering, quoting style, and detected EOL.
+ *
+ * See docs/superpowers/specs/2026-05-17-frontmatter-editor-and-yaml-consolidation-design.md
+ * §5 for the full contract.
+ */
+
+import { Document, parseDocument } from 'yaml';
+
+export class FrontmatterParseError extends Error {
+  public override readonly cause: unknown;
+
+  constructor(message: string, cause: unknown) {
+    super(message);
+    this.name = 'FrontmatterParseError';
+    this.cause = cause;
+  }
+}
+
+/** Path to a value in the parsed frontmatter document. */
+export type FrontmatterPath = string | readonly (string | number)[];
+
+/** Scalar value type accepted by mutation methods. */
+export type FrontmatterScalar = string | number | boolean | null;
+
+export interface FrontmatterEditor {
+  body: string;
+  get(path: FrontmatterPath): unknown;
+  set(path: FrontmatterPath, value: FrontmatterScalar): void;
+  setArrayItem(path: FrontmatterPath, index: number, value: FrontmatterScalar): void;
+  appendArrayItem(path: FrontmatterPath, value: FrontmatterScalar): void;
+  delete(path: FrontmatterPath): void;
+  toString(): string;
+  /**
+   * Returns true if any mutating method has been called or `body` was
+   * reassigned to a different string. Use to gate writeFileSync and avoid
+   * the no-op-rewrite churn described in §"What's preserved, what isn't"
+   * of the markdown-rewriting skill.
+   *
+   * **Caveat:** any call to `set` / `setArrayItem` / `appendArrayItem` /
+   * `delete` flips the flag, even if the underlying value didn't change
+   * (e.g. `set('foo', sameValue)`). For strict byte-level dirty detection
+   * compare `editor.toString() !== originalText` instead. `body =` is the
+   * one exception — it only flips dirty on actual string change.
+   */
+  isDirty(): boolean;
+}
+
+interface FrontmatterSplit {
+  hasFrontmatter: boolean;
+  frontmatterText: string;
+  body: string;
+  eol: '\n' | '\r\n';
+}
+
+const OPENING_FENCE = /^---\r?\n/;
+// Closing fence: either immediately after opening (empty frontmatter), or
+// preceded by a newline. Trailing variants accept newline or EOF.
+const EMPTY_CLOSING_FENCE = /^---(?:\r?\n|$)/;
+const CLOSING_FENCE = /(?:\r?\n---\r?\n|\r?\n---$)/;
+
+function detectEol(input: string): '\n' | '\r\n' {
+  const firstBreak = input.indexOf('\n');
+  if (firstBreak === -1) return '\n';
+  return firstBreak > 0 && input.charAt(firstBreak - 1) === '\r' ? '\r\n' : '\n';
+}
+
+function splitFrontmatter(input: string): FrontmatterSplit {
+  const eol = detectEol(input);
+  const openingMatch = OPENING_FENCE.exec(input);
+  if (!openingMatch) {
+    return { hasFrontmatter: false, frontmatterText: '', body: input, eol };
+  }
+  const afterOpening = input.slice(openingMatch[0].length);
+  // Handle empty frontmatter (closing fence immediately follows opening fence)
+  const emptyMatch = EMPTY_CLOSING_FENCE.exec(afterOpening);
+  if (emptyMatch) {
+    const bodyStart = emptyMatch[0].length;
+    return {
+      hasFrontmatter: true,
+      frontmatterText: '',
+      body: afterOpening.slice(bodyStart),
+      eol,
+    };
+  }
+  const closingMatch = CLOSING_FENCE.exec(afterOpening);
+  if (!closingMatch) {
+    return { hasFrontmatter: false, frontmatterText: '', body: input, eol };
+  }
+  const frontmatterText = afterOpening.slice(0, closingMatch.index);
+  const bodyStart = closingMatch.index + closingMatch[0].length;
+  const body = afterOpening.slice(bodyStart);
+  return { hasFrontmatter: true, frontmatterText, body, eol };
+}
+
+class FrontmatterEditorImpl implements FrontmatterEditor {
+  private readonly doc: Document.Parsed | Document;
+  private readonly hasFrontmatter: boolean;
+  private readonly eol: '\n' | '\r\n';
+  private _body: string;
+  private _dirty = false;
+
+  get body(): string {
+    return this._body;
+  }
+
+  set body(value: string) {
+    if (value !== this._body) {
+      this._body = value;
+      this._dirty = true;
+    }
+  }
+
+  isDirty(): boolean {
+    return this._dirty;
+  }
+
+  constructor(input: string) {
+    const split = splitFrontmatter(input);
+    this.hasFrontmatter = split.hasFrontmatter;
+    this.eol = split.eol;
+    this._body = split.body;
+    if (!split.hasFrontmatter) {
+      this.doc = new Document({});
+      return;
+    }
+    try {
+      this.doc = parseDocument(split.frontmatterText, { prettyErrors: true });
+      if (this.doc.errors.length > 0) {
+        throw new FrontmatterParseError(
+          `Invalid YAML frontmatter: ${this.doc.errors[0]?.message ?? 'unknown error'}`,
+          this.doc.errors[0],
+        );
+      }
+    } catch (error) {
+      if (error instanceof FrontmatterParseError) throw error;
+      throw new FrontmatterParseError(
+        `Failed to parse frontmatter: ${error instanceof Error ? error.message : String(error)}`,
+        error,
+      );
+    }
+  }
+
+  private toPath(path: FrontmatterPath): readonly (string | number)[] {
+    if (Array.isArray(path)) return path;
+    if (typeof path === 'string') return [path];
+    return path as readonly (string | number)[];
+  }
+
+  get(path: FrontmatterPath): unknown {
+    const segments = this.toPath(path);
+    if (segments.length === 0) return this.doc.toJS();
+    return this.doc.getIn(segments as Iterable<unknown>, false);
+  }
+
+  set(path: FrontmatterPath, value: FrontmatterScalar): void {
+    const segments = this.toPath(path);
+    this.doc.setIn(segments as Iterable<unknown>, value);
+    this._dirty = true;
+  }
+
+  setArrayItem(path: FrontmatterPath, index: number, value: FrontmatterScalar): void {
+    const segments = [...this.toPath(path), index];
+    this.doc.setIn(segments as Iterable<unknown>, value);
+    this._dirty = true;
+  }
+
+  appendArrayItem(path: FrontmatterPath, value: FrontmatterScalar): void {
+    const segments = this.toPath(path);
+    this.doc.addIn(segments as Iterable<unknown>, value);
+    this._dirty = true;
+  }
+
+  delete(path: FrontmatterPath): void {
+    const segments = this.toPath(path);
+    this.doc.deleteIn(segments as Iterable<unknown>);
+    this._dirty = true;
+  }
+
+  toString(): string {
+    // No frontmatter originally, and nothing was added → return body unchanged.
+    if (!this.hasFrontmatter && this.isDocEffectivelyEmpty()) {
+      return this.body;
+    }
+    // Empty frontmatter (e.g. `---\n---\n`) where the doc remained empty —
+    // preserve the empty fence block without injecting `null` or `{}` between.
+    if (this.hasFrontmatter && this.isDocEffectivelyEmpty()) {
+      return `---${this.eol}---${this.eol}${this.body}`;
+    }
+    const fmText = this.doc.toString();
+    const normalized = this.eol === '\r\n' ? fmText.replaceAll('\n', '\r\n') : fmText;
+    return `---${this.eol}${normalized}---${this.eol}${this.body}`;
+  }
+
+  private isDocEffectivelyEmpty(): boolean {
+    const contents = this.doc.contents;
+    if (contents === null) return true;
+    // yaml.YAMLMap and YAMLSeq expose `items`; an empty map/seq counts as empty.
+    const maybeItems = (contents as { items?: unknown[] }).items;
+    if (Array.isArray(maybeItems) && maybeItems.length === 0) return true;
+    return false;
+  }
+}
+
+export function openFrontmatter(markdown: string): FrontmatterEditor {
+  return new FrontmatterEditorImpl(markdown);
+}