Wesley

Note

Wesley is pre-alpha. It does work, but it's somewhere between MVP and alpha.
Just being real: probably don't want to use this in prod until at least beta. Star the repo, watch for updates! It's under active development. - flyingrobots

The data layer compiler that turns GraphQL schemas into production-ready PostgreSQL—with zero-downtime migrations, comprehensive tests, and cryptographic deployment proofs.

Wesley inverts the entire database development paradigm. While everyone else generates GraphQL from databases, Wesley generates a battle-tested PostgreSQL backend from GraphQL—along with TypeScript types, Zod schemas, Row-Level Security (RLS) policies, comprehensive tests, and SHA-locked deployment certificates. All from a single source of truth.

Stop maintaining schemas in 5 places. Start shipping with confidence.

type Document @wes_table @wes_tenant(by: "org_id") @wes_rls(enabled: true) {
  id: ID! @wes_pk
  title: String!
  org_id: ID! @wes_fk(ref: "Org.id")
  created_by: ID! @wes_fk(ref: "User.id")
}

TL;DR – Getting Started

Goal	Command(s)	Notes
Install tooling & sanity-check repo	`pnpm install` `pnpm run bootstrap`	Bootstraps dependencies, runs preflight, executes workspace tests.
Generate everything from the example schema	`node packages/wesley-host-node/bin/wesley.mjs generate --schema test/fixtures/examples/schema.graphql --ops test/fixtures/examples/ops --emit-bundle --out-dir out/examples`	Produces SQL, pgTAP, ops SQL, and a `.wesley/` evidence bundle.
Preview migration plan & rehearsal	`node packages/wesley-host-node/bin/wesley.mjs plan --schema test/fixtures/examples/schema.graphql --explain` `node packages/wesley-host-node/bin/wesley.mjs rehearse --schema test/fixtures/examples/schema.graphql --dry-run --json`	No database required for `--dry-run`; inspect JSON for lock levels and REALM verdicts.
Run HOLMES evidence checks	`pnpm --filter @wesley/holmes exec node packages/wesley-host-node/bin/wesley.mjs generate --schema test/fixtures/examples/schema.graphql --emit-bundle --out-dir out/examples` `pnpm --filter @wesley/holmes exec node packages/wesley-holmes/src/cli.mjs investigate --json holmes.json > holmes.md`	Generates scores + markdown report; see Evidence, HOLMES, and Observability.
Experience the Daywalker (BLADE) demo	`node packages/wesley-host-node/bin/wesley.mjs blade --schema test/fixtures/blade/schema-v2.graphql --out-dir out/blade --dry-run`	Uses curated fixtures to demonstrate the zero-downtime flow end-to-end.
Dive into docs/tests/scripts	`docs/README.md`, `scripts/README.md`, `test/README.md`	Each guide explains prerequisites, commands, and fixture usage.

What You Get

When you run wesley generate, it outputs a complete, ready-to-deploy data layer:

✓ migrations/
  ├─ 001_expand.sql      # Online DDL (CONCURRENTLY, NOT VALID)
  ├─ 001_backfill.sql    # Idempotent data transformations
  └─ 001_contract.sql    # Cleanup phase
✓ types/generated.ts     # TypeScript interfaces
✓ schemas/zod.ts         # Runtime validation
✓ policies/rls.sql       # Row-level security + helpers
✓ tests/                 # pgTAP suites
  ├─ structure/          # Table, column, constraint tests
  ├─ rls/                # Policy enforcement tests
  └─ plan/               # Migration plan validation
✓ certs/
  └─ deploy-<sha>.json   # Cryptographic deployment proof

flowchart LR
    subgraph YOU["You Write"]
      GQL["📝 GraphQL Schema<br/><small>schema.graphql</small>"]
    end

    subgraph WES["Wesley Generates"]
      IR["🧠 Wesley IR"]
      SQL["🗄️ Postgres DDL<br/><small>+ phased migrations</small>"]
      TS["📘 TypeScript<br/><small>+ Zod</small>"]
      RLS["🔒 RLS Policies<br/><small>+ helpers</small>"]
      TEST["✅ pgTAP Suite<br/><small>structure/constraints/RLS/plan</small>"]
      CERT["🔏 SHA-Locked Cert<br/><small>proofs & hashes</small>"]
    end

    subgraph PLAN["Zero-Downtime Plan"]
      EXP[Expand]
      BKG[Backfill]
      VAL[Validate]
      SWT[Switch]
      CTR[Contract]
    end

    subgraph PROD["You Deploy"]
      DEP["🚀 Production"]
    end

    GQL -->|"wesley generate"| IR
    IR --> SQL
    IR --> TS
    IR --> RLS
    IR --> TEST
    IR --> CERT

    SQL --> EXP --> BKG --> VAL --> SWT --> CTR -->|"wesley deploy"| DEP

    classDef p1 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    classDef p2 fill:#fff3e0,stroke:#ff9800
    classDef p3 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    class GQL p1
    class SQL,TS,RLS,TEST,CERT p2
    class DEP p3

Quick Start

git clone https://github.com/flyingrobots/wesley.git
cd wesley
pnpm install

# Explore the CLI via the workspace script
pnpm wesley --help

# Generate everything from your GraphQL schema
pnpm wesley generate --schema schema.graphql

# Deploy to production (with zero-downtime planning)
pnpm wesley deploy

Try the Examples

# Generate everything for the example schema
node packages/wesley-host-node/bin/wesley.mjs generate \
  --schema test/fixtures/examples/schema.graphql \
  --ops test/fixtures/examples/ops \
  --emit-bundle \
  --out-dir out/examples

# Preview migration plan (no database required)
node packages/wesley-host-node/bin/wesley.mjs plan \
  --schema test/fixtures/examples/schema.graphql \
  --explain

# Validate the entire repository
pnpm run bootstrap   # install deps → preflight → test

Key Features

Wesley is engineered for safety, speed, and confidence.

🔒 Safety First

Zero-downtime DDL: All operations automatically use CONCURRENTLY and NOT VALID patterns.
Phased Migration Protocol: Implements the battle-tested Expand → Backfill → Validate → Switch → Contract strategy.
Advisory Locks: Automated locking prevents concurrent migration disasters.
Lock-Aware Planning: The DDL planner rewrites SQL operations to minimize lock impact.
Drift Detection: Runtime validation catches schema mismatches before damage occurs.

🔄 Comprehensive Testing & Validation

pgTAP Suites: Generates PostgreSQL-native tests for structure, constraints, RLS enforcement, and migration logic.
Property-Based Testing: Uses fast-check to prove the DDL planner's correctness.
Round-Trip Validation: Guarantees schema preservation: GraphQL → SQL → GraphQL.
Idempotence Checks: All generated operations are safe to retry.

📊 ### Observability & Proofs (SHA-lock HOLMES)

SHA-Locked Certificates: Provides an immutable, auditable record of the deployed state.
Explain Mode: Shows the precise lock levels for every operation in the migration plan.
HOLMES Scoring: An evidence-based confidence system that produces SCS/TCI/MRI metrics (Schema Coverage, Test Confidence, Migration Risk) for deployment readiness.
Dead Column Detection: Tools to find and flag unused database columns for safe cleanup.

Evidence, HOLMES, and Observability

EvidenceMap is the authoritative mapping between schema elements and generated artifacts. Generators record evidence under stable UIDs:
- Tables: tbl:TableName
- Columns: col:TableName.columnName
SQL comments like COMMENT ON COLUMN … IS 'uid: …' are human-readable hints. Tooling (SourceMap, scoring, HOLMES) reads from EvidenceMap, not from the comment strings.
To surface a SQL error in the original GraphQL SDL, load the evidence bundle (.wesley/bundle.json) and call findSourceForSql(evidenceMap, { file, line }).
Scores (SCS/TCI/MRI) are computed from EvidenceMap; ensure generators record artifacts to keep scores accurate.

Example: map a SQL error back to SDL

import fs from 'node:fs/promises';
import { EvidenceMap } from '@wesley/core';
// Temporary deep import until re-exported at package root
import { findSourceForSql } from '@wesley/core/src/application/SourceMap.mjs';

// Load the bundle written by `wesley generate --emit-bundle`
const raw = await fs.readFile('.wesley/bundle.json', 'utf8');
const bundle = JSON.parse(raw);

// Evidence payload may be nested; normalize it
const payload = bundle?.evidence?.evidence ? bundle.evidence : bundle;
const ev = EvidenceMap.fromJSON(payload);

// If a failure mentions out/schema.sql:123
const mapped = findSourceForSql(ev, { file: 'out/schema.sql', line: 123 });
if (mapped?.source) {
  console.log(`SDL: ${mapped.source.file} lines ${mapped.source.lines} (uid ${mapped.uid})`);
}

Comparison

	Hand-written	ORMs	Wesley
Source of truth	❌ Many files	❌ Code-first	✅ GraphQL schema
Zero-downtime	❌ Manual	❌ Table locks risk	✅ Planned by default
RLS generation	❌ Manual SQL	❌ Limited	✅ Automated + tests
Drift detection	❌ Ad-hoc	❌ Partial	✅ Enforced
Test coverage	❌ Rare	❌ App-only	✅ pgTAP suites
Proof of safety	❌ None	❌ None	✅ SHA-locked certs

Example: Schema Evolution

Define your schema (v1):

type User @wes_table @wes_rls(enabled: true) {
  id: ID! @wes_pk
  email: String! @wes_unique
}

Evolve your schema (v2):

type User @wes_table @wes_rls(enabled: true) {
  id: ID! @wes_pk
  email: String! @wes_unique
  posts: [Post!]! @wes_hasMany  # New relationship
}

type Post @wes_table @wes_rls(enabled: true) {
  id: ID! @wes_pk
  title: String!
  author_id: ID! @wes_fk(ref: "User.id")
  published: Boolean! @wes_default(value: "false")
}

Generate and deploy:

wesley generate                  # Generates migrations, types, policies, tests
wesley plan                      # Shows lock-aware migration plan
wesley rehearse                  # Tests on shadow database
wesley certify                   # Creates SHA-locked proof
wesley deploy                    # Applies to production

The Deployment Process:

Wesley ensures a safe, zero-downtime deployment by automatically creating:

The new posts table with the foreign key and RLS policies.
All required TypeScript types and Zod schemas.
All pgTAP tests to validate the new structure and security.

Advanced Features

Experimental: Query IR (QIR)

Wesley includes an experimental Query Intermediate Representation pipeline that compiles GraphQL operations into deterministic, optimized SQL.

The QIR pipeline translates queries, mutations, and subscriptions, then emits optimized PostgreSQL and generates pgTAP tests for operation contracts. See the documentation for details.

wesley generate \
  --schema schema.graphql \
  --ops ./operations \
  --emit-bundle

See docs/guides/qir-ops.md for details.

SHA-locked HOLMES: Evidence-Based Deployments

The HOLMES (Heuristic for Observable Logic, Metrics, and Evidence System) toolkit inspects Wesley's evidence bundles (.wesley/) to produce an objective, machine-readable score for deployment readiness.

# Investigate deployment readiness
holmes investigate --bundle .wesley/

# Verify against previous deployment
watson verify --current .wesley/ --baseline .wesley/previous/

# Predict migration impact
moriarty predict --bundle .wesley/

This system allows you to define a minimum confidence score before a deploy can proceed.
The certificate is generates is SHA-locked to the commit it ran against.

See packages/wesley-holmes/README.md for the complete guide.

Documentation

📚 Getting Started

Documentation Hub — Philosophy, architecture, and manifesto
Quick Start Guide — Get running in 60 seconds
Migration Strategies — Schema evolution patterns
Query Operations (QIR) — Experimental operation pipeline

🏗️ Architecture

The Paradigm Shift — Why GraphQL is your source of truth
Architecture Overview — Hexagonal, event-driven design
The Algorithm — How GraphQL becomes SQL
Delivery Lifecycle — Transform → Plan → Rehearse → Ship
HOLMES Integration — Evidence bundles and scoring

🔧 Implementation

Internals Deep Dive — How Wesley works under the hood
Event Flow — Tracing events through the system
Parser Design — GraphQL SDL to domain model

📦 Packages

@wesley/cli — Command-line interface
@wesley/core — Pure domain logic (directive registry, IR, SQL emission)
@wesley/host-node — Node.js adapters and binary entrypoint
@wesley/generator-js — JavaScript/TypeScript/Zod emitters
@wesley/generator-supabase — Supabase-specific generators
@wesley/holmes — SHA-lock investigations and scoring
@wesley/tasks — Task orchestration primitives
@wesley/slaps — Lock-aware scheduling utilities

🧪 Testing & Fixtures

test/ — Integration and E2E test suites
schemas/ — Canonical GraphQL schemas
test/fixtures/reference/ — Comprehensive SDL for experiments and future tests

🛠️ Development

Scripts Reference — Complete pnpm run commands guide
scripts/ — Maintenance and automation scripts
Roadmap — Current focus and upcoming milestones
SAGENTS Codex — Protocol for human and AI contributors

🎬 Demos

BLADE (Daywalker Deploys) — 5-minute demo of the full pipeline

Workspace Organization

Wesley is a monorepo managed with pnpm workspaces:

wesley/
├── packages/           # Core packages
│   ├── wesley-cli/     # Command-line interface
│   ├── wesley-core/    # Pure domain logic
│   ├── wesley-holmes/  # Evidence scoring
│   └── ...
├── docs/              # Documentation
├── test/              # Integration tests
│   └── fixtures/      # Canonical test inputs
├── schemas/           # Reference schemas
├── scripts/           # Automation tools
└── .wesley/           # Build artifacts (gitignored)
    ├── snapshot.json  # IR snapshot for diffs
    ├── realm.json     # Rehearsal verdicts
    └── SHIPME.md      # Deployment certificate

Working with Packages

# Run tests for specific package
pnpm --filter @wesley/core test
pnpm --filter @wesley/cli test

# Full system validation
pnpm run bootstrap

# Watch mode during development
wesley watch --schema schema.graphql

Configuration

Environment Variables

Copy .env.example to .env:

# Logging
WESLEY_LOG_LEVEL=info              # trace|debug|info|warn|error|silent

# Git integration
WESLEY_GIT_POLICY=emit             # emit|strict|off

# Schema limits
WESLEY_MAX_SCHEMA_BYTES=5242880    # 5MB default

# Database connections
SUPABASE_DB_URL=postgresql://...
WESLEY_TEST_DSN=postgresql://...

DSN Quick Reference

--dsn flag wins for all commands
With --provider supabase, falls back to SUPABASE_DB_URL/SUPABASE_POSTGRES_URL
Otherwise, uses local default: postgres://wesley:wesley_test@localhost:5432/wesley_test

Compatibility

Node.js: 18.x, 20.x, 22.x (CI uses Node 20 LTS)
Package manager: pnpm 9 (workspace pinned)
CI runners: Ubuntu (macOS removed to control costs)
Development: Works on macOS/Windows, but CI targets Ubuntu

FAQ

Q: What if I need custom SQL?
Use @custom blocks. Wesley will test them and preserve them across generations.

Q: Can I bring an existing database?
Yes—introspect to a starting GraphQL schema, then let Wesley own future diffs.

Q: What about breaking changes?
Detected and flagged. Wesley prefers backward-compatible plans; explicit approval required for breaking steps.

Q: How does Wesley compare to Prisma?
Prisma focuses on queries. Wesley compiles the entire data layer (DDL, migrations, RLS, tests, proofs).

Q: Can I use Wesley with [framework]?
Yes! Wesley generates standard SQL, TypeScript, and Zod schemas that work with any framework. Dedicated integrations for Next.js/Remix/SvelteKit are on the roadmap.

Contributing

Wesley follows the SAGENTS Codex for contribution guidelines. Whether you're human or machine:

Obey repository rules — Every rule was written for a reason
Respect .llmignore — It guards focus from noise
Log your work — Append to the Chronicles, never alter history
Test thoroughly — Run pnpm run bootstrap before submitting
Read AGENTS.md — Guide for AI Agents

See the roadmap for current priorities and the Wesley Project Board for active work.

The Future

Wesley is just the beginning. The roadmap includes:

Visual Schema Editor — Design schemas visually
Multi-Database Support — MySQL, SQLite, and more
Framework Integration — First-class Next.js, Remix, SvelteKit plugins
Time-Travel Debugging — Replay schema evolution
AI-Powered Optimization — Let AI suggest schema improvements

Philosophy

"Things are only impossible until they're not." — Jean-Luc Picard

Wesley is named after Wesley Crusher, the brilliant ensign who saw possibilities others couldn't. Like his namesake, Wesley (the tool) transcends conventional thinking to solve problems in ways that seem obvious only in hindsight.

The revolution is declaring GraphQL as the single source of truth.
The innovation is making that actually work.
The magic is making it boring.

Wesley — The Data Layer Compiler

Stop playing schema telephone.
Start shipping with confidence.
Make it so. 🖖

Links

Website: https://flyingrobots.github.io/wesley/
GitHub: https://github.com/flyingrobots/wesley
Issues: https://github.com/flyingrobots/wesley/issues
Project Board: https://github.com/users/flyingrobots/projects/5

Name		Name	Last commit message	Last commit date
Latest commit History 518 Commits
.devcontainer		.devcontainer
.githooks		.githooks
.github		.github
docs		docs
meta		meta
packages		packages
schemas		schemas
scripts		scripts
test		test
wesley-website		wesley-website
.dependency-cruiser.mjs		.dependency-cruiser.mjs
.editorconfig		.editorconfig
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.llmignore		.llmignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CHRONICLES_OF_THE_MACHINE-KIND_VOL_00000001.jsonl		CHRONICLES_OF_THE_MACHINE-KIND_VOL_00000001.jsonl
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
mkdocs.yml		mkdocs.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
requirements-docs.txt		requirements-docs.txt
wesley.config.mjs		wesley.config.mjs

License

flyingrobots/wesley

Folders and files

Latest commit

History

Repository files navigation

Wesley

TL;DR – Getting Started

Table of Contents

Why Wesley Exists

The Wesley Philosophy

What You Get

Quick Start

Try the Examples

Key Features

🔒 Safety First

🔄 Comprehensive Testing & Validation

📊 ### Observability & Proofs (SHA-lock HOLMES)

Evidence, HOLMES, and Observability

Comparison

Example: Schema Evolution

Define your schema (v1):

Evolve your schema (v2):

Generate and deploy:

The Deployment Process:

Advanced Features

Experimental: Query IR (QIR)

SHA-locked HOLMES: Evidence-Based Deployments

Documentation

📚 Getting Started

🏗️ Architecture

🔧 Implementation

📦 Packages

🧪 Testing & Fixtures

🛠️ Development

🎬 Demos

Workspace Organization

Working with Packages

Configuration

Environment Variables

DSN Quick Reference

Compatibility

FAQ

Contributing

The Future

Philosophy

Wesley — The Data Layer Compiler

Links

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Uh oh!

Languages

Packages