@magic-spells/constellation 0.1.0

package/skill/types/datatype.md

@@ -0,0 +1,26 @@
+# DATATYPE cards (`DATATYPE-`, `datatype/`)
+
+No structured fields. The type declaration lives in the body as a fenced code
+block (` ```ts `, ` ```sql `, …) — readable, diffable, and copy-pasteable into code.
+
+Example — `constellation/datatype/DATATYPE-TICKET.md`:
+
+````markdown
+---
+name: Ticket
+status: built
+connections:
+  - DB-TICKETS
+---
+
+The canonical ticket shape, returned by every ticket endpoint.
+
+```ts
+interface Ticket {
+  id: string;
+  subject: string;
+  status: 'open' | 'assigned' | 'resolved' | 'closed';
+  created_at: string; // ISO 8601
+}
+```
+````

package/skill/types/db.md

@@ -0,0 +1,33 @@
+# DB cards (`DB-`, `db/`)
+
+One card per table/collection. Suggested `kind`: `sql-table`, `document-collection`,
+`kv`, `time-series`, `graph`.
+
+| Field | Type | Notes |
+|---|---|---|
+| `table_name` | string | physical name |
+| `columns` | array | `{ name, sql_type?, primary_key?, not_null?, unique?, default? }` |
+| `indexes` | array | `{ name?, columns?, unique? }` |
+| `foreign_keys` | array | `{ columns?, references_table?, references_columns?, on_delete? }` |
+
+Example — `constellation/db/DB-TICKETS.md`:
+
+```markdown
+---
+name: tickets table
+kind: sql-table
+status: built
+table_name: tickets
+columns:
+  - { name: id, sql_type: UUID, primary_key: true, default: gen_random_uuid() }
+  - { name: subject, sql_type: TEXT, not_null: true }
+  - { name: status, sql_type: TEXT, not_null: true, default: "'open'" }
+indexes:
+  - { name: tickets_status_idx, columns: [status] }
+connections:
+  - DATATYPE-TICKET
+---
+
+One row per ticket. `status` values mirror [[STATE-TICKET]]; rows are never
+deleted, only moved to `closed`.
+```

package/skill/types/diagram.md

@@ -0,0 +1,32 @@
+# DIAGRAM cards (`DIAGRAM-`, `diagram/`)
+
+Architecture diagrams, three tiers — always prefer the cheapest that works:
+
+1. **Don't author at all**: node neighborhoods can be rendered from the real
+   connection graph on demand. Only author a diagram for *conceptual* views.
+2. **Mermaid in the body** (the default): use **handles as Mermaid node IDs** so
+   the diagram joins the graph automatically.
+3. **Pinned layout** (rare): structured `nodes`/`edges`/`phases` frontmatter with
+   explicit positions — see `schemas/diagram.json`. Only when layout carries meaning;
+   positions make noisy diffs.
+
+Example — `constellation/diagram/DIAGRAM-SYSTEM-OVERVIEW.md`:
+
+````markdown
+---
+name: System overview
+status: built
+---
+
+# System overview
+
+```mermaid
+flowchart LR
+  PAGE-INBOX --> API-TICKETS
+  API-TICKETS --> DB-TICKETS
+  API-TICKETS --> EVENT-TICKET-CREATED
+  EVENT-TICKET-CREATED --> JOB-AUTO-ASSIGN
+```
+
+Intake is synchronous down the left edge; everything after the event is async.
+````

package/skill/types/doc.md

@@ -0,0 +1,23 @@
+# DOC cards (`DOC-`, `doc/`)
+
+No structured fields — DOC cards are prose. Suggested `kind`: `guide`, `rule`,
+`decision`, `meta`. Decisions (ADRs) get one DOC card each (`kind: decision`),
+never a section in `plan.md`.
+
+Example — `constellation/doc/DOC-TICKET-LIFECYCLE.md`:
+
+```markdown
+---
+name: How tickets move through the system
+kind: guide
+status: built
+---
+
+# Ticket lifecycle
+
+A ticket is born when the public form posts to [[API-TICKETS]] — the whole
+sequence is [[FLOW-CREATE-TICKET]]. From there it walks [[STATE-TICKET]].
+
+Invariant the code must never break: state transitions happen only in the API
+layer. Nothing writes the `status` column directly.
+```

package/skill/types/event.md

@@ -0,0 +1,31 @@
+# EVENT cards (`EVENT-`, `event/`)
+
+One card per domain event. `emitter` and `payload_schema` are handles and connect
+automatically.
+
+| Field | Type | Notes |
+|---|---|---|
+| `emitter` | handle | card that emits this event |
+| `payload_schema` | handle | DATATYPE of the payload |
+| `delivery_semantics` | enum | `at-least-once` \| `at-most-once` \| `exactly-once` |
+| `ordering` | enum | `per-aggregate` \| `total` \| `none` |
+| `idempotency_key_field` | string | payload field consumers dedupe on |
+| `version` | integer | ≥ 1 |
+
+Example — `constellation/event/EVENT-TICKET-CREATED.md`:
+
+```markdown
+---
+name: Ticket created
+status: built
+emitter: API-TICKETS
+payload_schema: DATATYPE-TICKET
+delivery_semantics: at-least-once
+ordering: none
+idempotency_key_field: id
+version: 1
+---
+
+Fired after a ticket row is committed. Consumers must dedupe on the ticket `id`.
+Currently the only consumer is [[JOB-AUTO-ASSIGN]].
+```

package/skill/types/external.md

@@ -0,0 +1,30 @@
+# EXTERNAL cards (`EXTERNAL-`, `external/`)
+
+One card per external service. Suggested `kind`: `saas-vendor`, `cloud-infra`,
+`external-microservice`, `hardware-peripheral`.
+
+| Field | Type | Notes |
+|---|---|---|
+| `vendor` | string | e.g. `Stripe`, `Postmark` |
+| `purpose` | string | what it's used for |
+| `docs_url` | string | |
+| `status_url` | string | |
+| `credentials_envs` | string[] | env var **names** only — never values |
+
+Example — `constellation/external/EXTERNAL-EMAIL-PROVIDER.md`:
+
+```markdown
+---
+name: Email provider
+kind: saas-vendor
+status: built
+vendor: Postmark
+purpose: Transactional email (ticket confirmations, assignment notices)
+docs_url: https://postmarkapp.com/developer
+credentials_envs:
+  - POSTMARK_SERVER_TOKEN
+---
+
+All outbound email goes through Postmark. This app only sends template IDs and
+variables, never raw HTML.
+```

package/skill/types/file.md

@@ -0,0 +1,28 @@
+# FILE cards (`FILE-`, `file/`)
+
+Reference from the plan to a real source file. `path` is the only required field
+in the entire format. Create FILE cards for load-bearing files (entry points,
+route tables, core modules) — not for every file in the repo.
+
+| Field | Type | Notes |
+|---|---|---|
+| `path` | string | **required** — relative to repo root |
+| `language` | string | `typescript`, `python`, … |
+| `summary` | string | one line |
+
+Example — `constellation/file/FILE-TICKETS-ROUTE.md`:
+
+```markdown
+---
+name: tickets route handler
+status: built
+path: src/api/tickets.ts
+language: typescript
+summary: Express route handlers for the tickets API
+connections:
+  - API-TICKETS
+---
+
+Implements [[API-TICKETS]]. Validation lives here; persistence is in the
+repository module it imports.
+```

package/skill/types/flow.md

@@ -0,0 +1,29 @@
+# FLOW cards (`FLOW-`, `flow/`)
+
+A FLOW is a linear narrative: numbered steps in the **body**, with nested list
+items for error/edge branches. If it genuinely branches, it's a Mermaid flowchart
+or actually a STATE card. Steps never go in frontmatter.
+
+| Field | Type | Notes |
+|---|---|---|
+| `triggers` | array | `{ kind: cron\|event\|manual, schedule?, event? (handle) }` |
+
+Example — `constellation/flow/FLOW-CREATE-TICKET.md`:
+
+```markdown
+---
+name: Create ticket
+status: built
+triggers:
+  - { kind: manual }
+---
+
+# Create ticket
+
+1. Requester submits the public ticket form
+2. [[API-TICKETS]] POST validates the body against [[DATATYPE-CREATE-TICKET-INPUT]]
+   - invalid → 422 with per-field errors
+3. Row inserted into [[DB-TICKETS]] with status `open`
+4. [[EVENT-TICKET-CREATED]] fires
+5. [[JOB-AUTO-ASSIGN]] picks an agent
+```

package/skill/types/job.md

@@ -0,0 +1,27 @@
+# JOB cards (`JOB-`, `job/`)
+
+One card per background/scheduled/queued task.
+
+| Field | Type | Notes |
+|---|---|---|
+| `trigger` | enum | `cron` \| `queue` \| `event` \| `manual` |
+| `schedule` | string | cron expression when `trigger: cron` |
+| `flow` | handle | FLOW this job executes, if any |
+| `max_retries` | integer | ≥ 0 |
+| `idempotency_key` | string | what makes runs idempotent |
+
+Example — `constellation/job/JOB-AUTO-ASSIGN.md`:
+
+```markdown
+---
+name: Auto-assign tickets
+status: planned
+trigger: event
+max_retries: 3
+connections:
+  - EVENT-TICKET-CREATED
+---
+
+Listens for [[EVENT-TICKET-CREATED]], picks the agent with the fewest open
+tickets, writes the assignment to [[DB-TICKETS]]. Idempotent per ticket `id`.
+```

package/skill/types/page.md

@@ -0,0 +1,28 @@
+# PAGE cards (`PAGE-`, `page/`)
+
+One card per route/screen. Route fields are flat (no nested `route` object).
+
+| Field | Type | Notes |
+|---|---|---|
+| `route` | string | URL pattern, e.g. `/inbox/:ticket_id?` |
+| `parent` | handle | parent PAGE (layout/shell) this nests under |
+| `path_params` | array | `{ name, type?, required? }` |
+| `query_params` | array | same shape |
+
+Example — `constellation/page/PAGE-INBOX.md`:
+
+```markdown
+---
+name: Inbox
+status: building
+route: /inbox/:ticket_id?
+path_params:
+  - { name: ticket_id, type: string, required: false }
+connections:
+  - API-TICKETS
+  - COMPONENT-TICKET-CARD
+---
+
+The agent-facing ticket list. Loads tickets from [[API-TICKETS]] and renders each
+as a [[COMPONENT-TICKET-CARD]].
+```

package/skill/types/plan.md

@@ -0,0 +1,37 @@
+# PLAN cards (`PLAN-`, `plan/` — and `plan.md` at the root)
+
+`constellation/plan.md` is the card `PLAN-PROJECT`: the short, living summary of
+where the project stands. Scoped plans (`PLAN-FRONTEND`) live in `plan/`.
+
+Keep it **short**. Three rules:
+
+- Decisions go in DOC cards (`kind: decision`), one file each — not in the plan.
+- Per-card status lives on the cards (`status:`), not in plan checklists.
+- Edit the relevant section; never bulk-rewrite the file (it's shared state).
+
+| Field | Type | Notes |
+|---|---|---|
+| `scope` | string | area for scoped plans, e.g. `frontend`; omit for `plan.md` |
+
+Example — `constellation/plan.md`:
+
+```markdown
+---
+name: Project plan
+---
+
+# Project Plan
+
+## Current state
+
+- Core ticket loop specced: [[FLOW-CREATE-TICKET]], [[API-TICKETS]], [[DB-TICKETS]]
+- Auto-assignment ([[JOB-AUTO-ASSIGN]]) planned, not built
+
+## Conventions
+
+- All ticket payloads use [[DATATYPE-TICKET]]; never inline ticket shapes.
+
+## Last synced
+
+Code last reconciled against plan commit `<sha>` (maintained by the sync agent).
+```

package/skill/types/role.md

@@ -0,0 +1,25 @@
+# ROLE cards (`ROLE-`, `role/`)
+
+One card per role or permission group.
+
+| Field | Type | Notes |
+|---|---|---|
+| `permissions` | string[] | conventionally `resource:action` |
+| `issued_by` | string | `app`, `org`, `tenant`, `os`, … |
+
+Example — `constellation/role/ROLE-SUPPORT-AGENT.md`:
+
+```markdown
+---
+name: Support agent
+status: built
+permissions:
+  - tickets:read
+  - tickets:write
+  - tickets:assign
+issued_by: app
+---
+
+A human agent working the inbox. Cannot delete tickets — nothing can; see
+[[DB-TICKETS]].
+```

package/skill/types/state.md

@@ -0,0 +1,38 @@
+# STATE cards (`STATE-`, `state/`)
+
+One card per state machine. Prefer a ` ```mermaid stateDiagram-v2 ` block in the
+body; the structured frontmatter fields are optional, for tooling that needs them.
+
+| Field | Type | Notes |
+|---|---|---|
+| `states` | array | `{ name, initial?, terminal? }` |
+| `transitions` | array | `{ from, to, event? (handle), guard?, action? }` |
+
+Example — `constellation/state/STATE-TICKET.md`:
+
+````markdown
+---
+name: Ticket lifecycle
+status: built
+states:
+  - { name: open, initial: true }
+  - { name: assigned }
+  - { name: resolved }
+  - { name: closed, terminal: true }
+transitions:
+  - { from: open, to: assigned, action: notify assignee }
+  - { from: resolved, to: closed, guard: requester confirms or 7 days pass }
+connections:
+  - DB-TICKETS
+---
+
+```mermaid
+stateDiagram-v2
+  [*] --> open
+  open --> assigned: agent assigned
+  assigned --> resolved: agent resolves
+  resolved --> closed: confirmed / 7 days
+```
+
+Transitions are enforced in the API layer, never by direct column updates.
+````

package/skill/types/test.md

@@ -0,0 +1,28 @@
+# TEST cards (`TEST-`, `test/`)
+
+One card per meaningful test spec (a suite or scenario, not every assertion).
+The category goes in the reserved `kind`: `unit`, `integration`, `e2e`. Connect
+the card to what it covers.
+
+| Field | Type | Notes |
+|---|---|---|
+| `framework` | string | `vitest`, `jest`, `pytest`, `playwright`, … |
+
+Example — `constellation/test/TEST-CREATE-TICKET.md`:
+
+```markdown
+---
+name: Create ticket — integration
+kind: integration
+status: verified
+framework: vitest
+connections:
+  - API-TICKETS
+  - FLOW-CREATE-TICKET
+---
+
+Covers the full [[FLOW-CREATE-TICKET]] happy path plus the 422 branch:
+
+- valid input → 201, row in [[DB-TICKETS]], event emitted
+- missing subject → 422, no row, no event
+```

package/viewer/dist/assets/arc-Kj6pF3JI.js

@@ -0,0 +1 @@
+import{n as e,t}from"./path-BWPyau1x.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-CFOOgrqc.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(e,t,n,r,i,a,o){var c=e-n,l=t-r,u=(o?a:-a)/d(c*c+l*l),f=u*l,p=-u*c,m=e+f,h=t+p,g=n+f,_=r+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=i-a,w=m*_-g*h,T=(x<0?-1:1)*d(s(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(i/C-1),y11:D*(i/C-1)}}function x(){var s=m,x=h,S=e(0),C=null,w=g,T=_,E=v,D=null,O=t(k);function k(){var e,t,m=+s.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-r,_=T.apply(this,arguments)-r,v=l(_-g),k=_>g;if(D||=e=O(),h<m&&(t=h,h=m,m=t),!(h>1e-12))D.moveTo(0,0);else if(v>c-1e-12)D.moveTo(h*u(g),h*a(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*u(_),m*a(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):d(m*m+h*h)),R=p(l(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=o(L/m*a(I)),W=o(L/h*a(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*u(A),K=h*a(A),q=m*u(N),J=m*a(N);if(R>1e-12){var Y=h*u(j),X=h*a(j),Z=m*u(M),Q=m*a(M),$;if(v<i)if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/a(f((ee*ne+te*re)/(d(ee*ee+te*te)*d(ne*ne+re*re)))/2),ae=d($[0]*$[0]+$[1]*$[1]);z=p(R,(m-ae)/(ie-1)),B=p(R,(h-ae)/(ie+1))}else z=B=0}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,h,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,n(H.y11,H.x11),n(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,m,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,n(H.y11,H.x11),n(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),e)return D=null,e+``||null}return k.centroid=function(){var e=(+s.apply(this,arguments)+ +x.apply(this,arguments))/2,t=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-i/2;return[u(t)*e,a(t)*e]},k.innerRadius=function(t){return arguments.length?(s=typeof t==`function`?t:e(+t),k):s},k.outerRadius=function(t){return arguments.length?(x=typeof t==`function`?t:e(+t),k):x},k.cornerRadius=function(t){return arguments.length?(S=typeof t==`function`?t:e(+t),k):S},k.padRadius=function(t){return arguments.length?(C=t==null?null:typeof t==`function`?t:e(+t),k):C},k.startAngle=function(t){return arguments.length?(w=typeof t==`function`?t:e(+t),k):w},k.endAngle=function(t){return arguments.length?(T=typeof t==`function`?t:e(+t),k):T},k.padAngle=function(t){return arguments.length?(E=typeof t==`function`?t:e(+t),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};

package/viewer/dist/assets/architecture-7EHR7CIX-CGfWeim3.js

@@ -0,0 +1 @@
+import"./chunk-NNHCCRGN-DlpIbxXb.js";import{x as e}from"./mermaid-parser.core-DzlZTbbh.js";export{e as createArchitectureServices};