tieline

tieline

Static frontend↔backend contract-drift checker. Pact without writing a single contract test.

tieline reads the code you already wrote on both sides of an API boundary — the HTTP calls your frontend makes and the routes your backend exposes — and tells you where they disagree. No contract tests to author, no broker to run, no backend to boot. It finishes in well under a second and is built to run in CI as a gate.

Delete the LLM and a developer still installs it. tieline is a deterministic

tool first; an agent reading its output is a bonus.

---

How it works

  frontend code                                  backend code

(axios, rtk-query, …) (express, nestjs, openapi, …) │ │ client adapter server adapter │ normalize ${id} :id {id} → {} │ └───────────────► join on (METHOD, path) ◄──────┘ │ ✅ matched ❌ drift ⚠️ unverifiable 🟡 dead

Both sides are reduced to a canonical (METHOD, path) and joined. The matcher is adapter-agnostic — any client adapter pairs with any server adapter, so the same engine checks a React app against Express, an Angular app against Spring, or anything against an OpenAPI spec.

---

tieline vs alternatives

These tools solve neighbouring problems — pick by what you have and what you want guaranteed.

They compose: tieline catches FE↔BE drift statically in every PR, tieline doctor keeps code↔spec honest, and a runtime tool like Pact or Schemathesis can guard the payload/behaviour layer underneath.

---

Quick start

Install (or run with npx):

npm install -g @nugehs/tieline

or, from a clone: git clone … && cd tieline && npm link

Generate a tieline.config.json — init sniffs the surrounding directories (cwd, its children, and its siblings) for known stacks and writes a ready-to-run config:

tieline init

  tieline · init

scanning ~/code for repos… ✔ client: rtk-query → web (roots: src/redux/apis) ✔ server: nestjs → api (roots: src)

📝 wrote tieline.config.json

It detects adapters from package.json deps (@reduxjs/toolkit, axios, @angular/core, @nestjs/core, express, fastify, next), requirements.txt / pyproject.toml (fastapi, flask), pom.xml / build.gradle (spring), and any OpenAPI doc as a fallback. Anything it can't detect is written as a placeholder for you to edit. The file is always overwritten, so re-run it whenever your layout changes.

Or write it by hand — at the root of (or above) your repos:

{

"client": { "adapter": "rtk-query", "repo": "../web", "roots": ["src/redux/apis"], "basePath": "/api/v1" }, "server": { "adapter": "nestjs", "repo": "../api", "roots": ["src"], "globalPrefix": "api/v1" }, "failOn": ["drift"] }

Run it:

tieline check

  tieline · contract check

❌ 2 drift (FE calls a route the backend does not expose) GET /users/{} getUser · web/src/redux/apis/user-api.ts:42 → did you mean "user/{}"? # plural vs singular — a guaranteed 404 PUT /orders/{} updateOrder · web/src/redux/apis/order-api.ts:88 → path exists but as GET, not PUT # method mismatch

✅ 274 matched ❌ 2 drift ⚠️ 6 unverifiable 🟡 31 unused backend routes

check exits non-zero when any failOn bucket is non-empty — drop it into CI and the build fails the moment the two sides disagree.

---

Commands

tieline init       # auto-detect nearby repos and write tieline.config.json

tieline check # FE↔BE drift; exits non-zero on drift (the CI gate) tieline list # the full resolved contract map (every endpoint + status) tieline orphans # backend routes no frontend call reaches tieline doctor # code↔spec drift (see below)

---

Supported stacks

Any client adapter pairs with any server adapter — the matcher never changes.

That covers MERN (rtk/axios ↔ express), MEAN (angular ↔ express), MEVN (axios ↔ express), Next full-stack, Python (fastapi/flask), and enterprise (angular ↔ spring) — plus openapi for any backend that emits a spec (Express+swagger-jsdoc, FastAPI, Spring springdoc, .NET Swashbuckle, …).

Notes:

• `express` walks the app.use() mount graph across require/import boundaries and nested routers; routers it can't reach are flagged, never dropped.
• `next` is file-system routing — app-router files export GET/POST/…; pages-router handlers serve any verb (matched as ALL).
• Runtime-built urls (e.g. `users/${id}?x=${q}` ) are surfaced as unverifiable rather than guessed.

---

Configuration

tieline.config.json — repo paths resolve relative to the config file.

{

"client": { "adapter": "rtk-query", // rtk-query | axios-fetch | angular-http "repo": "../web", "roots": ["src/redux/apis"], // dirs to scan for call sites "basePath": "/api/v1" // stripped from call sites before matching }, "server": { "adapter": "nestjs", // nestjs | express | fastify | next | fastapi | flask | spring | openapi "repo": "../api", "roots": ["src"], "globalPrefix": "api/v1", // stripped from routes before matching "spec": "openapi.json" // openapi adapter & doctor only — file path or URL }, "ignore": ["internal/.*"], // regexes on the normalized path "failOn": ["drift"] // buckets that make check exit non-zero }

---

Visual report

tieline check --html report.html writes one self-contained file (inline CSS/JS, no external assets) you can open in any browser or attach to a PR:

• a contract-flow diagram — frontend resources on the left, backend on the right, curved links coloured green (matched) / red (drift), with a ∅ no route node catching calls that land nowhere; hover a resource to highlight its links
• a health ring, summary cards, and live-filterable drift / unverifiable / unused tables

---

tieline doctor — does your code match your published docs?

doctor diffs routes parsed from source (a native adapter like nestjs) against the routes declared in your OpenAPI spec (server.spec):

  tieline · doctor   code (nestjs)  ↔  spec (http://localhost:9999/doc-json)

❌ 4 undocumented (in code, missing from the published spec) GET /billing/invoices src/billing/billing.controller.ts:54 POST /webhooks/stripe src/webhooks/webhooks.controller.ts:21 ... 👻 1 phantom (in the spec, no matching route in code)

✅ 312 agree ❌ 4 undocumented 👻 1 phantom (316 code routes, 313 spec routes)

• undocumented — working routes invisible to anyone generating an SDK or partner integration from the spec.
• phantom — the spec promises a route the code no longer serves (stale docs).

Run it alongside check and your spec can never silently drift from your code.

---

Use as an MCP server

tieline ships an MCP server so an agent can ask "do these two repos still agree?" and get the same structured result the CLI produces — no LLM does the analysis, the deterministic engine does. It's still zero-dependency: the server is hand-rolled stdio JSON-RPC, no SDK.

Register it with any MCP client (Claude Code, Claude Desktop, …):

{

"mcpServers": { "tieline": { "command": "npx", "args": ["-y", "-p", "@nugehs/tieline", "tieline-mcp"] } } }

Or, from a global install (npm i -g @nugehs/tieline), just "command": "tieline-mcp".

It exposes five tools, each returning JSON:

config defaults to searching upward from the server's working directory, exactly like the CLI — so an agent dropped into a repo with a tieline.config.json can just