@caddis/cli 0.4.43 → 0.4.45

package/bundles/codex/.codex/skills/frontend/flow-studio/model.schema.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "flow-studio model",
+  "description": "What an author writes. The engine renders it. validate.mjs also enforces rules a schema cannot (unique ids, links that point at real nodes, no overlap, no orphan).",
+  "type": "object",
+  "required": ["version", "meta", "layout", "columns", "lanes", "states", "nodes", "links"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "meta": {
+      "type": "object",
+      "required": ["title", "help", "asOf", "source"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string" },
+        "help": { "type": "string" },
+        "asOf": { "type": "string" },
+        "source": { "type": "string" },
+        "labels": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "layout": { "const": "columns-lanes" },
+    "columns": {
+      "type": "array", "minItems": 1,
+      "items": {
+        "type": "object", "required": ["id", "title", "width"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" }, "title": { "type": "string" }, "short": { "type": "string" },
+          "width": { "type": "number", "minimum": 60 }, "phase": { "type": "string" }
+        }
+      }
+    },
+    "lanes": {
+      "type": "array", "minItems": 1,
+      "items": {
+        "type": "object", "required": ["id", "title"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" }, "title": { "type": "string" }, "badge": { "type": "string" },
+          "badgeTone": { "enum": ["ok", "warn", "muted"] }, "note": { "type": "string" }, "gap": { "type": "boolean" }
+        }
+      }
+    },
+    "states": {
+      "type": "object", "minProperties": 1,
+      "additionalProperties": {
+        "type": "object", "required": ["word", "tone", "border", "edge", "motion", "bucket"], "additionalProperties": false,
+        "properties": {
+          "word": { "type": "string" },
+          "tone": { "enum": ["ok", "warn", "crit", "info", "muted", "accent"] },
+          "border": { "enum": ["solid", "dashed", "dotted"] },
+          "edge": { "enum": ["flow", "dash", "dash-short", "dot"] },
+          "motion": { "enum": ["flow", "flow-slow", "breathe", "none"] },
+          "bucket": { "enum": ["good", "neutral", "gap"] }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "kind", "lane", "col", "row", "state", "title"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "enum": ["card", "group", "chip", "gateway", "start", "end", "event", "placeholder", "note"] },
+          "lane": { "type": "string" }, "col": { "type": "integer", "minimum": 0 }, "colSpan": { "type": "integer", "minimum": 1 },
+          "row": { "type": "number" }, "state": { "type": "string" },
+          "stateIn": { "type": "object", "additionalProperties": { "type": "string" } },
+          "visibleIn": { "type": "array", "items": { "type": "string" } },
+          "title": { "type": "string" }, "subtitle": { "type": "string" },
+          "members": { "type": "array", "items": { "type": "string" } },
+          "weight": { "type": "number", "minimum": 0 }, "ref": { "type": "string" },
+          "upgrade": { "type": "string" }, "allowIsolated": { "type": "boolean" }
+        }
+      }
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "from", "to", "state"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "state": { "type": "string" },
+          "stateIn": { "type": "object", "additionalProperties": { "type": "string" } },
+          "visibleIn": { "type": "array", "items": { "type": "string" } }, "label": { "type": "string" }
+        }
+      }
+    },
+    "views": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["id", "label"], "additionalProperties": false,
+        "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "default": { "type": "boolean" } }
+      }
+    },
+    "inspector": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "relations": {
+          "type": "array", "maxItems": 3,
+          "items": {
+            "type": "object", "required": ["id", "label", "dir"], "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string" }, "label": { "type": "string" }, "dir": { "enum": ["up", "down"] },
+              "filter": { "type": "object", "additionalProperties": false, "properties": { "col": { "type": "integer" }, "kind": { "type": "string" } } }
+            }
+          }
+        },
+        "actions": {
+          "type": "array",
+          "items": {
+            "type": "object", "required": ["id", "label", "dir", "staleText"], "additionalProperties": false,
+            "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "dir": { "const": "down" }, "staleText": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "notes": {
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["anchor", "title", "text"], "additionalProperties": false,
+        "properties": { "anchor": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" } }
+      }
+    }
+  }
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "flow-studio",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --experimental-strip-types --test src/*.test.ts scripts/lib/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "build:engine": "node --experimental-strip-types scripts/build-engine.mjs",
+    "check:engine": "node --experimental-strip-types scripts/build-engine.mjs --check"
+  }
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/references/patterns.md

@@ -0,0 +1,79 @@
+# Scenario recipes
+
+Each recipe says how to express a scenario in a flow-studio model. **Proven** means an example model passes the
+check harness. **Candidate** means the recipe is written but not built yet: say so when you use it.
+Version 0.1 draws left-to-right flows only (see `SKILL.md`); where a scenario needs a loop or a branch, the
+recipe says what to do today.
+
+Common states to start from (change the words to fit the scenario):
+
+| State id | Word | tone | border | edge | motion | bucket |
+|---|---|---|---|---|---|---|
+| `ok` | OK | ok | solid | flow | flow | good |
+| `planned` | PLANNED | muted | dashed | dash | flow-slow | neutral |
+| `late` | LATE | warn | solid | flow | flow | neutral |
+| `breached` | BREACHED | crit | solid | flow | flow | gap |
+| `unknown` | NOT RECORDED | warn | dotted | dot | breathe | gap |
+
+## 1. Data lineage and dependency impact (proven: `examples/lineage.json`)
+
+- **Columns:** source, host, database, jobs, tables, refreshers, report tables, apps, pages.
+- **Lanes:** one per app or system; a lane with no document gets `gap: true` and a note saying what is missing.
+- **States:** measured, declared, inferred, not recorded. Views: Today (what is measured) and Complete (adds the
+  declared layer).
+- **Inspector:** Feeds this, Downstream, Pages (`filter: {col: <pages column>}`). **Action:** "Simulate: this stops
+  updating".
+- **Questions:** which layers matter, which sources are measured and which are declared, who owns each document.
+- **Traps:** guessing a link (use a placeholder), counting a declared snapshot as current (carry its date).
+
+## 2. Ticket, case or order lifecycle (candidate)
+
+- **Columns:** the stages (New, Triage, In progress, Waiting, Resolved, Closed). **Lanes:** the owning team or
+  system. **States:** on time, at risk, breached. **Nodes:** one card per stage and team; `weight` = open count.
+- **Loops:** "reopened" and "back to triage" are loops: not drawn yet. Add a "Reopened" node in a later column.
+- **Inspector:** Came from, Goes to, Closed. **Action:** "Simulate: SLA breach".
+- **Traps:** drawing every status as a column when only some have owners.
+
+## 3. Agent, user or customer journey (candidate)
+
+- **Columns:** phases (Discover, Try, Buy, Use, Renew) or time steps. **Lanes:** actors (customer, agent, system).
+  **Nodes:** touchpoints. **States:** smooth, friction, failure. **Metrics:** put the figure in `subtitle`.
+- **Traps:** mixing actors in one lane; no states (a journey with no pain points hides the point).
+
+## 4. Incident timeline and root cause (candidate)
+
+- **Columns:** time buckets (T-30m, T-10m, T0, T+10m, T+1h). **Lanes:** systems. **Nodes:** events.
+  **States:** normal, degraded, failed. **Action:** "Simulate: this failed" shows the blast radius.
+
+## 5. CI/CD pipeline and release train (candidate)
+
+- **Columns:** stages (commit, build, test, scan, deploy, verify). **Lanes:** environments or services.
+  **States:** passed, running, failed, skipped. **Inspector:** Upstream, Downstream, Environments.
+
+## 6. Approval or business process (candidate)
+
+- **Columns:** steps; **lanes:** roles. Branches ("approved" and "rejected") are two nodes in the next column.
+  Gateway diamonds are not drawn yet: use a card titled "Decision: ...".
+
+## 7. Service or architecture dependency map (candidate)
+
+- **Columns:** tiers (client, edge, service, data store). **Lanes:** domains. **States:** healthy, degraded, down.
+  **Action:** "Simulate: this is down" ripples to the dependents.
+
+## 8. State machine (candidate; needs loops)
+
+- Not a good fit until loop-back links exist. Draw the forward path only and list the returns in the inspector
+  (`members`).
+
+## 9 to 16. Further candidates
+
+Multi-agent or LLM orchestration trace, job schedule and batch dependency, decision tree or runbook, data model or
+entity explorer, access and permission graph, supply chain, learning path or roadmap, network topology. Start from
+recipe 1 or 5 and say they are unproven. When one passes the checks, add its model under `examples/` and change
+"candidate" to "proven" here.
+
+## Choosing the lanes (the usual mistake)
+
+If every node sits in one lane, the page has no structure: a lane answers "who or what owns this row". If there
+are more than about 10 lanes, group them (a lane per team, not per person). If a lane has no source of truth,
+mark it `gap: true` so the gap is visible instead of looking like a forgotten node.

package/bundles/codex/.codex/skills/frontend/flow-studio/scripts/build-engine.mjs

@@ -0,0 +1,55 @@
+// Build templates/engine.html from the TypeScript sources.
+//   node --experimental-strip-types scripts/build-engine.mjs           write templates/engine.html
+//   node --experimental-strip-types scripts/build-engine.mjs --check   exit 1 if the committed file is stale
+// esbuild is a dev-time tool. It is looked up in this folder, in the caddis cli folder, then in the
+// current directory. The built page has no dependency on it.
+
+import { createRequire } from "node:module";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+
+function loadEsbuild() {
+  const candidates = [join(root, "package.json"), resolve(root, "../../../../cli/package.json"), join(process.cwd(), "package.json")];
+  for (const c of candidates) {
+    if (!existsSync(dirname(c))) continue;
+    try { return createRequire(c)("esbuild"); } catch { /* try the next place */ }
+  }
+  throw new Error("esbuild was not found. Run `npm i -D esbuild` in the skill folder, or run this from the caddis checkout (cli/node_modules has it).");
+}
+
+const normalise = text => text.replace(/\r\n/g, "\n");
+
+export async function buildEngine() {
+  const esbuild = loadEsbuild();
+  const out = await esbuild.build({
+    entryPoints: [join(root, "src/engine.ts")],
+    bundle: true, format: "iife", target: "es2022", minify: false, write: false, legalComments: "none", logLevel: "silent",
+  });
+  const js = out.outputFiles[0].text;
+  if (/<\/script/i.test(js)) throw new Error("The bundle contains a closing script tag; it would end the page's script early.");
+  const css = readFileSync(join(root, "src/styles.css"), "utf8");
+  if (/<\/style/i.test(css)) throw new Error("The stylesheet contains a closing style tag; it would end the page style early.");
+  if (css.includes("/*__ENGINE__*/") || css.includes("/*__MODEL__*/") || css.includes("/*__NOTES__*/")) throw new Error("The stylesheet contains a template slot marker.");
+  const shell = readFileSync(join(root, "templates/engine.shell.html"), "utf8");
+  for (const slot of ["/*__CSS__*/", "/*__ENGINE__*/", "/*__MODEL__*/{}", "/*__NOTES__*/[]"]) {
+    if (!shell.includes(slot)) throw new Error(`The shell is missing the slot ${slot}`);
+  }
+  return normalise(shell.replace("/*__CSS__*/", () => css).replace("/*__ENGINE__*/", () => js));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const target = join(root, "templates/engine.html");
+  const html = await buildEngine();
+  if (process.argv.includes("--check")) {
+    const have = existsSync(target) ? normalise(readFileSync(target, "utf8")) : "";
+    if (have !== html) { console.error("templates/engine.html is stale. Run: node --experimental-strip-types scripts/build-engine.mjs"); process.exit(1); }
+    console.log("templates/engine.html is up to date");
+  } else {
+    writeFileSync(target, html, "utf8");
+    console.log(`wrote templates/engine.html (${html.length} bytes)`);
+  }
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/scripts/build.mjs

@@ -0,0 +1,37 @@
+// Build one self-contained HTML page from a model.
+//   node --experimental-strip-types scripts/build.mjs <model.json> <out.html> [--notes notes.json]
+// The model is validated first. Any error stops the build (exit 1). Warnings are printed.
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateModel } from "../src/model.ts";
+import { embedModel } from "./lib/embed.mjs";
+import { loadModel, report } from "./validate.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const notesAt = args.indexOf("--notes");
+const notesPath = notesAt >= 0 ? args.splice(notesAt, 2)[1] : null;
+const [modelPath, outPath] = args;
+if (!modelPath || !outPath) {
+  console.error("usage: node --experimental-strip-types scripts/build.mjs <model.json> <out.html> [--notes notes.json]");
+  process.exit(2);
+}
+
+const model = loadModel(modelPath);
+const errors = report(validateModel(model));
+if (errors) {
+  console.error(`${errors} error(s): not building.`);
+  process.exit(1);
+}
+const extra = notesPath ? loadModel(notesPath) : [];
+if (notesPath && !Array.isArray(extra)) {
+  console.error(`${notesPath} must be a JSON array of notes.`);
+  process.exit(2);
+}
+const notes = [...(Array.isArray(model.notes) ? model.notes : []), ...(Array.isArray(extra) ? extra : [])].map((n, i) => ({ ...n, id: i + 1 }));
+const shell = readFileSync(resolve(here, "../templates/engine.html"), "utf8");
+mkdirSync(dirname(resolve(outPath)), { recursive: true });
+writeFileSync(outPath, embedModel(shell, model, notes), "utf8");
+console.log(`wrote ${outPath}`);