vibeX skill

---
name: vibex
description: 'Diagrams and checkable docs from a codebase. Draws ERDs, C4 context/container/component views, API endpoint catalogues, lifecycle/state machines, sequence diagrams, and service-to-service call maps as a validated JSON spec plus a standalone HTML viewer, with Mermaid export. Imports OpenAPI, GraphQL SDL and Prisma; otherwise reads the code (NestJS, TypeORM, Express) and writes the spec. Use for: database diagram, ERD, data model, table relationships, C4 or architecture diagram, system context, API map, endpoint list, "show me the endpoints", status flow, state machine, allowed transitions, "what happens after X is approved", sequence diagram, request flow, how services call each other, microservice map, Mermaid diagram. Also writes documentation as a fact graph: each statement carries its source and a computed confidence, and a drift check fails CI when the code moves. Use to document a system, write architecture or onboarding docs, or explain how a system works.'
license: MIT
metadata:
  version: "0.8.1"
  cli: node bin/vibex.mjs
  repository: https://github.com/Raja0sama/vibex
---

# vibeX

*You vibed it into existence. vibeX shows you what you actually built.*

Output is always two files: `<name>.<type>.json` (the spec, the source of truth) and `<name>.<type>.html` (self-contained viewer: pan/zoom, search, click-for-details, dark/light, SVG/PNG export). Not fancy. Correct and readable.

Skill root: the directory containing this file. Every command below is `node <skill-root>/bin/vibex.mjs …`.

## Steps

1. **Pick the type** from the ask. One diagram per type per question; do not mix.

   | Ask | Type | Spec file |
   |---|---|---|
   | tables, models, schema, relations, FKs, data model | `erd` | `schemas/erd.schema.json` |
   | context, containers, components, who talks to what, system boundary | `c4` | `schemas/c4.schema.json` |
   | endpoints, routes, API surface, GraphQL operations, events/topics | `endpoints` | `schemas/endpoints.schema.json` |
   | statuses, state machine, lifecycle, what happens after X, allowed transitions | `lifecycle` | `schemas/lifecycle.schema.json` |
   | sequence diagram, request flow, what happens when the user clicks X, who calls whom and in what order | `sequence` | `schemas/sequence.schema.json` |

2. **Find a machine-readable source first.** Search the repo before reading code:
   - `endpoints`: `openapi.*`, `swagger.*`, `*.graphql`, `schema.gql`, or a generated schema endpoint dump. Run `import openapi` or `import graphql`.
   - `erd`: `schema.prisma` → `import prisma`. A GraphQL SDL can also seed an ERD with `import graphql <file> out.json --erd`.
   - `c4`: never importable. Author it (step 3).

   ```bash
   node bin/vibex.mjs import openapi  path/to/openapi.yaml  out/api.endpoints.json
   node bin/vibex.mjs import graphql  path/to/schema.graphql out/api.endpoints.json
   node bin/vibex.mjs import prisma   prisma/schema.prisma   out/db.erd.json
   ```

   After an import, open the JSON and edit it like a human would: rename groups, drop noise endpoints (health, metrics), add `entities` links on endpoints, add `sources`. The import is a starting point, not the deliverable.

3. **No source file? Dig in the code.** Read the schema file for your type once, then read one example in `examples/`. Author the JSON fresh. Where to look:
   - **NestJS REST**: `@Controller('prefix')` + `@Get/@Post/@Put/@Patch/@Delete('path')` → one endpoint each, path = prefix + path with `:id` rewritten as `{id}`. `@UseGuards(...)`/`@Roles(...)` → `auth`. `@Body()` DTO class → `request`. Return type / `@ApiOkResponse` → `response`. One group per controller. Put `sources: [{path, line}]` on every endpoint pointing at the handler method. Prepend `app.setGlobalPrefix()` and `@Version()`/`VersioningType.URI` segments to every path. `@Param()` → `params[].in: "path"`, `@Query()` → `"query"`, `@Headers()` → `"header"`; a DTO class in `@Query()` becomes one param per property.
   - **NestJS GraphQL**: `@Query()`, `@Mutation()`, `@Subscription()` in `*.resolver.ts` → method QUERY/MUTATION/SUBSCRIPTION, path = `name(arg: Type)`. `@ObjectType`/`@InputType` classes → `types`.
   - **Express/Fastify**: `router.get('/x', …)`, `app.post(...)`, `fastify.route({method, url})`.
   - **TypeORM**: `@Entity('table')` classes; `@PrimaryGeneratedColumn`/`@PrimaryColumn` → `pk`; `@Column({nullable, unique, type})`; `@ManyToOne` + `@JoinColumn` → FK on this side, relationship `from` this entity `to` target with `from_cardinality: many`; `@OneToOne` → `one`/`zero-or-one`; `@ManyToMany` + `@JoinTable` → a join entity or a many↔many relationship.
   - **Prisma**: prefer the importer. The importer already fills `sources` (path + model line); add `description` and `groups` by hand. It names entities by the lowercased model name (`OrderItem` → `orderitem`; `@@map` only changes the label).
   - **SQL migrations**: `CREATE TABLE`, `REFERENCES`, `PRIMARY KEY`, `UNIQUE`.