domainforge 0.13.0

package/docs/templates/template_explanation.md

@@ -0,0 +1,14 @@
+# Explanation Template
+
+Title:
+Summary: (Explain the concept, context and why it matters)
+
+## Details
+
+- Provide diagrams and examples
+- Clarify tradeoffs and design decisions
+
+## Links
+
+- Deeper reference pages
+- How-Tos that use the concept

package/docs/templates/template_howto.md

@@ -0,0 +1,21 @@
+# How-To Template
+
+Title:
+Summary: (1-line)
+Goal: (outcome)
+
+## Prerequisites
+
+- None
+
+## Steps (be concise)
+
+1.
+2.
+
+## Common pitfalls / Troubleshooting
+
+Links:
+
+- Tutorials
+- Reference

package/docs/templates/template_playbook.md

@@ -0,0 +1,21 @@
+# Playbook Template
+
+Title:
+Scope: (What incidents or workflows this covers)
+
+## Prerequisites and safety checks
+
+-
+
+## Step-by-step runbook
+
+1.
+2.
+
+## Rollback steps
+
+## Contacts & Escalation
+
+## Links
+
+- Related How-Tos and Reference

package/docs/templates/template_reference.md

@@ -0,0 +1,17 @@
+# Reference Template
+
+## Title
+Replace with the title of this reference.
+
+## Summary
+What this reference covers.
+
+## Shape & Schema
+
+- JSON/YAML examples if applicable
+- Code samples for API usage
+
+## Notes & Links
+
+- Backwards compatibility
+- Related APIs

package/docs/templates/template_tutorial.md

@@ -0,0 +1,24 @@
+# Tutorial Template
+
+Title:
+Audience:
+Goal:
+
+## Prerequisites
+
+- List the required tools, versions, and any environment setup.
+
+## Steps
+
+1. Step 1: Briefly describe the first action readers must take.
+2. Step 2: Explain the next key change or command to run.
+3. Step 3: Note how to verify the step or transition to the next phase.
+
+## Result / Verify
+
+## Troubleshooting
+
+## Links
+
+- Related How-Tos
+- Reference pages

package/docs/tutorials/README.md

@@ -0,0 +1,12 @@
+# Tutorials — DomainForge
+
+Purpose: Provide task-based, goal-oriented walkthroughs for users who want to accomplish a larger goal and learn by doing.
+
+MECE checklist for tutorials:
+
+- Audience: beginner/experienced
+- Learning outcome: what users will be able to do
+- Prerequisites: environment and tools
+- Step-by-step instructions with example inputs and outputs
+- Troubleshooting/FAQ
+- Links to related How-Tos and Reference docs

package/docs/tutorials/first-sea-model.md

@@ -0,0 +1,85 @@
+# Building Your First Complete SEA Model
+
+In this tutorial, we will build a comprehensive domain model for a fictional E-Commerce system. We will cover Entities, Resources, Flows, and Instances.
+
+## The Scenario
+
+We are modeling "ShopEasy", an online store. It has:
+- A **Storefront** (Web App)
+- An **Order Service** (Backend API)
+- A **Payment Gateway** (External Service)
+- An **Order Database** (Storage)
+
+## Step 1: Define Entities
+
+Create a file `shopeasy.sea`. Start by defining the active components.
+
+```sea
+@namespace "shopeasy"
+
+Entity "Storefront"
+Entity "OrderService"
+Entity "PaymentGateway"
+Entity "OrderDatabase"
+```
+
+## Step 2: Define Resources
+
+Now define the passive infrastructure.
+
+```sea
+Resource "OrderRequest" units
+Resource "OrderRecord" units
+Resource "PaymentIntent" units
+Resource "ConfirmationMessage" units
+```
+
+## Step 3: Connect with Flows
+
+Model how these components interact.
+
+```sea
+Flow "OrderRequest" from "Storefront" to "OrderService"
+Flow "OrderRecord" from "OrderService" to "OrderDatabase"
+Flow "PaymentIntent" from "OrderService" to "PaymentGateway"
+Flow "ConfirmationMessage" from "OrderService" to "Storefront"
+```
+
+## Step 4: Define Instances
+
+Model the physical deployment in the production environment.
+
+```sea
+Instance prod_order_service of "OrderService" {
+    env: "production",
+    replicas: 3
+}
+
+Instance prod_db of "OrderDatabase" {
+    env: "production",
+    region: "us-west-2"
+}
+```
+
+## Step 5: Validate
+
+Run the CLI to verify your model structure.
+
+```bash
+sea-cli parse shopeasy.sea
+```
+
+## Understanding the Output
+
+The parser confirms that:
+1. All references are valid (e.g., `Flow "OrderRequest" from "Storefront"` points to declared entities).
+2. The syntax is correct.
+3. The graph is connected.
+
+## Conclusion
+
+You have successfully modeled a microservices architecture with data flows and infrastructure definitions. This model can now be used to generate diagrams, Terraform code, or validate security policies.
+
+## See Also
+
+- [Semantic Modeling Concepts](../explanations/semantic-modeling-concepts.md)

package/docs/tutorials/getting-started.md

@@ -0,0 +1,98 @@
+# Getting Started with DomainForge
+
+This tutorial will guide you through installing the DomainForge CLI, writing your first Semantic Enterprise Architecture (SEA) model, and validating it.
+
+**Time to complete**: 15 minutes
+
+## Prerequisites
+
+- **Rust**: You need Rust and Cargo installed. [Install Rust](https://rustup.rs/).
+
+## Step 1: Install the CLI
+
+Build and install the CLI tool directly from the source.
+
+```bash
+# From the root of the domainforge repository
+cargo install --path . --features cli
+```
+
+Verify the installation:
+
+```bash
+sea-cli --version
+# Output: sea-cli 0.1.0 (or current version)
+```
+
+## Step 2: Create Your First Model
+
+Create a new file named `hello.sea` in your favorite text editor. We will model a simple "Hello World" system with a Web Server and a Database.
+
+```sea
+@namespace "hello.world"
+
+Entity "WebServer"
+Entity "UserDatabase"
+Resource "UserData" units
+Flow "UserData" from "WebServer" to "UserDatabase" quantity 1
+```
+
+## Step 3: Parse and Validate
+
+Run the CLI to parse your file. This checks for syntax errors and builds the internal graph.
+
+```bash
+sea-cli parse hello.sea
+```
+
+**Expected Output:**
+```text
+Successfully parsed hello.sea
+Found:
+  - 1 Entities
+  - 1 Resources
+  - 1 Flows
+```
+
+## Step 4: Add a Policy
+
+Let's add a rule to ensure our architecture is secure. Append this to `hello.sea`:
+
+```sea
+Policy secure_db_access as:
+    forall f in flows: (f.to = "UserDatabase" and f.quantity <= 1)
+```
+
+Run the parser again. The CLI automatically evaluates policies.
+
+```bash
+sea-cli parse hello.sea
+```
+
+**Expected Output:**
+```text
+...
+Policy Results:
+  [PASS] secure_db_access
+```
+
+## Step 5: Break the Policy
+
+Increase the quantity on the flow and re-validate to see the policy fail.
+
+```sea
+Flow "UserData" from "WebServer" to "UserDatabase" quantity 5
+```
+
+**Expected Output:**
+```text
+...
+Policy Results:
+  [FAIL] secure_db_access
+     -> Violation at Flow("UserData")
+```
+
+## Next Steps
+
+- Learn more about [Semantic Modeling Concepts](../explanations/semantic-modeling-concepts.md).
+- Try the [Python Binding Quickstart](python-binding-quickstart.md).

package/docs/tutorials/python-binding-quickstart.md

@@ -0,0 +1,107 @@
+# Python Binding Quickstart
+
+This guide shows how to use DomainForge programmatically using Python. This is useful for writing custom analysis scripts, generating reports, or integrating SEA into Python-based tooling.
+
+## Prerequisites
+
+- Python 3.8+
+- `maturin` (for building bindings locally, or install from PyPI if available)
+
+## Step 1: Installation
+
+If you are working in the repo:
+
+```bash
+# Create venv
+python -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies and build bindings
+pip install maturin
+maturin develop --features python
+```
+
+## Step 2: Create a Script
+
+Create `analyze_model.py`.
+
+```python
+import domainforge
+from domainforge import Entity, Flow
+
+# 1. Define a simple model string (or load from file)
+sea_content = """
+entity Web { type = "service" }
+resource DB { type = "database" }
+flow f1 { from = Web, to = DB, interaction = "read" }
+"""
+
+# 2. Parse the content
+try:
+    model = domainforge.parse(sea_content)
+    print("Parse successful!")
+except Exception as e:
+    print(f"Error: {e}")
+    exit(1)
+
+# 3. Inspect the graph
+print(f"Entities: {len(model.entities)}")  # Entities includes only entity objects (resources are separate)
+print(f"Flows: {len(model.flows)}")
+
+# 4. Iterate and analyze
+for flow in model.flows:
+    source = flow.from_entity
+    target = flow.to_entity
+    print(f"Flow: {source.name} -> {target.name} ({flow.interaction})")
+
+# 5. Programmatic Modification (Hypothetical API)
+# new_entity = Entity(name="Cache", type="redis")
+# model.add_entity(new_entity)
+```
+
+## Step 3: Run the Script
+
+```bash
+python analyze_model.py
+```
+
+**Expected Output:**
+```text
+Parse successful!
+Entities: 1
+Flows: 1
+Flow: Web -> DB (read)
+```
+
+## Integration with Pytest
+
+You can use DomainForge to test your architecture definitions.
+
+```python
+# test_architecture.py
+import pytest
+import domainforge
+
+def test_no_plaintext_passwords():
+    # Use parse_file if provided by the API; otherwise fallback to parse(file.contents)
+    if hasattr(domainforge, 'parse_file'):
+        model = domainforge.parse_file("production.sea")
+    else:
+        with open("production.sea") as f:
+            model = domainforge.parse(f.read())
+    for flow in model.flows:
+        # Only check properties that are part of the confirmed public API to avoid relying on internal fields.
+        payload = getattr(flow, 'payload', '')
+        encrypted = getattr(flow, 'encrypted', None)
+        if payload and "password" in str(payload).lower():
+            # Only assert encrypted if the API exposes the field; otherwise log for debugging.
+            if encrypted is not None:
+                assert encrypted == True, f"Flow {getattr(flow, 'name', '<unnamed>')} sends passwords in plain text!"
+            else:
+                # If `encrypted` is not provided, check the flow name and warn instead of failing the test
+                pytest.skip("Encrypted attribute not exposed by this API/binding; skip strict assertion")
+```
+
+## See Also
+
+- [Cross-Language Binding Strategy](../explanations/cross-language-binding-strategy.md)

package/docs/tutorials/typescript-binding-quickstart.md

@@ -0,0 +1,91 @@
+# TypeScript Binding Quickstart
+
+This guide demonstrates how to use DomainForge in a Node.js/TypeScript environment.
+
+## Prerequisites
+
+- Node.js 16+
+- npm or yarn
+
+## Step 1: Installation
+
+```bash
+npm install @godspeedai/domainforge
+# Or if building locally:
+# npm install ../domainforge-core/typescript
+```
+
+## Step 2: Create a Script
+
+Create `index.ts`.
+
+```typescript
+import { parse, Model, Flow } from '@godspeedai/domainforge';
+
+const seaContent = `
+entity API { type = "service" }
+resource Bucket { type = "storage" }
+flow upload { from = API, to = Bucket, interaction = "write" }
+`;
+
+async function main() {
+  try {
+    // 1. Parse
+    const model: Model = parse(seaContent);
+    console.log(`Parsed model with ${model.entities.length} entities.`);
+
+    // 2. Analyze
+    model.flows.forEach((flow: Flow) => {
+      console.log(`Found flow: ${flow.name}`);
+      console.log(`  From: ${flow.from.name}`);
+      console.log(`  To: ${flow.to.name}`);
+    });
+
+  } catch (error) {
+    console.error("Failed to parse SEA model:", error);
+  }
+}
+
+main();
+```
+
+## Step 3: Run
+
+```bash
+npx ts-node index.ts
+```
+
+**Expected Output:**
+```text
+Parsed model with 1 entities.
+Found flow: upload
+  From: API
+  To: Bucket
+```
+
+## Integration with Vitest
+
+```typescript
+// architecture.test.ts
+import { describe, it, expect, beforeAll } from 'vitest';
+import { parse } from '@godspeedai/domainforge';
+import * as fs from 'fs';
+
+describe('Architecture Rules', () => {
+  let model;
+  beforeAll(() => {
+    model = parse(fs.readFileSync('./system.sea', 'utf-8'));
+  });
+
+  it('should have all databases encrypted', () => {
+    const dbs = model.resources.filter(r => r.type === 'database');
+    dbs.forEach(db => {
+      expect(db.properties.encrypted).toBe(true);
+    });
+  });
+});
+```
+
+## See Also
+
+- [Cross-Language Binding Strategy](../explanations/cross-language-binding-strategy.md)

package/docs/tutorials/wasm-in-browser.md

@@ -0,0 +1,75 @@
+# Running DomainForge in the Browser (WASM)
+
+DomainForge can run entirely client-side using WebAssembly. This allows for building interactive editors or visualizers without a backend.
+
+## Prerequisites
+
+- Rust with `wasm32-unknown-unknown` target
+- `wasm-pack`
+
+## Step 1: Build WASM
+
+```bash
+# From the project root, build the WASM bundle into an example folder
+mkdir -p examples/wasm-demo
+wasm-pack build domainforge-core --target web --out-dir examples/wasm-demo/pkg --features wasm
+```
+
+## Step 2: HTML Setup
+
+Create `examples/wasm-demo/index.html`.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>SEA WASM Demo</title>
+</head>
+<body>
+    <h1>SEA Parser</h1>
+    <textarea id="input" rows="10" cols="50">
+entity Web { type = "service" }
+    </textarea>
+    <button id="parseBtn">Parse</button>
+    <pre id="output"></pre>
+
+    <script type="module">
+        import init, { Graph } from './pkg/domainforge_core.js';
+
+        async function run() {
+            await init(); // Initialize WASM module
+
+            document.getElementById('parseBtn').onclick = () => {
+                const input = document.getElementById('input').value;
+                try {
+                    const graph = Graph.parse(input);
+                    document.getElementById('output').textContent =
+                        JSON.stringify(graph.toJSON(), null, 2);
+                } catch (e) {
+                    document.getElementById('output').textContent = "Error: " + e;
+                }
+            };
+        }
+
+        run();
+    </script>
+</body>
+</html>
+```
+
+## Step 3: Serve
+
+You need a local web server to serve the WASM file (due to CORS).
+
+```bash
+# Using python
+python3 -m http.server 8000
+```
+
+Open `http://localhost:8000` in your browser (use `python3 -m http.server <port>` if you prefer another port). Click "Parse". You should see the JSON representation of the parsed model.
+
+> If you rename the crate or output path, check the generated `pkg/` folder for the exact `.js` wrapper name and exported functions, then adjust the import accordingly.
+
+## See Also
+
+- [Cross-Language Binding Strategy](../explanations/cross-language-binding-strategy.md)