feat: contractual pivot - schema lifecycle orchestrator

[omermorad]

🔄 The Pivot

Before: Contractual was a TypeSpec-first code generation tool for Node.js/TypeScript - generating ts-rest clients and server contracts from .tsp files.

After: Contractual is now the Buf equivalent for REST, events, and data - a schema lifecycle orchestrator that wraps existing best-in-class tools through a single CLI and declarative config.

🎯 Why This Change?

The original vision was too narrow. Every schema ecosystem (OpenAPI, JSON Schema, AsyncAPI, ODCS) has the same lifecycle needs:

validate → detect breaking changes → version → generate → publish

But only Protobuf has complete tooling (Buf). Everything else is fragmented - teams manually wire 4-5 separate tools in CI.

Contractual is now the orchestration layer that doesn't exist.

🏗️ What's New

Single Config, Full Lifecycle

# contractual.yaml
contracts:
  - name: orders-api
    path: ./specs/orders.openapi.yaml
    type: openapi

  - name: order-schema
    path: ./schemas/order.schema.json
    type: json-schema

CLI Commands

Command	Description
contractual init	Scaffold project with config
contractual lint	Lint all contracts (Redocly, AJV)
contractual breaking	Detect breaking changes against snapshots
contractual changeset	Auto-generate changeset from detected changes
contractual version	Consume changesets, bump versions
contractual status	Show versions and pending changesets

Changesets Workflow (Adapted from @changesets/cli)

Developer PR → changeset file committed → PR merges
                    ↓
GitHub Action → "Version Contracts" PR opened
                    ↓
Maintainer merges → versions bumped, snapshots updated

Native JSON Schema Differ

The JSON Schema ecosystem has 150M+ weekly downloads but no production-quality breaking change detection. The JSON Schema organization acknowledged this as the #1 missing capability (GSoC 2026 project accepted).

We built it:

• Semantic classification of changes (breaking vs non-breaking)
• Handles additionalProperties, required fields, type changes, enum modifications
• Full $ref resolution support

📦 New Package Structure

packages/
├── types/              # @contractual/types - shared TypeScript types
├── changesets/         # @contractual/changesets - versioning logic
├── governance/         # @contractual/governance - linters & differs
├── json-schema-differ/ # @contractual/json-schema-differ - standalone differ
└── cli/                # @contractual/cli - orchestration layer

---

This is a complete rewrite. The old TypeSpec/ts-rest approach is removed. Contractual is now positioned as the missing orchestration layer for schema contract lifecycle management.