@knot0/cli (MVP)

Knot0 DSL CLI for validating manifests against the v2 schemas and emitting actionable diagnostics for humans, CI, and LLM agents.

Features

• Validates YAML manifests (**/*.knot0.yml) using JSON Schema (draft 2020-12)
• Loads schemas from the published package @knot0/schemas (with local fallbacks)
• Multiple outputs: human, ndjson, sarif (MVP)
• Stable diagnostic shape (code, path, message) for automation
• Non-interactive, deterministic, fast

Install (local)

cd knot0-src/cli
yarn install
yarn build

Optionally link for global use:

yarn link
knot0 --help

Usage

Validate current directory (recursively discovers **/*.knot0.yml):

knot0 validate --format human | cat
knot0 validate --format ndjson > .reports/validate.ndjson
knot0 validate --format sarif > .reports/validate.sarif

Options:

• --format human|ndjson|sarif (default: human)
• --max-errors N (default: 200)

Exit codes:

• 0 = success (no errors)
• 1 = validation errors
• 2 = CLI failure

Diagnostic format (ndjson)

Each line is one JSON object:

{"code":"KSCHEMA","severity":"error","file":"components/x/component.knot0.yml","json_pointer":"/contract/inputs","message":"must be object"}

Fields:

• code: error code (KSCHEMA for schema failures; custom rules add Kxxx)
• severity: info|warning|error
• file: absolute or repo-relative path
• json_pointer: JSON Pointer within the YAML document (if available)
• message: human-readable detail
• hint, docs_url: reserved for custom rules

Schema resolution

Order of precedence when loading schemas:

1. Published package @knot0/schemas (preferred)
2. Local JSON cache schemas-cache/*.json (if present)
3. Local source schemas-v2/yaml/*.yaml (if present)

Per-file, the CLI resolves which schema to use by:

1. $schema field, if present
2. Fallback by kind (Component, Workflow, Application, DataAsset, DataType, Infrastructure, System, Policy, Event)

CI example (GitHub Actions)

- name: Validate manifests
  run: |
    npm i -g @knot0/cli @knot0/schemas
    knot0 validate . --format ndjson > .reports/validate.ndjson
- uses: actions/upload-artifact@v4
  with:
    name: validate
    path: .reports/validate.ndjson

For LLM agents

Typical loop:

1. Generate/modify YAML
2. knot0 validate --format ndjson
3. Parse diagnostics → apply structured fixes
4. Re-validate until clean

Roadmap

• Custom semantic rules (K001..):
  • Capabilities under permissions only
  • Runner-specific permission checks
  • Metric naming/units; benchmark↔telemetry mapping
  • Expressions parser/type checks
  • Resource mapping type-safety
• fmt command (style enforcement)
• migrate command (autofixes for common issues)
• doctor (env/schema checks)

License

MIT