ketatlas 0.1.0

package/templates/process/README.md

@@ -0,0 +1,14 @@
+# My KetAtlas project
+
+Run with Node.js 22 or newer:
+
+```sh
+npx ketatlas serve atlas.json
+npx ketatlas audit atlas.json --strict
+```
+
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML or build step is needed.
+
+This template models a process without HTML screens. Add a screen registry and screen nodes when needed.
+
+Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.

package/templates/process/atlas.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "./ketatlas.schema.json",
+  "version": 1,
+  "title": "Order fulfilment",
+  "screens": [],
+  "flows": [
+    {
+      "id": "fulfilment",
+      "title": "From request to delivery",
+      "group": "Operations",
+      "description": "A process can be mapped without any screens. Connect people, decisions, and external handoffs with the same viewer.",
+      "start": "received",
+      "ends": ["delivered"],
+      "nodes": [
+        {
+          "id": "received",
+          "type": "note",
+          "title": "Request received",
+          "description": "Operations checks the delivery address and confirms the requested items.",
+          "column": 0
+        },
+        {
+          "id": "ready",
+          "type": "note",
+          "title": "Ready to ship",
+          "description": "The warehouse packs the order and records the parcel weight.",
+          "column": 1
+        },
+        {
+          "id": "carrier",
+          "type": "external",
+          "title": "Carrier handoff",
+          "description": "A delivery partner accepts the parcel. This step happens outside the product.",
+          "column": 2
+        },
+        {
+          "id": "delivered",
+          "type": "note",
+          "title": "Delivery confirmed",
+          "description": "The recipient confirms delivery. Operations closes the request.",
+          "column": 3
+        },
+        {
+          "id": "restock",
+          "type": "note",
+          "title": "Wait for replenishment",
+          "description": "Purchasing requests the missing stock and notifies operations when it arrives.",
+          "column": 1,
+          "row": 1
+        }
+      ],
+      "edges": [
+        {
+          "from": "received",
+          "to": "ready",
+          "label": "Items available"
+        },
+        {
+          "from": "ready",
+          "to": "carrier",
+          "label": "Parcel collected"
+        },
+        {
+          "from": "carrier",
+          "to": "delivered",
+          "label": "Proof of delivery"
+        },
+        {
+          "from": "received",
+          "to": "restock",
+          "label": "Stock unavailable",
+          "kind": "conditional"
+        },
+        {
+          "from": "restock",
+          "to": "ready",
+          "label": "Stock received",
+          "kind": "recovery"
+        }
+      ]
+    }
+  ]
+}

package/templates/process/ketatlas.schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "KetAtlas configuration",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "title": {
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "description": {
+      "type": "string"
+    },
+    "viewport": {
+      "type": "object",
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 160,
+          "maximum": 4096
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 160,
+          "maximum": 4096
+        }
+      },
+      "required": ["width", "height"],
+      "additionalProperties": false
+    },
+    "screens": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "title": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "url": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "viewport": {
+            "type": "object",
+            "properties": {
+              "width": {
+                "type": "integer",
+                "minimum": 160,
+                "maximum": 4096
+              },
+              "height": {
+                "type": "integer",
+                "minimum": 160,
+                "maximum": 4096
+              }
+            },
+            "required": ["width", "height"],
+            "additionalProperties": false
+          },
+          "description": {
+            "type": "string"
+          },
+          "badge": {
+            "type": "string"
+          }
+        },
+        "required": ["id", "title", "url"],
+        "additionalProperties": false
+      }
+    },
+    "flows": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "title": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "group": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "start": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "ends": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+            }
+          },
+          "nodes": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "screen": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "type": {
+                  "enum": ["screen", "note", "external"]
+                },
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "column": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 100
+                },
+                "row": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 100
+                }
+              },
+              "required": ["id"],
+              "additionalProperties": false
+            }
+          },
+          "edges": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "from": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "to": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "label": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "kind": {
+                  "enum": ["primary", "conditional", "recovery"]
+                }
+              },
+              "required": ["from", "to", "label"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": ["id", "title", "nodes", "edges"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["version", "title", "flows"],
+  "additionalProperties": false
+}

package/templates/web/README.md

@@ -0,0 +1,14 @@
+# My KetAtlas project
+
+Run with Node.js 22 or newer:
+
+```sh
+npx ketatlas serve atlas.json
+npx ketatlas audit atlas.json --strict
+```
+
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML or build step is needed.
+
+Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
+
+Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.

package/templates/web/atlas.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "./ketatlas.schema.json",
+  "version": 1,
+  "title": "Purchase approval",
+  "screens": [
+    {
+      "id": "request-list",
+      "title": "Purchase requests",
+      "url": "./screens/portal.html?screen=list",
+      "viewport": {
+        "width": 1280,
+        "height": 800
+      },
+      "badge": "Web"
+    },
+    {
+      "id": "request-review",
+      "title": "Review purchase request",
+      "url": "./screens/portal.html?screen=review",
+      "viewport": {
+        "width": 1280,
+        "height": 800
+      },
+      "badge": "Web"
+    },
+    {
+      "id": "approved",
+      "title": "Approval recorded",
+      "url": "./screens/portal.html?screen=approved",
+      "viewport": {
+        "width": 1280,
+        "height": 800
+      },
+      "badge": "Web"
+    }
+  ],
+  "flows": [
+    {
+      "id": "purchase",
+      "title": "Review a purchase request",
+      "group": "Web portal",
+      "description": "Open a pending request, review its items, and approve it. Web screens retain their 1280 × 800 layout.",
+      "nodes": [
+        {
+          "id": "inbox",
+          "screen": "request-list"
+        },
+        {
+          "id": "review",
+          "screen": "request-review"
+        },
+        {
+          "id": "approved",
+          "screen": "approved"
+        }
+      ],
+      "edges": [
+        {
+          "from": "inbox",
+          "to": "review",
+          "label": "Open request"
+        },
+        {
+          "from": "review",
+          "to": "approved",
+          "label": "Approve request"
+        },
+        {
+          "from": "review",
+          "to": "inbox",
+          "label": "Return to inbox",
+          "kind": "recovery"
+        }
+      ]
+    }
+  ]
+}

package/templates/web/ketatlas.schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "KetAtlas configuration",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "title": {
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "description": {
+      "type": "string"
+    },
+    "viewport": {
+      "type": "object",
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 160,
+          "maximum": 4096
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 160,
+          "maximum": 4096
+        }
+      },
+      "required": ["width", "height"],
+      "additionalProperties": false
+    },
+    "screens": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "title": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "url": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "viewport": {
+            "type": "object",
+            "properties": {
+              "width": {
+                "type": "integer",
+                "minimum": 160,
+                "maximum": 4096
+              },
+              "height": {
+                "type": "integer",
+                "minimum": 160,
+                "maximum": 4096
+              }
+            },
+            "required": ["width", "height"],
+            "additionalProperties": false
+          },
+          "description": {
+            "type": "string"
+          },
+          "badge": {
+            "type": "string"
+          }
+        },
+        "required": ["id", "title", "url"],
+        "additionalProperties": false
+      }
+    },
+    "flows": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "title": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "group": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "start": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "ends": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+            }
+          },
+          "nodes": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "screen": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "type": {
+                  "enum": ["screen", "note", "external"]
+                },
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "column": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 100
+                },
+                "row": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 100
+                }
+              },
+              "required": ["id"],
+              "additionalProperties": false
+            }
+          },
+          "edges": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "from": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "to": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "label": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "kind": {
+                  "enum": ["primary", "conditional", "recovery"]
+                }
+              },
+              "required": ["from", "to", "label"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": ["id", "title", "nodes", "edges"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["version", "title", "flows"],
+  "additionalProperties": false
+}