@helmstack/schemas

Contract-first schemas for the HelmStack ecosystem. This repository defines the single source of truth for all commands, flags, payload schemas, and validation rules.

📋 Overview

HelmStack follows a contract-first approach where all components (core, cli, addons, ml) operate against the same schema definitions:

• spec.yml - Complete command surface definition
• schemas/ - JSON Schema payload definitions
• tools/ - Code generators for types, validators, and help content

🏗️ Structure

helmstack-schemas/
├── spec/
│   └── spec.yml              # Master command specification
├── schemas/
│   ├── common/               # Shared types and envelope format
│   ├── plan/                 # Plan command schemas
│   ├── review/               # Review command schemas
│   └── ...                   # Other command schemas
├── tools/                    # Code generation tools
└── tests/                    # Contract tests

🚀 Usage

# Install dependencies
npm install

# Generate types, validators, and help content
npm run generate

# Run contract tests
npm test:contract

# Lint schemas and spec
npm run lint

📝 Contract Validation

All HelmStack components must pass contract tests against these schemas:

• Input validation (where defined)
• Output payload validation (required for all commands)
• Envelope format compliance

🔄 Versioning

This package follows semantic versioning:

• Patch: Documentation, examples, non-breaking additions
• Minor: New commands/flags, backward-compatible schema changes
• Major: Breaking changes to existing commands or schemas

🤝 Contributing

Schema changes require approval from the Schema Working Group. For major changes, please open an RFC first.

Part of the HelmStack ecosystem.