@shobman/strata-cli

CLI toolchain and contract engine for the Strata layout protocol. Validates YAML contracts, generates TypeScript types, and scaffolds routes and components.

Installation

npm install @shobman/strata-cli

Commands

strata init

Initialise a project with Strata contracts and AI skill file. Idempotent — safe to run multiple times.

npx strata init

Creates:

.claude/skills/STRATA-SKILL.md    # AI agent skill file
components/atoms/_contract.yml     # atom level contract
components/molecules/_contract.yml # molecule level contract
components/organisms/_contract.yml # organism level contract
routes/_contract.yml               # root route contract

Also adds strata:check and strata:build scripts to your package.json.

strata check

Validate all contracts (YAML only, no source code). Fast — runs in CI.

npx strata check

Exit code 1 if errors are found. Output format:

error  fills-reference-real-slots       routes/funds/index/_contract.yml
       Fill "nonexistent" does not match any slot in ancestors or self

warn   route-level-consistency          routes/funds/_contract.yml
       Route-level contract should use level: route, rank: 3

Validation rules:

| Rule | Severity | Description | |------|----------|-------------| | fills-reference-real-slots | error | All fills must reference slots declared by ancestors or self | | required-slots-satisfied | error | Required slots must be filled through the default/redirect chain | | default-redirect-mutual-exclusivity | error | A route cannot have both default and redirect | | default-redirect-target-exists | error | Named child must exist as a subfolder | | param-route-excluded-from-default-redirect | error | Dynamic routes ([param]) cannot be defaults or redirects | | route-level-consistency | warn | Routes should be level: route, rank: 3 | | component-level-consistency | warn | Components should match their directory level |

strata build

Generate TypeScript types from YAML contracts.

npx strata build

Creates .strata.types.ts next to each _contract.yml:

// AUTO-GENERATED by strata build — do not edit
export type FundsFundIdSlots = "tabs" | "contextPanel";
export type FundsFundIdRequiredSlots = "tabs";
export type FundsFundIdInheritedSlots = "breadcrumb" | "actions";
export type FundsFundIdAllSlots = FundsFundIdSlots | FundsFundIdInheritedSlots;

Type naming convention: path segments are PascalCased and joined. routes/funds/[fundId] becomes FundsFundId.

strata add route <path>

Scaffold a new route with contract, page stub, and optional layout.

npx strata add route funds/[fundId]/compliance
npx strata add route funds --fills menu --slots listActions --default index

| Flag | Description | |------|-------------| | --fills <slots> | Comma-separated slot names this route fills | | --slots <slots> | Comma-separated slot names this layout declares (generates _layout.tsx) | | --default <child> | Child that renders at this route's URL (index route) | | --redirect <child> | Child that this route redirects to | | --param <name> | Route parameter name (auto-detected from brackets) |

Creates _contract.yml and index.tsx. If --slots is provided, also creates _layout.tsx with SlotProvider/SlotTarget boilerplate. Runs strata build automatically after scaffolding.

strata add <level> <name>

Scaffold a component at the specified level.

npx strata add atom Button
npx strata add molecule SearchBar
npx strata add organism FundPanel

Creates components/<level>s/<Name>/index.tsx and the level's _contract.yml if missing.

Contract Format

Every route directory contains a _contract.yml:

param: fundId                     # route parameter name (optional)
level:
  name: route                     # atom | molecule | organism | route
  rank: 3                         # 0 | 1 | 2 | 3
fills: [breadcrumb, actions]      # ancestor slots this route fills
layout:
  slots:
    tabs: required                # slot declarations (required or null)
    contextPanel:
  default: overview               # child renders at this URL (index route)
  redirect: performance           # parent URL redirects to child URL

Programmatic API

The contract engine is available as a library:

import {
  buildContractTree,
  validateContracts,
  resolveAvailableSlots,
} from "@shobman/strata-cli";

| Export | Description | |--------|-------------| | buildContractTree(rootDir) | Build hierarchical contract tree from filesystem | | validateContracts(tree) | Run all validation rules, returns diagnostics | | resolveAvailableSlots(node) | Get all slots available to a node (own + ancestor) | | resolveAncestorSlots(node) | Get ancestor slots only | | isSlotFilledInChain(node, name) | Check if slot is filled through default/redirect chain | | parseContractFile(path) | Parse a single _contract.yml |

Tips

YAML bracket quoting

[fundId] is valid YAML array syntax. All _contract.yml references to parameterised folders must use quotes:

# Correct
default: "[fundId]"

# Wrong — YAML parses this as an array
default: [fundId]

The strata add command handles this automatically when generating contracts for bracket segments.

License

MIT