@typerion/cli

Typerion

Coherence infrastructure for the AI era.

Two ways to see the paradigm — choose what fits your situation :

Greenfield — one .tp source becomes every layer your system needs :

npx @typerion/cli init
npx @typerion/cli build schema.tp --target ts          # TypeScript types
npx @typerion/cli build schema.tp --target openapi     # OpenAPI 3.1 spec
npx @typerion/cli build schema.tp --target jsonschema  # JSON Schema (draft 2020-12)

Three commands, three projections, one shared fingerprint. Open the generated files side-by-side : they are the same fact, projected three ways.

Brownfield — point Typerion at an existing TypeScript repo :

npx @typerion/cli scan --dry-run           # inspect what would be sent (no account)
npx @typerion/cli login                    # device-code OAuth, free sandbox tier
npx @typerion/cli scan                     # detect cohort divergences (auto-detects first run vs re-scan)
npx @typerion/cli explain H001             # decision card : SUMMARY · WHY · IMPACT · INTENT · 4 ACTIONS
npx @typerion/cli list                     # triage open / accepted / clustered divergences
npx @typerion/cli intents                  # cross-layer Intent Graph clusters (≥ 3 layers)
npx @typerion/cli accept H001 --reason "…" # record a deliberate outlier
npx @typerion/cli history trend            # snapshot timeline across re-scans
npx @typerion/cli pr-comment               # GitHub-flavored markdown for PR-native UX

Walks your repo, groups structurally-similar files into cohorts, surfaces files that break the cohort's dominant pattern. Source code never leaves your machine — only file paths + boolean facts are sent to the server.

No install. No sudo. No PATH surgery. npx fetches the latest version on each run.

---

What this edition is

A minimal, deliberate proof that the coherence paradigm is real, in two complementary modes :

Greenfield — one .tp source becomes every layer your system needs :

• A .tp source file is the single contractual statement of your domain.
• Every projection (types, API spec, schema) is derived from that source.
• Changing the source changes all projections deterministically.

Brownfield — point Typerion at an existing repo, it learns the contracts :

• typerion scan walks your repo, groups structurally-similar files into cohorts, and detects three kinds of divergence : drift (minority pattern at a facet), redundancy (low semantic_density), intent legitimacy (is_at_package_boundary etc. — so legitimate barrels and facades aren't reported as defects). Also extracts lexical event-name and versioned-URL tokens for behavioral and contract-evolution clusters.
• typerion explain <id> shows the decision card : 30-second SUMMARY, WHY this matters, IMPACT (inbound_count blast radius), INTENT CONTEXT (cross-layer clusters touching this file), and four named options — align · accept · isolate · widen. Options are described, never auto-applied.
• typerion intents [signal] lists Intent Graph V1 clusters (default : ≥ 3 layers). Markers ⚡ for events, 📄 for HTTP contracts, identifiers otherwise.
• typerion accept <id> --reason "…" records deliberate outliers.

Doctrine guard : every metric surface carries the line "These metrics describe structural properties. They are observational, not normative quality grades." exactly once per output block. Typerion describes structure ; it never modifies your code.

The brownfield commands require a free account (sandbox tier) for the cohort detection ; the source code never leaves your machine — only file paths + boolean facts are sent to the server. Use --dry-run to inspect exactly what would be sent before signing up.

No magic, no runtime, no framework lock-in.

What this edition is not

Before you change code, Typerion shows what you might break.

Typerion does not sell scans. It does not sell AI adaptation. It does not sell code insights or graph visualization.

It sells safe structural change — the moment-of-action question : "I'm about to touch this system, and I don't want to break 10 invisible things."

This OSS CLI is the acquisition surface — the aha moment where you see what's structurally diverging in your codebase for the first time. The paid tiers are what protect you the next time you act on the system, by answering how a change here propagates everywhere else.

Free — acquisition / aha moment (this OSS package)

You see. You don't yet act safely.

• typerion scan — single-repo, local-walk, sandbox cohort detection (500 files / scan / day cap)
• typerion explain <id> — limited depth (single-divergence)
• typerion intents — limited view (top-N, ≥ 3 layers default)
• typerion list / typerion accept — local triage

Dev Paid — continuous structural safety ($20 / dev / month)

You act, the system warns before you break things invisibly :

• PR check : pr-comment runs in CI and blocks unsafe changes against the team baseline
• CI gating : severity thresholds, coherence-score floors, fail- the-build on regressions
• explain full depth : multi-cluster reasoning across all V1.5 axes (behavioral / contract / security / AI / test / compliance)
• Impact simulation before merge : "if you change this file, here's the cluster ripple"
• Cross-file dependency warnings : "3 files import this and rely on facets that are about to change"
• AI adapter suggestions (preview / limited) — concrete textual alignment proposals, never auto-applied
• history trend / diff — drift across snapshots over time
• Unlimited scans (sandbox cap lifted)

Enterprise — org-wide governance over change

You act org-wide ; the system gates and audits the change :

• Multi-repo cluster correlation (RBAC across services, AI model- routing across products, contract-versioning across teams)
• AI governance overlay — cross-repo ai: cluster supervision + usage policy gates
• Security & compliance policy packs — fire on authz: / compliance: cluster fragmentation org-wide
• Governance audit logs — signed baseline + decision trail
• 270+ codegen targets (Python SDK, Go server, Prisma, Drizzle, etc.)
• Trust modes (observe / verify / selective / enforced)
• AI-workflow adapters (Claude / Cursor / Copilot)

See typerion.io for tier scope.

Why this split

The free CLI gives you the snapshot — you see what's wrong once. The paid tiers give you the gate — the system tells you "don't merge this yet, here's what breaks" every time you act.

CLI = entry point. SaaS = memory + coordination + safety-at-change. The closed-source cohort algorithm runs server-side ; the CLI is a thin client. Forking the client is allowed — the algorithm and the gating stay in the hosted service.

---

Why .tp

Software systems drift by default. Schemas drift from APIs. APIs drift from clients. Clients drift from documentation. Documentation drifts from runtime behavior. AI tools amplify the divergence.

.tp is one file that becomes every layer your system needs. What you change in one source propagates to every projection automatically. Drift becomes structurally impossible — by construction, not by discipline.

That is the paradigm. This package lets you see it.

A note on what gets generated

Each projection is deterministic : the same .tp input always produces byte-identical output. The fingerprint header at the top of every generated file is your guarantee.

If you need that property — across many languages, with structural drift detection and repair — Typerion Pro is where it lives. This OSS edition exists so the paradigm is observable before you decide.

---

Quick example

entity User {
  id    : UUID    @primary
  email : String  @unique
  name  : String
}

entity Post {
  id     : UUID    @primary
  author : User    @ref
  title  : String
  body   : String
}

Save as schema.tp and run :

npx @typerion/cli build schema.tp --target ts
npx @typerion/cli build schema.tp --target openapi
npx @typerion/cli build schema.tp --target jsonschema

You now have three files. They all describe the same thing. The TypeScript types match the OpenAPI request bodies match the JSON Schema validators. They cannot drift, because they are derived from the same source.

That is what coherence-first development means.

---

Brownfield example (existing TypeScript repo)

You don't have to start with a .tp. Point Typerion at any TypeScript project and it learns the contracts your code already follows :

# 1. Inspect what would be sent — no account needed.
npx @typerion/cli scan --dry-run

# 2. Sign up (free), then run for real :
npx @typerion/cli login          # device-code OAuth, opens browser
npx @typerion/cli scan           # first run writes .tp/baseline.json ; re-runs auto-detect

scan walks the repo, groups structurally-similar files into cohorts (e.g. all files in src/stores/*.ts), and surfaces divergences where a small number of files break the cohort's dominant pattern. The runtime auto-detects first-run vs re-scan from the presence of .tp/baseline.json — no flag needed. A real-world run on an 18 k-file marketplace codebase finishes in ~3 s.

Then dig into one :

npx @typerion/cli explain H001
# ═══════ Divergence H001 ═══════
# WHERE       src/stores/shipping.ts
# COHORT      src/stores/*.ts  (6 files)
# FACET       has_try_catch    this : false   dominant : true (83%)
# WHY         5 of 6 store files wrap fetch in try/catch ; shipping.ts
#             does not — consumers handling .error will get an unhandled
#             rejection instead of a structured error.
# DECIDE      align / outlier / widen

If the divergence is deliberate, record it :

npx @typerion/cli accept H001 --reason "shipping has its own retry queue"

The acceptance is persisted in .tp/baseline.json and survives every future scan (matched by cohort × node × facet — re-scans won't re-flag a triaged outlier).

Privacy : the CLI walks your code locally and only sends file paths

• boolean facts to the server. Source code never leaves your machine. Use --dry-run to verify exactly what would be sent.

---

Running Typerion

Typerion is designed to run on demand. npx @typerion/cli <command> is the canonical invocation — it works on a clean machine without installing anything globally, so you never hit EACCES on /usr/local, never need sudo, never need to touch your PATH. Each run pulls the latest published version.

If you invoke Typerion frequently and want a shorter command, install it into a user-owned prefix (one-time setup, applies to every npm global package — not just Typerion) :

npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc
npm install -g @typerion/cli

typerion build schema.tp --target ts

We deliberately don't recommend sudo npm install -g. It leaves root-owned files under /usr/local and the next global package you install will hit the same wall. The user-prefix setup above fixes the class of error once.

---

License

Apache License 2.0. See LICENSE.

This is the OSS edition of Typerion. The full system lives at typerion.io.