@hashicorp/kits 0.1.0

package/schemas/manifest.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://hashicorp.com/schemas/manifest.schema.json",
+  "title": "Installation Manifest",
+  "description": "Schema for the installation manifest. Location varies by scope: ~/.agents/manifest.json (global) or .agents/manifest.json (project).",
+  "type": "object",
+  "required": ["version", "scope", "lastUpdated", "harnesses"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Manifest schema version"
+    },
+    "scope": {
+      "$ref": "#/definitions/installationScope",
+      "description": "Installation scope: global (user-level) or project (repository-level)"
+    },
+    "projectRoot": {
+      "type": "string",
+      "description": "Absolute path to project root. Required when scope is 'project'."
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Last update timestamp (ISO 8601)"
+    },
+    "source": {
+      "type": "string",
+      "description": "Last used source repository"
+    },
+    "harnesses": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/harnessInstallation"
+      },
+      "description": "Installations per harness"
+    }
+  },
+  "additionalProperties": false,
+  "if": {
+    "properties": { "scope": { "const": "project" } }
+  },
+  "then": {
+    "required": ["projectRoot"]
+  },
+  "definitions": {
+    "installationScope": {
+      "type": "string",
+      "enum": ["global", "project"],
+      "description": "Installation scope: global (user-level, ~/.agents/) or project (repository-level, .agents/)"
+    },
+    "harnessName": {
+      "type": "string",
+      "enum": ["claude-code", "codex", "gemini-cli", "github-copilot", "opencode"],
+      "description": "AI agent harness identifier"
+    },
+    "primitiveType": {
+      "type": "string",
+      "enum": ["commands", "skills", "subagents", "mcp", "hooks"],
+      "description": "Primitive type identifier"
+    },
+    "harnessInstallation": {
+      "type": "object",
+      "required": ["kits"],
+      "properties": {
+        "kits": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/installedKit"
+          },
+          "description": "Installed kits"
+        },
+        "mcpInstances": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/mcpInstance"
+          },
+          "description": "Installed MCP instances"
+        },
+        "hookInstances": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/hookInstance"
+          },
+          "description": "Installed hook instances"
+        }
+      },
+      "additionalProperties": false
+    },
+    "installedKit": {
+      "type": "object",
+      "required": ["version", "installedAt", "source", "primitives"],
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Installed kit version"
+        },
+        "installedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Installation timestamp (ISO 8601)"
+        },
+        "source": {
+          "type": "string",
+          "description": "Source repository"
+        },
+        "primitives": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/installedPrimitive"
+          },
+          "description": "Installed primitives"
+        }
+      },
+      "additionalProperties": false
+    },
+    "installedPrimitive": {
+      "type": "object",
+      "required": ["name", "type", "namespacedName", "isInline", "installedPath"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Primitive name"
+        },
+        "type": {
+          "$ref": "#/definitions/primitiveType"
+        },
+        "namespacedName": {
+          "type": "string",
+          "description": "Namespaced name (kit.primitive)"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Resolved version for referenced primitives"
+        },
+        "versionSpec": {
+          "type": "string",
+          "description": "Original version spec (e.g., ^1.0.0)"
+        },
+        "isInline": {
+          "type": "boolean",
+          "description": "Whether this is an inline primitive"
+        },
+        "installedPath": {
+          "type": "string",
+          "description": "Actual path where installed"
+        },
+        "instanceName": {
+          "type": "string",
+          "description": "Instance name override (MCP, hooks)"
+        },
+        "configHash": {
+          "type": "string",
+          "description": "Instance config hash (MCP, hooks)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "mcpInstance": {
+      "type": "object",
+      "required": ["version", "configHash", "usedBy", "sourcePrimitive", "installedAt"],
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Resolved version"
+        },
+        "configHash": { "type": "string" },
+        "usedBy": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "sourcePrimitive": { "type": "string" },
+        "installedAt": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    },
+    "hookInstance": {
+      "type": "object",
+      "required": ["version", "configHash", "usedBy", "sourcePrimitive", "installedAt"],
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Resolved version"
+        },
+        "configHash": { "type": "string" },
+        "usedBy": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "sourcePrimitive": { "type": "string" },
+        "installedAt": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/mcp-server.schema.json

@@ -0,0 +1,305 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hashicorp.com/schemas/mcp-server.schema.json",
+  "title": "MCP Server Configuration",
+  "description": "Schema for MCP server configuration files with sensitivity classification for environment variables and headers",
+  "type": "object",
+  "required": ["name", "version", "description", "transport"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100,
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "MCP server name (lowercase kebab-case)"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Server version (semver)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Brief description of the server"
+    },
+    "transport": {
+      "oneOf": [
+        { "$ref": "#/$defs/stdioTransport" },
+        { "$ref": "#/$defs/httpTransport" }
+      ],
+      "description": "Transport configuration (STDIO or HTTP)"
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/envVarDefinition"
+      },
+      "description": "Environment variable definitions"
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/toolDefinition"
+      },
+      "description": "Tools provided by this server"
+    },
+    "resources": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/resourceDefinition"
+      },
+      "description": "Resources provided by this server"
+    },
+    "prompts": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/promptDefinition"
+      },
+      "description": "Prompts provided by this server"
+    },
+    "capabilities": {
+      "$ref": "#/$defs/capabilities",
+      "description": "Server capabilities"
+    },
+    "metadata": {
+      "$ref": "#/$defs/metadata",
+      "description": "Additional metadata"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "stdioTransport": {
+      "type": "object",
+      "required": ["type", "command"],
+      "properties": {
+        "type": {
+          "const": "stdio",
+          "description": "STDIO transport type"
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Command to execute"
+        },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Command arguments"
+        },
+        "cwd": {
+          "type": "string",
+          "description": "Working directory for the command"
+        }
+      },
+      "additionalProperties": false,
+      "description": "STDIO transport configuration"
+    },
+    "httpTransport": {
+      "type": "object",
+      "required": ["type", "url"],
+      "properties": {
+        "type": {
+          "const": "http",
+          "description": "HTTP transport type"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "HTTP endpoint URL"
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/headerDefinition"
+          },
+          "description": "HTTP header definitions"
+        }
+      },
+      "additionalProperties": false,
+      "description": "HTTP transport configuration"
+    },
+    "envVarDefinition": {
+      "type": "object",
+      "required": ["description", "required", "sensitive"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Description of the environment variable"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether this variable is required"
+        },
+        "sensitive": {
+          "type": "boolean",
+          "description": "Whether this variable contains sensitive data (secrets, tokens, passwords)"
+        },
+        "default": {
+          "type": "string",
+          "description": "Default value (only allowed for nonsensitive variables)"
+        }
+      },
+      "additionalProperties": false,
+      "if": {
+        "properties": {
+          "sensitive": { "const": true }
+        },
+        "required": ["sensitive"]
+      },
+      "then": {
+        "not": {
+          "required": ["default"]
+        }
+      },
+      "description": "Environment variable definition with sensitivity classification"
+    },
+    "headerDefinition": {
+      "type": "object",
+      "required": ["description", "sensitive"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Description of the header"
+        },
+        "sensitive": {
+          "type": "boolean",
+          "description": "Whether this header contains sensitive data"
+        },
+        "envVar": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*$",
+          "description": "Environment variable name to read header value from (required if sensitive)"
+        },
+        "value": {
+          "type": "string",
+          "description": "Static header value (only allowed for nonsensitive headers)"
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether this header is required"
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "sensitive": { "const": true }
+            },
+            "required": ["sensitive"]
+          },
+          "then": {
+            "required": ["envVar"],
+            "not": {
+              "required": ["value"]
+            }
+          }
+        }
+      ],
+      "description": "HTTP header definition with sensitivity classification"
+    },
+    "toolDefinition": {
+      "type": "object",
+      "required": ["description"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Description of the tool"
+        }
+      },
+      "additionalProperties": true,
+      "description": "Tool definition"
+    },
+    "resourceDefinition": {
+      "type": "object",
+      "required": ["description"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Description of the resource"
+        },
+        "mimeType": {
+          "type": "string",
+          "description": "MIME type of the resource"
+        }
+      },
+      "additionalProperties": true,
+      "description": "Resource definition"
+    },
+    "promptDefinition": {
+      "type": "object",
+      "required": ["description"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Description of the prompt"
+        }
+      },
+      "additionalProperties": true,
+      "description": "Prompt definition"
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "tools": {
+          "type": "boolean",
+          "default": false,
+          "description": "Server provides tools"
+        },
+        "resources": {
+          "type": "boolean",
+          "default": false,
+          "description": "Server provides resources"
+        },
+        "prompts": {
+          "type": "boolean",
+          "default": false,
+          "description": "Server provides prompts"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Server capabilities"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "author": {
+          "type": "string",
+          "description": "Author name or organization"
+        },
+        "license": {
+          "type": "string",
+          "description": "SPDX license identifier"
+        },
+        "homepage": {
+          "type": "string",
+          "format": "uri",
+          "description": "Homepage URL"
+        },
+        "repository": {
+          "type": "string",
+          "format": "uri",
+          "description": "Repository URL"
+        },
+        "keywords": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Keywords for discovery"
+        }
+      },
+      "additionalProperties": true,
+      "description": "Additional metadata"
+    }
+  }
+}

package/schemas/primitives.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://hashicorp.com/schemas/primitives.schema.json",
+  "title": "Primitives Registry",
+  "description": "Schema for primitives.json - the shared primitives registry at the repository root",
+  "type": "object",
+  "required": ["schemaVersion", "primitives"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Version of this schema (semver)"
+    },
+    "primitives": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/primitiveEntry"
+          },
+          "description": "Command primitives"
+        },
+        "skills": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/primitiveEntry"
+          },
+          "description": "Skill primitives"
+        },
+        "subagents": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/primitiveEntry"
+          },
+          "description": "Subagent primitives"
+        },
+        "mcp": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/primitiveEntry"
+          },
+          "description": "MCP server primitives"
+        },
+        "hooks": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/primitiveEntry"
+          },
+          "description": "Hook primitives"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "primitiveEntry": {
+      "type": "object",
+      "required": ["description", "path", "versions", "latest"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Brief description of the primitive"
+        },
+        "path": {
+          "type": "string",
+          "description": "Base path to primitive directory relative to repo root"
+        },
+        "versions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/versionEntry"
+          },
+          "minItems": 1,
+          "description": "Available versions (ordered newest first)"
+        },
+        "latest": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Version string of the latest release"
+        }
+      },
+      "additionalProperties": false
+    },
+    "versionEntry": {
+      "type": "object",
+      "required": ["version", "released", "changelog", "path"],
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Semver version string"
+        },
+        "released": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "Release date (ISO 8601 date: YYYY-MM-DD)"
+        },
+        "changelog": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Description of changes in this version"
+        },
+        "path": {
+          "type": "string",
+          "description": "Relative path from base path to version content"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}