bundle.alpic
The deterministic, spec-first compiler that keeps AI-written software coherent, safe, and regenerable.
Installation
npx @contractspec/bundle.alpicAsk AI about bundle.alpic
Powered by Claude Β· Grounded in docs
I know everything about bundle.alpic. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ContractSpec
Website: https://contractspec.io
Stabilize your AI-generated code
The open spec system for AI-native software. Define explicit contracts, keep every surface aligned, regenerate safely, and adopt Studio when you want the operating layer on top.
The Problem
In 2025, "vibe coding" and AI agents generate enormous amounts of code. But they have critical limitations:
- Can't enforce invariants β AI-generated code drifts from business rules over time
- Break multi-surface consistency β API, DB, UI, and events get out of sync
- Hallucinate refactors β AI "improvements" introduce subtle bugs and break contracts
- Destroy long-term maintainability β No source of truth, no safe regeneration path
The result: Teams ship fast initially, then spend months untangling AI-generated spaghetti.
How ContractSpec Works
- Define contracts once β Write specs in TypeScript. Just types and Zod schemas you already know.
- Generate all surfaces β One spec generates API, DB schema, UI types, events, and MCP tools.
- Regenerate safely β Update specs, regenerate code. Invariants are enforced. Breaking changes caught at compile time.
- AI reads specs β AI agents read contracts as their source of truth, not implementations.
What Gets Generated
From a single contract spec:
| Surface | Output |
|---|---|
| REST API | Type-safe endpoints with validation |
| GraphQL | Schema and resolvers |
| Database | Prisma migrations and types |
| MCP Tools | AI agent tool definitions |
| Client SDK | Type-safe API clients |
| UI Components | React forms and views |
Open, Ejectable Foundation
ContractSpec is an open system, not a closed platform:
- β Generated code is standard TypeScript you can read and modify
- β Uses standard tech (Prisma, GraphQL, Zod, React)
- β No proprietary runtime β eject anytime, keep everything
- β Incremental adoption β start with one module, expand at your pace
Quick Start
Choose one verified starting path. For the public CLI onboarding flows below, use Bun on Linux or macOS.
Greenfield
bun add -D contractspec
contractspec quickstart
contractspec onboard
contractspec init
contractspec create --type operation
contractspec generate
contractspec ci
Brownfield OpenAPI Import
bun add -D contractspec
contractspec init
contractspec openapi import path/to/openapi.yaml
contractspec ci
Example-First Exploration
bun add -D contractspec
contractspec examples list
contractspec examples init crm-pipeline
See the CLI documentation and tutorials for the maintained onboarding flows.
Support Matrix
| Area | Supported Path |
|---|---|
| Package manager | bun 1.3.x is first-class for CLI onboarding and daily use |
| Operating system | Linux and macOS are covered by packaged smoke tests; Windows is not yet a supported CLI onboarding target |
| Alternate package managers | npm and pnpm can install libraries, but the contractspec CLI onboarding path is not yet certified on them |
| Greenfield onboarding | contractspec quickstart + contractspec onboard + contractspec init |
| Brownfield onboarding | contractspec openapi import |
| Example exploration | contractspec examples list + contractspec examples init |
| CI validation | contractspec ci (--check-drift optional when generated artifacts are part of the contract) |
| Diagnostics | contractspec doctor (read-only), contractspec doctor --fix (repair mode) |
Connect For Coding-Agent Safety
ContractSpec Connect keeps risky coding-agent actions attached to local, reviewable artifacts instead of adapter-specific prompt rules.
contractspec connect contextprojects repo state and impacted surfaces into a task-scopedContextPack.contractspec connect plancompiles aPlanPacketbefore risky edits or shell execution.contractspec connect verifyemitsPatchVerdictdecisions for file edits and commands, with review and replay artifacts under.contractspec/connect/.connect.adoptionin.contractsrc.jsoncan mirror the local adoption catalog and prefer workspace or ContractSpec reuse before greenfield implementation.
See the maintained walkthroughs in Connect in a repo and the Connect spec page.
Builder Control Plane
Builder is the governed authoring control plane that sits on top of the OSS foundation. It keeps multimodal capture, provider routing, readiness, preview, export, and mobile review explicit instead of hiding them inside a frontier coding agent.
- Builder workspace config supports
runtimeMode: "managed" | "local" | "hybrid". - Preset-driven bootstrap now uses canonical
managed_mvp,local_daemon_mvp, andhybrid_mvpvalues. - Builder API defaults and local runtime metadata live in
.contractsrc.json, so CLI, editors, and hosted shells can resolve the same control-plane settings.
See Host the Builder workbench and Builder control plane.
First-Class Surfaces
- Contracts and generation:
@contractspec/lib.contracts-spec, the main CLI, and runtime adapters for REST, GraphQL, MCP, and React. - Connect and governed repo workflows: ContractSpec Connect for context packs, plan packets, patch verdicts, local review packets, replay, and evaluation artifacts.
- Builder control plane: governed authoring, provider routing, runtime modes, previews, readiness gates, exports, and mobile review surfaces.
- Agent and chat runtime:
@contractspec/lib.ai-agentand@contractspec/module.ai-chatfor tool-aware, MCP-aware, agent-governed experiences. - Harness and evaluation:
@contractspec/lib.harnessand@contractspec/integration.harness-runtimefor controlled inspection, replay, evaluation, and proof-oriented workflows. - Ranking and MCP operations: provider-ranking module and MCP surfaces for ingesting benchmarks, refreshing rankings, and serving leaderboards.
- Docs, registry, and Studio: the public docs/web app, the agentpacks registry surfaces, and ContractSpec Studio's trusted operating loop.
Trust & Verification
- Published npm packages are shipped from provenance-enabled GitHub Actions runs, and each release run uploads a manifest artifact with package name, version, dist-tag, tarball filename, and SHA256.
- Release communication is now changeset-backed in two files:
.changeset/<slug>.mdfor package/version intent and.changeset/<slug>.release.yamlfor summary, migration guidance, validation commands, and evidence. - Run
bun run release:buildto materialize the compact current-release manifests used by GitHub Release notes and upgrade guidance. - Run
contractspec release build --scope all --output generated/releases/historybefore building full historical changelog surfaces. - Run
bun run repo:healthin this repo to reproduce the baseline trust checks locally: doctor, contract CI, and example validation. - Verify the published CLI tag with
npm view contractspec dist-tags --json. - Verify a specific published package with
npm view contractspec@<version> dist.tarball dist.integrity --json. - Security disclosure and support expectations are documented in SECURITY.md.
Release Capsules
Every publishable changeset should leave behind both:
.changeset/<slug>.mdfor package bumps and reader-facing change intent.changeset/<slug>.release.yamlfor structured release metadata such as audiences, migration steps, upgrade steps, validation commands, and evidence
Use:
contractspec release init
contractspec release build
contractspec release check --strict
This keeps current-release upgrade prompts and maintainer guidance compact. Full historical changelog builds should use the explicit history output path.
GitHub Actions Quickstart
Use the ContractSpec actions directly; this repo's workflows are thin wrappers around them.
PR checks
name: ContractSpec PR
on: pull_request
jobs:
contractspec:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- name: ContractSpec PR checks
uses: lssm-tech/contractspec/packages/apps/action-pr@main
with:
generate-command: 'bun contractspec generate'
Drift check
name: ContractSpec Drift
on:
push:
branches: [main]
jobs:
contractspec:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- name: ContractSpec drift check
uses: lssm-tech/contractspec/packages/apps/action-drift@main
with:
generate-command: 'bun contractspec generate'
Notes: add pull-requests: write permissions for PR comments, and add contents: write + pull-requests: write for drift PR creation.
Inputs (defaults)
| Action | Input | Default | Notes |
|---|---|---|---|
| PR | package-manager | bun | bun, npm, pnpm, yarn |
| PR | working-directory | . | Repo root or package path |
| PR | report-mode | summary | summary, comment, both, off |
| PR | enable-drift | true | Runs generate + drift check |
| PR | fail-on | any | breaking, drift, any, never |
| PR | generate-command | required | Required when drift enabled |
| PR | contracts-dir | empty | Directory for contract changes |
| PR | contracts-glob | empty | Glob for contract changes |
| Drift | generate-command | required | Regenerate artifacts |
| Drift | on-drift | fail | fail, issue, pr |
| Drift | drift-paths-allowlist | empty | Comma-separated globs |
Sample output
## ContractSpec Report
### 1) What changed
2 contract file(s) changed.
ContractSpec Studio
ContractSpec Studio is the operating product built on top of ContractSpec.
It starts with one trusted product loop for certified live signals, reviewed drafts, supervised exports, and scheduled checks:
Activate -> Connect -> Draft -> Review -> Export -> Check
- Operate: Run the trusted loop with certified connectors, reviewed work drafts, guarded exports, and follow-up checks.
- Explore: Scan any company's public signals to generate Spec Packs, Drift Registers, competitive analysis, and other structured deliverables.
- Current certified wedge: Sandbox activation, PostHog, Slack, GitHub, Linear, and Notion.
- Governance first: Self-serve workspaces stay draft-only before export, with policy gates, audit trails, retention controls, and no autopilot code push, PR merge, or deployment in v0.
contractspec is the open foundation: contracts, generation, runtimes, harnesses, and agent-facing surfaces. Studio is the operating layer that runs on top of it across web, API, and MCP surfaces.
Example Contract
import { defineCommand } from '@contractspec/lib.contracts-spec';
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
const UserInput = new SchemaModel({
name: 'UserInput',
fields: {
email: { type: ScalarTypeEnum.Email(), isOptional: false },
name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
},
});
export const CreateUser = defineCommand({
meta: {
name: 'user.create',
version: '1.0.0',
description: 'Register a new user',
owners: ['team-auth'],
tags: ['auth'],
},
io: {
input: UserInput,
output: new SchemaModel({
name: 'UserOutput',
fields: {
id: { type: ScalarTypeEnum.String(), isOptional: false },
},
}),
},
policy: {
auth: 'anonymous',
},
});
Packages
Contracts Core
| npm | Package | Description |
|---|---|---|
@contractspec/lib.contracts-spec | Core contract declarations, registries, policy, workflow, and shared spec types | |
@contractspec/lib.contracts-integrations | Integration definitions (providers, capabilities, connection/runtime metadata) | |
@contractspec/lib.schema | Schema definitions for multi-surface consistency | |
@contractspec/app.cli-contractspec | CLI for creating, generating, validating, and running CI checks |
Contracts Runtime Adapters
| npm | Package | Description |
|---|---|---|
@contractspec/lib.contracts-runtime-client-react | React runtime adapters for forms and feature rendering | |
@contractspec/lib.contracts-runtime-server-rest | REST server adapters (rest-next-app, rest-express, rest-elysia, generic) | |
@contractspec/lib.contracts-runtime-server-graphql | GraphQL runtime adapter (graphql-pothos) | |
@contractspec/lib.contracts-runtime-server-mcp | MCP runtime adapter (provider-mcp + MCP registrars) |
AI & Evolution
| npm | Package | Description |
|---|---|---|
@contractspec/lib.ai-agent | AI agent orchestration with contract governance | |
@contractspec/module.ai-chat | Reusable AI chat system | |
@contractspec/lib.evolution | Auto-evolution and safe regeneration |
Runtime, MCP & Evaluation
| npm | Package | Description |
|---|---|---|
@contractspec/lib.harness | Harness orchestration, evidence, policy, replay, and evaluation runtime | |
@contractspec/integration.harness-runtime | Runtime adapters for browser, sandbox, artifact, and MCP-backed harness targets | |
@contractspec/module.provider-ranking | Ranking pipelines, storage, and orchestration for provider benchmark data | |
@contractspec/app.provider-ranking-mcp | MCP server for ranking ingest, refresh, leaderboards, and model-profile queries |
Testing & Quality
| npm | Package | Description |
|---|---|---|
@contractspec/lib.testing | Golden tests for safe regeneration verification | |
@contractspec/lib.observability | Tracing, metrics, and structured logging |
Legacy Package
| npm | Package | Description |
|---|---|---|
@contractspec/lib.contracts (deprecated) | Deprecated monolith kept as migration marker; use split packages above |
Who It's For
AI-Native Startups & Technical Founders
- Using Cursor, Copilot, Claude, or AI agents heavily
- Messy AI-generated backends, inconsistent APIs
- Need to stabilize without rewriting
Small Teams with AI-Generated Chaos
- Shipped fast with AI, now have tech debt
- Multiple surfaces out of sync
- Need incremental stabilization
AI Dev Agencies
- Building many projects for clients
- Need reusable templates and consistent quality
- Need professional handoff artifacts
Learn More
License
MIT
