@hashicorp/kits 0.1.0

package/dist/validation/validate-subagents.js

@@ -0,0 +1,269 @@
+/**
+ * Subagent primitive validation script.
+ *
+ * Validates all subagent Markdown files in a kit repository against
+ * the canonical format specification:
+ * - YAML frontmatter required
+ * - `name` field required and non-empty
+ * - `description` field required and non-empty
+ * - `allowedTools`/`disallowedTools` optional but must be string or array of strings if present
+ * - `skills` optional but must be array of strings if present
+ * - `hooks` optional but must be an array of bindings if present
+ * - hook binding `event` limited to tool.before, tool.after, subagent.stop
+ * - Body content required and non-empty
+ * - Body must include <agent_role> tags
+ *
+ * Exits with code 0 on success, 1 on validation failure.
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath } from "node:url";
+import pc from "picocolors";
+import { parseSubagentFrontmatter } from "../adapters/subagent-frontmatter.js";
+import { formatValidationSourceError, resolveValidationSource } from "./source.js";
+import { findMarkdownFiles, summarizeResults, printValidationResults, } from "./utils.js";
+/**
+ * Find all subagent files in a kit repository.
+ *
+ * Searches for:
+ * - Shared primitives: primitives/subagents/{name}/v{version}/{name}.md
+ * - Inline kit primitives: kits/{kit}/primitives/subagents/{name}.md
+ */
+async function findSubagentFiles(agentKitsPath) {
+    const subagentFiles = [];
+    const sharedSubagentsDir = path.join(agentKitsPath, "primitives/subagents");
+    subagentFiles.push(...(await findMarkdownFiles(sharedSubagentsDir)));
+    const kitsDir = path.join(agentKitsPath, "kits");
+    try {
+        const kitEntries = await fs.readdir(kitsDir, { withFileTypes: true });
+        for (const kitEntry of kitEntries) {
+            if (!kitEntry.isDirectory()) {
+                continue;
+            }
+            const kitSubagentsDir = path.join(kitsDir, kitEntry.name, "primitives/subagents");
+            subagentFiles.push(...(await findMarkdownFiles(kitSubagentsDir)));
+        }
+    }
+    catch {
+        // kits directory doesn't exist - ignore
+    }
+    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) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const { frontmatter, body, hasFrontmatter } = parseSubagentFrontmatter(content);
+        if (!hasFrontmatter) {
+            return {
+                file: filePath,
+                valid: false,
+                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) {
+            return {
+                file: filePath,
+                valid: false,
+                error: "subagent missing required 'description' field in frontmatter",
+            };
+        }
+        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,
+                valid: false,
+                error: "subagent body cannot be empty; content after frontmatter is required",
+            };
+        }
+        if (!body.includes("<agent_role>") || !body.includes("</agent_role>")) {
+            return {
+                file: filePath,
+                valid: false,
+                error: "subagent body must include <agent_role> tags",
+            };
+        }
+        return { file: filePath, valid: true };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return { file: filePath, valid: false, error: errorMessage };
+    }
+}
+/**
+ * Validate all subagent files in a kit repository.
+ */
+export async function validateSubagents(agentKitsPath) {
+    const subagentFiles = await findSubagentFiles(agentKitsPath);
+    const results = [];
+    for (const file of subagentFiles) {
+        results.push(await validateSubagentFile(file));
+    }
+    return summarizeResults(results);
+}
+/**
+ * Main entry point for CLI execution.
+ */
+export async function main(args) {
+    let source = args[0];
+    if (!source) {
+        const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+        const fallbackPath = path.resolve(scriptDir, "../../test-kits");
+        try {
+            const stat = await fs.stat(fallbackPath);
+            if (stat.isDirectory()) {
+                source = fallbackPath;
+            }
+        }
+        catch {
+            source = undefined;
+        }
+    }
+    if (!source) {
+        console.error(pc.red("Error: no kit repository path provided"));
+        console.error(pc.dim("Usage: validate-subagents <path-to-kits-repo | org/repo[@ref]>"));
+        return 1;
+    }
+    let fetchResult;
+    try {
+        fetchResult = await resolveValidationSource(source);
+    }
+    catch (error) {
+        const message = formatValidationSourceError(error);
+        console.error(pc.red(`Error: ${message}`));
+        console.error(pc.dim("Usage: validate-subagents <path-to-kits-repo | org/repo[@ref]>"));
+        return 1;
+    }
+    const agentKitsPath = fetchResult.localPath;
+    console.log(pc.dim(`Validating subagents in: ${agentKitsPath}`));
+    try {
+        const summary = await validateSubagents(agentKitsPath);
+        printValidationResults("Subagent Primitive Validation", summary, agentKitsPath);
+        if (summary.failed > 0) {
+            console.error(pc.red(`Subagent validation failed: ${summary.failed} of ${summary.total} file(s) failed`));
+            return 1;
+        }
+        console.log(pc.green("Subagent validation passed"));
+        return 0;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(pc.red(`Error: ${errorMessage}`));
+        return 1;
+    }
+}
+//# sourceMappingURL=validate-subagents.js.map

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

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

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@hashicorp/kits",
+  "version": "0.1.0",
+  "description": "Install AI agent kits into your favorite coding assistants",
+  "type": "module",
+  "bin": {
+    "kits": "./bin/kits.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "bin/",
+    "dist/",
+    "schemas/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "npm run build && INTEGRATION_TESTS=1 vitest run tests/integration",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint src/ tests/ --fix",
+    "format": "prettier --write src/ tests/",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist/",
+    "prepublishOnly": "npm run clean && npm run build",
+    "validate:commands": "node ./bin/kits.js validate --commands ./test-kits",
+    "validate:kits": "node ./bin/kits.js validate --kits ./test-kits",
+    "validate:skills": "node ./bin/kits.js validate --skills ./test-kits",
+    "validate:subagents": "node ./bin/kits.js validate --subagents ./test-kits",
+    "validate:hooks": "node ./bin/kits.js validate --hooks ./test-kits",
+    "validate:mcp": "node ./bin/kits.js validate --mcp ./test-kits",
+    "validate:primitives": "node ./bin/kits.js validate ./test-kits"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "codex",
+    "gemini",
+    "copilot",
+    "opencode",
+    "terraform",
+    "vault",
+    "hashicorp",
+    "installer",
+    "cli"
+  ],
+  "author": {
+    "name": "HashiCorp",
+    "url": "https://hashicorp.com"
+  },
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hashicorp/agent-kit-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hashicorp/agent-kit-cli/issues"
+  },
+  "homepage": "https://github.com/hashicorp/agent-kit-cli#readme",
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "@iarna/toml": "^2.2.5",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "commander": "^13.1.0",
+    "picocolors": "^1.1.1",
+    "semver": "^7.7.1",
+    "simple-git": "^3.27.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "@types/semver": "^7.5.8",
+    "@typescript-eslint/eslint-plugin": "^8.24.0",
+    "@typescript-eslint/parser": "^8.24.0",
+    "@vitest/coverage-v8": "^3.0.5",
+    "eslint": "^9.20.1",
+    "eslint-config-prettier": "^10.0.1",
+    "memfs": "^4.17.0",
+    "prettier": "^3.5.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}

package/schemas/command.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://hashicorp.com/schemas/command.schema.json",
+  "title": "Command Frontmatter",
+  "description": "Schema for command primitive YAML frontmatter",
+  "type": "object",
+  "required": ["description"],
+  "properties": {
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200,
+      "description": "Brief description shown in command menus (50-200 chars recommended)"
+    },
+    "argumentHint": {
+      "type": "string",
+      "maxLength": 50,
+      "pattern": "^[<\\[][A-Z_]+[>\\]](\\s+[<\\[][A-Z_]+[>\\]])*$",
+      "description": "Placeholder shown after command name (e.g., [PATH], <WORKSPACE>, [OPTIONS])"
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,20 @@
+{
+  "event": "tool.before",
+  "matcher": {
+    "tool": "shell",
+    "command_pattern": "terraform\\s+apply"
+  },
+  "policy": {
+    "on_success": "continue",
+    "on_failure": "block",
+    "on_timeout": "warn"
+  },
+  "runtime": {
+    "timeout_ms": 15000,
+    "working_directory": "${PROJECT_DIR}",
+    "args": ["--strict"]
+  },
+  "env": {
+    "STRICT_MODE": "true"
+  }
+}

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

@@ -0,0 +1,25 @@
+{
+  "name": "pre-apply-validation",
+  "version": "1.0.0",
+  "description": "Validate Terraform input before apply",
+  "runtime": {
+    "type": "command",
+    "entrypoint": "hook.sh",
+    "shell": "bash",
+    "working_directory": "inherit",
+    "args": ["--strict"],
+    "timeout_ms": 15000
+  },
+  "io": {
+    "stdin": "json",
+    "stdout": "json",
+    "error_codes": {
+      "success": [0],
+      "warn": [1],
+      "block": [2]
+    }
+  },
+  "env": {
+    "LOG_LEVEL": "info"
+  }
+}

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

@@ -0,0 +1,82 @@
+{
+  "$schema": "../mcp-server.schema.json",
+  "name": "example-http-server",
+  "version": "1.0.0",
+  "description": "Example HTTP MCP server demonstrating sensitive and nonsensitive headers",
+  "transport": {
+    "type": "http",
+    "url": "https://api.example.com/mcp",
+    "headers": {
+      "Authorization": {
+        "description": "Bearer token for API authentication",
+        "sensitive": true,
+        "envVar": "EXAMPLE_API_TOKEN",
+        "required": true
+      },
+      "X-API-Key": {
+        "description": "Secondary API key for rate limiting",
+        "sensitive": true,
+        "envVar": "EXAMPLE_API_KEY"
+      },
+      "X-Client-Version": {
+        "description": "Client version identifier",
+        "sensitive": false,
+        "value": "1.0.0"
+      },
+      "Accept": {
+        "description": "Accepted content types",
+        "sensitive": false,
+        "value": "application/json",
+        "required": true
+      },
+      "X-Request-ID": {
+        "description": "Optional request tracking header (can be set via environment)",
+        "sensitive": false,
+        "envVar": "REQUEST_ID",
+        "required": false
+      }
+    }
+  },
+  "env": {
+    "EXAMPLE_API_TOKEN": {
+      "description": "Bearer token for authenticating with the API",
+      "required": true,
+      "sensitive": true
+    },
+    "EXAMPLE_API_KEY": {
+      "description": "API key for rate limit identification",
+      "required": false,
+      "sensitive": true
+    },
+    "REQUEST_ID": {
+      "description": "Optional request tracking identifier",
+      "required": false,
+      "sensitive": false,
+      "default": "default-client"
+    }
+  },
+  "tools": {
+    "remote_query": {
+      "description": "Execute a query against the remote API"
+    },
+    "remote_mutation": {
+      "description": "Execute a mutation against the remote API"
+    }
+  },
+  "resources": {
+    "api://schema": {
+      "description": "API schema definition",
+      "mimeType": "application/json"
+    }
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": true,
+    "prompts": false
+  },
+  "metadata": {
+    "author": "HashiCorp",
+    "license": "MPL-2.0",
+    "homepage": "https://example.com/mcp-server"
+  }
+}

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

@@ -0,0 +1,16 @@
+{
+  "$schema": "../mcp-server.schema.json",
+  "name": "invalid-server",
+  "version": "1.0.0",
+  "description": "This config should fail validation",
+  "transport": {
+    "type": "http",
+    "url": "https://api.example.com/mcp",
+    "headers": {
+      "Authorization": {
+        "description": "This is invalid - sensitive headers must have envVar",
+        "sensitive": true
+      }
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "$schema": "../mcp-server.schema.json",
+  "name": "invalid-server",
+  "version": "1.0.0",
+  "description": "This config should fail validation",
+  "transport": {
+    "type": "http",
+    "url": "https://api.example.com/mcp",
+    "headers": {
+      "Authorization": {
+        "description": "This is invalid - sensitive headers cannot have static values",
+        "sensitive": true,
+        "value": "Bearer secret-token"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,19 @@
+{
+  "$schema": "../mcp-server.schema.json",
+  "name": "invalid-server",
+  "version": "1.0.0",
+  "description": "This config should fail validation",
+  "transport": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@example/server"]
+  },
+  "env": {
+    "API_TOKEN": {
+      "description": "This is invalid - sensitive vars cannot have defaults",
+      "required": true,
+      "sensitive": true,
+      "default": "secret-token-value"
+    }
+  }
+}

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

@@ -0,0 +1,55 @@
+{
+  "$schema": "../mcp-server.schema.json",
+  "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"],
+    "cwd": "."
+  },
+  "env": {
+    "API_TOKEN": {
+      "description": "API authentication token (sensitive - must be set in environment)",
+      "required": true,
+      "sensitive": true
+    },
+    "DATABASE_PASSWORD": {
+      "description": "Database password for backend storage",
+      "required": false,
+      "sensitive": true
+    },
+    "WORKING_DIR": {
+      "description": "Working directory for file operations",
+      "required": false,
+      "sensitive": false,
+      "default": "."
+    },
+    "LOG_LEVEL": {
+      "description": "Logging verbosity (debug, info, warn, error)",
+      "required": true,
+      "sensitive": false
+    },
+    "MAX_RETRIES": {
+      "description": "Maximum retry attempts for failed operations",
+      "required": false,
+      "sensitive": false,
+      "default": "3"
+    }
+  },
+  "tools": {
+    "example_tool": {
+      "description": "An example tool that does something useful"
+    }
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": false,
+    "prompts": false
+  },
+  "metadata": {
+    "author": "HashiCorp",
+    "license": "MPL-2.0"
+  }
+}