@specverse/engines

The SpecVerse toolchain — parser, inference, realize, generators, AI, registry, and bundles, exposed as subpath imports. This is the package that turns a .specly specification into a complete application.

Purpose

SpecVerse is a declarative specification language: write a .specly file describing what a system does, and the engine generates the implementation. @specverse/engines is the engine. It runs the three-stage pipeline:

.specly file (WHAT)
    │
    ▼  ./parser        →  SpecVerseAST
    │
    ▼  ./inference     →  full architecture (controllers / services / events / views / deployments)
    │
    ▼  ./realize       →  generated code (Fastify / Prisma / React / CLI / tools / diagrams)

Most users never import this directly — they use the @specverse/self CLI (spv), which orchestrates these engines. Import @specverse/engines when you want the toolchain programmatically (build a custom pipeline, embed realize in a service, drive analysis of an existing codebase).

Installation

npm install @specverse/engines

Requires Node 20+. Pulls in its sibling engine packages (@specverse/types, @specverse/entities, @specverse/runtime, @specverse/assets) automatically.

Subpath Exports

The toolchain is split into focused entry points — import only what you need:

| Subpath | Purpose | |---|---| | @specverse/engines/parser | Parse + schema-validate a .specly file → SpecVerseAST | | @specverse/engines/inference | Expand a minimal spec into the full architecture | | @specverse/engines/analyse-prepass | Structural extraction from an existing codebase (the analyse prepass — facts + adapters) | | @specverse/engines/realize | Generate code from a realized spec + manifest | | @specverse/engines/realize/post-emit-verify | Post-emit verification of generated output | | @specverse/engines/normalise | Spec normalisation utilities | | @specverse/engines/generators | Diagram + artifact generators (Mermaid, etc.) | | @specverse/engines/ai | LLM-backed behaviour/analyse services (provider-agnostic) | | @specverse/engines/registry | Engine discovery / EngineRegistry | | @specverse/engines/bundles | Composed entity-module bundles + catalog |

Usage

import { parseSpecVerse } from '@specverse/engines/parser';
import { runInference } from '@specverse/engines/inference';
import { realizeAll } from '@specverse/engines/realize';

// 1. WHAT — parse + validate the spec
const ast = await parseSpecVerse(specText);

// 2. infer — expand to the full architecture
const inferred = await runInference(ast);

// 3. realize — generate the implementation
await realizeAll(inferred, { manifestPath, outDir });

(Exact entry-point signatures live in each subpath's .d.ts. The @specverse/self CLI is the reference consumer of these calls.)

Manifest controls technology, spec controls logic

The spec describes WHAT; a manifest + instance factories describe HOW. Swap Fastify for another framework, or SQLite for Postgres, in the manifest — the spec doesn't change. The engine ships instance factories (./libs) for controllers, services, ORMs, applications, CLIs, communication, and infrastructure.

Related packages

| Package | Role | |---|---| | @specverse/self | The spv CLI + templates — the way most people use the engine | | @specverse/types | Shared AST types + engine interfaces | | @specverse/entities | Entity modules + schema composition | | @specverse/runtime | Runtime view walker + React/Tailwind adapters |

Docs: docs.specverse.org · Source: github.com/SpecVerse/specverse-engines

License

Source-available under the PolyForm Noncommercial License 1.0.0 — free for non-commercial use. Commercial use (including consulting and client engagements) requires a commercial licence — contact [email protected]. Code generated by the toolchain (your realized application) is yours, under your own terms.

Copyright © 2025–2026 Nicholas J W Caine.