@vibe-agent-toolkit/resources 0.1.37 → 0.1.39-rc.1

package/README.md

@@ -47,7 +47,7 @@ console.log(`Errors: ${result.errorCount}, Warnings: ${result.warningCount}`);
 // Show any issues
 for (const issue of result.issues) {
   console.log(`${issue.severity.toUpperCase()}: ${issue.message}`);
-  if (issue.line) console.log(`  at ${issue.resourcePath}:${issue.line}`);
+  if (issue.line) console.log(`  at ${issue.location}:${issue.line}`);
 }
 ```
 
@@ -546,27 +546,35 @@ interface ValidationResult {
 
 A single validation issue found during link validation.
 
+`ValidationIssue` is the unified issue shape every VAT validator emits (defined
+in `@vibe-agent-toolkit/agent-schema`). Each issue carries a registry `code`
+(see [Validation Codes](../../docs/validation-codes.md)) and a resolved
+`severity`.
+
 ```typescript
 interface ValidationIssue {
-  severity: ValidationSeverity;      // Issue severity level
-  resourcePath: string;              // Absolute path to the resource containing the issue
-  line?: number;                     // Line number where the issue occurs
-  type: string;                      // Issue type identifier (e.g., 'broken_file', 'broken_anchor')
-  link: string;                      // The problematic link
+  code: string;                      // Registry code, e.g. 'LINK_BROKEN_FILE', 'EXTERNAL_URL_DEAD'
+  severity: SeverityLevel;           // Resolved severity (after config overrides)
   message: string;                   // Human-readable description
+  location?: string;                 // Project-relative path of the file containing the issue
+  line?: number;                     // Line number where the issue occurs
+  link?: string;                     // The problematic link (when applicable)
+  fix?: string;                      // Fix hint from the code registry
+  reference?: string;                // Anchor into docs/validation-codes.md
   suggestion?: string;               // Optional suggestion for fixing
 }
 ```
 
-### ValidationSeverity
+### SeverityLevel
 
 ```typescript
-type ValidationSeverity = 'error' | 'warning' | 'info';
+type SeverityLevel = 'error' | 'warning' | 'info' | 'ignore';
 ```
 
 - `error` - Critical issue that should block usage (e.g., broken file link)
-- `warning` - Non-critical issue that should be addressed (e.g., questionable link format)
-- `info` - Informational message (e.g., external URL not validated)
+- `warning` - Non-critical issue that should be addressed (e.g., dead external URL)
+- `info` - Informational message
+- `ignore` - Suppressed; the issue is not emitted (set via `validation.severity` config)
 
 ## Frontmatter Support
 
@@ -721,19 +729,19 @@ vat resources validate docs/ --frontmatter-schema schema.json
 
 ### Validation Result
 
-Frontmatter validation results are included in `ValidationResult`:
+Frontmatter findings are emitted into the same unified `result.issues` array as
+link findings — each carries a `FRONTMATTER_*` registry code (e.g.
+`FRONTMATTER_MISSING`, `FRONTMATTER_SCHEMA_ERROR`, `FRONTMATTER_INVALID_YAML`)
+and a resolved `severity`. There is no separate `frontmatterValidation` field.
 
 ```typescript
-interface ValidationResult {
-  // ... existing fields
-  frontmatterValidation?: {
-    valid: boolean;
-    errors: Array<{
-      resourcePath: string;
-      message: string;
-      field?: string;
-    }>;
-  };
+const result = await registry.validate();
+
+const frontmatterIssues = result.issues.filter((i) =>
+  i.code.startsWith('FRONTMATTER_'),
+);
+for (const issue of frontmatterIssues) {
+  console.log(`[${issue.severity}] ${issue.code} at ${issue.location}: ${issue.message}`);
 }
 ```
 
@@ -889,9 +897,10 @@ const warnings = result.issues.filter(i => i.severity === 'warning');
 // Group by resource
 const issuesByResource = new Map<string, ValidationIssue[]>();
 for (const issue of result.issues) {
-  const issues = issuesByResource.get(issue.resourcePath) ?? [];
+  const key = issue.location ?? '(unknown)';
+  const issues = issuesByResource.get(key) ?? [];
   issues.push(issue);
-  issuesByResource.set(issue.resourcePath, issues);
+  issuesByResource.set(key, issues);
 }
 
 // Show summary
@@ -926,7 +935,7 @@ async function validateDocs() {
     console.error(`\nValidation failed with ${result.errorCount} errors\n`);
 
     for (const issue of result.issues.filter(i => i.severity === 'error')) {
-      console.error(`${issue.resourcePath}:${issue.line ?? '?'}`);
+      console.error(`${issue.location ?? '(unknown)'}:${issue.line ?? '?'}`);
       console.error(`  ${issue.message}`);
       if (issue.suggestion) {
         console.error(`  Suggestion: ${issue.suggestion}`);
@@ -1082,7 +1091,7 @@ Valid by default.
 
 ## Related Packages
 
-- [@vibe-agent-toolkit/utils](../utils) - Core shared utilities
+- [@vibe-agent-toolkit/utils](../utils/README.md) - Core shared utilities
 
 ## Future Enhancements
 
@@ -1098,7 +1107,7 @@ Planned features for future releases:
 
 ## Documentation
 
-- [Project Documentation](../../docs)
+- [Project Documentation](../../docs/README.md)
 - [Architecture](../../docs/architecture/README.md)
 
 ## License

package/dist/ajv-factory.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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';
+/**
+ * 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 declare function createAjvWithUriFormats(options?: AjvOptions): Ajv;
+//# sourceMappingURL=ajv-factory.d.ts.map

package/dist/ajv-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajv-factory.d.ts","sourceRoot":"","sources":["../src/ajv-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,GAAG,EAAE,KAAK,OAAO,IAAI,UAAU,EAAE,MAAM,KAAK,CAAC;AActD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,UAAe,GAAG,GAAG,CAUrE"}

package/dist/ajv-factory.js

@@ -0,0 +1,51 @@
+/**
+ * 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 } 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';
+const addFormats = ajvFormatsModule.default ??
+    ajvFormatsModule;
+/**
+ * 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 = {}) {
+    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;
+}
+//# sourceMappingURL=ajv-factory.js.map

package/dist/ajv-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajv-factory.js","sourceRoot":"","sources":["../src/ajv-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,GAAG,EAA8B,MAAM,KAAK,CAAC;AACtD,8EAA8E;AAC9E,wEAAwE;AACxE,uEAAuE;AACvE,oEAAoE;AACpE,oEAAoE;AACpE,OAAO,KAAK,gBAAgB,MAAM,aAAa,CAAC;AAIhD,MAAM,UAAU,GACb,gBAA0D,CAAC,OAAO;IAClE,gBAA4C,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAsB,EAAE;IAC9D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7B,UAAU,CAAC,GAAG,CAAC,CAAC;IAChB,wEAAwE;IACxE,sEAAsE;IACtE,sEAAsE;IACtE,qEAAqE;IACrE,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC3B,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IACrC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/config-parser.d.ts

@@ -4,24 +4,6 @@
  * Discovers and parses project configuration files with directory tree walk-up.
  */
 import { type ProjectConfig } from './schemas/project-config.js';
-/**
- * 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 declare function findConfigFile(startDir?: string): Promise<string | undefined>;
 /**
  * Parse a project configuration file.
  *

package/dist/config-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-parser.d.ts","sourceRoot":"","sources":["../src/config-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAItF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAwBlG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsBhF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAOrG"}
+{"version":3,"file":"config-parser.d.ts","sourceRoot":"","sources":["../src/config-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEtF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAqBhF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAQrG"}

package/dist/config-parser.js

@@ -4,50 +4,9 @@
  * Discovers and parses project configuration files with directory tree walk-up.
  */
 import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { safePath } from '@vibe-agent-toolkit/utils';
-import { CORE_SCHEMA, load as loadYaml } from 'js-yaml';
+import { findConfigFile } from '@vibe-agent-toolkit/utils';
+import { parse as parseYaml } from 'yaml';
 import { ProjectConfigSchema } 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 = process.cwd()) {
-    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.
  *
@@ -71,8 +30,7 @@ export async function parseConfigFile(configPath) {
     // Parse YAML
     let parsed;
     try {
-        // CORE_SCHEMA: YAML 1.2 spec — see link-parser.ts for rationale.
-        parsed = loadYaml(content, { schema: CORE_SCHEMA });
+        parsed = parseYaml(content);
     }
     catch (error) {
         throw new Error(`Invalid YAML in config file: ${error instanceof Error ? error.message : String(error)}`);
@@ -106,7 +64,8 @@ export async function parseConfigFile(configPath) {
  * ```
  */
 export async function loadConfig(startDir = process.cwd()) {
-    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/dist/config-parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-parser.js","sourceRoot":"","sources":["../src/config-parser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config-parser.js","sourceRoot":"","sources":["../src/config-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAE,mBAAmB,EAAsB,MAAM,6BAA6B,CAAC;AAEtF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,UAAkB;IACtD,oBAAoB;IACpB,kHAAkH;IAClH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAEpD,aAAa;IACb,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,gCAAgC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5G,CAAC;IAED,0BAA0B;IAC1B,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9F,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,WAAmB,OAAO,CAAC,GAAG,EAAE;IAC/D,+EAA+E;IAC/E,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;AAC3C,CAAC"}

package/dist/frontmatter-editor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+export declare class FrontmatterParseError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+/** 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;
+}
+export declare function openFrontmatter(markdown: string): FrontmatterEditor;
+//# sourceMappingURL=frontmatter-editor.d.ts.map

package/dist/frontmatter-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-editor.d.ts","sourceRoot":"","sources":["../src/frontmatter-editor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAE5B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAK5C;AAED,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAEpE,sDAAsD;AACtD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC;IACpC,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC3D,YAAY,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnF,eAAe,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvE,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IACpC,QAAQ,IAAI,MAAM,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,OAAO,CAAC;CACpB;AA8JD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAEnE"}

package/dist/frontmatter-editor.js

@@ -0,0 +1,161 @@
+/**
+ * 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 {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'FrontmatterParseError';
+        this.cause = cause;
+    }
+}
+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) {
+    const firstBreak = input.indexOf('\n');
+    if (firstBreak === -1)
+        return '\n';
+    return firstBreak > 0 && input.charAt(firstBreak - 1) === '\r' ? '\r\n' : '\n';
+}
+function splitFrontmatter(input) {
+    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 {
+    doc;
+    hasFrontmatter;
+    eol;
+    _body;
+    _dirty = false;
+    get body() {
+        return this._body;
+    }
+    set body(value) {
+        if (value !== this._body) {
+            this._body = value;
+            this._dirty = true;
+        }
+    }
+    isDirty() {
+        return this._dirty;
+    }
+    constructor(input) {
+        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);
+        }
+    }
+    toPath(path) {
+        if (Array.isArray(path))
+            return path;
+        if (typeof path === 'string')
+            return [path];
+        return path;
+    }
+    get(path) {
+        const segments = this.toPath(path);
+        if (segments.length === 0)
+            return this.doc.toJS();
+        return this.doc.getIn(segments, false);
+    }
+    set(path, value) {
+        const segments = this.toPath(path);
+        this.doc.setIn(segments, value);
+        this._dirty = true;
+    }
+    setArrayItem(path, index, value) {
+        const segments = [...this.toPath(path), index];
+        this.doc.setIn(segments, value);
+        this._dirty = true;
+    }
+    appendArrayItem(path, value) {
+        const segments = this.toPath(path);
+        this.doc.addIn(segments, value);
+        this._dirty = true;
+    }
+    delete(path) {
+        const segments = this.toPath(path);
+        this.doc.deleteIn(segments);
+        this._dirty = true;
+    }
+    toString() {
+        // 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}`;
+    }
+    isDocEffectivelyEmpty() {
+        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.items;
+        if (Array.isArray(maybeItems) && maybeItems.length === 0)
+            return true;
+        return false;
+    }
+}
+export function openFrontmatter(markdown) {
+    return new FrontmatterEditorImpl(markdown);
+}
+//# sourceMappingURL=frontmatter-editor.js.map

package/dist/frontmatter-editor.js.map

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

package/dist/frontmatter-link-validator.d.ts

@@ -7,11 +7,11 @@
  * frontmatter-specific type codes plus a list of external URLs the registry
  * can fold into its existing external URL collection.
  *
- * Type mapping:
- *   broken_file        -> frontmatter_link_broken
- *   broken_anchor      -> frontmatter_anchor_missing
- *   link_to_gitignored -> frontmatter_link_to_gitignored
- *   unknown_link       -> frontmatter_unknown_link
+ * Code mapping:
+ *   LINK_BROKEN_FILE    -> FRONTMATTER_LINK_BROKEN
+ *   LINK_BROKEN_ANCHOR  -> FRONTMATTER_ANCHOR_MISSING
+ *   LINK_TO_GITIGNORED  -> FRONTMATTER_LINK_TO_GITIGNORED
+ *   LINK_UNKNOWN        -> FRONTMATTER_UNKNOWN_LINK
  *
  * Skipped (no issue, no external):
  *   email (mailto:)

package/dist/frontmatter-link-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter-link-validator.d.ts","sourceRoot":"","sources":["../src/frontmatter-link-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,KAAK,EAAE,WAAW,EAAgB,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7E,kFAAkF;AAClF,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,YAAY,EAAE,sBAAsB,EAAE,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAChD,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAC1C,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,+BAA+B,CAAC,CAoC1C"}
+{"version":3,"file":"frontmatter-link-validator.d.ts","sourceRoot":"","sources":["../src/frontmatter-link-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,KAAK,EAAE,WAAW,EAAgB,eAAe,EAAE,MAAM,YAAY,CAAC;AAU7E,kFAAkF;AAClF,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,YAAY,EAAE,sBAAsB,EAAE,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAChD,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAC1C,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,+BAA+B,CAAC,CAoC1C"}

package/dist/frontmatter-link-validator.js

@@ -7,19 +7,27 @@
  * frontmatter-specific type codes plus a list of external URLs the registry
  * can fold into its existing external URL collection.
  *
- * Type mapping:
- *   broken_file        -> frontmatter_link_broken
- *   broken_anchor      -> frontmatter_anchor_missing
- *   link_to_gitignored -> frontmatter_link_to_gitignored
- *   unknown_link       -> frontmatter_unknown_link
+ * Code mapping:
+ *   LINK_BROKEN_FILE    -> FRONTMATTER_LINK_BROKEN
+ *   LINK_BROKEN_ANCHOR  -> FRONTMATTER_ANCHOR_MISSING
+ *   LINK_TO_GITIGNORED  -> FRONTMATTER_LINK_TO_GITIGNORED
+ *   LINK_UNKNOWN        -> FRONTMATTER_UNKNOWN_LINK
  *
  * Skipped (no issue, no external):
  *   email (mailto:)
  *   anchor-only (validated as anchor in current file via validateLink)
  */
+import { createRegistryIssue } from '@vibe-agent-toolkit/agent-schema';
 import { classifyLink } from './link-parser.js';
 import { validateLink } from './link-validator.js';
 import { walkFrontmatterUriReferences } from './schema-uri-walker.js';
+/** Map the link-level code emitted by validateLink to its frontmatter-scoped code. */
+const LINK_CODE_TO_FRONTMATTER_CODE = {
+    LINK_BROKEN_FILE: 'FRONTMATTER_LINK_BROKEN',
+    LINK_BROKEN_ANCHOR: 'FRONTMATTER_ANCHOR_MISSING',
+    LINK_TO_GITIGNORED: 'FRONTMATTER_LINK_TO_GITIGNORED',
+    LINK_UNKNOWN: 'FRONTMATTER_UNKNOWN_LINK',
+};
 /**
  * Validate every URI-family frontmatter value against the file system.
  *
@@ -63,24 +71,17 @@ export async function validateFrontmatterLinks(frontmatter, schema, sourceFilePa
     return { issues, externalUrls };
 }
 function rewriteIssue(issue, dottedPath) {
-    return {
-        ...issue,
-        type: mapType(issue.type),
-        message: `field \`${dottedPath}\`: ${issue.message}`,
-    };
-}
-function mapType(originalType) {
-    switch (originalType) {
-        case 'broken_file':
-            return 'frontmatter_link_broken';
-        case 'broken_anchor':
-            return 'frontmatter_anchor_missing';
-        case 'link_to_gitignored':
-            return 'frontmatter_link_to_gitignored';
-        case 'unknown_link':
-            return 'frontmatter_unknown_link';
-        default:
-            return originalType;
-    }
+    const mappedCode = LINK_CODE_TO_FRONTMATTER_CODE[issue.code] ?? issue.code;
+    const message = `field \`${dottedPath}\`: ${issue.message}`;
+    const extras = {};
+    if (issue.location !== undefined)
+        extras.location = issue.location;
+    if (issue.line !== undefined)
+        extras.line = issue.line;
+    if (issue.link !== undefined)
+        extras.link = issue.link;
+    if (issue.suggestion !== undefined)
+        extras.suggestion = issue.suggestion;
+    return createRegistryIssue(mappedCode, message, extras);
 }
 //# sourceMappingURL=frontmatter-link-validator.js.map