commit 9e451469f595789385600aa5439e05844d91ce3c Author: Carlos Gutierrez Date: Fri Jan 16 09:01:29 2026 -0500 git commit -m "feat: initial release of Strata framework v0.1.0 - Static compiler with STRC pattern (Static Template Resolution with Compartmentalized Layers) - Template syntax: { } interpolation, { s-for }, { s-if/s-elif/s-else } - File types: .strata, .compiler.sts, .service.sts, .api.sts, .sts, .scss - CLI tools: strata dev, strata build, strata g (generators) - create-strata scaffolding CLI with Pokemon API example - Dev server with WebSocket HMR (Hot Module Replacement) - Documentation: README, ARCHITECTURE, CHANGELOG, CONTRIBUTING, LICENSE diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b3364d6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,65 @@ +# Dependencies +node_modules/ +.pnp +.pnp.js + +# Build outputs +bin/ +dist/ +.strata/ +*.exe +*.dll +*.so +*.dylib + +# Coverage +coverage/ +coverage.out +coverage.html +*.lcov + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ +.DS_Store + +# Environment +.env +.env.local +.env.*.local +*.local + +# Logs +logs/ +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Testing +.nyc_output/ + +# Temporary files +tmp/ +temp/ +*.tmp +*.temp + +# OS files +Thumbs.db +ehthumbs.db + +# Strata generated +examples/*/dist/ +examples/*/.strata/ + +# Go +*.test +*.prof + +# Codetyper.nvim - AI coding partner files +*.coder.* +.coder/ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..9932a47 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,860 @@ +# Strata Framework Architecture + +**Strata** = Static Template Rendering Architecture + +A compile-time web framework that resolves templates to pure HTML at build time. + +``` + ╔═══════════════════════════════════════════════════════════════════╗ + ║ ║ + ║ Code Faster. Load Quick. Deploy ASAP. ║ + ║ ║ + ╚═══════════════════════════════════════════════════════════════════╝ +``` + +--- + +## Table of Contents + +1. [Core Principles](#core-principles) +2. [Design Pattern: STRC](#design-pattern-strc) +3. [Compilation Flow](#compilation-flow) +4. [File Types & Layers](#file-types--layers) +5. [Template Syntax](#template-syntax) +6. [Import Hierarchy](#import-hierarchy) +7. [Runtime Architecture](#runtime-architecture) +8. [Dev Server Architecture](#dev-server-architecture) +9. [Future: Shared Worker](#future-shared-worker-architecture) +10. [Future: Smart Fetch](#future-smart-fetch-system) +11. [Future: Encrypted Store](#future-encrypted-store) +12. [Performance Targets](#performance-targets) + +--- + +## Core Principles + +| # | Principle | Description | +|---|-----------|-------------| +| 1 | **Static First** | All templates resolved at build time, not runtime | +| 2 | **Zero Runtime Overhead** | Output is pure HTML with no framework code | +| 3 | **Strict Separation** | Each file type has exactly one responsibility | +| 4 | **Go Compiler** | Fast builds with native performance | +| 5 | **Compartmentalized Layers** | Clear boundaries between template, data, and logic | + +--- + +## Design Pattern: STRC + +**STRC** = **S**tatic **T**emplate **R**esolution with **C**ompartmentalized Layers + +### Pattern Overview + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ BUILD TIME │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ SOURCE FILES STATIC COMPILER │ +│ ════════════ ═══════════════ │ +│ │ +│ ┌─────────────┐ │ +│ │ .strata │─────┐ │ +│ │ (Template) │ │ │ +│ └─────────────┘ │ ┌────────────────────────────────┐ │ +│ │ │ │ │ +│ ┌─────────────┐ ├─────────▶│ STRATA STATIC COMPILER │ │ +│ │ .compiler │─────┤ │ │ │ +│ │ .sts │ │ │ 1. Parse .strata to AST │ │ +│ │ (Variables) │ │ │ 2. Load .compiler.sts exports │ │ +│ └─────────────┘ │ │ 3. Resolve { variables } │ │ +│ │ │ 4. Expand { s-for } loops │ │ +│ ┌─────────────┐ │ │ 5. Evaluate { s-if } blocks │ │ +│ │ .service │─────┘ │ 6. Output pure HTML │ │ +│ │ .sts │ │ │ │ +│ │ (Logic) │ └──────────────┬─────────────────┘ │ +│ └─────────────┘ │ │ +│ │ │ +│ ┌─────────────┐ │ │ +│ │ .scss │───────────────────────────────┤ │ +│ │ (Styles) │ │ │ +│ └─────────────┘ │ │ +│ │ │ +└─────────────────────────────────────────────────┼────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ RUNTIME │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ OUTPUT │ +│ ══════ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ PURE HTML │ │ +│ │ │ │ +│ │ • No { } syntax │ │ +│ │ • No s-for directives │ │ +│ │ • No s-if conditionals │ │ +│ │ • No framework JavaScript (unless .service.sts defines) │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Optional: Runtime JavaScript from .service.sts │ │ +│ │ (Event handlers, interactivity, etc.) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Layer Responsibilities + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ STRC LAYERS │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ LAYER 1: TEMPLATE (.strata) │ +│ ═══════════════════════════ │ +│ • Pure HTML structure │ +│ • Strata directives ({ }, s-for, s-if) │ +│ • No logic, no JavaScript │ +│ • Variables injected from compiler layer │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ LAYER 2: COMPILER (.compiler.sts) │ +│ ═════════════════════════════════ │ +│ • Variable definitions │ +│ • Data structures (arrays, objects) │ +│ • Build-time constants │ +│ • Executed during compilation │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ LAYER 3: SERVICE (.service.sts) │ +│ ════════════════════════════════ │ +│ • Business logic │ +│ • API calls (build-time or runtime) │ +│ • Event handlers │ +│ • Optional browser interactivity │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ LAYER 4: API CONTRACT (.api.sts) │ +│ ════════════════════════════════ │ +│ • Declarative endpoint definitions │ +│ • Request/response schemas │ +│ • Cache policies │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ LAYER 5: UTILITIES (.sts) │ +│ ═════════════════════════ │ +│ • Pure functions │ +│ • No side effects │ +│ • Shared helpers │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Compilation Flow + +### Step-by-Step Process + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ COMPILATION PIPELINE │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ STEP 1: PARSE TEMPLATE │ +│ ══════════════════════ │ +│ │ +│ Input: Output: │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ │ │ │ └─ Interp... │ │ +│ └──────────────────────┘ └──────────────────────┘ │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ STEP 2: LOAD COMPILER SCOPE │ +│ ═══════════════════════════ │ +│ │ +│ Input: Output: │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ export const title │ │ scope = { │ │ +│ │ = 'Hello'; │ ────▶ │ title: 'Hello', │ │ +│ │ export const items │ │ items: [...] │ │ +│ │ = [...]; │ │ } │ │ +│ └──────────────────────┘ └──────────────────────┘ │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ STEP 3: RESOLVE TEMPLATE │ +│ ════════════════════════ │ +│ │ +│ Process: │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ For each AST node: │ │ +│ │ │ │ +│ │ • InterpolationNode { var } → Look up in scope, output │ │ +│ │ • ForBlockNode { s-for } → Iterate, create loop scope │ │ +│ │ • IfBlockNode { s-if } → Evaluate, include/exclude │ │ +│ │ • ElementNode
→ Output tag + recurse │ │ +│ │ • TextNode → Output as-is │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ STEP 4: OUTPUT │ +│ ══════════════ │ +│ │ +│ Result: │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │

Hello

│ │ +│ │
Item 1
│ │ +│ │
Item 2
│ │ +│ │
Item 3
│ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +│ Pure HTML. No framework syntax. No runtime overhead. │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Expression Resolution + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ EXPRESSION RESOLUTION │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ SIMPLE VARIABLE │ +│ ─────────────── │ +│ Template: { title } │ +│ Scope: { title: "Hello World" } │ +│ Output: Hello World │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ PROPERTY ACCESS │ +│ ─────────────── │ +│ Template: { user.name } │ +│ Scope: { user: { name: "Alice", age: 30 } } │ +│ Output: Alice │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ NESTED ACCESS │ +│ ───────────── │ +│ Template: { config.api.baseUrl } │ +│ Scope: { config: { api: { baseUrl: "https://..." } } } │ +│ Output: https://... │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ LOOP VARIABLE │ +│ ───────────── │ +│ Template: { s-for item in items } │ +│ { item.name } │ +│ { /s-for } │ +│ │ +│ Scope: { items: [{ name: "A" }, { name: "B" }] } │ +│ │ +│ Loop 1: loopScope = { ...scope, item: { name: "A" } } │ +│ Output: A │ +│ │ +│ Loop 2: loopScope = { ...scope, item: { name: "B" } } │ +│ Output: B │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## File Types & Layers + +### File Extension Matrix + +| Extension | Layer | Execution | Can Import | Purpose | +|-----------|-------|-----------|------------|---------| +| `.strata` | Template | Build | `.strata` | HTML structure | +| `.compiler.sts` | Compiler | Build | `.service.sts`, `.api.sts`, `.sts` | Variables | +| `.service.sts` | Service | Build + Runtime | `.api.sts`, `.sts` | Logic | +| `.api.sts` | API | Build | `.sts` | Endpoints | +| `.sts` | Utility | Both | `.sts` | Pure functions | +| `.scss` | Style | Build | - | Styles | + +### Component/Page Structure + +``` +src/pages/index/ +├── index.strata # Template (what to render) +├── index.compiler.sts # Data (what values to use) +├── index.service.sts # Logic (how it behaves) +└── index.scss # Styles (how it looks) +``` + +### File Content Examples + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ index.strata │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────┐ +│ index.compiler.sts │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ export const title = 'My Page'; │ +│ │ +│ export const items = [ │ +│ { name: 'Item 1' }, │ +│ { name: 'Item 2' }, │ +│ { name: 'Item 3' }, │ +│ ]; │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────┐ +│ index.service.sts │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ // Runtime interactivity (optional) │ +│ const mount = function() { │ +│ document.getElementById('btn') │ +│ .addEventListener('click', handleClick); │ +│ }; │ +│ │ +│ return { mount }; │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Template Syntax + +### Interpolation + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ SYNTAX: { expression } │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ Simple: { title } │ +│ Property: { user.name } │ +│ Nested: { config.api.url } │ +│ │ +│ Note: Single braces, not double {{ }} │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Loop Directive + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ SYNTAX: { s-for item in collection } ... { /s-for } │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ Basic: │ +│ { s-for user in users } │ +│
{ user.name }
│ +│ { /s-for } │ +│ │ +│ With Index: │ +│ { s-for user, index in users } │ +│
#{ index }: { user.name }
│ +│ { /s-for } │ +│ │ +│ Nested: │ +│ { s-for category in categories } │ +│

{ category.name }

│ +│ { s-for item in category.items } │ +│
{ item.name }
│ +│ { /s-for } │ +│ { /s-for } │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Conditional Directives + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ SYNTAX: { s-if } / { s-elif } / { s-else } / { /s-if } │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ Simple If: │ +│ { s-if isLoggedIn } │ +│
Welcome back!
│ +│ { /s-if } │ +│ │ +│ If-Else: │ +│ { s-if isAdmin } │ +│
Admin Panel
│ +│ { s-else } │ +│
User Dashboard
│ +│ { /s-if } │ +│ │ +│ If-Elif-Else: │ +│ { s-if role === 'admin' } │ +│
Admin
│ +│ { s-elif role === 'mod' } │ +│
Moderator
│ +│ { s-else } │ +│
User
│ +│ { /s-if } │ +│ │ +│ Negation: │ +│ { s-if !isLoggedIn } │ +│ Log In │ +│ { /s-if } │ +│ │ +│ Comparison Operators: │ +│ === == !== != > < >= <= │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Import Hierarchy + +### Strict Layer Enforcement + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ IMPORT HIERARCHY │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ │ +│ │ .strata │ │ +│ │ (Template) │ │ +│ └──────┬──────┘ │ +│ │ │ +│ │ can import │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │ .strata │ (other templates only) │ +│ └─────────────┘ │ +│ │ +│ ════════════════════════════════════════════════════════════════ │ +│ │ +│ ┌─────────────────┐ │ +│ │ .compiler.sts │ │ +│ │ (Variables) │ │ +│ └────────┬────────┘ │ +│ │ │ +│ │ can import │ +│ ▼ │ +│ ┌──────────────┼──────────────┐ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ +│ │ .service │ │ .api.sts │ │ .sts │ │ +│ │ .sts │ │ │ │ │ │ +│ └───────────┘ └───────────┘ └───────────┘ │ +│ │ +│ ════════════════════════════════════════════════════════════════ │ +│ │ +│ ┌─────────────────┐ │ +│ │ .service.sts │ │ +│ │ (Logic) │ │ +│ └────────┬────────┘ │ +│ │ │ +│ │ can import │ +│ ▼ │ +│ ┌────────┴────────┐ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌───────────┐ ┌───────────┐ │ +│ │ .api.sts │ │ .sts │ │ +│ └───────────┘ └───────────┘ │ +│ │ +│ ════════════════════════════════════════════════════════════════ │ +│ │ +│ ┌─────────────────┐ │ +│ │ .api.sts │ │ +│ │ (API Contract) │ │ +│ └────────┬────────┘ │ +│ │ │ +│ │ can import │ +│ ▼ │ +│ ┌───────────┐ │ +│ │ .sts │ │ +│ └───────────┘ │ +│ │ +│ ════════════════════════════════════════════════════════════════ │ +│ │ +│ ┌─────────────────┐ │ +│ │ .sts │ │ +│ │ (Utilities) │ │ +│ └────────┬────────┘ │ +│ │ │ +│ │ can import │ +│ ▼ │ +│ ┌───────────┐ │ +│ │ .sts │ (other utilities only) │ +│ └───────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + +VIOLATION = BUILD ERROR +``` + +--- + +## Runtime Architecture + +### Minimal Runtime + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ RUNTIME OUTPUT │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ index.html │ +│ ══════════ │ +│ │ +│ │ +│ │ +│ │ +│ │ +│ │ +│ │ +│
│ +│ │ +│ │ +│ │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ app.js │ +│ ══════ │ +│ │ +│ // Pages registry with pre-compiled HTML │ +│ const pages = { │ +│ '/': { │ +│ render() { │ +│ return `
...
`; // Pure HTML, no framework │ +│ }, │ +│ mount() { │ +│ // Optional: runtime interactivity from .service.sts │ +│ } │ +│ } │ +│ }; │ +│ │ +│ // Simple router │ +│ function mount() { │ +│ const page = pages[location.pathname] || pages['/']; │ +│ document.getElementById('app').innerHTML = page.render(); │ +│ page.mount(); │ +│ } │ +│ │ +│ mount(); │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Dev Server Architecture + +### Built-in Go Server with HMR + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ strata dev │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌───────────────┐ │ +│ │ File System │ │ +│ └───────┬───────┘ │ +│ │ │ +│ │ fsnotify │ +│ ▼ │ +│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ +│ │ Watcher │────▶│ Compiler │────▶│ Dev Server │ │ +│ │ (Go) │ │ (Go) │ │ (Go) │ │ +│ └───────────────┘ └───────────────┘ └───────┬───────┘ │ +│ │ │ +│ ┌────────┴────────┐ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌──────────┐ ┌──────────┐│ +│ │ HTTP │ │WebSocket ││ +│ │ :3000 │ │ HMR ││ +│ └──────────┘ └──────────┘│ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ WATCH TARGETS: │ +│ │ +│ src/ │ +│ ├── pages/**/*.strata → Recompile page │ +│ ├── pages/**/*.compiler.sts → Recompile page │ +│ ├── pages/**/*.service.sts → Recompile page │ +│ ├── pages/**/*.scss → Hot reload CSS │ +│ ├── components/**/* → Recompile dependents │ +│ └── ... │ +│ │ +│ strataconfig.ts → Full rebuild │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ HMR MESSAGES: │ +│ │ +│ { type: "reload" } → Full page reload │ +│ { type: "css", path: "..." } → CSS hot swap │ +│ { type: "component" } → Component reload │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Future: Shared Worker Architecture + +> **Status: Planned** + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Strata Shared Worker │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Tab 1 │ │ Tab 2 │ │ Tab 3 │ │ Tab N │ │ +│ │ tabId:a1 │ │ tabId:b2 │ │ tabId:c3 │ │ tabId:xx │ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ +│ │ │ │ │ │ +│ └─────────────┴──────┬──────┴─────────────┘ │ +│ │ │ +│ ┌────────▼────────┐ │ +│ │ Shared Worker │ │ +│ │ │ │ +│ │ ┌───────────┐ │ │ +│ │ │ Store │ │ ◄── Encrypted State │ +│ │ └───────────┘ │ │ +│ │ ┌───────────┐ │ │ +│ │ │ Cache │ │ ◄── API Response Cache │ +│ │ └───────────┘ │ │ +│ │ ┌───────────┐ │ │ +│ │ │ TabSync │ │ ◄── Tab Registry │ +│ │ └───────────┘ │ │ +│ └─────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Tab Management (Planned) + +```typescript +// Auto-generated tabId for each browser tab +const tabId = strata.tabId; // e.g., "tab_a1b2c3" + +// Tab-specific state +strata.store.setForTab(tabId, { draft: formData }); + +// Shared state (all tabs) +strata.store.setShared({ user: currentUser }); + +// Broadcast to specific tabs +strata.broadcast('logout', { reason: 'session_expired' }, ['tab_a1b2c3']); + +// Broadcast to all tabs +strata.broadcast('refresh', { entity: 'users' }); +``` + +--- + +## Future: Smart Fetch System + +> **Status: Planned** + +### Request Deduplication + +```typescript +// These calls are deduplicated - only ONE request is made +const [users1, users2, users3] = await Promise.all([ + strata.fetch('/api/users'), + strata.fetch('/api/users'), + strata.fetch('/api/users'), +]); +// All three resolve with the same data from single request +``` + +### Caching Strategy + +```typescript +strata.fetch('/api/users', { + cache: 'smart', // Default: cache until data changes + cache: 'none', // No caching + cache: '5m', // Cache for 5 minutes + cache: 'permanent', // Cache until manual invalidation + + // Stale-while-revalidate pattern + stale: '1m', // Serve stale for 1 min while fetching fresh +}); +``` + +--- + +## Future: Encrypted Store + +> **Status: Planned** + +### Build-Time Encryption + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Build Process │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. Generate encryption key at build time │ +│ key = crypto.randomBytes(32) │ +│ │ +│ 2. Embed key in compiled runtime (obfuscated) │ +│ const _k = [0x2f, 0xa1, ...]; // Split & scattered │ +│ │ +│ 3. Store data encrypted in SharedWorker │ +│ encrypted = AES256(JSON.stringify(state), key) │ +│ │ +│ 4. Browser can't read state even with DevTools │ +│ localStorage: "encrypted:a1b2c3d4e5f6..." │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Store Definition (Planned) + +```typescript +// stores/user.sts +import { createStore } from 'strata'; + +export const userStore = createStore('user', { + state: { + currentUser: null, + preferences: {}, + token: null, + }, + + actions: { + login(user, token) { + this.currentUser = user; + this.token = token; + }, + logout() { + this.currentUser = null; + this.token = null; + }, + }, + + encrypt: true, // Encrypt entire store + persist: true, // Persist to SharedWorker storage + shared: true, // Share across all tabs +}); +``` + +--- + +## Performance Targets + +| Metric | Target | Typical React | +|--------|--------|---------------| +| Build Memory | < 512MB | 8GB+ | +| Bundle Size | < 50KB | 2MB+ | +| Runtime | < 5KB | 40KB+ | +| Cold Start | < 500ms | 3s+ | +| HMR | < 100ms | 1s+ | +| TTFB | < 50ms | 200ms+ | + +--- + +## Project Structure + +``` +strata/ +├── cli/ +│ └── create-strata/ # Project scaffolding +│ └── index.js +│ +├── compiler/ +│ ├── cmd/ +│ │ └── strata/ # CLI entry point +│ │ ├── main.go +│ │ ├── dev.go +│ │ └── build.go +│ │ +│ └── internal/ +│ ├── ast/ # Abstract Syntax Tree +│ │ └── nodes.go +│ │ +│ ├── compiler/ # Static compiler +│ │ └── static.go +│ │ +│ ├── parser/ # Template parser +│ │ └── strata.go +│ │ +│ ├── server/ # Dev server +│ │ └── dev.go +│ │ +│ └── watcher/ # File watcher +│ └── watcher.go +│ +├── runtime/ # Browser runtime +│ └── strata.js +│ +├── templates/ # Project templates +│ └── default/ +│ +├── examples/ # Example projects +│ └── pokemon/ +│ +├── Makefile # Build commands +├── README.md # User documentation +├── ARCHITECTURE.md # This file +├── CHANGELOG.md # Version history +├── CONTRIBUTING.md # Contribution guidelines +└── LICENSE # Proprietary license +``` + +--- + +## Summary + +Strata implements the **STRC Pattern** (Static Template Resolution with Compartmentalized Layers) to achieve: + +1. **Build-time compilation** of all template syntax +2. **Zero runtime overhead** in production +3. **Clear separation** between template, data, and logic +4. **Strict import hierarchy** preventing layer violations +5. **Fast development** with Go-powered HMR + +The result: websites that are as fast as hand-written HTML, with the developer experience of a modern framework. + +--- + +

+ Strata - Static Template Rendering Architecture +

diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..097971c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,150 @@ +# Changelog + +All notable changes to the Strata framework will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +--- + +## [Unreleased] + +### Planned +- Component imports (`{ s-imp "@components/Button" }`) +- SCSS to CSS compilation pipeline +- Production build optimizations +- TypeScript type generation for templates +- VSCode extension for syntax highlighting +- Nested component slots + +--- + +## [0.1.0] - 2026-01-16 + +### Added + +#### Core Framework +- **Static Compiler**: Build-time template resolution engine + - Resolves all template syntax to pure HTML + - Zero runtime framework overhead + - Caches API responses during build + +- **STRC Design Pattern**: Static Template Resolution with Compartmentalized Layers + - Clear separation between template, compiler, service, and API layers + - Strict import hierarchy enforcement + - File-type based responsibility assignment + +#### Template Syntax +- **Variable Interpolation**: `{ variableName }` + - Supports dot notation for nested properties (`{ user.name }`) + - Handles strings, numbers, booleans, arrays, objects + +- **Loop Directive**: `{ s-for item in items }` ... `{ /s-for }` + - Iterates over arrays + - Optional index variable: `{ s-for item, index in items }` + - Nested loops supported + +- **Conditional Directives**: `{ s-if }`, `{ s-elif }`, `{ s-else }`, `{ /s-if }` + - Boolean evaluation + - Negation with `!` + - Comparison operators: `===`, `==`, `!==`, `!=`, `>`, `<`, `>=`, `<=` + +#### File Types +- `.strata` - HTML template files +- `.compiler.sts` - Build-time variable definitions +- `.service.sts` - Business logic layer (build + runtime) +- `.api.sts` - API contract definitions +- `.sts` - Pure utility functions +- `.scss` - Component/page styles + +#### CLI Tools +- `strata dev` - Development server with Hot Module Replacement (HMR) +- `strata build` - Production build +- `strata preview` - Preview production build +- Generator commands: + - `strata g component ` + - `strata g page ` + - `strata g service ` + - `strata g api ` + - `strata g util ` + - `strata g store ` + +#### Project Scaffolding +- `create-strata` CLI tool +- Pokemon API example template +- Index page with ASCII art branding +- Pre-configured project structure + +#### Development Server +- WebSocket-based Hot Module Replacement +- Automatic rebuild on file changes +- CSS hot reload without page refresh +- Component change detection + +#### Parser +- Custom Strata template parser +- AST-based template processing +- Balanced bracket extraction for complex structures +- JavaScript-to-JSON conversion for data parsing + +### Technical Details + +#### Compiler Implementation +- Written in Go for maximum performance +- Regex-based export extraction from `.compiler.sts` +- Recursive template resolution +- Property access chain support (`item.nested.value`) + +#### Build Process +1. Parse `.strata` template to AST +2. Load exports from `.compiler.sts` +3. Resolve all directives (for, if, interpolation) +4. Output pure HTML string +5. Bundle with optional runtime service code + +--- + +## [0.0.1] - 2026-01-15 + +### Added +- Initial project structure +- Basic Go compiler setup +- Makefile for build automation +- Development environment configuration + +--- + +## Version History Summary + +| Version | Date | Highlights | +|---------|------|------------| +| 0.1.0 | 2026-01-16 | Core framework, STRC pattern, template syntax, CLI tools | +| 0.0.1 | 2026-01-15 | Initial project setup | + +--- + +## Migration Guides + +### Migrating to 0.1.0 + +This is the first functional release. No migration required. + +--- + +## Deprecations + +None yet. + +--- + +## Security + +No security vulnerabilities reported. + +To report a security issue, please open an issue at https://github.com/CarGDev/strata/issues + +--- + +[Unreleased]: https://github.com/CarGDev/strata/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/CarGDev/strata/compare/v0.0.1...v0.1.0 +[0.0.1]: https://github.com/CarGDev/strata/releases/tag/v0.0.1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..919ba11 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,458 @@ +# Contributing to Strata + +Thank you for your interest in contributing to Strata! This document outlines the guidelines and process for contributing. + +--- + +## Development Status + +**Strata is currently in active development (pre-alpha).** + +During this phase: +- The API may change without notice +- Features may be added, modified, or removed +- Documentation may be incomplete +- Not all edge cases are handled + +--- + +## Contribution Policy + +### Current Phase: Closed Development + +At this time, **external contributions are not being accepted**. This includes: +- Pull requests +- Feature implementations +- Bug fixes (report only) + +### What You Can Do + +1. **Report Bugs**: Open an issue describing the bug +2. **Request Features**: Open an issue with your suggestion +3. **Ask Questions**: Use GitHub Discussions +4. **Provide Feedback**: Share your experience with the framework + +--- + +## How to Create an Issue + +### Step 1: Check Existing Issues + +Before creating a new issue, search existing issues to avoid duplicates: + +1. Go to [github.com/CarGDev/strata/issues](https://github.com/CarGDev/strata/issues) +2. Use the search bar with keywords related to your issue +3. Check both **Open** and **Closed** issues +4. If you find a related issue, add a comment instead of creating a duplicate + +### Step 2: Choose the Right Issue Type + +| Issue Type | When to Use | +|------------|-------------| +| **Bug Report** | Something isn't working as expected | +| **Feature Request** | You want new functionality | +| **Question** | Use GitHub Discussions instead | +| **Documentation** | Docs are missing, unclear, or incorrect | + +### Step 3: Create the Issue + +1. Go to [github.com/CarGDev/strata/issues/new/choose](https://github.com/CarGDev/strata/issues/new/choose) +2. Select the appropriate issue template +3. Fill out all required sections +4. Add relevant labels if you have permission +5. Click **Submit new issue** + +### Step 4: Follow Up + +- **Respond to questions** from maintainers promptly +- **Provide additional info** if requested +- **Test fixes** when a solution is proposed +- **Close the issue** if you find the solution yourself + +--- + +## Issue Templates + +### Bug Report Template + +Use this template when reporting bugs: + +```markdown +## Bug Report + +### Summary +A one-line description of the bug. + +### Environment +- **OS**: macOS 14.0 / Windows 11 / Ubuntu 22.04 +- **Go version**: 1.21.0 +- **Node version**: 18.0.0 +- **Strata version**: 0.1.0 + +### Steps to Reproduce +1. Create a new project with `npx create-strata my-app` +2. Add a for loop in `index.strata` +3. Run `npm run dev` +4. Observe the error + +### Expected Behavior +The for loop should render all items in the array. + +### Actual Behavior +The page renders empty. Console shows: `[error message here]` + +### Code Sample + +**index.strata** +```html + +\`\`\` + +**index.compiler.sts** +\`\`\`javascript +export const items = [ + { name: 'Item 1' }, + { name: 'Item 2' }, +]; +\`\`\` + +### Error Output +\`\`\` +[Paste full error message or stack trace here] +\`\`\` + +### Screenshots +[If applicable, add screenshots to help explain the problem] + +### Additional Context +[Any other relevant information] +``` + +### Feature Request Template + +Use this template when requesting features: + +```markdown +## Feature Request + +### Summary +A one-line description of the feature. + +### Problem Statement +Describe the problem this feature would solve. + +Example: "Currently, there's no way to import components from other files, +which means I have to copy-paste common UI elements across pages." + +### Proposed Solution +Describe how you envision this feature working. + +Example: "Add a `{ s-imp }` directive that allows importing components: +`{ s-imp Button from '@components/Button' }`" + +### Use Cases +1. Reusing header/footer across pages +2. Creating a component library +3. Sharing UI patterns between projects + +### Alternatives Considered +Other approaches you've thought about and why they don't work. + +### Additional Context +- Links to similar features in other frameworks +- Mockups or diagrams +- Priority level (nice-to-have vs. blocking) +``` + +### Documentation Issue Template + +Use this template for documentation problems: + +```markdown +## Documentation Issue + +### Type +- [ ] Missing documentation +- [ ] Incorrect documentation +- [ ] Unclear documentation +- [ ] Typo or formatting issue + +### Location +[Link to the documentation page or file path] + +### Current Content +[What the docs currently say, if applicable] + +### Suggested Change +[What the docs should say] + +### Additional Context +[Why this change would help] +``` + +--- + +## Issue Labels + +Understanding issue labels helps you categorize your report: + +| Label | Description | +|-------|-------------| +| `bug` | Something isn't working | +| `feature` | New feature request | +| `docs` | Documentation improvements | +| `question` | Further information needed | +| `good first issue` | Good for newcomers | +| `help wanted` | Extra attention needed | +| `priority: high` | Critical issue | +| `priority: low` | Nice to have | +| `wontfix` | Will not be addressed | +| `duplicate` | Already reported | + +--- + +## Tips for Good Issues + +### Do + +- **Be specific**: Include exact error messages, not "it doesn't work" +- **Be concise**: Get to the point quickly +- **Use code blocks**: Format code with triple backticks +- **Include versions**: Always mention OS, Go, Node, and Strata versions +- **One issue per report**: Don't combine multiple bugs +- **Search first**: Check if it's already reported + +### Don't + +- **Don't be vague**: "The compiler is broken" is not helpful +- **Don't include sensitive data**: No API keys, passwords, or personal info +- **Don't bump issues**: Adding "+1" doesn't help (use reactions instead) +- **Don't demand timelines**: This is open development +- **Don't cross-post**: One issue in one place + +--- + +## Code of Conduct + +### Our Standards + +- Be respectful and inclusive +- Provide constructive feedback +- Focus on the issue, not the person +- Accept responsibility for mistakes + +### Unacceptable Behavior + +- Harassment or discrimination +- Trolling or insulting comments +- Personal or political attacks +- Publishing private information + +--- + +## Development Setup (For Authorized Contributors) + +If you have been authorized to contribute: + +### Prerequisites + +```bash +# Required +go version # 1.21+ +node --version # 18+ +make --version + +# Optional +code --version # VSCode for development +``` + +### Clone and Build + +```bash +# Clone repository +git clone https://github.com/CarGDev/strata.git +cd strata + +# Build the compiler +make build + +# Run tests +make test + +# Install locally +make install +``` + +### Project Structure + +``` +strata/ +├── cli/ +│ └── create-strata/ # Project scaffolding tool +├── compiler/ +│ ├── cmd/ +│ │ └── strata/ # CLI entry point +│ └── internal/ +│ ├── ast/ # Abstract Syntax Tree +│ ├── compiler/ # Static compiler +│ ├── parser/ # Template parser +│ ├── server/ # Dev server +│ └── watcher/ # File watcher +├── runtime/ # Browser runtime (minimal) +├── templates/ # Project templates +├── examples/ # Example projects +└── scripts/ # Build scripts +``` + +### Coding Standards + +#### Go Code + +- Follow [Effective Go](https://golang.org/doc/effective_go) +- Use `gofmt` for formatting +- Add comments for exported functions +- Write tests for new functionality + +```go +// Good +// CompilePage compiles a page directory to static HTML. +// It reads the .strata template and .compiler.sts variables, +// resolves all directives, and returns pure HTML. +func (c *StaticCompiler) CompilePage(pageDir string) (*CompiledModule, error) { + // ... +} +``` + +#### JavaScript/TypeScript + +- Use ES modules +- Prefer `const` over `let` +- No semicolons (project style) +- Use meaningful variable names + +```javascript +// Good +const formatDate = (date) => { + return new Intl.DateTimeFormat('en-US').format(date) +} + +// Bad +var f = function(d) { return d.toString(); }; +``` + +### Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): + +[optional body] + +[optional footer] +``` + +Types: +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation +- `style`: Formatting (no code change) +- `refactor`: Code restructuring +- `test`: Adding tests +- `chore`: Maintenance + +Examples: +``` +feat(compiler): add support for nested loops + +fix(parser): handle escaped quotes in attributes + +docs(readme): update installation instructions +``` + +### Branch Naming + +``` +feature/description +fix/description +docs/description +refactor/description +``` + +Examples: +``` +feature/add-component-imports +fix/parser-nested-loops +docs/update-api-reference +``` + +--- + +## Testing + +### Running Tests + +```bash +# All tests +make test + +# Specific package +go test ./compiler/internal/parser/... + +# With coverage +go test -cover ./... +``` + +### Writing Tests + +```go +func TestCompilePage_WithForLoop(t *testing.T) { + compiler := NewStaticCompiler("/test/project") + + result, err := compiler.CompilePage("/test/project/src/pages/index") + + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + if !strings.Contains(result.HTML, "expected content") { + t.Errorf("expected HTML to contain 'expected content', got: %s", result.HTML) + } +} +``` + +--- + +## Review Process + +For authorized contributors: + +1. Create a branch from `main` +2. Make your changes +3. Write/update tests +4. Update documentation +5. Submit a pull request +6. Address review feedback +7. Squash and merge when approved + +--- + +## Questions? + +- **GitHub Issues**: For bugs and features +- **GitHub Discussions**: For questions and ideas +- **GitHub**: [@CarGDev](https://github.com/CarGDev) + +--- + +## License Reminder + +By contributing to Strata, you agree that your contributions will be licensed under the same terms as the project. Currently, Strata is proprietary software under development. + +--- + +Thank you for your interest in Strata! diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1acc77c --- /dev/null +++ b/LICENSE @@ -0,0 +1,113 @@ +STRATA PROPRIETARY LICENSE +Version 1.0, January 2026 + +Copyright (c) 2026 Carlos Gutierrez (CarGDev). All Rights Reserved. + +================================================================================ + +NOTICE: THIS SOFTWARE IS IN DEVELOPMENT AND NOT AVAILABLE FOR PUBLIC USE + +================================================================================ + +1. DEFINITIONS + +"Software" refers to the Strata framework, including but not limited to: +- Source code +- Compiled binaries +- Documentation +- Templates +- Examples +- Associated tooling + +"Licensor" refers to Carlos Gutierrez (CarGDev). + +"You" refers to any individual or entity accessing this Software. + +2. GRANT OF RIGHTS + +None. This Software is proprietary and confidential. No rights are granted +under this license. + +3. RESTRICTIONS + +You may NOT: + +a) Use the Software for any purpose, commercial or non-commercial +b) Copy, modify, or distribute the Software or any portion thereof +c) Reverse engineer, decompile, or disassemble the Software +d) Remove or alter any proprietary notices or labels on the Software +e) Sublicense, sell, rent, lease, or lend the Software +f) Create derivative works based on the Software +g) Use the Software to develop competing products +h) Share access credentials or bypass access controls + +4. CONFIDENTIALITY + +The Software contains trade secrets and proprietary information of the +Licensor. You agree to maintain the confidentiality of the Software and +not disclose any part of it to third parties without prior written consent +from the Licensor. + +5. NO WARRANTY + +THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. + +6. LIMITATION OF LIABILITY + +IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING +FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +7. TERMINATION + +This license is effective until terminated. Your rights under this license +will terminate automatically without notice if you fail to comply with any +of its terms. Upon termination, you must destroy all copies of the Software +in your possession. + +8. GOVERNING LAW + +This license shall be governed by and construed in accordance with the laws +of the State of California, United States, without regard to its conflict +of law provisions. + +9. ENTIRE AGREEMENT + +This license constitutes the entire agreement between you and the Licensor +concerning the Software and supersedes all prior or contemporaneous +understandings. + +10. SEVERABILITY + +If any provision of this license is held to be unenforceable, such provision +shall be reformed only to the extent necessary to make it enforceable, and +the remaining provisions shall continue in full force and effect. + +11. CONTACT + +For licensing inquiries, please contact: + +Carlos Gutierrez (CarGDev) +https://github.com/CarGDev + +================================================================================ + +DEVELOPMENT PREVIEW NOTICE + +This Software is currently in a development preview phase. It is made +available solely for internal evaluation and development purposes by +authorized personnel. + +Access to this repository does not constitute a license to use, modify, +or distribute the Software. Authorized users are bound by separate +agreements governing their access. + +Future versions may be released under different license terms at the sole +discretion of the Licensor. + +================================================================================ + +Last Updated: January 16, 2026 diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..bebe24c --- /dev/null +++ b/Makefile @@ -0,0 +1,283 @@ +.PHONY: build install install-global install-local uninstall upgrade doctor \ + dev clean test example-build \ + gen-component gen-page gen-store \ + setup link help + +# ============================================================================ +# BUILD +# ============================================================================ + +# Build the Go compiler +build: + @echo "Building Strata compiler..." + @mkdir -p bin + @cd compiler && go mod tidy && go build -ldflags="-s -w" -o ../bin/strata ./cmd/strata + @echo "Done! Binary at ./bin/strata" + +# Build with race detector (for development) +build-debug: + @echo "Building Strata compiler (debug)..." + @mkdir -p bin + @cd compiler && go build -race -o ../bin/strata-debug ./cmd/strata + @echo "Done! Binary at ./bin/strata-debug" + +# ============================================================================ +# INSTALLATION +# ============================================================================ + +# Full installation (local by default) +install: + @chmod +x scripts/install.sh + @./scripts/install.sh + +# Install globally to /usr/local/bin +install-global: + @chmod +x scripts/install.sh + @./scripts/install.sh --global + +# Install locally to ~/.strata only +install-local: + @chmod +x scripts/install.sh + @./scripts/install.sh --local + +# Quick setup (build + npm install, no shell config) +setup: build + @echo "Installing npm dependencies..." + @npm install --silent + @echo "" + @echo "Strata setup complete!" + @echo " Binary: ./bin/strata" + @echo "" + @echo "Run 'make install' for full installation with shell config." + +# Link binary to /usr/local/bin (quick global access) +link: build + @echo "Linking strata to /usr/local/bin..." + @if [ -w /usr/local/bin ]; then \ + ln -sf "$(PWD)/bin/strata" /usr/local/bin/strata; \ + else \ + sudo ln -sf "$(PWD)/bin/strata" /usr/local/bin/strata; \ + fi + @echo "Done! 'strata' command is now available globally." + +# Unlink from /usr/local/bin +unlink: + @echo "Unlinking strata from /usr/local/bin..." + @if [ -w /usr/local/bin ]; then \ + rm -f /usr/local/bin/strata; \ + else \ + sudo rm -f /usr/local/bin/strata; \ + fi + @echo "Done!" + +# Uninstall Strata +uninstall: + @chmod +x scripts/uninstall.sh + @./scripts/uninstall.sh + +# Uninstall without confirmation +uninstall-force: + @chmod +x scripts/uninstall.sh + @./scripts/uninstall.sh --force + +# ============================================================================ +# MAINTENANCE +# ============================================================================ + +# Upgrade to latest version +upgrade: + @chmod +x scripts/upgrade.sh + @./scripts/upgrade.sh + +# Check for updates only +upgrade-check: + @chmod +x scripts/upgrade.sh + @./scripts/upgrade.sh --check + +# Diagnose installation issues +doctor: + @chmod +x scripts/doctor.sh + @./scripts/doctor.sh + +# Auto-fix installation issues +doctor-fix: + @chmod +x scripts/doctor.sh + @./scripts/doctor.sh --fix + +# ============================================================================ +# DEVELOPMENT +# ============================================================================ + +# Run dev server on example app +dev: build + @cd examples/basic-app && ../../bin/strata dev + +# Run dev server with browser open +dev-open: build + @cd examples/basic-app && ../../bin/strata dev --open + +# Build example app for production +example-build: build + @cd examples/basic-app && ../../bin/strata build + +# Preview example app production build +example-preview: build + @cd examples/basic-app && ../../bin/strata preview + +# Watch and rebuild compiler on changes +watch: + @echo "Watching for compiler changes..." + @while true; do \ + find compiler -name '*.go' | entr -d make build; \ + done + +# ============================================================================ +# TESTING +# ============================================================================ + +# Run all tests +test: + @echo "Running Go tests..." + @cd compiler && go test ./... + @echo "" + @echo "Running npm tests..." + @npm test + +# Run Go tests only +test-go: + @cd compiler && go test ./... + +# Run Go tests with verbose output +test-go-verbose: + @cd compiler && go test -v ./... + +# Run npm tests only +test-npm: + @npm test + +# Run tests with coverage +test-coverage: + @cd compiler && go test -coverprofile=coverage.out ./... + @cd compiler && go tool cover -html=coverage.out -o coverage.html + @echo "Coverage report: compiler/coverage.html" + +# ============================================================================ +# CODE GENERATION +# ============================================================================ + +# Generate component (usage: make gen-component NAME=MyComponent) +gen-component: build + @if [ -z "$(NAME)" ]; then \ + echo "Usage: make gen-component NAME=MyComponent"; \ + exit 1; \ + fi + @cd examples/basic-app && ../../bin/strata generate component $(NAME) + +# Generate page (usage: make gen-page NAME=about) +gen-page: build + @if [ -z "$(NAME)" ]; then \ + echo "Usage: make gen-page NAME=about"; \ + exit 1; \ + fi + @cd examples/basic-app && ../../bin/strata generate page $(NAME) + +# Generate store (usage: make gen-store NAME=cart) +gen-store: build + @if [ -z "$(NAME)" ]; then \ + echo "Usage: make gen-store NAME=cart"; \ + exit 1; \ + fi + @cd examples/basic-app && ../../bin/strata generate store $(NAME) + +# Shorthand aliases +c: gen-component +p: gen-page +s: gen-store + +# ============================================================================ +# CLEANUP +# ============================================================================ + +# Clean all build artifacts +clean: + @rm -rf bin/ + @rm -rf dist/ + @rm -rf .strata/ + @rm -rf examples/basic-app/dist/ + @rm -rf examples/basic-app/.strata/ + @rm -rf compiler/coverage.out + @rm -rf compiler/coverage.html + @echo "Cleaned!" + +# Deep clean (includes node_modules and go cache) +clean-all: clean + @rm -rf node_modules/ + @cd compiler && go clean -cache + @echo "Deep cleaned!" + +# ============================================================================ +# RELEASE +# ============================================================================ + +# Build release binaries for all platforms +release: + @echo "Building release binaries..." + @mkdir -p dist/release + @cd compiler && GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o ../dist/release/strata-darwin-amd64 ./cmd/strata + @cd compiler && GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o ../dist/release/strata-darwin-arm64 ./cmd/strata + @cd compiler && GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o ../dist/release/strata-linux-amd64 ./cmd/strata + @cd compiler && GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o ../dist/release/strata-linux-arm64 ./cmd/strata + @cd compiler && GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o ../dist/release/strata-windows-amd64.exe ./cmd/strata + @echo "Release binaries built in dist/release/" + +# ============================================================================ +# HELP +# ============================================================================ + +# Show help +help: + @echo "" + @echo "Strata Framework - Development Commands" + @echo "========================================" + @echo "" + @echo "Installation:" + @echo " make install Full installation with shell config" + @echo " make install-global Install globally to /usr/local/bin" + @echo " make install-local Install locally to ~/.strata" + @echo " make setup Quick setup (build + npm, no shell config)" + @echo " make link Link binary to /usr/local/bin" + @echo " make uninstall Uninstall Strata" + @echo "" + @echo "Maintenance:" + @echo " make upgrade Upgrade to latest version" + @echo " make upgrade-check Check for updates" + @echo " make doctor Diagnose installation issues" + @echo " make doctor-fix Auto-fix installation issues" + @echo "" + @echo "Building:" + @echo " make build Build the Go compiler" + @echo " make build-debug Build with race detector" + @echo " make release Build release binaries for all platforms" + @echo "" + @echo "Development:" + @echo " make dev Run dev server (examples/basic-app)" + @echo " make dev-open Run dev server and open browser" + @echo " make example-build Build example app for production" + @echo " make example-preview Preview production build" + @echo " make watch Watch and rebuild compiler" + @echo "" + @echo "Testing:" + @echo " make test Run all tests" + @echo " make test-go Run Go tests only" + @echo " make test-npm Run npm tests only" + @echo " make test-coverage Run tests with coverage report" + @echo "" + @echo "Code Generation:" + @echo " make gen-component NAME=Button Generate component" + @echo " make gen-page NAME=about Generate page" + @echo " make gen-store NAME=cart Generate store" + @echo "" + @echo "Cleanup:" + @echo " make clean Clean build artifacts" + @echo " make clean-all Deep clean (includes node_modules)" + @echo "" diff --git a/README.md b/README.md new file mode 100644 index 0000000..ab59504 --- /dev/null +++ b/README.md @@ -0,0 +1,728 @@ +# Strata + +**Static Template Rendering Architecture** + +Strata is a compile-time web framework that resolves templates to pure HTML at build time. Zero runtime framework overhead. Maximum performance. + +``` + ╔═══════════════════════════════════════════════════════╗ + ║ ███████╗████████╗██████╗ █████╗ ████████╗ █████╗ ║ + ║ ██╔════╝╚══██╔══╝██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗ ║ + ║ ███████╗ ██║ ██████╔╝███████║ ██║ ███████║ ║ + ║ ╚════██║ ██║ ██╔══██╗██╔══██║ ██║ ██╔══██║ ║ + ║ ███████║ ██║ ██║ ██║██║ ██║ ██║ ██║ ██║ ║ + ║ ╚══════╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ║ + ╚═══════════════════════════════════════════════════════╝ +``` + +--- + +## Table of Contents + +- [Philosophy](#philosophy) +- [Design Pattern: STRC](#design-pattern-strc) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [CLI Commands](#cli-commands) +- [Project Structure](#project-structure) +- [File Types](#file-types) +- [Template Syntax](#template-syntax) +- [Examples](#examples) +- [Import Hierarchy](#import-hierarchy) +- [Development](#development) +- [License](#license) + +--- + +## Philosophy + +Strata follows three core principles: + +1. **Compile-Time Resolution**: All template logic is resolved during build, not at runtime +2. **Zero Runtime Overhead**: Output is pure HTML/CSS/JS with no framework dependencies +3. **Strict Separation of Concerns**: Each file type has a single responsibility + +--- + +## Design Pattern: STRC + +Strata implements the **STRC Pattern** (Static Template Resolution with Compartmentalized Layers): + +``` +┌─────────────────────────────────────────────────────────────┐ +│ BUILD TIME │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ .strata │◄───│ .compiler.sts│◄───│ .service.sts │ │ +│ │ (Template) │ │ (Variables) │ │ (Logic) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ │ │ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ STATIC COMPILER │ │ +│ │ Resolves all variables, loops, and conditionals │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ │ +└───────────────────────────┼─────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ RUNTIME │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ PURE HTML │ │ +│ │ No Strata syntax, no framework code │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### STRC Layer Responsibilities + +| Layer | File Extension | Purpose | Execution | +|-------|---------------|---------|-----------| +| **Template** | `.strata` | HTML structure with directives | Build time | +| **Compiler** | `.compiler.sts` | Variable definitions, data | Build time | +| **Service** | `.service.sts` | Business logic, API calls | Build time* | +| **Runtime** | `.service.sts` | Optional browser interactivity | Runtime | + +*Services can define both build-time data fetching and optional runtime interactivity. + +--- + +## Installation + +### Prerequisites + +- Go 1.21+ (for building the compiler) +- Node.js 18+ (for project scaffolding) + +### Install Strata CLI + +```bash +# Clone the repository +git clone https://github.com/CarGDev/strata.git +cd strata + +# Build the compiler +make build + +# Install globally +make install +``` + +This installs: +- `strata` - The main CLI compiler +- `create-strata` - Project scaffolding tool + +--- + +## Quick Start + +### Create a New Project + +```bash +# Create a new Strata project +npx create-strata my-app + +# Navigate to project +cd my-app + +# Install dependencies +npm install + +# Start development server +npm run dev +``` + +Open http://localhost:3000 to see your app. + +### Build for Production + +```bash +npm run build +``` + +Output is in the `dist/` folder - pure static HTML ready for any hosting. + +--- + +## CLI Commands + +### Main CLI (`strata`) + +```bash +# Development server with HMR +strata dev [--port 3000] [--open] + +# Production build +strata build [--output dist] + +# Preview production build +strata preview [--port 4000] +``` + +### Generator Commands + +Generate new files with the correct structure: + +```bash +# Generate a component +strata g component Button +# Creates: src/components/Button/ +# ├── Button.strata +# ├── Button.compiler.sts +# ├── Button.service.sts +# └── Button.scss + +# Generate a page +strata g page about +# Creates: src/pages/about/ +# ├── about.strata +# ├── about.compiler.sts +# ├── about.service.sts +# └── about.scss + +# Generate a service +strata g service auth +# Creates: src/services/auth.service.sts + +# Generate an API contract +strata g api users +# Creates: src/api/users.api.sts + +# Generate a utility +strata g util format +# Creates: src/utils/format.sts + +# Generate a store +strata g store cart +# Creates: src/stores/cart.store.sts +``` + +### Shorthand Commands + +```bash +strata g c Button # component +strata g p about # page +strata g s auth # service +strata g a users # api +strata g u format # util +``` + +--- + +## Project Structure + +``` +my-app/ +├── src/ +│ ├── components/ # Reusable UI components +│ │ └── Button/ +│ │ ├── Button.strata +│ │ ├── Button.compiler.sts +│ │ ├── Button.service.sts +│ │ └── Button.scss +│ │ +│ ├── pages/ # Route-based pages +│ │ ├── index/ +│ │ │ ├── index.strata +│ │ │ ├── index.compiler.sts +│ │ │ ├── index.service.sts +│ │ │ └── index.scss +│ │ └── about/ +│ │ └── ... +│ │ +│ ├── services/ # Business logic +│ │ └── auth.service.sts +│ │ +│ ├── api/ # API contracts +│ │ └── users.api.sts +│ │ +│ ├── stores/ # State management +│ │ └── cart.store.sts +│ │ +│ ├── utils/ # Pure utilities +│ │ └── format.sts +│ │ +│ └── assets/ +│ └── styles/ +│ ├── _variables.scss +│ └── global.scss +│ +├── public/ # Static assets (copied as-is) +├── dist/ # Build output +├── strataconfig.ts # Project configuration +└── package.json +``` + +--- + +## File Types + +### `.strata` - Template Files + +Pure HTML structure with Strata directives. No logic, no JavaScript. + +```html + +``` + +**Rules:** +- Must contain a single `