clou-lang 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clou Language
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,128 @@
+# Clou
+
+**The programming language so simple, even kids can build websites.**
+
+Clou compiles to HTML/CSS/JS for websites and runs terminal apps directly. No frameworks, no dependencies, no complexity.
+
+## Install
+
+```bash
+npm install -g clou-lang
+```
+
+## Quick Start
+
+Create `mysite.clou`:
+
+```
+page "My Website":
+    theme "neon"
+
+    navbar "My Site":
+        link "Home" to "#"
+        link "About" to "#about"
+
+    section "hero":
+        center
+        heading "Hello World!"
+        text "Built with Clou in 10 seconds."
+        button "Click me":
+            show message "It works!"
+
+    footer:
+        text "Made with Clou"
+```
+
+Run it:
+
+```bash
+clou mysite.clou
+```
+
+That's it. Your website opens in the browser.
+
+## Commands
+
+```bash
+clou mysite.clou          # Build and open in browser
+clou build mysite.clou    # Build to HTML
+clou dev mysite.clou      # Live dev server with auto-reload
+clou playground           # Open browser-based live editor
+clou themes               # List all 10 built-in themes
+clou ai                   # Copy AI prompt to clipboard
+clou help                 # Show help
+```
+
+## Features
+
+### Website Mode
+- **19 elements**: page, heading, text, image, video, button, link, input, list, box, row, grid, card, section, navbar, footer, modal, icon, space
+- **10 themes**: neon, ocean, sunset, forest, candy, minimal, midnight, retro, glass, aurora
+- **Variables**: `set name to "Alex"` + `{name}` interpolation
+- **Templates**: reusable components with parameters
+- **Animations**: fade, slide, bounce, grow, glow
+- **Multi-page**: `page "About" at "/about":`
+- **Import**: `import "shared.clou"`
+- **Styling**: gradients, shadows, rounded corners, responsive grids
+
+### Terminal Mode
+- **Print with colors**: `print color green "Success!"`
+- **User input**: `ask "Name?" save as name`
+- **Math**: `add 5 to count`
+- **Conditions**: `if count greater than 10:`
+- **Loops**: `repeat 5:` and `while x less than 10:`
+- **Functions**: `function greet(name):`
+- **File I/O**: `read file "data.txt" save as content`
+- **Shell commands**: `run "dir" save as files`
+
+### Themes
+
+Just add one line to transform your entire website:
+
+```
+theme "aurora"
+```
+
+Available: `neon` `ocean` `sunset` `forest` `candy` `minimal` `midnight` `retro` `glass` `aurora`
+
+### Templates
+
+```
+template feature(emoji, title, desc):
+    card:
+        icon "{emoji}"
+        heading "{title}"
+        text "{desc}"
+
+page "My Site":
+    grid:
+        use feature("🚀", "Fast", "Built for speed")
+        use feature("🔒", "Secure", "Safe by default")
+```
+
+### AI Integration
+
+```bash
+clou ai
+```
+
+Copies a system prompt to your clipboard. Paste it into ChatGPT or Claude, and the AI becomes a Clou expert that generates perfect Clou code.
+
+### Playground
+
+```bash
+clou playground
+```
+
+Opens a browser-based editor where you can write Clou and see the result live.
+
+## VS Code Extension
+
+Syntax highlighting for `.clou` files is included. Copy the `clou-vscode` folder to your VS Code extensions directory:
+
+- **Windows**: `%USERPROFILE%\.vscode\extensions\clou-language`
+- **macOS/Linux**: `~/.vscode/extensions/clou-language`
+
+## License
+
+MIT

package/ai/clou-ai-prompt.md

@@ -0,0 +1,239 @@
+# Clou Language - AI System Prompt
+
+You are an expert in the **Clou** programming language. Clou is a simple programming language designed to build websites and terminal apps. It's so simple that even kids can use it.
+
+## How Clou Works
+
+Clou code compiles to HTML/CSS/JS for websites, or runs directly in the terminal for CLI apps.
+
+**Run:** `clou mysite.clou` (auto-detects website vs terminal)
+**Build:** `clou build mysite.clou`
+**Dev server:** `clou dev mysite.clou`
+
+## Website Mode — Full Syntax Reference
+
+```clou
+// Variables
+set name to "value"
+set count to "0"
+
+// Templates (reusable components)
+template card-item(title, desc):
+    card:
+        heading "{title}"
+        text "{desc}"
+
+// Use templates
+use card-item("Hello", "World")
+
+// Page with optional route (for multi-page)
+page "Title" at "/":
+    theme "midnight"        // neon|ocean|sunset|forest|candy|minimal|midnight|retro|glass|aurora
+
+    // Navigation
+    navbar "Brand":
+        link "Home" to "/"
+        link "About" to "/about"
+
+    // Sections & Layout
+    section "name":
+        center
+        box:                // generic container
+        row:                // horizontal flex row
+        grid:               // auto-responsive grid
+        card:               // styled card with hover effect
+
+    // Content Elements
+    title "Big Title"       // h1
+    heading "Heading"       // h2
+    text "Paragraph"        // p
+    image "url"             // img
+    video "url"             // video
+    icon "🚀"              // large emoji
+    link "text" to "url"    // anchor
+    line                    // horizontal rule
+    space 40                // vertical spacing (px)
+
+    // Interactive
+    button "Click me":
+        show message "Alert text!"
+        open "modal-name"
+        close "modal-name"
+        toggle "element-id"
+        go to "url"
+
+    input "placeholder"
+
+    list:
+        text "Item 1"
+        text "Item 2"
+
+    // Modals
+    modal "name":
+        heading "Title"
+        text "Content"
+        button "Close":
+            close "name"
+
+    // Footer
+    footer:
+        text "Footer content"
+
+// Styling (inline or in style block)
+style:
+    background color #hexcode
+    text color #hexcode
+    button color #hexcode
+    center / left / right
+    bold / italic
+    rounded / shadow
+    padding 20
+    margin 10
+    width 100%
+    height 200
+    gap 16
+    font Arial
+    size 18
+    gradient #color1 to #color2
+    animate fade / slide / bounce / grow / glow
+    big / huge / small / tiny
+    full
+    sticky
+
+// Import other files
+import "shared.clou"
+
+// Repeat
+repeat 5:
+    text "Item {i}"
+```
+
+## Available Themes
+
+| Theme | Style |
+|-------|-------|
+| `neon` | Electric green on black, cyberpunk |
+| `ocean` | Deep blues, calm serif |
+| `sunset` | Purple to coral, warm gradients |
+| `forest` | Natural greens, earthy serif |
+| `candy` | Sweet pastels, pink accents |
+| `minimal` | Black on white, clean |
+| `midnight` | Deep purple-blue, modern |
+| `retro` | Orange on brown, monospace |
+| `glass` | Glassmorphism, purple gradient |
+| `aurora` | Northern lights, cyan-purple |
+
+## Terminal Mode — Full Syntax Reference
+
+```clou
+app "My App":
+    // Output
+    print "text"
+    print color green "colored text"
+    // Colors: red, green, yellow, blue, magenta, cyan, white, gray, orange, pink, purple
+
+    // Input
+    ask "Question?" save as varname
+
+    // Variables & Math
+    set count to "0"
+    add 5 to count
+    subtract 2 to count
+    multiply 3 by count
+    divide 2 by count
+
+    // Conditions
+    if name is "Alex":
+        print "Hi Alex!"
+    else:
+        print "Who are you?"
+
+    if count greater than 10:
+        print "Big number!"
+
+    if name is not "":
+        print "Name is set"
+
+    // Loops
+    repeat 5:
+        print "Number {i}"
+
+    while count less than 100:
+        add 1 to count
+
+    // Functions
+    function greet(name):
+        print "Hello {name}!"
+    call greet("World")
+
+    // File I/O
+    read file "data.txt" save as content
+    write "Hello" to file "out.txt"
+
+    // Shell commands
+    run "dir" save as files
+
+    // Utility
+    wait 2
+    clear
+    exit
+```
+
+## Rules for Generating Clou Code
+
+1. **Indentation**: Use 4 spaces. Blocks are defined by indentation (like Python).
+2. **Strings**: Always use double quotes `"text"`.
+3. **Variables**: Use `{varName}` to interpolate in any string.
+4. **Colons**: Elements with children end with `:` followed by an indented block.
+5. **Themes**: Always add `theme "name"` as the first line inside a page for consistent design.
+6. **Templates**: Use templates for any repeated pattern (cards, sections, etc.)
+7. **Comments**: Use `//` for comments.
+8. **Keep it simple**: Clou's power is simplicity. Don't overcomplicate.
+
+## Example: Complete Website
+
+```clou
+set brand to "TechStartup"
+
+template feature(emoji, title, desc):
+    card:
+        icon "{emoji}"
+        heading "{title}"
+        text "{desc}"
+        animate slide
+
+page "{brand}":
+    theme "aurora"
+
+    navbar "{brand}":
+        link "Features" to "#features"
+        link "Pricing" to "#pricing"
+
+    section "hero":
+        center
+        space 30
+        heading "Build the Future":
+            huge
+            animate fade
+        text "Simple tools for complex problems.":
+            big
+        space 20
+        button "Get Started":
+            show message "Welcome!"
+        space 30
+
+    section "features":
+        center
+        heading "Features":
+            huge
+        space 20
+        grid:
+            use feature("⚡", "Fast", "Built for speed.")
+            use feature("🔒", "Secure", "Safe by default.")
+            use feature("🎨", "Beautiful", "Looks great.")
+
+    footer:
+        text "© 2026 {brand}"
+```
+
+When the user asks you to build something with Clou, generate clean, well-structured Clou code following these patterns.

package/bin/clou.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+
+// Clou Language - CLI Tool
+// Usage:
+//   clou mysite.clou                  - Build and open in browser (shortcut!)
+//   clou run mysite.clou              - Build and open in browser
+//   clou build mysite.clou            - Build to HTML file
+//   clou build mysite.clou -o out.html - Build to specific file
+//   clou dev mysite.clou              - Live dev server with auto-reload
+
+const fs = require('fs');
+const path = require('path');
+const { buildClou } = require('../src/index');
+
+const args = process.argv.slice(2);
+
+function printHelp() {
+  console.log(`
+  ╔═══════════════════════════════════════╗
+  ║         CLOU Language v0.2            ║
+  ║   Simple enough for kids to code.     ║
+  ╚═══════════════════════════════════════╝
+
+  Usage:
+    clou <file.clou>                    Build and open in browser
+    clou run <file.clou>                Same as above
+    clou build <file.clou>              Build to HTML file
+    clou build <file.clou> -o <output>  Build to specific file
+    clou dev <file.clou>                Start live dev server
+    clou dev <file.clou> -p <port>      Dev server on custom port
+    clou themes                         List all available themes
+    clou help                           Show this help
+
+  Examples:
+    clou mysite.clou
+    clou build mysite.clou -o index.html
+    clou dev mysite.clou
+
+  Themes:
+    neon, ocean, sunset, forest, candy,
+    minimal, midnight, retro, glass, aurora
+  `);
+}
+
+function printThemes() {
+  const { themes } = require('../src/themes');
+  console.log(`
+  ╔═══════════════════════════════════════╗
+  ║          CLOU Themes                  ║
+  ╚═══════════════════════════════════════╝
+`);
+  const descriptions = {
+    neon:     '🟢  Electric green on black — cyberpunk vibes',
+    ocean:    '🌊  Deep blues — calm and serene',
+    sunset:   '🌅  Purple to coral — warm and vibrant',
+    forest:   '🌲  Natural greens — earthy and organic',
+    candy:    '🍬  Sweet pastels — playful and fun',
+    minimal:  '⬜  Black on white — pure simplicity',
+    midnight: '🌙  Deep purple-blue — elegant and modern',
+    retro:    '📺  Orange on brown — nostalgic monospace',
+    glass:    '🔮  Glassmorphism — blurred purple gradient',
+    aurora:   '🌌  Northern lights — cyan meets purple',
+  };
+  for (const [name, desc] of Object.entries(descriptions)) {
+    console.log(`    ${name.padEnd(12)} ${desc}`);
+  }
+  console.log(`
+  Usage:  theme "${Object.keys(descriptions)[0]}"
+  `);
+}
+
+function getOutputPath(inputFile, customOutput) {
+  if (customOutput) return customOutput;
+  const base = path.basename(inputFile, '.clou');
+  return path.join(path.dirname(inputFile), base + '.html');
+}
+
+function openInBrowser(filePath) {
+  const absPath = path.resolve(filePath);
+  const { exec } = require('child_process');
+
+  if (process.platform === 'win32') {
+    exec(`start "" "${absPath}"`);
+  } else if (process.platform === 'darwin') {
+    exec(`open "${absPath}"`);
+  } else {
+    exec(`xdg-open "${absPath}"`);
+  }
+}
+
+// Detect if a .clou file is a terminal app (starts with "app" or has "print"/"ask" at top level)
+function isTerminalApp(source) {
+  const trimmed = source.trim();
+  if (trimmed.startsWith('app ')) return true;
+  // Check if it uses terminal-only keywords at top level
+  const lines = trimmed.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('//') && !l.startsWith('#'));
+  const terminalKeywords = ['print ', 'ask ', 'clear', 'run ', 'exit'];
+  for (const line of lines.slice(0, 10)) {
+    for (const kw of terminalKeywords) {
+      if (line.startsWith(kw)) return true;
+    }
+  }
+  return false;
+}
+
+async function runTerminal(inputFile) {
+  const { tokenize } = require('../src/lexer');
+  const { parseTerminal } = require('../src/terminal-parser');
+  const { TerminalRuntime } = require('../src/terminal-runtime');
+
+  const source = fs.readFileSync(inputFile, 'utf-8');
+  const tokens = tokenize(source);
+  const ast = parseTerminal(tokens);
+  const runtime = new TerminalRuntime();
+  await runtime.run(ast);
+}
+
+function runFile(inputFile) {
+  const source = fs.readFileSync(inputFile, 'utf-8');
+
+  // Auto-detect: terminal app or website?
+  if (isTerminalApp(source)) {
+    runTerminal(inputFile).catch(err => {
+      console.error(`\n  Clou Error: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  const basePath = path.dirname(path.resolve(inputFile));
+  const result = buildClou(source, { basePath });
+
+  if (result.pages) {
+    // Multi-page build
+    const outDir = path.dirname(path.resolve(inputFile));
+    for (const [filename, pageData] of Object.entries(result.pages)) {
+      const outPath = path.join(outDir, filename);
+      fs.writeFileSync(outPath, pageData.html, 'utf-8');
+      console.log(`  Built: ${filename}`);
+    }
+    const mainFile = path.join(outDir, 'index.html');
+    console.log('  Opening in browser...');
+    openInBrowser(fs.existsSync(mainFile) ? mainFile : path.join(outDir, Object.keys(result.pages)[0]));
+  } else {
+    const outputFile = getOutputPath(inputFile);
+    fs.writeFileSync(outputFile, result.html, 'utf-8');
+    console.log(`  Built: ${inputFile} -> ${outputFile}`);
+    console.log('  Opening in browser...');
+    openInBrowser(outputFile);
+  }
+}
+
+function buildFile(inputFile, outputFile) {
+  const source = fs.readFileSync(inputFile, 'utf-8');
+  const basePath = path.dirname(path.resolve(inputFile));
+  const result = buildClou(source, { basePath });
+
+  if (result.pages) {
+    const outDir = outputFile ? path.dirname(outputFile) : path.dirname(path.resolve(inputFile));
+    for (const [filename, pageData] of Object.entries(result.pages)) {
+      const outPath = path.join(outDir, filename);
+      fs.writeFileSync(outPath, pageData.html, 'utf-8');
+      console.log(`  Built: ${filename}`);
+    }
+  } else {
+    fs.writeFileSync(outputFile, result.html, 'utf-8');
+    console.log(`  Built: ${inputFile} -> ${outputFile}`);
+  }
+}
+
+// ── Main ──────────────────────────────────────────
+
+if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (args[0] === 'themes' || args[0] === '--themes') {
+  printThemes();
+  process.exit(0);
+}
+
+if (args[0] === 'ai') {
+  const aiPromptPath = path.resolve(__dirname, '..', 'ai', 'clou-ai-prompt.md');
+  const prompt = fs.readFileSync(aiPromptPath, 'utf-8');
+
+  // Try to copy to clipboard
+  try {
+    const { execSync } = require('child_process');
+    if (process.platform === 'win32') {
+      execSync('clip', { input: prompt });
+    } else if (process.platform === 'darwin') {
+      execSync('pbcopy', { input: prompt });
+    } else {
+      execSync('xclip -selection clipboard', { input: prompt });
+    }
+    console.log(`
+  ╔═══════════════════════════════════════╗
+  ║          CLOU AI Prompt               ║
+  ╚═══════════════════════════════════════╝
+
+  The Clou AI system prompt has been copied
+  to your clipboard!
+
+  Paste it into any AI (ChatGPT, Claude, etc.)
+  and the AI will become a Clou expert.
+
+  Then ask it things like:
+    "Build me a portfolio website"
+    "Create a landing page for a coffee shop"
+    "Make a quiz game for the terminal"
+
+  The AI will generate perfect Clou code!
+`);
+  } catch (e) {
+    console.log(`
+  ╔═══════════════════════════════════════╗
+  ║          CLOU AI Prompt               ║
+  ╚═══════════════════════════════════════╝
+
+  AI prompt file location:
+  ${aiPromptPath}
+
+  Copy the contents and paste into any AI
+  (ChatGPT, Claude, etc.) to teach it Clou!
+`);
+  }
+  process.exit(0);
+}
+
+if (args[0] === 'playground' || args[0] === 'play') {
+  const playgroundPath = path.resolve(__dirname, '..', 'playground', 'index.html');
+  console.log('  Opening Clou Playground...');
+  openInBrowser(playgroundPath);
+  process.exit(0);
+}
+
+// Smart detection: if first arg ends with .clou, treat as "clou run file.clou"
+let command, inputFile;
+
+if (args[0].endsWith('.clou')) {
+  command = 'run';
+  inputFile = args[0];
+} else {
+  command = args[0];
+  inputFile = args[1];
+}
+
+if (!inputFile) {
+  console.error('  Error: No input file specified.');
+  console.error('  Usage: clou mysite.clou');
+  process.exit(1);
+}
+
+if (!fs.existsSync(inputFile)) {
+  console.error(`  Error: File not found: ${inputFile}`);
+  process.exit(1);
+}
+
+try {
+  if (command === 'dev') {
+    const { DevServer } = require('../src/devserver');
+    const portIdx = args.indexOf('-p');
+    const port = portIdx !== -1 ? parseInt(args[portIdx + 1]) : 3000;
+    const server = new DevServer(inputFile, port);
+    server.start();
+  } else if (command === 'build') {
+    const outputIdx = args.indexOf('-o');
+    const outputFile = outputIdx !== -1 ? args[outputIdx + 1] : getOutputPath(inputFile);
+    buildFile(inputFile, outputFile);
+  } else if (command === 'run' || args[0].endsWith('.clou')) {
+    runFile(inputFile);
+  } else {
+    console.error(`  Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+  }
+} catch (err) {
+  console.error(`\n  Clou Error: ${err.message}\n`);
+  process.exit(1);
+}