@caddis/cli 0.4.44 → 0.4.45

package/bundles/antigravity-plugin/skills/flow-studio/templates/engine.shell.html

@@ -0,0 +1,61 @@
+<!doctype html>
+<!--
+  flow-studio page (generated). Do not edit this file by hand.
+  Source: .github/skills/frontend/flow-studio (src/*.ts, src/styles.css, templates/engine.shell.html).
+  Rebuild the engine:  node --experimental-strip-types scripts/build-engine.mjs
+  Build a page:        node --experimental-strip-types scripts/build.mjs model.json out.html
+  The model and the notes are JSON in the two script tags at the end of the body.
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>flow-studio</title>
+<style id="state-css"></style>
+<style>/*__CSS__*/</style>
+</head>
+<body>
+<header class="top">
+  <span class="brand"><i></i>flow-studio</span>
+  <span class="spacer"></span>
+  <button id="notesBtn" type="button" aria-pressed="false">Implementation notes (N)</button>
+  <button id="theme" type="button" aria-label="Toggle light and dark">☀ / ☾</button>
+</header>
+<main>
+  <div class="titlerow"><h1 id="title"></h1><span class="readline" id="readat"></span></div>
+  <p class="help" id="help"></p>
+
+  <section class="summary"><div class="layerstrip" id="layerstrip" aria-label="Completeness by column"></div><div class="tiles" id="kpis" aria-label="Summary"></div></section>
+
+  <div class="toolbar">
+    <div class="seggrp" role="tablist" aria-label="View" id="modeSwitch"></div>
+    <input id="q" type="search" placeholder="Find a group or member…  ( / )" aria-label="Find a group or member">
+    <span id="matchinfo" class="note" style="margin:0"></span>
+  </div>
+
+  <div class="workspace" id="workspace">
+    <section class="canvaswrap">
+      <div id="viewport" tabindex="0" role="application" aria-label="Flow canvas. Scroll to zoom, drag to pan. Keys: V select, H hand, plus and minus zoom, 0 fit, 1 actual size, F zoom to selection, arrows pan.">
+        <div id="world"><svg id="edges" aria-hidden="true"><defs><marker id="arr" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="0"><path d="M0 0 L8 4 L0 8 z" fill="context-stroke"/></marker></defs><g id="edgeLayer"></g></svg></div>
+        <div id="cols" aria-hidden="true"></div>
+        <div id="tools" role="toolbar" aria-label="Canvas controls" aria-orientation="vertical"></div>
+        <div id="zoomLabel" aria-hidden="true">100%</div>
+      </div>
+      <div class="keyline" id="legend" aria-label="Legend"></div>
+      <aside class="insp" id="inspector" aria-label="Inspector" aria-hidden="true"></aside>
+    </section>
+  </div>
+  <div id="live" class="sr" role="status" aria-live="polite"></div>
+
+  <div class="ledger" id="ledger"></div>
+  <details class="tableview"><summary>Table view</summary><table class="sources" id="tbl"></table></details>
+  <details class="spec" id="spec"><summary>Model reference (for the person or agent who builds this)</summary><div id="specbody"></div></details>
+</main>
+<footer id="footer"></footer>
+<aside id="drawer" aria-label="Implementation notes"><h2>Implementation notes</h2><p class="note">Numbered markers on the page match these cards. Hover a card to find its place; click a marker to jump to its card.</p><div id="notelist"></div></aside>
+
+<script type="application/json" id="flow-model">/*__MODEL__*/{}</script>
+<script type="application/json" id="flow-notes">/*__NOTES__*/[]</script>
+<script>/*__ENGINE__*/</script>
+</body>
+</html>

package/bundles/antigravity-plugin/skills/flow-studio/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "types": []
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/README.md

@@ -0,0 +1,53 @@
+# flow-studio (engine source)
+
+Stage S1a of the `flow-studio` skill: a model file (JSON) describes a flow, lifecycle or journey, and one
+engine draws it as a self-contained HTML page with pan and zoom, lanes, linked nodes, a slide-in
+inspector, motion that carries state, and numbered implementation notes. The design is in
+`.caddis/plans/flow-studio-skill-design.md`; the plan for this stage is `.caddis/plans/flow-studio-s1a-plan.md`.
+There is no `SKILL.md` yet: the playbook arrives in stage S2.
+
+## Use it
+
+```bash
+# from this folder (Node 22.6 or newer)
+node --experimental-strip-types scripts/validate.mjs examples/lineage.json
+node --experimental-strip-types scripts/build.mjs examples/lineage.json out/lineage.html
+```
+
+Open `out/lineage.html`. It has no network access and no libraries.
+
+`build.mjs` embeds the model's own `notes` plus any extra notes from `--notes notes.json` (the model's
+notes come first, then the file's). Note anchors are CSS selectors for parts of the page, for example
+`#viewport`.
+
+## Check a page
+
+The harness drives a real browser. Run it from a folder whose `node_modules` has `playwright`
+(it is looked up from the current folder, not from this one):
+
+```bash
+node /path/to/flow-studio/scripts/check.mjs out/lineage.html --out shots --hostile out/hostile.html --channel msedge
+```
+
+It checks structure (no overlap, links touch their nodes, text stays inside cards, readable first view),
+interaction (zoom, pan, select, what-if, view switch), accessibility (names, focus, contrast in both themes,
+reduced motion), safety (no network, hostile text stays inert) and performance (200 nodes). Exit code 0 means
+every check passed.
+
+`scripts/lib/check-selftest.test.mjs` feeds the harness pages with one deliberate defect each and fails
+if a defect is not caught. It is skipped when Playwright cannot be resolved, so run it from a folder that has
+it: `FLOW_STUDIO_CHANNEL=msedge node --test /path/to/flow-studio/scripts/lib/check-selftest.test.mjs`.
+
+## Develop it
+
+- The source of truth is `src/*.ts`. The pure modules (`model`, `viewport`, `routing`, `trace`, `layout`,
+  `rules`, `stateCss`) have unit tests. The DOM modules (`render`, `controls`, `interact`, `inspector`,
+  `chrome`, `notes`, `engine`) are tested through the check harness.
+- `npm test` runs the unit tests (`node --experimental-strip-types --test`).
+- `templates/engine.html` is generated and committed. After you change `src/` or `templates/engine.shell.html`,
+  run `node --experimental-strip-types scripts/build-engine.mjs`. A test fails when the committed file is stale.
+- `build-engine.mjs` needs `esbuild`. It looks in this folder, then in the caddis `cli/` folder, then in the
+  current folder. In a caddis checkout, `cli/node_modules` already has it. Elsewhere, run `npm i -D esbuild`. The stale-engine check compares bytes, so use the same esbuild version as the checkout that committed the file (the caddis `cli/` one).
+- Type check with `tsc -p tsconfig.json` (TypeScript from `cli/node_modules` or your own install).
+- Examples use fictional data only: this repository is public.
+- Delete the `out/` folder before exporting bundles. It is ignored by git but not by a file copy.

package/bundles/codex/.codex/skills/frontend/flow-studio/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: flow-studio
+description: Design an interactive flow, lifecycle or journey page (nodes, lanes, links, motion, inspector, notes) from a JSON model as a self-contained demo, then build it in an app. Use for lineage, pipelines, ticket or agent journeys.
+---
+
+# flow-studio
+
+Turns a one-paragraph brief into an explorable page: stages across, lanes down, linked nodes, pan and zoom,
+a slide-in inspector, motion that carries meaning, and numbered implementation notes. One JSON **model**
+describes the scenario. One engine draws it. A check script proves it is sound.
+
+Use it for: data lineage and dependency impact, a ticket or case lifecycle, an agent or customer journey, a CI/CD
+or release pipeline, an approval flow, an incident timeline, a service map. See `references/patterns.md`.
+Not for: a static screen or UI variants (use `mockup` or `sketch`), a chart, a graph with more than 300 nodes.
+
+## What works today (version 0.1)
+
+Left-to-right flows in **columns** (stages) and **lanes** (apps, systems or actors): states with their own look
+and motion, portal chips for shared nodes, wide placeholders for what is not recorded, two or more views
+(for example Today and Complete), search, a what-if action (a red ripple downstream), a table view, and notes.
+
+**Not yet** (planned, do not promise them): links that go back to an earlier stage (loops), gateway diamonds,
+automatic placement, token playback along a path, live data updates, free x and y placement. If the scenario
+needs a loop, show the return as its own node in a later column (for example "Reopened") and say so.
+
+## Process: demo mode
+
+1. **Ask at most three questions**: what is the page for, who reads it, and what are the nouns (the stages, the
+   lanes, the states). If the brief already says, ask none.
+2. **Map the scenario** to the model (`references/patterns.md` has a recipe per scenario):
+   columns = stages left to right, lanes = who or what owns the row, states = the vocabulary (for example
+   new, open, waiting, breached, resolved), nodes = the things, links = the flow.
+3. **Write `model.json`.** Fields are in `model.schema.json`; `examples/lineage.json` is a complete model.
+4. **Validate:** `node --experimental-strip-types scripts/validate.mjs model.json`. Fix every error. Read every
+   warning.
+5. **Build:** `node --experimental-strip-types scripts/build.mjs model.json out/page.html`. It is one file with
+   no network use.
+6. **Check:** from a folder that has `playwright`:
+   `node <skill folder>/scripts/check.mjs out/page.html --out shots [--channel msedge]`.
+   Every check must pass. Open the screenshots and look at them: the checks do not judge taste.
+7. **Show** the page and the screenshots. Do not call it done until the checks pass and you have looked.
+
+Paths above are relative to the folder that holds this file. Node 22.6 or newer is needed.
+
+## Design rules (the engine and the checks enforce most of them)
+
+1. **No orphan.** Every node sits in a lane and has a link. A missing neighbour is a dotted placeholder that says
+   what is missing. Never guess a link.
+2. **The first view is readable**: fit to width at zoom 0.6 or more (up to 60 groups). Key `0` shows everything.
+3. **Read left to right**, with pinned column headers and a phase ribbon.
+4. **Motion carries state**: links flow by state, gaps breathe, the selected path draws in, a what-if ripples.
+   No decorative loops, no sweeping scan line, no bounce.
+5. **No permanent side panel.** The inspector slides in on a click and closes with Esc.
+6. **Standard controls**: select, hand, zoom in and out, fit, 100 percent, zoom to selection, fullscreen, keys.
+7. **Every state has a word as well as a colour.** Contrast at least 4.5 in light and dark.
+8. **Titles stay short** (one line at the column width). Long text goes in `subtitle` or `members`.
+9. **Fixed node sizes per kind.** The engine never measures text, so layout does not depend on fonts.
+10. **Reduced motion** removes all motion and keeps the glow.
+
+## Model in one screen
+
+```
+version 1, meta {title, help, asOf, source, labels?}, layout "columns-lanes"
+columns [{id, title, short?, width, phase?}]              stages, left to right
+lanes   [{id, title, badge?, badgeTone?, note?, gap?}]    rows; gap true = dashed amber "no document" lane
+states  {id: {word, tone, border, edge, motion, bucket}} the vocabulary; bucket good|neutral|gap
+nodes   [{id, kind, lane, col, colSpan?, row, state, title, subtitle?, members?, weight?, ref?, upgrade?,
+          stateIn?, visibleIn?}]                          kind: card group chip placeholder (others draw as cards)
+links   [{id, from, to, state, label?, stateIn?, visibleIn?}]   from must be in an earlier column than to
+views   [{id, label, default?}]                           the first view is the baseline
+inspector {relations [3 of {id,label,dir,filter?}], actions [{id,label,dir,staleText}]}
+notes   [{anchor, title, text}]                           anchor is a CSS selector for a part of the page
+```
+
+Rows are numbers (1 row = 62 px). Keep nodes in one column at least 1 row apart. A lane needs about 1.75 rows of
+space between single-row lanes. `validate.mjs` checks all of this and names the node or link at fault.
+
+## Build mode: implement it in a real app
+
+Use the demo page as the visual contract and `model.schema.json` as the data contract.
+
+1. Copy the pure modules from `src/` into the app: `model.ts`, `layout.ts`, `viewport.ts`, `routing.ts`,
+   `trace.ts`, `rules.ts`, `stateCss.ts`, and their `*.test.ts` files. They have no DOM and no dependencies.
+2. Work test first: run the copied tests, then write a failing test for each change.
+3. Write the components in the app's own framework and design system (the demo's DOM and CSS are in
+   `src/render.ts`, `src/controls.ts`, `src/inspector.ts`, `src/chrome.ts`, `src/styles.css`). Feed them from the
+   app's real data through the app's hook and service layer. Make node and link ids stable (use business keys, not
+   array positions).
+4. Keep typed loading, empty and error states. A failed refresh keeps the last good graph. Never draw a missing
+   value as zero.
+5. Run `scripts/check.mjs` against the running app page for the structural, interaction and accessibility checks
+   (the page must expose the same element ids, or copy the harness and adapt it).
+
+A packaged React kit and live-update API are planned; until then, build mode is "copy the pure modules, port the
+DOM modules".
+
+## Gotchas
+
+- Examples and any committed data must be invented: a public repo must not carry real host, job or repo names.
+- A model string is data, never markup. The engine renders text safely; keep it that way in any port.
+- The caddis pool budgets all skill descriptions together. Keep this one short.
+- `templates/engine.html` is generated. After changing `src/`, run `node --experimental-strip-types
+  scripts/build-engine.mjs` (it needs `esbuild`; see `README.md`).

package/bundles/codex/.codex/skills/frontend/flow-studio/examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+Model files only. Build one with `node --experimental-strip-types scripts/build.mjs examples/<name>.json out/<name>.html`.
+
+| File | What it shows |
+|---|---|
+| `lineage.json` | A fictional data estate ("Northwind Analytics"): nine columns from source system to page, eight lanes (documented, infrastructure, gaps), four evidence states, two views (Today and Complete), portal chips, wide placeholders, the failure what-if. The proof that the generic engine reproduces a hand-built lineage page. |
+| `hostile.json` | The same model with markup and script text in every free-text field (`</script>`, an image with an `onerror`, quotes, U+2028 and U+2029). The check harness loads it to prove nothing executes. Do not use it as a template. |
+
+All data is fictional. The names are invented, and no real host, job, table or repository appears in them.
+`lineage.json` and `hostile.json` are generated by a script that is not part of the skill; edit the JSON directly.