@hashicorp/kits 0.1.9 → 0.1.11

package/dist/validation/validate-subagents.js

@@ -22,6 +22,8 @@ import pc from "picocolors";
 import { parseSubagentFrontmatter } from "../adapters/subagent-frontmatter.js";
 import { formatValidationSourceError, resolveValidationSource } from "./source.js";
 import { findMarkdownFiles, summarizeResults, printValidationResults, } from "./utils.js";
+import { SchemaResolutionError } from "./schema-registry.js";
+import { createSchemaValidator, formatSchemaErrors, SchemaValidationError, } from "./schema-validator.js";
 /**
  * Find all subagent files in a kit repository.
  *
@@ -49,14 +51,10 @@ async function findSubagentFiles(agentKitsPath) {
     }
     return subagentFiles;
 }
-function isStringArray(value) {
-    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
-}
-const ALLOWED_SUBAGENT_HOOK_EVENTS = new Set(["tool.before", "tool.after", "subagent.stop"]);
 /**
  * Validate a single subagent Markdown file.
  */
-async function validateSubagentFile(filePath) {
+async function validateSubagentFile(filePath, validateSchema) {
     try {
         const content = await fs.readFile(filePath, "utf-8");
         const { frontmatter, body, hasFrontmatter } = parseSubagentFrontmatter(content);
@@ -67,122 +65,15 @@ async function validateSubagentFile(filePath) {
                 error: "subagent missing YAML frontmatter; expected ---\\n...\\n--- at start of file",
             };
         }
-        const name = frontmatter["name"];
-        if (typeof name !== "string" || name.trim().length === 0) {
-            return {
-                file: filePath,
-                valid: false,
-                error: "subagent missing required 'name' field in frontmatter",
-            };
-        }
-        const description = frontmatter["description"];
-        if (typeof description !== "string" || description.trim().length === 0) {
+        const result = await validateSchema("subagent", frontmatter);
+        if (!result.valid) {
+            const errorText = formatSchemaErrors(result.errors ?? []);
             return {
                 file: filePath,
                 valid: false,
-                error: "subagent missing required 'description' field in frontmatter",
+                error: `Schema validation failed: ${errorText}`,
             };
         }
-        if (Object.prototype.hasOwnProperty.call(frontmatter, "allowedTools")) {
-            const allowedTools = frontmatter["allowedTools"];
-            if (!(typeof allowedTools === "string" || isStringArray(allowedTools))) {
-                return {
-                    file: filePath,
-                    valid: false,
-                    error: "subagent 'allowedTools' must be a string or array of strings when present",
-                };
-            }
-        }
-        if (Object.prototype.hasOwnProperty.call(frontmatter, "disallowedTools")) {
-            const disallowedTools = frontmatter["disallowedTools"];
-            if (!(typeof disallowedTools === "string" || isStringArray(disallowedTools))) {
-                return {
-                    file: filePath,
-                    valid: false,
-                    error: "subagent 'disallowedTools' must be a string or array of strings when present",
-                };
-            }
-        }
-        if (Object.prototype.hasOwnProperty.call(frontmatter, "maxTurns")) {
-            const maxTurns = frontmatter["maxTurns"];
-            if (typeof maxTurns !== "number") {
-                return {
-                    file: filePath,
-                    valid: false,
-                    error: "subagent 'maxTurns' must be a number when present",
-                };
-            }
-        }
-        if (Object.prototype.hasOwnProperty.call(frontmatter, "timeout")) {
-            const timeout = frontmatter["timeout"];
-            if (typeof timeout !== "number") {
-                return {
-                    file: filePath,
-                    valid: false,
-                    error: "subagent 'timeout' must be a number when present",
-                };
-            }
-        }
-        if (Object.prototype.hasOwnProperty.call(frontmatter, "skills")) {
-            const skills = frontmatter["skills"];
-            if (!isStringArray(skills)) {
-                return {
-                    file: filePath,
-                    valid: false,
-                    error: "subagent 'skills' must be an array of strings when present",
-                };
-            }
-        }
-        if (Object.prototype.hasOwnProperty.call(frontmatter, "hooks")) {
-            const hooks = frontmatter["hooks"];
-            if (!Array.isArray(hooks)) {
-                return {
-                    file: filePath,
-                    valid: false,
-                    error: "subagent 'hooks' must be an array when present",
-                };
-            }
-            for (const hookEntry of hooks) {
-                if (!hookEntry || typeof hookEntry !== "object") {
-                    return {
-                        file: filePath,
-                        valid: false,
-                        error: "subagent 'hooks' entries must be objects",
-                    };
-                }
-                const ref = hookEntry["ref"];
-                if (typeof ref !== "string" || ref.trim().length === 0) {
-                    return {
-                        file: filePath,
-                        valid: false,
-                        error: "subagent 'hooks' entries must include a non-empty 'ref' string",
-                    };
-                }
-                const binding = hookEntry["binding"];
-                if (!binding || typeof binding !== "object") {
-                    return {
-                        file: filePath,
-                        valid: false,
-                        error: "subagent 'hooks' entries must include a 'binding' object",
-                    };
-                }
-                const event = binding["event"];
-                if (typeof event !== "string" || event.trim().length === 0) {
-                    return {
-                        file: filePath,
-                        valid: false,
-                        error: "subagent hook binding requires an 'event' string",
-                    };
-                }
-                if (!ALLOWED_SUBAGENT_HOOK_EVENTS.has(event)) {
-                    return {
-                        file: filePath,
-                        valid: false,
-                        error: "subagent hook binding event must be one of: tool.before, tool.after, subagent.stop",
-                    };
-                }
-            }
-        }
         if (body.trim().length === 0) {
             return {
                 file: filePath,
@@ -200,6 +91,9 @@ async function validateSubagentFile(filePath) {
         return { file: filePath, valid: true };
     }
     catch (error) {
+        if (error instanceof SchemaResolutionError || error instanceof SchemaValidationError) {
+            return { file: filePath, valid: false, error: error.message };
+        }
         const errorMessage = error instanceof Error ? error.message : String(error);
         return { file: filePath, valid: false, error: errorMessage };
     }
@@ -207,11 +101,14 @@ async function validateSubagentFile(filePath) {
 /**
  * Validate all subagent files in a kit repository.
  */
-export async function validateSubagents(agentKitsPath) {
+export async function validateSubagents(agentKitsPath, options = {}) {
+    const schemaRoot = options.schemaRoot ??
+        path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../schemas");
+    const schemaValidator = createSchemaValidator(schemaRoot);
     const subagentFiles = await findSubagentFiles(agentKitsPath);
     const results = [];
     for (const file of subagentFiles) {
-        results.push(await validateSubagentFile(file));
+        results.push(await validateSubagentFile(file, schemaValidator.validate));
     }
     return summarizeResults(results);
 }

package/dist/validation/validate-subagents.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashicorp/kits",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Install AI agent kits into your favorite coding assistants",
   "type": "module",
   "bin": {

package/schemas/{command.schema.json → command.schema.v1.0.0.json}

@@ -1,11 +1,24 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema#",
-  "$id": "https://hashicorp.com/schemas/command.schema.json",
+  "$id": "https://hashicorp.com/schemas/command.schema.v1.0.0.json",
   "title": "Command Frontmatter",
   "description": "Schema for command primitive YAML frontmatter",
   "type": "object",
-  "required": ["description"],
+  "required": [
+    "$schema",
+    "schemaVersion",
+    "description"
+  ],
   "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0.0",
+      "description": "Version of this schema (semver)"
+    },
     "description": {
       "type": "string",
       "minLength": 10,

package/schemas/examples/hook-program-valid.json

@@ -1,4 +1,6 @@
 {
+  "$schema": "https://raw.githubusercontent.com/hashicorp-labs/kits/refs/heads/main/schemas/hook-program.schema.v1.0.0.json",
+  "schemaVersion": "1.0.0",
   "name": "pre-apply-validation",
   "version": "1.0.0",
   "description": "Validate Terraform input before apply",
@@ -7,16 +9,24 @@
     "entrypoint": "hook.sh",
     "shell": "bash",
     "working_directory": "inherit",
-    "args": ["--strict"],
+    "args": [
+      "--strict"
+    ],
     "timeout_ms": 15000
   },
   "io": {
     "stdin": "json",
     "stdout": "json",
     "error_codes": {
-      "success": [0],
-      "warn": [1],
-      "block": [2]
+      "success": [
+        0
+      ],
+      "warn": [
+        1
+      ],
+      "block": [
+        2
+      ]
     }
   },
   "env": {

package/schemas/examples/http-server-valid.json

@@ -1,5 +1,6 @@
 {
-  "$schema": "../mcp-server.schema.json",
+  "$schema": "https://raw.githubusercontent.com/hashicorp-labs/kits/refs/heads/main/schemas/mcp-server.schema.v1.0.0.json",
+  "schemaVersion": "1.0.0",
   "name": "example-http-server",
   "version": "1.0.0",
   "description": "Example HTTP MCP server demonstrating sensitive and nonsensitive headers",

package/schemas/examples/invalid-sensitive-header-no-envvar.json

@@ -1,5 +1,6 @@
 {
-  "$schema": "../mcp-server.schema.json",
+  "$schema": "https://raw.githubusercontent.com/hashicorp-labs/kits/refs/heads/main/schemas/mcp-server.schema.v1.0.0.json",
+  "schemaVersion": "1.0.0",
   "name": "invalid-server",
   "version": "1.0.0",
   "description": "This config should fail validation",

package/schemas/examples/invalid-sensitive-header-with-value.json

@@ -1,5 +1,6 @@
 {
-  "$schema": "../mcp-server.schema.json",
+  "$schema": "https://raw.githubusercontent.com/hashicorp-labs/kits/refs/heads/main/schemas/mcp-server.schema.v1.0.0.json",
+  "schemaVersion": "1.0.0",
   "name": "invalid-server",
   "version": "1.0.0",
   "description": "This config should fail validation",

package/schemas/examples/invalid-sensitive-var-with-default.json

@@ -1,12 +1,16 @@
 {
-  "$schema": "../mcp-server.schema.json",
+  "$schema": "https://raw.githubusercontent.com/hashicorp-labs/kits/refs/heads/main/schemas/mcp-server.schema.v1.0.0.json",
+  "schemaVersion": "1.0.0",
   "name": "invalid-server",
   "version": "1.0.0",
   "description": "This config should fail validation",
   "transport": {
     "type": "stdio",
     "command": "npx",
-    "args": ["-y", "@example/server"]
+    "args": [
+      "-y",
+      "@example/server"
+    ]
   },
   "env": {
     "API_TOKEN": {

package/schemas/examples/stdio-server-valid.json

@@ -1,12 +1,16 @@
 {
-  "$schema": "../mcp-server.schema.json",
+  "$schema": "https://raw.githubusercontent.com/hashicorp-labs/kits/refs/heads/main/schemas/mcp-server.schema.v1.0.0.json",
+  "schemaVersion": "1.0.0",
   "name": "example-stdio-server",
   "version": "1.0.0",
   "description": "Example STDIO MCP server demonstrating sensitive and nonsensitive environment variables",
   "transport": {
     "type": "stdio",
     "command": "npx",
-    "args": ["-y", "@example/mcp-server"],
+    "args": [
+      "-y",
+      "@example/mcp-server"
+    ],
     "cwd": "."
   },
   "env": {

package/schemas/hook-binding.schema.v1.0.0.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://hashicorp.com/schemas/hook-binding.schema.v1.0.0.json",
+  "title": "Hook Binding",
+  "description": "Schema for canonical hook binding objects used in kit.json and subagent frontmatter",
+  "type": "object",
+  "required": [
+    "event"
+  ],
+  "properties": {
+    "event": {
+      "type": "string",
+      "enum": [
+        "session.start",
+        "session.end",
+        "prompt.submit",
+        "tool.before",
+        "tool.after",
+        "permission.request",
+        "notification",
+        "compaction.before",
+        "subagent.start",
+        "subagent.stop",
+        "error"
+      ],
+      "description": "Canonical hook event"
+    },
+    "matcher": {
+      "type": "object",
+      "properties": {
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "policy": {
+      "type": "object",
+      "properties": {
+        "on_success": {
+          "type": "string",
+          "enum": [
+            "continue",
+            "warn",
+            "block"
+          ]
+        },
+        "on_failure": {
+          "type": "string",
+          "enum": [
+            "continue",
+            "warn",
+            "block"
+          ]
+        },
+        "on_timeout": {
+          "type": "string",
+          "enum": [
+            "continue",
+            "warn",
+            "block"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "args": {
+      "type": "object",
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string",
+            "minLength": 1
+          },
+          {
+            "type": "number"
+          },
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number",
+                "boolean"
+              ]
+            }
+          }
+        ]
+      }
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "additionalProperties": false
+}