@vibe-agent-toolkit/resources 0.1.38 → 0.1.39-rc.10

package/src/schemas/link-auth.ts

@@ -0,0 +1,146 @@
+/**
+ * Zod schema for `resources.linkAuth` config.
+ *
+ * Validates the shape of an adopter's linkAuth configuration: providers
+ * (each either a `use: <macro>` reference or a full inline provider) plus
+ * an optional cache config. Strict — typos in provider field names are
+ * errors, per Postel's law ("writing our output → conservative").
+ *
+ * Provider entries accept EITHER:
+ *   - `{ use: <name>, ...overrides }` — reference a shipped macro by name;
+ *     override fields are deep-merged on top at expansion time. Overrides
+ *     are NOT strictly typed at this layer because they must match the
+ *     macro's shape, which we cannot see until expansion. A typo in an
+ *     override silently no-ops; the full provider shape is validated
+ *     after expansion (slice 2 wires that).
+ *   - A full inline `{ match, rewrite, auth, token, check }` — every field
+ *     required, every nested object strict.
+ *
+ * Mirrors the runtime types in `@vibe-agent-toolkit/utils`'s `link-auth/`
+ * module. Keep these aligned: a config that parses here must satisfy the
+ * `Provider` / `LinkAuthConfig` interfaces over there.
+ *
+ * Per design issue #113 §4 (vocabulary) and §5 (macros).
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Leaf types
+// ---------------------------------------------------------------------------
+
+export const ProviderMatchSchema = z
+  .object({
+    host: z.string().min(1).describe('Glob matched against URL hostname'),
+    excludeHost: z
+      .array(z.string().min(1))
+      .optional()
+      .describe('Globs that, if any match the hostname, exclude this provider'),
+  })
+  .strict()
+  .describe('Provider selection — match.host + optional excludeHost globs');
+
+export const RewriteRuleSchema = z
+  .object({
+    when: z.string().min(1).describe('Regex source (RFC-style, JavaScript-compatible) matched against the URL'),
+    vars: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe('Computed variables, each a template that references captures from `when`'),
+    to: z.string().min(1).describe('URL template — interpolates ${capture} and ${var}'),
+  })
+  .strict()
+  .describe('A single rewrite rule (one entry in a provider\'s ordered rewrite list)');
+
+export const ProviderAuthSchema = z
+  .object({
+    headers: z
+      .record(z.string(), z.string())
+      .describe('Header name → value template. Values interpolate ${token} and any capture/var.'),
+  })
+  .strict()
+  .describe('Auth headers attached to the authenticated fetch');
+
+export const TokenSourceSchema = z
+  .union([
+    z.object({ env: z.string().min(1) }).strict(),
+    z
+      .object({
+        command: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
+      })
+      .strict(),
+  ])
+  .describe('A single token source — env var, or argv command (preferred), or convenience string');
+
+export const ProviderCheckSchema = z
+  .object({
+    method: z.enum(['GET', 'HEAD']),
+    aliveStatus: z
+      .array(z.number().int().min(100).max(599))
+      .min(1)
+      .describe('HTTP status codes meaning the URL is alive (per host semantics)'),
+    notFoundMeaning: z
+      .enum(['ambiguous', 'dead'])
+      .describe(
+        'Per-host: does 404 mean "dead" (honest 404 host like Graph) or "ambiguous" (masking host like GitHub)?',
+      ),
+  })
+  .strict()
+  .describe('Status-to-outcome classifier (consumed by the resources layer, not the pure engine)');
+
+// ---------------------------------------------------------------------------
+// Provider entry (inline OR macro reference)
+// ---------------------------------------------------------------------------
+
+const InlineProviderSchema = z
+  .object({
+    match: ProviderMatchSchema,
+    rewrite: z.array(RewriteRuleSchema).min(1).describe('Ordered rewrite rules — first matching wins'),
+    auth: ProviderAuthSchema,
+    token: z.array(TokenSourceSchema).describe('Ordered token sources — first non-empty wins'),
+    check: ProviderCheckSchema,
+  })
+  .strict();
+
+const MacroProviderSchema = z
+  .object({
+    use: z.string().min(1).describe('Macro name (e.g. "github", "sharepoint")'),
+  })
+  .passthrough()
+  .describe(
+    'Reference a shipped macro by name. Override fields (match/rewrite/auth/token/check) deep-merge on top at expansion time.',
+  );
+
+export const ProviderEntrySchema = z
+  .union([MacroProviderSchema, InlineProviderSchema])
+  .describe('A provider entry — either { use: <macro>, ...overrides } or a full inline provider');
+
+// ---------------------------------------------------------------------------
+// Top-level linkAuth config
+// ---------------------------------------------------------------------------
+
+export const LinkAuthCacheSchema = z
+  .object({
+    ttlMinutes: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe('Content cache TTL in minutes (default 30 — used by slice 3 content-fetch)'),
+  })
+  .strict();
+
+export const LinkAuthConfigSchema = z
+  .object({
+    cache: LinkAuthCacheSchema.optional(),
+    providers: z
+      .array(ProviderEntrySchema)
+      .describe('Ordered list of providers — first claiming-by-host wins'),
+  })
+  .strict()
+  .describe('`resources.linkAuth` — authenticated external link resolution config');
+
+export type LinkAuthConfig = z.infer<typeof LinkAuthConfigSchema>;
+export type ProviderEntry = z.infer<typeof ProviderEntrySchema>;
+export type RewriteRule = z.infer<typeof RewriteRuleSchema>;
+export type TokenSource = z.infer<typeof TokenSourceSchema>;

package/src/schemas/project-config.ts

@@ -1,6 +1,8 @@
 import { ValidationConfigSchema } from '@vibe-agent-toolkit/agent-schema';
 import { z } from 'zod';
 
+import { LinkAuthConfigSchema } from './link-auth.js';
+
 /**
  * Official semver regex from https://semver.org/ (anchored).
  *
@@ -96,6 +98,10 @@ export const ResourcesConfigSchema = z.object({
     .describe('Global default exclude patterns (not used by collections in Phase 2)'),
   collections: z.record(z.string(), CollectionConfigSchema).optional()
     .describe('Named collections of resources'),
+  validation: ValidationConfigSchema.optional()
+    .describe('Validation framework config: severity overrides and per-code allow entries (applied inside ResourceRegistry.validate)'),
+  linkAuth: LinkAuthConfigSchema.optional()
+    .describe('Authenticated external link resolution config (issue #113 / link-auth engine)'),
 }).describe('Resources section of project configuration');
 
 export type ResourcesConfig = z.infer<typeof ResourcesConfigSchema>;
@@ -134,6 +140,72 @@ export const SkillFileEntrySchema = z.object({
 
 export type SkillFileEntry = z.infer<typeof SkillFileEntrySchema>;
 
+/**
+ * A typed "skill source" descriptor as it appears in vibe-agent-toolkit.config.yaml.
+ *
+ * This is the CONFIG representation. Task 13's staging maps it onto Plan 1's
+ * runtime `SkillSource` union before calling `resolveSkillSource`. Kept here so
+ * `configure`/`run` parse a single strict source of truth.
+ */
+export const SkillSourceDescriptorSchema = z.union([
+  z.object({ workspace: z.string().min(1) }).strict(),
+  z.object({ npm: z.string().min(1) }).strict(),
+  z.object({ url: z.string().min(1), sha256: z.string().min(1).optional() }).strict(),
+  z.object({ path: z.string().min(1) }).strict(),
+  z.object({ vendored: z.literal(true) }).strict(),
+]).describe('Typed skill source: workspace | npm | url(+sha256) | path | vendored');
+
+export type SkillSourceDescriptor = z.infer<typeof SkillSourceDescriptorSchema>;
+
+/**
+ * Per-skill `test:` block for `vat skill test`. Strict — unknown keys are a
+ * config error (Postel: this is vat-produced/validated data, §schema strategy).
+ * Every field is optional; omitted knobs fall back to built-in defaults.
+ */
+export const TestConfigSchema = z.object({
+  model: z.string().min(1).optional()
+    .describe('Pinned model for reproducibility (default: a fixed model, not "whatever the caller has")'),
+  maxTurns: z.number().int().positive().optional()
+    .describe('Cap on experimenter turns'),
+  maxBudgetUsd: z.number().positive().optional()
+    .describe('Hard USD budget cap passed to the CLI'),
+  timeout: z.number().int().positive().optional()
+    .describe('Wall-clock timeout in seconds'),
+  stall: z.number().int().positive().optional()
+    .describe('Stall-watchdog seconds (kill on no stream output)'),
+  evals: z.string().min(1).optional()
+    .describe('Path to evals.json (relative to skill source)'),
+  experimenterPrompt: z.string().min(1).optional()
+    .describe('Path to an override experimenter prompt (must preserve §6c invariants)'),
+  auth: z.enum(['inherit', 'subscription', 'api-key', 'auto']).optional()
+    .describe('Auth-mechanism selection (default: inherit)'),
+  requireAuth: z.enum(['subscription', 'api-key']).optional()
+    .describe('Fail-fast guard: preflight exits 2 if effective mechanism is not this'),
+  baseline: z.boolean().optional()
+    .describe('Run the opt-in with/without A/B baseline (default: false)'),
+  skillCreator: SkillSourceDescriptorSchema.optional()
+    .describe('Source for skill-creator (default: { vendored: true })'),
+  with: z.array(SkillSourceDescriptorSchema).optional()
+    .describe('Declared-dependency skills/plugins to stage'),
+  optional: z.array(SkillSourceDescriptorSchema).optional()
+    .describe('Optional dependencies, absent by default'),
+  /**
+   * Shell command to run once, before staging, to generate build artifacts.
+   * Runs with cwd = config root (directory containing vibe-agent-toolkit.config.yaml).
+   * Useful when a skill references a generated file (e.g. `node scripts/report.mjs`)
+   * that is produced by a bundler step and not committed to source.
+   * A non-zero exit code aborts the run (preflight failure, exit 2).
+   */
+  env: z.record(z.string(), z.string()).optional()
+    .describe('Feature B: explicit env var injections for the experimenter spawn. Values support ${fixturesDir}, ${stagedSkillDir}, ${harnessRoot}, ${resultsDir} interpolation (resolved at stage time). Protected names (PATH, auth, model, admin) cannot be overridden.'),
+  passEnv: z.array(z.string().min(1)).optional()
+    .describe('Feature A: names of host env vars to forward to the experimenter spawn if present. Protected names are ignored with a warning.'),
+  build: z.string().min(1).optional()
+    .describe('Shell command run once, before staging, to generate build artifacts (cwd = config root)'),
+}).strict().describe('Per-skill vat skill test configuration');
+
+export type TestConfig = z.infer<typeof TestConfigSchema>;
+
 /**
  * Skill packaging configuration.
  *
@@ -153,10 +225,14 @@ export const SkillPackagingConfigSchema = z.object({
   targets: z.array(z.enum(['claude-chat', 'claude-cowork', 'claude-code'])).optional()
     .describe('Declared runtime targets for this skill. Suppresses non-applicable compat verdicts.'),
   files: z.array(SkillFileEntrySchema).optional().describe('Explicit source→dest file mappings for build artifacts, unlinked files, or routing overrides'),
+  test: TestConfigSchema.optional()
+    .describe('vat skill test configuration for this skill'),
 }).strict().describe('Skill packaging configuration');
 
 export type SkillPackagingConfig = z.infer<typeof SkillPackagingConfigSchema>;
 
+// NOTE: project-config has no generated JSON Schema generator (unlike packages with generate:schemas script); Zod schema is the tracked source of truth.
+
 /**
  * Skills discovery and packaging configuration.
  *

package/src/schemas/resource-metadata.ts

@@ -6,6 +6,7 @@ import { SHA256Schema } from './checksum.js';
  * Type of link found in markdown resources.
  *
  * - `local_file`: Link to a local file (relative or absolute path)
+ * - `local_directory`: Link to a local directory, e.g. a ref ending in `/`
  * - `anchor`: Link to a heading anchor (e.g., #heading-slug)
  * - `external`: HTTP/HTTPS URL to external resource
  * - `email`: Mailto link
@@ -13,6 +14,7 @@ import { SHA256Schema } from './checksum.js';
  */
 export const LinkTypeSchema = z.enum([
   'local_file',
+  'local_directory',
   'anchor',
   'external',
   'email',
@@ -36,6 +38,16 @@ export const LinkNodeTypeSchema = z.enum([
 
 export type LinkNodeType = z.infer<typeof LinkNodeTypeSchema>;
 
+/**
+ * Zod schema for an HTML well-formedness diagnostic.
+ */
+export const HtmlParseErrorSchema = z.object({
+  message: z.string().describe('parse5 error code (e.g. "missing-end-tag")'),
+  line: z.number().int().positive().optional().describe('1-based source line, when known'),
+}).describe('HTML well-formedness diagnostic');
+
+export type HtmlParseError = z.infer<typeof HtmlParseErrorSchema>;
+
 /**
  * Represents a heading node in the document's table of contents.
  *
@@ -96,6 +108,10 @@ export const ResourceMetadataSchema = z.object({
   filePath: z.string().describe('Absolute path to the resource file'),
   links: z.array(ResourceLinkSchema).describe('All links found in the resource'),
   headings: z.array(HeadingNodeSchema).describe('Document table of contents (top-level headings only; children are nested)'),
+  anchors: z.array(z.string()).optional()
+    .describe('Fragment targets for anchor validation (HTML id/name attributes)'),
+  parseErrors: z.array(HtmlParseErrorSchema).optional()
+    .describe('HTML well-formedness diagnostics (populated for HTML resources only)'),
   frontmatter: z.record(z.string(), z.unknown()).optional()
     .describe('Parsed YAML frontmatter (if present in markdown file)'),
   frontmatterError: z.string().optional()
@@ -106,6 +122,6 @@ export const ResourceMetadataSchema = z.object({
   checksum: SHA256Schema.describe('SHA-256 checksum of file content'),
   collections: z.array(z.string()).optional()
     .describe('Collection names this resource belongs to (populated when using config-based discovery)'),
-}).describe('Complete metadata for a markdown resource');
+}).strict().describe('Complete metadata for a markdown resource');
 
 export type ResourceMetadata = z.infer<typeof ResourceMetadataSchema>;

package/src/schemas/validation-result.ts

@@ -1,32 +1,7 @@
+import { ValidationIssueSchema } from '@vibe-agent-toolkit/agent-schema';
 import { z } from 'zod';
 
-/**
- * A single validation issue found during link validation.
- *
- * Issue types:
- * - broken_file: Local file link points to non-existent file
- * - broken_anchor: Anchor link points to non-existent heading
- * - frontmatter_missing: Schema requires frontmatter, file has none
- * - frontmatter_invalid_yaml: YAML syntax error in frontmatter
- * - frontmatter_schema_error: Frontmatter fails JSON Schema validation
- * - external_url_dead: External URL returned error status (4xx, 5xx)
- * - external_url_timeout: External URL request timed out
- * - external_url_error: External URL validation failed (DNS, network, etc.)
- * - unknown_link: Unknown link type
- *
- * Includes details about what went wrong, where it occurred, and optionally
- * how to fix it.
- */
-export const ValidationIssueSchema = z.object({
-  resourcePath: z.string().describe('Absolute path to the resource containing the issue'),
-  line: z.number().int().positive().optional().describe('Line number where the issue occurs'),
-  type: z.string().describe('Issue type identifier (e.g., "broken_file", "broken_anchor", "frontmatter_schema_error", "unknown_link")'),
-  link: z.string().describe('The problematic link'),
-  message: z.string().describe('Human-readable description of the issue'),
-  suggestion: z.string().optional().describe('Optional suggestion for fixing the issue'),
-}).describe('A single validation issue found during link validation');
-
-export type ValidationIssue = z.infer<typeof ValidationIssueSchema>;
+export { type ValidationIssue, ValidationIssueSchema } from '@vibe-agent-toolkit/agent-schema';
 
 /**
  * Complete results from validating a collection of resources.
@@ -38,9 +13,10 @@ export const ValidationResultSchema = z.object({
   totalResources: z.number().int().nonnegative().describe('Total number of resources validated'),
   totalLinks: z.number().int().nonnegative().describe('Total number of links found across all resources'),
   linksByType: z.record(z.string(), z.number().int().nonnegative()).describe('Count of links by type (e.g., {"local_file": 10, "external": 5})'),
-  issues: z.array(ValidationIssueSchema).describe('All validation issues found'),
-  errorCount: z.number().int().nonnegative().describe('Number of issues found'),
+  issues: z.array(ValidationIssueSchema).describe('Emitted validation issues (allow-filtered + severity-resolved; ignored issues dropped)'),
+  errorCount: z.number().int().nonnegative().describe('Number of emitted issues'),
   passed: z.boolean().describe('True if validation succeeded (errorCount === 0)'),
+  hasErrors: z.boolean().describe('True when any emitted issue has resolved severity "error"'),
   durationMs: z.number().nonnegative().describe('Validation duration in milliseconds'),
   timestamp: z.date().describe('When validation was performed'),
 }).describe('Complete results from validating a collection of resources');

package/src/types/resources.ts

@@ -6,8 +6,9 @@
  * with optional absolutePath for runtime operations.
  */
 
+import type { ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
+
 import type { SHA256 } from '../schemas/checksum.js';
-import type { ValidationIssue } from '../schemas/validation-result.js';
 
 /**
  * Resource type discriminator for type-safe handling

package/src/utils.ts

@@ -9,6 +9,21 @@ import path from 'node:path';
 import { toForwardSlash, safePath } from '@vibe-agent-toolkit/utils';
 import picomatch from 'picomatch';
 
+/**
+ * Compute a `ValidationIssue.location`: the (absolute) source file path made
+ * relative to the project root. When no project root is known, fall back to the
+ * source path forward-slashed so the location is still useful and stable.
+ *
+ * @param sourceFilePath - Absolute path to the file the issue was found in.
+ * @param projectRoot - Project root, or undefined when none could be determined.
+ * @returns Forward-slashed relative location (or the forward-slashed absolute path).
+ */
+export function issueLocation(sourceFilePath: string, projectRoot: string | undefined): string {
+  return projectRoot === undefined
+    ? toForwardSlash(sourceFilePath)
+    : safePath.relative(projectRoot, sourceFilePath);
+}
+
 /**
  * Check if a file path matches a glob pattern.
  *