@itsthecsguy/linework 0.1.2 → 0.1.4

package/dist/render/fonts.js

@@ -2,7 +2,9 @@
 // SVG gets a subset of the faces it uses (only the glyphs in its text), so a
 // diagram looks the same on GitHub, in a browser and in a doc, and text that fit
 // when linework sized the boxes still fits wherever it is shown.
+import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import subsetFont from 'subset-font';
 import { assetsDir } from './browser.js';
@@ -54,7 +56,7 @@ export async function embedFonts(svg) {
     text = [...new Set(text + text.toUpperCase() + ' ')].join('');
     const rules = [];
     for (const f of FACES.filter((x) => families.includes(x.family))) {
-        const sub = await subsetFont(read(f), text, { targetFormat: 'woff2' });
+        const sub = await subset(f, text);
         rules.push(`@font-face{font-family:"${f.family}";font-weight:${f.weight};font-style:normal;src:url(data:font/woff2;base64,${sub.toString('base64')}) format("woff2");}`);
     }
     const style = `<style id="aiviz-fonts" type="text/css">${rules.join('')}</style>`;
@@ -64,3 +66,65 @@ export async function embedFonts(svg) {
         return svg.replace(/<defs[^>]*>/, (m) => m + style);
     return svg.replace(/<svg\b[^>]*>/, (m) => `${m}<defs>${style}</defs>`);
 }
+// ---------- subset cache ----------
+//
+// Compressing a subset to WOFF2 is most of embedFonts' time, and rebuilding a
+// diagram after a small edit usually needs the same characters again. A subset
+// depends only on the font file and the set of characters (not their order), so
+// that pair is the key. Kept in memory and in the user's own cache folder, never
+// a shared temp dir: whatever is there ends up inside the SVGs.
+const memo = new Map();
+const fileHash = new Map();
+/** Drop the in-memory copies, so the next lookup reads the disk cache. For tests. */
+export function forgetSubsets() {
+    memo.clear();
+}
+function cacheDir() {
+    if (process.env.LINEWORK_NO_CACHE)
+        return undefined;
+    const home = os.homedir();
+    const base = process.env.XDG_CACHE_HOME ||
+        (process.platform === 'darwin' ? path.join(home, 'Library', 'Caches') : process.platform === 'win32' ? process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local') : path.join(home, '.cache'));
+    return path.join(base, 'linework', 'fonts');
+}
+async function subset(f, text) {
+    const font = read(f);
+    let fh = fileHash.get(f.file);
+    if (!fh)
+        fileHash.set(f.file, (fh = crypto.createHash('sha256').update(font).digest('hex')));
+    const chars = [...new Set(text)].sort().join('');
+    const key = crypto.createHash('sha256').update(`${fh}\0${chars}`).digest('hex').slice(0, 32);
+    const hit = memo.get(key);
+    if (hit)
+        return hit;
+    const dir = cacheDir();
+    const file = dir && path.join(dir, `${key}.woff2`);
+    let out;
+    try {
+        const b = file ? fs.readFileSync(file) : undefined;
+        // A WOFF2 file starts with its signature; anything else is a broken write.
+        if (b && b.subarray(0, 4).toString('latin1') === 'wOF2')
+            out = b;
+    }
+    catch {
+        // not cached yet
+    }
+    if (!out) {
+        out = await subsetFont(font, text, { targetFormat: 'woff2' });
+        if (file) {
+            try {
+                fs.mkdirSync(dir, { recursive: true });
+                const tmp = `${file}.${process.pid}.tmp`;
+                fs.writeFileSync(tmp, out);
+                fs.renameSync(tmp, file);
+            }
+            catch {
+                // A read-only or full disk only costs the cache.
+            }
+        }
+    }
+    if (memo.size >= 64)
+        memo.delete(memo.keys().next().value);
+    memo.set(key, out);
+    return out;
+}

package/dist/spec/model.js

@@ -36,7 +36,9 @@ export const KINDS = {
         person: { shape: 'box', color: 'pink', description: 'a human actor' },
         client: { shape: 'box', color: 'blue', description: 'browser, mobile app, CLI' },
         function: { shape: 'box', color: 'violet', dashed: true, description: 'serverless function or job' },
-        database: { shape: 'box', color: 'green', description: 'database or cache' },
+        database: { shape: 'box', color: 'green', description: 'relational or document database' },
+        cache: { shape: 'box', color: 'green', description: 'Redis, Memcached, CDN cache' },
+        storage: { shape: 'box', color: 'green', description: 'object or file storage' },
         queue: { shape: 'box', color: 'amber', description: 'queue, topic or event stream' },
         external: { shape: 'box', color: 'gray', dashed: true, description: 'third-party system' },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itsthecsguy/linework",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Software diagrams an AI can write and a person can edit. YAML spec in, .drawio.svg out, editable in draw.io.",
   "keywords": [
     "diagram",

package/skills/linework/SKILL.md

@@ -33,7 +33,14 @@ Never fall back to writing SVG or draw.io XML by hand. Tell the user what failed
    - `er`: database tables, their columns and how they relate.
 
    If the doc already has a Mermaid diagram, convert it instead of rewriting it: `linework import doc.md --block 1 -o docs/diagrams/x.drawio.svg`.
-3. **Write the spec** to `/tmp/spec.yaml`, or pipe it on stdin with `-` as the file. Start from the closest file in `examples/` next to this guide: `checkout.yaml` (architecture), `serverless-aws.yaml` (architecture with AWS icons), `refund-flow.yaml` (flow), `payment-state.yaml` (state), `pay-sequence.yaml` (sequence), `billing-er.yaml` (ER). The `.drawio.svg` is the source of truth, so you don't need to keep the YAML.
+3. **Write the spec** to `/tmp/spec.yaml`, or pipe it on stdin with `-` as the file. Start from the closest file in `examples/` next to this guide:
+   - architecture: `checkout.yaml` (small), `platform.yaml` (clients, nested groups, 17 nodes), `serverless-aws.yaml` (AWS icons), `gcp-ingest.yaml` (GCP icons)
+   - flow: `refund-flow.yaml` (branches), `deploy-flow.yaml` (a retry loop back to an earlier step)
+   - state: `payment-state.yaml`, `job-state.yaml` (pause/resume pairs and a self-transition)
+   - sequence: `pay-sequence.yaml` (alt, note), `auth-seq.yaml` (loop with a nested opt)
+   - ER: `billing-er.yaml` (small), `shop-er.yaml` (7 tables, composite keys)
+
+   The `.drawio.svg` is the source of truth, so you don't need to keep the YAML.
 4. **Build with a preview:**
    ```bash
    linework build /tmp/spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png

package/skills/linework/examples/auth-seq.yaml

@@ -0,0 +1,35 @@
+type: sequence
+title: OAuth login with refresh
+participants:
+  user:  { label: User, kind: person }
+  app:   { label: SPA, kind: client }
+  bff:   { label: BFF, tech: Node.js }
+  idp:   { label: Identity provider, kind: external }
+  api:   { label: Resource API }
+  cache: { label: Token cache, kind: cache }
+messages:
+  - user -> app: Sign in
+  - app -> bff: GET /login
+  - bff --> app: 302 to /authorize
+  - app -> idp: /authorize?code_challenge=...
+  - idp -> user: Login form
+  - user -> idp: Credentials + MFA
+  - idp --> app: redirect with code
+  - app -> bff: GET /callback?code
+  - bff ==> idp: POST /token (code, verifier)
+  - idp --> bff: access + refresh tokens
+  - bff -> cache: store refresh token
+  - note right of bff: tokens never reach the browser
+  - bff --> app: Set-Cookie session
+  - loop: every API call
+    do:
+      - app -> bff: GET /orders
+      - opt: access token expired
+        do:
+          - bff -> cache: read refresh token
+          - bff -> idp: POST /token (refresh)
+          - idp --> bff: new access token
+      - bff -> api: GET /orders + Bearer
+      - api -> api: validate JWT
+      - api --> bff: 200 orders
+      - bff --> app: orders

package/skills/linework/examples/deploy-flow.yaml

@@ -0,0 +1,32 @@
+type: flow
+title: Deploy pipeline
+nodes:
+  push:    { label: Push to main, kind: terminal }
+  build:   { label: Build and unit test }
+  ok:      { label: Tests pass?, kind: decision }
+  fix:     { label: Notify author, kind: error }
+  stage:   { label: Deploy to staging }
+  smoke:   { label: Run smoke tests against staging }
+  smokeok: { label: Healthy?, kind: decision }
+  canary:  { label: Canary 5% of traffic }
+  metrics: { label: Error rate under 0.1%?, kind: decision }
+  roll:    { label: Roll back canary, kind: error }
+  full:    { label: Promote to 100% }
+  done:    { label: Released, kind: terminal }
+  artifact: { label: Container image, kind: data }
+edges:
+  - push -> build
+  - build -> ok
+  - ok -> fix: "no"
+  - ok -> artifact: "yes"
+  - artifact -> stage
+  - stage -> smoke
+  - smoke -> smokeok
+  - smokeok -> canary: "yes"
+  - smokeok -> roll: "no"
+  - canary -> metrics
+  - metrics -> full: "yes"
+  - metrics -> roll: "no"
+  - roll -> fix
+  - fix -> build: retry after fix
+  - full -> done

package/skills/linework/examples/gcp-ingest.yaml

@@ -0,0 +1,21 @@
+type: architecture
+title: Ingest pipeline on GCP
+groups:
+  gcp: { label: Google Cloud project }
+nodes:
+  devices: { label: Sensors, kind: client, tech: MQTT }
+  lb:      { label: Load balancer, icon: gcp.cloud_load_balancing, in: gcp }
+  run:     { label: Ingest API, icon: gcp.cloud_run, tech: Cloud Run, in: gcp }
+  ps:      { label: telemetry, kind: queue, icon: gcp.pubsub, tech: Pub/Sub, in: gcp }
+  df:      { label: Stream job, icon: gcp.dataflow, tech: Dataflow, in: gcp }
+  bq:      { label: Warehouse, kind: database, icon: gcp.bigquery, tech: BigQuery, in: gcp }
+  gcs:     { label: Raw archive, kind: storage, icon: gcp.cloud_storage, tech: GCS, in: gcp }
+  looker:  { label: Looker, kind: external, tech: Dashboards }
+edges:
+  - devices -> lb: HTTPS
+  - lb -> run
+  - run -.-> ps: publish
+  - ps -.-> df: subscribe
+  - df -> bq: stream insert
+  - df -> gcs: write Avro
+  - looker -> bq: SQL

package/skills/linework/examples/job-state.yaml

@@ -0,0 +1,25 @@
+type: state
+title: Background job
+nodes:
+  queued:    {}
+  running:   {}
+  paused:    {}
+  retrying:  { label: Waiting to retry }
+  succeeded: { kind: success }
+  failed:    { kind: error }
+  cancelled: {}
+edges:
+  - "[*] -> queued"
+  - queued -> running: worker picks up
+  - running -> succeeded: exit 0
+  - running -> retrying: error, attempts < 5
+  - retrying -> queued: backoff elapsed
+  - running -> failed: error, attempts = 5
+  - running -> paused: pause
+  - paused -> running: resume
+  - queued -> cancelled: cancel
+  - paused -> cancelled: cancel
+  - running -> running: heartbeat
+  - "succeeded -> [*]"
+  - "failed -> [*]"
+  - "cancelled -> [*]"

package/skills/linework/examples/platform.yaml

@@ -0,0 +1,45 @@
+type: architecture
+title: Platform
+groups:
+  edge: { label: Edge }
+  cluster: { label: Kubernetes cluster }
+  core: { label: Core services, in: cluster }
+  data: { label: Data tier }
+nodes:
+  user:    { label: Customer, kind: person }
+  admin:   { label: Support agent, kind: person }
+  mobile:  { label: Mobile app, kind: client, tech: Swift }
+  web:     { label: Web dashboard, kind: client, tech: React }
+  cdn:     { label: CDN, kind: cache, tech: CloudFront, in: edge }
+  gw:      { label: API gateway, tech: Kong, in: edge }
+  auth:    { label: Auth service, tech: Go, in: core }
+  orders:  { label: Orders service, tech: Kotlin, in: core, highlight: true }
+  search:  { label: Search service, tech: Rust, in: core }
+  notify:  { label: Notification worker, kind: function, tech: Node.js, in: cluster }
+  bus:     { label: domain-events, kind: queue, tech: Kafka, in: cluster }
+  pg:      { label: Orders DB, kind: database, tech: Postgres 16, in: data }
+  es:      { label: Search index, kind: database, tech: OpenSearch, in: data }
+  redis:   { label: Session store, kind: cache, tech: Redis, in: data }
+  s3:      { label: Media bucket, kind: storage, tech: S3, in: data }
+  twilio:  { label: Twilio, kind: external, tech: SMS }
+  idp:     { label: Okta, kind: external, tech: OIDC }
+edges:
+  - user -> mobile
+  - user -> web
+  - admin -> web
+  - mobile -> cdn: assets
+  - web -> cdn: assets
+  - mobile ==> gw: HTTPS
+  - web ==> gw: HTTPS
+  - cdn -> s3: origin fetch
+  - gw -> auth: verify token
+  - auth -> idp: OIDC
+  - auth -> redis: sessions
+  - gw ==> orders: gRPC
+  - gw -> search: gRPC
+  - orders ==> pg: SQL
+  - orders -.-> bus: OrderPlaced
+  - bus -.-> search: reindex
+  - bus -.-> notify: consume
+  - search -> es: query
+  - notify -> twilio: send SMS

package/skills/linework/examples/shop-er.yaml

@@ -0,0 +1,26 @@
+type: er
+title: Storefront schema
+nodes:
+  customers:
+    fields: [id: uuid pk, email: text unique, name: text, created_at: timestamptz]
+  addresses:
+    fields: [id: uuid pk, customer_id: uuid fk, line1: text, city: text, country: char(2)]
+  orders:
+    fields: [id: uuid pk, customer_id: uuid fk, shipping_address_id: uuid fk, status: order_status, total_cents: bigint, placed_at: timestamptz null]
+  order_items:
+    fields: [order_id: uuid pk fk, product_id: uuid pk fk, quantity: int, unit_price_cents: bigint]
+  products:
+    fields: [id: uuid pk, sku: text unique, title: text, price_cents: bigint]
+  inventory:
+    fields: [product_id: uuid pk fk, warehouse: text pk, on_hand: int]
+  payments:
+    kind: external
+    fields: [id: text pk, order_id: uuid fk, provider: text]
+edges:
+  - addresses }o--|| customers: has
+  - orders }o--|| customers: placed by
+  - orders }o--|| addresses: ships to
+  - order_items }|--|| orders: contains
+  - order_items }o--|| products: of
+  - inventory }o--|| products: stocks
+  - payments |o..|| orders: pays

package/skills/linework/references/style-guide.md

@@ -38,9 +38,17 @@ Linework handles the layout and the look. These rules are about content, which i
 - **Keep error and success kinds for real errors and successes.** They're red and green in every style.
 - **Pick the style for the medium**: `clean` for docs and READMEs, `dark` for dark-mode pages, `soft` for slides, `sketch` for early drafts, `blueprint` for technical deep dives. Use one style across all the diagrams in a doc.
 
+## Order
+
+Layout reads the spec top to bottom, so the order you write things in shows up in the picture.
+
+- **List nodes and edges in reading order**: the entry point first, then each step as the request or flow reaches it. A flow's main path then runs straight down, and an edge back to an earlier node (a retry, a resume) is drawn as the loop it is.
+- **Write a reply after its call** (`api -> stripe`, then `stripe -.-> api`). The pair is drawn side by side.
+- **In ER, name foreign keys after the table they point at**: `customer_id` for `customers`, `shipping_address_id` for `addresses`. The relationship line then attaches to that row and to the other table's primary key. A key named anything else attaches to the table as a whole.
+
 ## Direction
 
-- Leave out `direction` on the first build. `auto` tries both and keeps the one that fits a doc page, which is about 800px wide.
+- Leave out `direction` on the first build. `auto` tries both and keeps the one that fits a doc page, which is about 800px wide. ER diagrams always run left to right, since relationships attach to the sides of the key rows.
 - Set it only after looking at the result, and only if it reads wrong. A short linear pipeline of 5 or fewer steps can read better as LR.
 - Don't force LR on a diagram with more than about 6 nodes in a row. It comes out 1,500px or more wide, and embedded in a doc its text shrinks to unreadable. `check` warns about this as `too-wide`.