@hashicorp/kits 0.1.0

package/schemas/hook-binding.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://hashicorp.com/schemas/hook-binding.schema.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": {
+        "tool": { "type": "string" },
+        "command_pattern": { "type": "string" },
+        "file_pattern": { "type": "string" },
+        "prompt_pattern": { "type": "string" }
+      },
+      "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
+    },
+    "runtime": {
+      "type": "object",
+      "properties": {
+        "timeout_ms": { "type": "number" },
+        "working_directory": { "type": "string" },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/hook-program.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://hashicorp.com/schemas/hook-program.schema.json",
+  "title": "Hook Program Config",
+  "description": "Schema for hook program config.json files",
+  "type": "object",
+  "required": ["name", "version", "description", "runtime", "io"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 50,
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "description": "Hook program name in lowercase kebab-case"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver version string"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200,
+      "description": "Description of the hook program"
+    },
+    "runtime": {
+      "type": "object",
+      "required": ["type", "entrypoint"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["command", "prompt", "opencode-plugin"],
+          "description": "Hook runtime type"
+        },
+        "entrypoint": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Entrypoint file for the hook program"
+        },
+        "shell": {
+          "type": "string",
+          "description": "Shell to use for command runtime"
+        },
+        "working_directory": {
+          "type": "string",
+          "description": "Working directory for hook execution"
+        },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Arguments passed to the hook program"
+        },
+        "timeout_ms": {
+          "type": "number",
+          "description": "Execution timeout in milliseconds"
+        }
+      },
+      "additionalProperties": false
+    },
+    "io": {
+      "type": "object",
+      "required": ["stdin", "stdout"],
+      "properties": {
+        "stdin": {
+          "type": "string",
+          "enum": ["json", "none"],
+          "description": "Expected stdin format"
+        },
+        "stdout": {
+          "type": "string",
+          "enum": ["json", "none"],
+          "description": "Expected stdout format"
+        },
+        "error_codes": {
+          "type": "object",
+          "properties": {
+            "success": { "type": "array", "items": { "type": "number" } },
+            "warn": { "type": "array", "items": { "type": "number" } },
+            "block": { "type": "array", "items": { "type": "number" } }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Default environment variables for the hook program"
+    },
+    "inputs": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional input schema for hook programs"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Arbitrary metadata for the hook program"
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/kit.schema.json

@@ -0,0 +1,338 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://hashicorp.com/schemas/kit.schema.json",
+  "title": "Kit Manifest",
+  "description": "Schema for kit.json - the kit manifest file within each kit directory",
+  "type": "object",
+  "required": ["schemaVersion", "name", "version", "requires", "primitives"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Version of this schema (semver)"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 50,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+      "description": "Kit name (lowercase kebab-case)"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Kit version (semver)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Brief description of the kit"
+    },
+    "author": {
+      "$ref": "#/definitions/author"
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier"
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri",
+      "description": "Repository URL"
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri",
+      "description": "Homepage URL"
+    },
+    "keywords": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 30
+      },
+      "maxItems": 10,
+      "description": "Keywords for discovery"
+    },
+    "products": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 30
+      },
+      "maxItems": 10,
+      "description": "Products or platforms this kit provides capabilities for"
+    },
+    "requires": {
+      "$ref": "#/definitions/requirements"
+    },
+    "primitives": {
+      "$ref": "#/definitions/primitives"
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "author": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Author name"
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "description": "Author email"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Author URL"
+        }
+      },
+      "additionalProperties": false
+    },
+    "primitiveType": {
+      "type": "string",
+      "enum": ["commands", "skills", "subagents", "mcp", "hooks"],
+      "description": "Primitive type identifier"
+    },
+    "requirements": {
+      "type": "object",
+      "required": ["primitives"],
+      "properties": {
+        "primitives": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/primitiveType"
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Primitive types required by this kit"
+        }
+      },
+      "additionalProperties": false
+    },
+    "primitives": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/primitiveDeclaration"
+          },
+          "description": "Command primitives"
+        },
+        "skills": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/primitiveDeclaration"
+          },
+          "description": "Skill primitives"
+        },
+        "subagents": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/primitiveDeclaration"
+          },
+          "description": "Subagent primitives"
+        },
+        "mcp": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/primitiveDeclaration"
+          },
+          "description": "MCP server primitives"
+        },
+        "hooks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/hookPrimitiveDeclaration"
+          },
+          "description": "Hook primitives"
+        }
+      },
+      "additionalProperties": false
+    },
+    "primitiveDeclaration": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/referencedPrimitive"
+        },
+        {
+          "$ref": "#/definitions/inlinePrimitive"
+        }
+      ]
+    },
+    "hookPrimitiveDeclaration": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/hookReferencedPrimitive"
+        },
+        {
+          "$ref": "#/definitions/hookInlinePrimitive"
+        }
+      ]
+    },
+    "referencedPrimitive": {
+      "type": "object",
+      "required": ["ref"],
+      "properties": {
+        "ref": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*@(latest|\\^?\\~?[0-9]|>=|<|\\d+\\.\\d+\\.\\d+)",
+          "description": "Reference to shared primitive (format: name@version-spec)"
+        },
+        "instanceName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional MCP instance name override (MCP only)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "inlinePrimitive": {
+      "type": "object",
+      "required": ["name", "entrypoint"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 50,
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "description": "Primitive name (lowercase kebab-case)"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Brief description of the primitive"
+        },
+        "entrypoint": {
+          "type": "string",
+          "description": "Relative path to primitive file from kit directory"
+        },
+        "instanceName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional MCP instance name override (MCP only)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "hookReferencedPrimitive": {
+      "type": "object",
+      "required": ["ref", "binding"],
+      "properties": {
+        "ref": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*@(latest|\\^?\\~?[0-9]|>=|<|\\d+\\.\\d+\\.\\d+)",
+          "description": "Reference to shared hook program (format: name@version-spec)"
+        },
+        "instanceName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional hook instance name override"
+        },
+        "binding": {
+          "$ref": "#/definitions/hookBinding"
+        }
+      },
+      "additionalProperties": false
+    },
+    "hookInlinePrimitive": {
+      "type": "object",
+      "required": ["name", "entrypoint", "binding"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 50,
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "description": "Hook program name (lowercase kebab-case)"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Brief description of the hook program"
+        },
+        "entrypoint": {
+          "type": "string",
+          "description": "Relative path to hook program config.json from kit directory"
+        },
+        "instanceName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional hook instance name override"
+        },
+        "binding": {
+          "$ref": "#/definitions/hookBinding"
+        }
+      },
+      "additionalProperties": false
+    },
+    "hookBinding": {
+      "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": {
+            "tool": { "type": "string" },
+            "command_pattern": { "type": "string" },
+            "file_pattern": { "type": "string" },
+            "prompt_pattern": { "type": "string" }
+          },
+          "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
+        },
+        "runtime": {
+          "type": "object",
+          "properties": {
+            "timeout_ms": { "type": "number" },
+            "working_directory": { "type": "string" },
+            "args": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/kits.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://hashicorp.com/schemas/kits.schema.json",
+  "title": "Kit Registry",
+  "description": "Schema for kits.json - the kit registry file at the repository root",
+  "type": "object",
+  "required": ["schemaVersion", "name", "kits"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Version of this schema (semver)"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 50,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+      "description": "Repository name (lowercase kebab-case)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Brief description of the repository"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Repository version (semver)"
+    },
+    "owner": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Owner name"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Owner URL"
+        }
+      },
+      "additionalProperties": false
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri",
+      "description": "Repository URL"
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier"
+    },
+    "kits": {
+      "type": "array",
+      "description": "List of kits in this repository",
+      "items": {
+        "$ref": "#/definitions/kitEntry"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "kitEntry": {
+      "type": "object",
+      "required": ["name", "path", "version"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 50,
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "description": "Kit name (lowercase kebab-case)"
+        },
+        "path": {
+          "type": "string",
+          "description": "Relative path to kit directory"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Brief description of the kit"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Kit version (semver)"
+        },
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 30
+          },
+          "maxItems": 10,
+          "description": "Keywords for discovery"
+        },
+        "products": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 30
+          },
+          "maxItems": 10,
+          "description": "Products or platforms this kit provides capabilities for"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}