@meltemi/diagrams-cli 1.9.0 → 1.11.1

package/skills/meltemi-diagrams/examples/architecture.meltemi

@@ -0,0 +1,73 @@
+language "0.2"
+
+// Shared model and views from the product proposal ("Modelos y vistas"), with a context view and
+// a component view that lift and combine the model's relations.
+model commerce {
+  person customer "Cliente" { description "Compra en línea" }
+
+  system shop "Commerce" {
+    description "Tienda en línea"
+    container web "Web" { technology "React" }
+    container api "API" {
+      technology "HTTP"
+      component orders "Pedidos" { technology "Kotlin" }
+      component payments "Pagos" { technology "Kotlin" }
+    }
+    datastore db "Pedidos" { technology "PostgreSQL" }
+    api.orders -> db: "Guarda" as store
+  }
+  system bank "Banco" {
+    description "Autoriza tarjetas"
+    external
+  }
+
+  customer -> shop.web: "Compra" as visit
+  shop.web -> shop.api: "HTTPS" as request { technology "JSON/HTTPS" }
+  shop.api -> shop.db: "SQL" as persist
+  shop.api.payments -> bank: "Autoriza" as authorize
+  shop.web -> shop.api.orders: "Pedidos" as orders
+}
+
+diagram context: c4 using commerce {
+  level context
+  layout assisted
+  title "Commerce en contexto"
+
+  placement {
+    place customer at (92, 64)
+    place shop at (456, 64)
+    place bank at (833, 64)
+  }
+}
+
+diagram containers: c4 using commerce {
+  level container
+  scope shop
+  include customer, shop.web, shop.api, shop.db
+  layout assisted
+  direction LR
+  theme "editorial.light"
+  label shop.api "API de pedidos"
+
+  placement {
+    place customer at (92, 93)
+    place shop.web at (473, 93)
+    place shop.api at (855, 93)
+    place shop.db at (1214, 94)
+  }
+}
+
+diagram components: c4 using commerce {
+  level component
+  scope shop.api
+  layout assisted
+  shop.web -> shop.api.orders: "Usa" as uses
+
+  placement {
+    place shop.web at (97, 88)
+    place shop.api.orders at (459, 88)
+    place shop.api.payments at (459, 200)
+    place shop.db at (845, 88)
+    place bank at (850, 210)
+  }
+}

package/skills/meltemi-diagrams/examples/platform.meltemi

@@ -0,0 +1,139 @@
+language "0.2"
+
+// A complete sheet using every construct of the flow profile: bands, nodes with descriptions,
+// data stores, a decision, notes, tags, named relations with numbered steps, waypoints, shared
+// styles for a palette and for "proposed" pieces, a legend and a file theme with the brand frame.
+
+theme acme {
+  extends "technical.light"
+  accent "#1D4ED8"
+  accentEnd "#0891B2"
+  brand "Acme · Meltemi Diagrams"
+}
+
+diagram paymentsPlatform: flow {
+  title "Payments platform"
+  description "Target architecture of the payments platform: edge, services, approval and data."
+  layout manual
+  theme "acme"
+
+  // ---- Bands --------------------------------------------------------------------------------
+  group identity "Identity" {
+    node login "Login + PKCE" { description "customers" }
+    node obo "Token exchange" { description "on behalf of" }
+    note identityLimits "To validate\nrate limits\ntoken lifetimes"
+  }
+
+  group services "Services" {
+    node orders "Orders" { description "Go · gRPC" }
+    node payments "Payments" { description "Go · gRPC" }
+    decision risky "Manual approval?"
+    node approvals "Approvals" { description "Temporal workflow" }
+  }
+
+  group data "Data" {
+    data documents "Documents" { description "S3" }
+    data ledger "Ledger" { description "PostgreSQL" }
+    data cache "Cache" { description "Redis · TTL" }
+  }
+
+  // ---- Edge and partners --------------------------------------------------------------------
+  node app "Mobile app" { description "signed-in user" }
+  node gateway "API Gateway" { description "validates JWT · routes" }
+  node partner "Partner API" { description "banks and PSPs" }
+
+  // ---- Tags: capability that acts at that point ---------------------------------------------
+  tag tPkce "PKCE"
+  tag tJwt "JWT"
+  tag tObo "OBO"
+
+  // ---- Main path (the numbers are the steps) ------------------------------------------------
+  // 1. The user signs in and the app calls the gateway with the user's JWT.
+  app -> gateway: "1" as r1
+  // 2. The gateway validates the token and routes to Orders.
+  gateway -> orders: "2" as r2
+  // 3. Orders asks Payments to charge.
+  orders -> payments: "3" as r3
+  // 4. Payments decides whether a human must approve.
+  payments -> risky: "4" as r4
+  // 5. Risky payments wait for approval in a durable workflow; the rest settle at once.
+  risky -> approvals: "yes" as r5
+  risky -> ledger: "no" as r6
+  approvals -> ledger as r7
+  approvals -> documents as r10
+  // Partners are called with a token exchanged on behalf of the user.
+  payments -> partner as r8
+  payments -> cache as r9
+
+  // ---- Legend --------------------------------------------------------------------------------
+  tag lgIdentity "Identity"
+  tag lgServices "Services"
+  tag lgData "Data"
+  tag lgDashed "Dashed: proposed"
+
+  placement {
+    // Bands
+    place identity at (120, 250); size identity (200, 460)
+    place services at (560, 340); size services (520, 280)
+    place data at (640, 620); size data (600, 160)
+
+    // Identity
+    place login at (120, 98); size login (160, 56)
+    place obo at (120, 178); size obo (160, 56)
+    place identityLimits at (118, 290); size identityLimits (150, 54)
+
+    // Edge and partners
+    place app at (380, 60); size app (180, 56)
+    place gateway at (560, 160); size gateway (420, 50)
+    place partner at (980, 160); size partner (160, 56)
+
+    // Services
+    place orders at (440, 300); size orders (160, 56)
+    place payments at (660, 300); size payments (160, 56)
+    place risky at (660, 410); size risky (180, 80)
+    place approvals at (440, 410); size approvals (160, 56)
+
+    // Data
+    place documents at (440, 640)
+    place ledger at (620, 640)
+    place cache at (840, 640)
+
+    // Tags on box corners
+    place tPkce at (470, 32)
+    place tJwt at (770, 135)
+    place tObo at (740, 272)
+
+    // Steps beside the arrows
+    label r1 at 50% offset (16, 0)
+    label r2 at 50% offset (16, 0)
+    label r3 at 50% offset (0, -16)
+    label r4 at 50% offset (16, 0)
+    label r5 at 50% offset (0, -16)
+    label r6 at 50% offset (16, 0)
+
+    // Bends: one waypoint per corner
+    route r7 from approvals.south to ledger.north via [(480, 520), (600, 520)]
+    route r8 from payments.east to partner.south via [(980, 300)]
+    route r9 from payments.south to cache.north via [(720, 345), (840, 345)]
+
+    // Legend
+    place lgIdentity at (80, 760)
+    place lgServices at (180, 760)
+    place lgData at (266, 760)
+    place lgDashed at (402, 760)
+  }
+
+  // ---- Palette -------------------------------------------------------------------------------
+  style identity, lgIdentity { fill "#f6f3fe"; stroke "#6a4fd0"; color "#33247a" }
+  style login, obo { fill "#ebe5fd"; stroke "#6a4fd0"; color "#33247a" }
+  style identityLimits { color "#33247a" }
+  style services, lgServices { fill "#eef6f9"; stroke "#2f7f9c"; color "#144a5e" }
+  style data, lgData { fill "#fdf5e6"; stroke "#b9800f"; color "#6b4500" }
+  style gateway { fill "#e2f3e5"; stroke "#3d8c50"; color "#1d5a2d" }
+  style tPkce, tJwt, tObo { fill "#6a4fd0"; color "#ffffff" }
+  style lgDashed { fill "#ffffff"; stroke "#526579"; color "#526579" }
+  style r1, r2, r3, r4 { fill "#0B1830"; color "#FFFFFF" }
+
+  // ---- Proposed or to validate ---------------------------------------------------------------
+  style obo, approvals, documents, partner, lgDashed { line dashed }
+}

package/skills/meltemi-diagrams/examples/sequence.meltemi

@@ -0,0 +1,52 @@
+language "0.2"
+
+// A payment with an approval branch, a call that returns, a retry loop and two scenarios.
+diagram payment: sequence {
+  title "Card payment"
+  autonumber
+
+  actor customer "Customer"
+  boundary web "Checkout page"
+  group backend "Backend" {
+    participant api "Payments API"
+    database ledger "Ledger"
+  }
+  participant bank "Card network"
+
+  customer -> web: "Pay" as pay
+  web -> api: "Create payment" as create
+  activate api
+  api -> bank: "Authorize" as authorize
+
+  alt result "Approved" {
+    bank --> api: "Approved" as approved
+    // The ledger is active for the call, until it returns.
+    api -> ledger: "Record" as record {
+      return "Recorded" as recorded
+    }
+    api --> web: "Receipt" as receipt
+  } else "Declined" {
+    bank --> api: "Declined" as declined
+    loop retries "Until the card works" {
+      api --> web: "Ask for another card" as again
+      web -> api: "New card" as card
+    }
+  }
+
+  note over web, api "The page never sees the card number"
+  deactivate api
+  api -> web: "Payment settled" as settled { kind async }
+
+  placement {
+    space authorize 14
+  }
+
+  scenario approved "Payment approved" {
+    choose result "Approved"
+  }
+
+  scenario declined "Declined twice" {
+    choose result "Declined"
+    repeat retries 2
+  }
+}

package/skills/meltemi-diagrams/examples/slide.meltemi

@@ -0,0 +1,60 @@
+language "0.2"
+
+// The source flow: the slide below links each of its boxes to these elements.
+diagram checkout: flow {
+  layout manual
+
+  client["Client app"]
+  api["Order API"]
+  data orders "Orders DB"
+
+  client -> api: "HTTPS" as request
+  api -> orders as persist
+
+  placement {
+    place client at (120, 60)
+    place api at (380, 60)
+    place orders at (640, 60)
+  }
+}
+
+// A free composition: text, shapes, an icon, a group placed by its interior, and two layers.
+diagram slide: free {
+  title "Checkout at a glance"
+  preset slide
+  routing orthogonal
+  layers main, front
+
+  text heading "Checkout at a glance"
+  text lead "Every order passes through one API" { class muted }
+
+  box client "Client app" { link checkout.client }
+  group backend "Backend" {
+    box api "Order API" { description "REST · validates input"; link checkout.api }
+    box orders "Orders DB" { link checkout.orders }
+    api -> orders as persist
+  }
+  icon secure "tabler:lock" { layer front }
+  text secureNote "TLS everywhere" { layer front }
+
+  client -> api: "HTTPS" as request
+
+  placement {
+    place heading at (960, 140)
+    place lead at (960, 210)
+    place client at (420, 560)
+    place backend at (1180, 560)
+    size backend (640, 240)
+    place api at (140, 92)
+    place orders at (460, 92)
+    place secure at (420, 420)
+    place secureNote at (420, 470)
+  }
+
+  class muted { color muted; fontSize 28; fontWeight 400 }
+  style heading { fontSize 56; fontWeight 700; textAlign center }
+  style lead { textAlign center }
+  style client { shape pill }
+  style orders { shape cylinder }
+  style secureNote { textAlign center }
+}

package/skills/meltemi-diagrams/examples/story.meltemi

@@ -0,0 +1,53 @@
+language "0.2"
+
+// A checkout flow and the story that walks through a purchase. Export any instant with
+// pnpm mdg export story.meltemi --story purchase --at 2.4s
+diagram checkout: flow {
+  title "Checkout"
+  layout manual
+
+  client["Client app"]
+  api["Order API"]
+  orders["Orders service"]
+  data db "Orders DB"
+
+  client -> api: "HTTPS" as request
+  api -> orders: "Create order" as create
+  orders -> db: "Persist" as save
+
+  placement {
+    place client at (120, 80)
+    place api at (380, 80)
+    place orders at (640, 80)
+    place db at (640, 220)
+  }
+
+  animate request { effect flow }
+}
+
+story purchase for checkout {
+  title "A purchase"
+  description "From the client's request to the stored order."
+
+  scene overview "The pieces" {
+    reveal client, api, orders, db over 800ms
+    hold 1s
+  }
+
+  scene request "The request" {
+    focus client, api
+    trace request over 1200ms
+    camera api, orders
+    trace create over 1200ms
+  }
+
+  scene stored "Stored" {
+    focus all
+    camera all
+    parallel {
+      trace save over 1200ms
+      highlight db over 1200ms
+    }
+    hold 2s
+  }
+}

package/skills/meltemi-diagrams/reference/c4.md

@@ -0,0 +1,92 @@
+# Models and C4 views
+
+Use a `model` block for the architecture (who uses what, which containers a system has) and C4
+views to draw it at one level each. Declare entities once in the model; views only list them.
+
+## Model
+
+```text
+model commerce {
+  person customer "Cliente" { description "Compra en línea" }
+  system shop "Commerce" {
+    container web "Web" { technology "React" }
+    container api "API" {
+      technology "Kotlin"
+      component orders "Pedidos"
+    }
+    datastore db "Pedidos" { technology "PostgreSQL" }
+    api -> db: "SQL" as persist          // inside shop: api is shop.api
+  }
+  system bank "Banco" { external }
+
+  customer -> shop.web: "Compra" as visit
+  shop.web -> shop.api: "HTTPS" as request { technology "JSON/HTTPS" }
+  shop.api.orders -> bank: "Autoriza" as authorize
+}
+```
+
+- Persons and systems at the root; containers and datastores in systems; components in containers
+  (`model.invalid-nesting` otherwise).
+- Entities are named by path: `shop.api.orders`. Relations use `->` only and name paths.
+- `external` marks persons and systems outside the organisation (drawn grey and dashed).
+
+## Views
+
+```text
+diagram containers: c4 using commerce {
+  level container          // context | container | component
+  scope shop               // a system; a container for component views
+  include customer, shop.web, shop.api, shop.db
+  label shop.api "API de pedidos"   // local text, the model keeps "API"
+  direction LR
+  layout assisted
+  placement { place shop.api at (420, 120) }
+  style shop.db { fill accent }
+}
+```
+
+- Without `include`, a view draws its default set: everything at the context level, otherwise
+  the scope's children and the entities related to them. `exclude` removes entities.
+- A container view draws the scope's containers and datastores (inside a dashed boundary),
+  persons and other systems; a component view the scope's components, the other containers of the
+  system, persons and other systems. Anything else is `c4.out-of-level`.
+- Relations come from the model; ends inside hidden entities are lifted to the drawn ancestor
+  (at the context level `customer -> shop.web` becomes `customer -> shop`). Two relations to the
+  same pair stay two arrows; to draw one, write a combination in the view:
+  `customer -> shop: "Usa" as uses`. A combination with no model relation behind it is
+  `c4.unsupported-relation`.
+- Placement, styles and routes take paths: `route request from shop.web.east to shop.api.west`.
+
+## Notes in views
+
+A view accepts `note <id> "Text" [on <entity path>]` beside its lists: an annotation of the view,
+never of the model and never an entity (`include`, `exclude`, `label` and relations cannot name it).
+`note cache "Cached 5 min" on shop.api` draws a note with a dotted leader to `shop.api`, which the
+view must draw (else `ref.unknown-element`). It takes `class` and `url`, the view's `style`, `class`,
+`rule` and `animate`, and a `place` in the view's `placement`.
+
+## Files
+
+Keep the model in `models/` and the views in `diagrams/` of a project, and import the model:
+
+```text
+import commerce from "../models/commerce.meltemi"
+diagram context: c4 using commerce { level context }
+```
+
+Sequence and free objects link to entities with `link commerce.shop.api`; a participant without its
+own label shows the entity's.
+
+## Diagnostics
+
+| Code                      | Fix                                                                      |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `c4.invalid-level`        | add `level context`, `level container` or `level component`              |
+| `c4.scope-required`       | add `scope <system>` (container view) or `scope <container>` (component) |
+| `c4.invalid-scope`        | scope a system or a container; datastores have no components             |
+| `c4.out-of-level`         | remove the entity from `include`, or change the level                    |
+| `c4.unsupported-relation` | add the relation to the model, or remove the combination                 |
+| `ref.unknown-entity`      | use the full path from the model's root (`shop.api`, not `api`)          |
+| `ref.unknown-model`       | declare or import the model named after `using`                          |
+| `model.invalid-nesting`   | move the entity into the right parent                                    |
+| `model.invalid-relation`  | relate separate entities, not an entity and its parent                   |

package/skills/meltemi-diagrams/reference/cloud.md

@@ -0,0 +1,19 @@
+# Sharing in the cloud (only when the person asks)
+
+A project can mirror itself in the optional Meltemi cloud service, to open it in the browser, share
+it or publish its catalog as a web page. These commands need a signed-in person and change things
+outside the repository, so run them only when asked, and never add `--force` unasked.
+
+- `pnpm mdg login` opens the person's browser to approve the request (`--no-browser` prints the
+  address); `logout` revokes the token and `whoami` says who it is for. In CI the token is
+  `MELTEMI_TOKEN`. Exit code 3 means "run `login`".
+- `pnpm mdg push <folder> --create` makes the cloud project and records it in `project.json`
+  (`cloud`). Later `push <folder>` lists what differs by path and by id and asks. `push --check`
+  writes nothing and exits 1 when the cloud differs, so it is safe to run.
+- `pnpm mdg pull [<id>] [folder]` brings the cloud's files into the folder (files that differ are
+  kept unless `--force`); `pnpm mdg review <folder> --base cloud` lists what differs by id.
+- `pnpm mdg publish <folder> --slug name` makes the catalog a public web page, so only on request;
+  `--unpublish` takes it down. `pnpm mdg projects --json` lists the person's cloud projects.
+
+Never print, read or copy a token (`mdg_…`): it lives in `MELTEMI_TOKEN` or in the credentials file
+that `login` keeps, and belongs in no command line, file or commit. `docs/cli.md` has the details.

package/skills/meltemi-diagrams/reference/converting.md

@@ -0,0 +1,101 @@
+# Converting an existing diagram into a `.meltemi` sheet
+
+The goal is a sheet whose export can be put beside the original with only intended differences.
+Work from the source's own geometry whenever it has one.
+
+## Mermaid and PlantUML: import
+
+Never retype a Mermaid or PlantUML diagram; import it:
+
+````bash
+pnpm mdg import docs/checkout.mmd            # writes docs/checkout.meltemi
+pnpm mdg import design.puml --out sheets/design.meltemi
+pnpm mdg import README.md                    # every ```mermaid and ```plantuml block
+````
+
+- Mermaid `flowchart`/`graph`, `sequenceDiagram`, `C4Context`/`C4Container`/`C4Component`/
+  `C4Dynamic`, `architecture-beta` and `block-beta`; PlantUML component, deployment, use case,
+  sequence and C4-PlantUML diagrams, with `!define`, `!procedure`, `!function`, variables,
+  conditionals, loops and local `!include` files. Other types are refused.
+- Read every finding: `import.approximated` (kept with another drawing), `import.unsupported-construct`
+  (dropped) and `import.syntax` (a line it could not read, kept as a `// Not imported:` comment).
+  Exit 1 means something essential is missing: add it by hand from the comment and the source.
+- Flow imports use `layout auto`; adjust them on the canvas or with `layout assisted` and `place`.
+  When the source changes, run `pnpm mdg import <source> --merge`: placement, styles, classes,
+  animations, scenarios and local labels are kept for everything still in the source.
+- C4 macros become a `model` and a view; check the level, the scope and the `include` list.
+- Shapes are kept: Mermaid hexagons, parallelograms, trapezoids, circles, stadiums, subroutines
+  and flags, and PlantUML clouds, hexagons, actors, use cases, interfaces and files become nodes
+  (or boxes) with `style <id> { shape … }`; mirrored Mermaid forms are drawn as the nearest shape
+  and reported. Mermaid `block:` groups become untitled groups.
+- `docs/import/mermaid.md` and `docs/import/plantuml.md` in the repository list what each construct
+  becomes.
+
+The rest of this page is for sources that cannot be imported: HTML, SVG, draw.io, screenshots.
+
+## 1. Get the geometry
+
+| Source                  | Where the numbers are                                                                       |
+| ----------------------- | ------------------------------------------------------------------------------------------- |
+| HTML or SVG sheet       | `rect x y width height` and `text x y`; arrows as `line`/`path`; classes tell the category  |
+| draw.io / Excalidraw    | the XML or JSON holds `x`, `y`, `width`, `height` per shape                                 |
+| D2 and other text tools | no coordinates: list nodes and edges, then design a grid (columns 200 px apart, rows 80 px) |
+| Screenshot or photo     | estimate on a 20 px grid; keep relative alignment, not pixel fidelity                       |
+
+Record each box as centre and size: `place id at (x + w/2, y + h/2)` and `size id (w, h)`.
+
+In draw.io a shape inside a container has `parent` set to the container and `x`, `y` relative to
+the container's top-left corner. In a free diagram write the container as a group and the child's
+`place` relative to the group's interior: `(x + w/2 - 16, y + h/2 - 16)` for an untitled group,
+`(x + w/2 - 16, y + h/2 - 40)` for a titled one (technical themes). In a flow diagram keep diagram
+coordinates.
+
+## 2. Map the pieces
+
+| In the original                                                  | In the sheet                                                                         |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Coloured band or swimlane with a title                           | `group id "Title" { ... }` with `place` and `size` of the band; colours in `style`   |
+| Nested plain rectangles, untitled containers (draw.io)           | untitled groups `group id "" { ... }`, `style id { fill "…"; stroke "…"; radius 0 }` |
+| Backdrop behind a row of boxes                                   | an untitled group with `place`, `size` and `layer back` (`layers back, main`)        |
+| Rectangles drawn one inside another                              | boxes declared outer first, outer labels `""`; the stack is not an overlap           |
+| Hexagon, ellipse, circle, cloud, document, actor, star, triangle | `style id { shape hexagon }` on a `node` (flow) or `box` (free); see the note below  |
+| Square or more rounded corners (`rounded=0`)                     | `style id { radius 0 }`, or `radius 16`; `rule group { radius 0 }` for all groups    |
+| Box with title and subtitle                                      | `node id "Title" { description "subtitle" }` (or `id["Title"]` without subtitle)     |
+| Database, cache, bucket, queue of records                        | `data id "Name" { description "..." }`                                               |
+| Diamond / question                                               | `decision id "Question?"`                                                            |
+| Free text, footnotes, limits                                     | `note id "line\nline"`                                                               |
+| Small badges or pills on boxes                                   | `tag id "TEXT"` placed on the corner                                                 |
+| Dashed outline, "proposed", "to validate"                        | `style a, b, c { line dashed }`                                                      |
+| Numbered step circles on arrows                                  | relation labels `"1"`, `"2"` with `label r1 at 50% offset (16, 0)` and a dark style  |
+| Arrow                                                            | `a -> b` (named `as id` when it has a label, a route or a style)                     |
+| Bent arrow                                                       | `route id from a.side to b.side via [(x, y)]`, one waypoint per bend                 |
+| Legend                                                           | a row of `tag`s under the sheet with the category colours                            |
+| Explanatory paragraphs, step list                                | comments next to the relations; the ones not drawn stay as comments                  |
+
+Some shapes are the nearest picture, not the same one. `shape triangle` points up, while draw.io's
+`triangle` points right unless rotated: draw a right-pointing marker as `shape arrow`, or accept
+the turned triangle. `shape person` is a head over a body, not draw.io's stick-figure actor.
+
+Keep the original ids where they exist; otherwise derive camelCase ids from the labels.
+
+## 3. Write the file
+
+Order inside the diagram: properties, bands with their children, free-standing elements, tags,
+relations with comments, legend, `placement`, then `style`. Group the placement block by area and
+the style block by palette, with one shared statement for "dashed".
+
+## 4. Prove it
+
+1. `pnpm mdg validate file.meltemi` until no diagnostics remain.
+2. `pnpm mdg export file.meltemi`, open the SVG beside the original (`pnpm preview`).
+3. Compare arrow by arrow: in the original the arrows usually join boxes where they overlap, which
+   is what the exporter does without routes; only arrows that bend need waypoints.
+4. Write down the intended differences (cylinders for stores, left-aligned band titles, legend inside
+   the sheet, fonts) in a README next to the file.
+
+## Worked example
+
+A real architecture sheet (30 boxes, 4 bands, 13 arrows, 8 steps, 7 tags) converts into one
+file where only one arrow carries a waypoint; every other arrow is reproduced by the anchor rules.
+See [examples/platform.meltemi](../examples/platform.meltemi) in this skill for a complete sheet
+of the same shape.