From 9e451469f595789385600aa5439e05844d91ce3c Mon Sep 17 00:00:00 2001 From: Carlos Gutierrez Date: Fri, 16 Jan 2026 09:01:29 -0500 Subject: [PATCH] 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 --- .gitignore | 65 + ARCHITECTURE.md | 860 ++++ CHANGELOG.md | 150 + CONTRIBUTING.md | 458 ++ LICENSE | 113 + Makefile | 283 ++ README.md | 728 +++ cli/create-strata/index.js | 1124 +++++ cli/create-strata/package.json | 23 + compiler/cmd/strata/build.go | 695 +++ compiler/cmd/strata/dev.go | 96 + compiler/cmd/strata/main.go | 99 + compiler/go.mod | 16 + compiler/go.sum | 18 + compiler/internal/ast/nodes.go | 304 ++ compiler/internal/compiler/static.go | 710 +++ compiler/internal/generator/html.go | 164 + compiler/internal/generator/injector.go | 181 + compiler/internal/parser/strata.go | 688 +++ compiler/internal/server/dev.go | 922 ++++ compiler/internal/watcher/watcher.go | 170 + examples/basic-app/package.json | 16 + .../basic-app/src/assets/styles/_mixins.scss | 144 + .../src/assets/styles/_variables.scss | 78 + .../basic-app/src/assets/styles/global.scss | 124 + .../basic-app/src/components/UserCard.strata | 158 + .../src/injectedscripts/analytics.js | 9 + .../src/injectedscripts/gtm-noscript.js | 9 + examples/basic-app/src/injectedscripts/gtm.js | 12 + examples/basic-app/src/pages/index.strata | 148 + examples/basic-app/src/stores/favorites.sts | 55 + examples/basic-app/src/stores/user.sts | 100 + examples/basic-app/strataconfig.ts | 21 + package-lock.json | 3892 +++++++++++++++++ package.json | 83 + runtime/core/strata.sts | 231 + runtime/fetch/fetch.sts | 233 + runtime/store/store.sts | 260 ++ runtime/worker/shared-worker.sts | 392 ++ scripts/doctor.sh | 294 ++ scripts/env.sh | 67 + scripts/get-strata.sh | 260 ++ scripts/install.sh | 624 +++ scripts/setup.sh | 64 + scripts/uninstall.sh | 177 + scripts/upgrade.sh | 189 + templates/.nvim.lua | 18 + templates/strataconfig.ts | 80 + 48 files changed, 15605 insertions(+) create mode 100644 .gitignore create mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.md create mode 100644 cli/create-strata/index.js create mode 100644 cli/create-strata/package.json create mode 100644 compiler/cmd/strata/build.go create mode 100644 compiler/cmd/strata/dev.go create mode 100644 compiler/cmd/strata/main.go create mode 100644 compiler/go.mod create mode 100644 compiler/go.sum create mode 100644 compiler/internal/ast/nodes.go create mode 100644 compiler/internal/compiler/static.go create mode 100644 compiler/internal/generator/html.go create mode 100644 compiler/internal/generator/injector.go create mode 100644 compiler/internal/parser/strata.go create mode 100644 compiler/internal/server/dev.go create mode 100644 compiler/internal/watcher/watcher.go create mode 100644 examples/basic-app/package.json create mode 100644 examples/basic-app/src/assets/styles/_mixins.scss create mode 100644 examples/basic-app/src/assets/styles/_variables.scss create mode 100644 examples/basic-app/src/assets/styles/global.scss create mode 100644 examples/basic-app/src/components/UserCard.strata create mode 100644 examples/basic-app/src/injectedscripts/analytics.js create mode 100644 examples/basic-app/src/injectedscripts/gtm-noscript.js create mode 100644 examples/basic-app/src/injectedscripts/gtm.js create mode 100644 examples/basic-app/src/pages/index.strata create mode 100644 examples/basic-app/src/stores/favorites.sts create mode 100644 examples/basic-app/src/stores/user.sts create mode 100644 examples/basic-app/strataconfig.ts create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 runtime/core/strata.sts create mode 100644 runtime/fetch/fetch.sts create mode 100644 runtime/store/store.sts create mode 100644 runtime/worker/shared-worker.sts create mode 100755 scripts/doctor.sh create mode 100755 scripts/env.sh create mode 100755 scripts/get-strata.sh create mode 100755 scripts/install.sh create mode 100755 scripts/setup.sh create mode 100755 scripts/uninstall.sh create mode 100755 scripts/upgrade.sh create mode 100644 templates/.nvim.lua create mode 100644 templates/strataconfig.ts 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 `