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
2026-01-16 09:01:29 -05:00
commit 9e451469f5
48 changed files with 15605 additions and 0 deletions
--- a/README.md
+++ 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
+<template>
+  <main class="page">
+    <h1>{ title }</h1>
+    <p>{ description }</p>
+  </main>
+</template>
+```
+
+**Rules:**
+- Must contain a single `<template>` root
+- Can only import other `.strata` files
+- Cannot contain `<script>` tags
+- All variables come from `.compiler.sts`
+
+### `.compiler.sts` - Compiler Files
+
+Defines variables available to the template. Executed at **build time**.
+
+```typescript
+// page.compiler.sts
+export const title = 'My Page';
+export const description = 'Welcome to my page';
+
+// Arrays for loops
+export const items = [
+  { id: 1, name: 'Item 1' },
+  { id: 2, name: 'Item 2' },
+];
+
+// Booleans for conditionals
+export const isProduction = false;
+export const showBanner = true;
+```
+
+**Rules:**
+- All exports become template variables
+- Can import from `.service.sts`, `.api.sts`, `.sts`
+- Cannot import from `.strata` files
+- Runs during compilation, not in browser
+
+### `.service.sts` - Service Files
+
+Business logic layer. Can define both build-time and runtime behavior.
+
+```typescript
+// auth.service.sts
+
+// Build-time: fetch data during compilation
+export async function fetchUserData() {
+  const response = await fetch('https://api.example.com/user');
+  return response.json();
+}
+
+// Runtime: browser interactivity (optional)
+const mount = function() {
+  document.getElementById('btn').addEventListener('click', () => {
+    console.log('Clicked!');
+  });
+};
+
+return { mount };
+```
+
+**Rules:**
+- Can import from `.api.sts`, `.sts`
+- Cannot import from `.strata`, `.compiler.sts`
+
+### `.api.sts` - API Contract Files
+
+Declarative API endpoint definitions.
+
+```typescript
+// users.api.sts
+export const endpoints = {
+  getUsers: {
+    method: 'GET',
+    url: '/api/users',
+    cache: 3600
+  },
+  createUser: {
+    method: 'POST',
+    url: '/api/users',
+    body: { name: 'string', email: 'string' }
+  }
+};
+```
+
+### `.sts` - Utility Files
+
+Pure functions with no side effects. Can be imported anywhere.
+
+```typescript
+// format.sts
+export function formatDate(date) {
+  return new Date(date).toLocaleDateString();
+}
+
+export function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+```
+
+### `.scss` - Style Files
+
+Scoped styles for components/pages. Standard SCSS syntax.
+
+```scss
+// Button.scss
+.button {
+  padding: 0.5rem 1rem;
+  border-radius: 4px;
+
+  &:hover {
+    opacity: 0.9;
+  }
+}
+```
+
+---
+
+## Template Syntax
+
+### Variable Interpolation
+
+```html
+{ variableName }
+```
+
+Variables are defined in the corresponding `.compiler.sts` file.
+
+```html
+<!-- page.strata -->
+<h1>{ title }</h1>
+<p>Author: { author.name }</p>
+```
+
+```typescript
+// page.compiler.sts
+export const title = 'Hello World';
+export const author = { name: 'John Doe' };
+```
+
+**Output:**
+```html
+<h1>Hello World</h1>
+<p>Author: John Doe</p>
+```
+
+### Loops: `s-for`
+
+```html
+{ s-for item in items }
+  <!-- content repeated for each item -->
+{ /s-for }
+```
+
+**With index:**
+```html
+{ s-for item, index in items }
+  <div>#{ index }: { item.name }</div>
+{ /s-for }
+```
+
+**Example:**
+```html
+<!-- page.strata -->
+<ul>
+  { s-for user in users }
+    <li>{ user.name } - { user.email }</li>
+  { /s-for }
+</ul>
+```
+
+```typescript
+// page.compiler.sts
+export const users = [
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: 'bob@example.com' },
+];
+```
+
+**Output:**
+```html
+<ul>
+  <li>Alice - alice@example.com</li>
+  <li>Bob - bob@example.com</li>
+</ul>
+```
+
+### Conditionals: `s-if` / `s-elif` / `s-else`
+
+```html
+{ s-if condition }
+  <!-- shown if condition is true -->
+{ s-elif otherCondition }
+  <!-- shown if otherCondition is true -->
+{ s-else }
+  <!-- shown if all conditions are false -->
+{ /s-if }
+```
+
+**Example:**
+```html
+{ s-if isAdmin }
+  <div class="admin-panel">Admin Controls</div>
+{ s-elif isModerator }
+  <div class="mod-panel">Moderator Controls</div>
+{ s-else }
+  <div class="user-panel">User Dashboard</div>
+{ /s-if }
+```
+
+```typescript
+// page.compiler.sts
+export const isAdmin = false;
+export const isModerator = true;
+```
+
+**Output:**
+```html
+<div class="mod-panel">Moderator Controls</div>
+```
+
+### Negation
+
+```html
+{ s-if !isLoggedIn }
+  <a href="/login">Please log in</a>
+{ /s-if }
+```
+
+### Comparison Operators
+
+```html
+{ s-if count > 0 }
+  <p>You have { count } items</p>
+{ /s-if }
+
+{ s-if status === 'active' }
+  <span class="badge">Active</span>
+{ /s-if }
+```
+
+Supported operators: `===`, `==`, `!==`, `!=`, `>`, `<`, `>=`, `<=`
+
+### Component Imports (Coming Soon)
+
+```html
+{ s-imp "@components/Button" }
+```
+
+---
+
+## Examples
+
+### Basic Page
+
+```html
+<!-- src/pages/index/index.strata -->
+<template>
+  <main class="home">
+    <h1>{ title }</h1>
+    <p>{ subtitle }</p>
+
+    <section class="features">
+      { s-for feature in features }
+        <div class="feature-card">
+          <span>{ feature.icon }</span>
+          <h3>{ feature.name }</h3>
+          <p>{ feature.description }</p>
+        </div>
+      { /s-for }
+    </section>
+
+    { s-if showCTA }
+      <a href="/signup" class="cta">Get Started</a>
+    { /s-if }
+  </main>
+</template>
+```
+
+```typescript
+// src/pages/index/index.compiler.sts
+export const title = 'Welcome to My App';
+export const subtitle = 'Build faster, deploy smarter';
+export const showCTA = true;
+
+export const features = [
+  { icon: '⚡', name: 'Fast', description: 'Blazing fast performance' },
+  { icon: '🔒', name: 'Secure', description: 'Built-in security' },
+  { icon: '📦', name: 'Simple', description: 'Easy to use' },
+];
+```
+
+### Page with Runtime Interactivity
+
+```html
+<!-- src/pages/counter/counter.strata -->
+<template>
+  <main class="counter-page">
+    <h1>Counter Example</h1>
+    <button id="counterBtn">Click Me</button>
+    <p>Count: <span id="count">0</span></p>
+  </main>
+</template>
+```
+
+```typescript
+// src/pages/counter/counter.service.sts
+const mount = function() {
+  const btn = document.getElementById('counterBtn');
+  const countEl = document.getElementById('count');
+  let count = 0;
+
+  btn.addEventListener('click', function() {
+    count++;
+    countEl.textContent = count;
+  });
+};
+
+return { mount };
+```
+
+### Build-Time Data Fetching
+
+```typescript
+// src/pages/pokemon/pokemon.compiler.sts
+export const title = 'Pokemon Gallery';
+
+// This data is fetched at BUILD TIME, not runtime
+export const pokemons = [
+  { id: 1, name: 'Bulbasaur', type: 'grass' },
+  { id: 4, name: 'Charmander', type: 'fire' },
+  { id: 7, name: 'Squirtle', type: 'water' },
+];
+
+export const totalCount = pokemons.length;
+```
+
+```html
+<!-- src/pages/pokemon/pokemon.strata -->
+<template>
+  <main class="pokemon-page">
+    <h1>{ title }</h1>
+    <p>Showing { totalCount } Pokemon</p>
+
+    <div class="grid">
+      { s-for pokemon in pokemons }
+        <div class="card">
+          <h3>{ pokemon.name }</h3>
+          <span class="type">{ pokemon.type }</span>
+        </div>
+      { /s-for }
+    </div>
+  </main>
+</template>
+```
+
+---
+
+## Import Hierarchy
+
+Strata enforces a strict import hierarchy to maintain separation of concerns:
+
+```
+┌─────────────┐
+│   .strata   │  Can only import: .strata
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────┐
+│ .compiler.sts   │  Can import: .service.sts, .api.sts, .sts
+└──────┬──────────┘
+       │
+       ▼
+┌─────────────────┐
+│  .service.sts   │  Can import: .api.sts, .sts
+└──────┬──────────┘
+       │
+       ▼
+┌─────────────────┐
+│    .api.sts     │  Can import: .sts
+└──────┬──────────┘
+       │
+       ▼
+┌─────────────────┐
+│      .sts       │  Can import: .sts only
+└─────────────────┘
+```
+
+**Violations will cause build errors.**
+
+---
+
+## Development
+
+### Running Tests
+
+```bash
+make test
+```
+
+### Building from Source
+
+```bash
+# Build compiler
+make build
+
+# Build and install
+make install
+
+# Clean build artifacts
+make clean
+```
+
+### Project Configuration
+
+```typescript
+// strataconfig.ts
+export default {
+  // Development server port
+  port: 3000,
+
+  // API proxy for development
+  api: {
+    baseUrl: 'http://localhost:8080',
+    proxy: true
+  },
+
+  // Build output directory
+  output: 'dist',
+
+  // Enable source maps in development
+  sourceMaps: true
+};
+```
+
+---
+
+## License
+
+**Proprietary - All Rights Reserved**
+
+This software is currently in development and is not available for public use, modification, or distribution. See [LICENSE](LICENSE) for details.
+
+---
+
+## Links
+
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Report Issues](https://github.com/CarGDev/strata/issues)
+
+---
+
+<p align="center">
+  <strong>Strata</strong> - Code Faster. Load Quick. Deploy ASAP.
+</p>