SunScript Compiler

The official compiler for SunScript - a natural language programming framework that uses AI (Claude Sonnet 4) to transform human intentions into production-ready code.

Philosophy: Write what you want to achieve in plain English. Let Claude 4 handle the implementation details.

Current Status

Version: 1.0.0
Stability: Beta - Core functionality complete, advanced features in development
Test Coverage: Comprehensive (7 test suites covering all major components)
Security: Production-ready with comprehensive validation and sanitization

Installation

1. Clone the repository:

git clone https://github.com/aw3-technology/sunscript.git
cd my-sunscript-project

2. Install dependencies:

npm install

3. Set up your AI provider (Claude Sonnet 4 recommended):

# Create .env file in project root
echo "ANTHROPIC_API_KEY=your-anthropic-api-key-here" > .env

Get your API key from Anthropic Console

4. Build the project:

npm run build

5. Link the CLI globally (optional):

npm link
# Now you can use 'sunscript' command globally

Quick Start

Standard Syntax Mode

Create a .sun file with traditional function syntax:

function greetUser {
  Create a simple greeting function that takes a name parameter.
  Return a greeting message saying "Hello, [name]!"
  Include the current time in a friendly format.
}

function calculateSum {
  Create a function that adds two numbers together.
  Include input validation and error handling.
  Return the sum with proper formatting.
}

Flex Syntax Mode (Free-form Natural Language)

@syntax flex

Create a simple calculator that can add and subtract numbers.
The calculator should have buttons for numbers 0-9 and operations + and -.
When someone clicks equals, show the result.
Make it look modern and responsive.

HTML Applications

@targets html

function createWebPage {
  Build a simple HTML page with a title "My SunScript App".
  Include a header with "Welcome to SunScript".
  Add a button that shows an alert when clicked.
  Make it responsive and visually appealing.
}

Compilation Commands

# Compile a single file
sunscript compile hello.sun --target javascript --output ./dist

# Compile with specific target language
sunscript compile app.sun --target html --output ./public

# Compile with Genesis v2 (preserves user code in regions)
sunscript genesis-v2 -f genesis.sun -v

# Dry-run mode (see what would be generated without writing files)
sunscript genesis-v2 -f genesis.sun --dry-run

# Use the creative "let there be light" command
sunscript let there be light --genesis genesis.sun

# Import projects from GitHub
sunscript import https://github.com/user/repo --output ./imported

# Run with debugging
sunscript compile app.sun --verbose

Genesis v2 - Region Preservation

Genesis v2 is a new compilation mode that preserves custom code across regenerations using region markers:

// @sun-region:custom-imports
import * as dotenv from 'dotenv';
import { logger } from './utils/logger';
// @sun-end-region:custom-imports

Features:

• ✅ Region Preservation - Custom code inside marked regions is preserved across regenerations
• ✅ Merge Strategy - Intelligently merges generated code with user modifications
• ✅ Dry-run Mode - Preview changes before writing files
• ✅ Verbose Logging - See detailed compilation progress

Usage:

# Create a genesis.sun file
echo '@project "MyApp"
@version "1.0.0"
# My Application' > genesis.sun

# Compile with genesis-v2
sunscript genesis-v2 -f genesis.sun

# Add custom code to generated files (within region markers)
# Regenerate - your custom code will be preserved!
sunscript genesis-v2 -f genesis.sun

🚀 Rapidash Stack: Production Apps with OpenAPI

SunScript includes Rapidash - a modern full-stack framework that generates production-ready applications with OpenAPI enabled by default (as of v0.2.0).

✨ OpenAPI by Default

Create a complete API with documentation in seconds - no configuration needed:

app MyAPI {
  stack: rapidash
  db: postgres + prisma
  // OpenAPI is automatically enabled!
}

model User {
  id: id
  email: string unique
  name: string
}

api /users {
  get -> User[]
  post(body: UserInput) -> User
}

What you get automatically:

✅ OpenAPI 3.0 Specification - Complete API spec at apps/api/openapi.json ✅ Interactive Documentation - Beautiful Scalar UI at http://localhost:3000/docs ✅ TypeScript SDK - Auto-generated client library in packages/sdk/ ✅ Full CRUD Operations - GET, POST, PUT, DELETE endpoints for all models ✅ Fastify Integration - Production-ready API server with OpenAPI middleware ✅ Request Validation - Automatic schema validation with Zod

🎨 Customize or Disable

Use Swagger UI instead of Scalar:

openapi: enabled docs(swagger) sdk(true)

Disable SDK generation:

openapi: enabled docs(scalar) sdk(false)

Completely disable OpenAPI:

openapi: disabled

📦 Complete Tech Stack

Rapidash generates a production-ready monorepo with:

• API: Fastify + OpenAPI + Prisma + PostgreSQL
• Web: Vite + React + TanStack Router + TanStack Query
• Database: PostgreSQL + Prisma ORM
• SDK: Auto-generated TypeScript client
• Auth: Session-based authentication (optional)
• Admin: RBAC admin panel (optional)
• Observability: Prometheus + Grafana (optional)
• Testing: Vitest + Playwright (optional)
• DevOps: Tilt + Docker Compose (optional)

📚 Learn More

• OpenAPI Default Guide - Complete OpenAPI documentation
• Rapidash Status - Implementation details
• Stdlib Guide - Module system documentation

Project Management & Cleanup

SunScript includes powerful trim/shred commands to keep your projects lean and bloat-free.

Analyze Project Bloat

Analyze your project to identify unused modules and removable files:

# Analyze project and show report
sunscript analyze

# Output JSON for CI/CD integration
sunscript analyze --json

# Override enabled modules
sunscript analyze --modules "core.project,api.fastify"

Output:

🌞 SunScript Project Analysis
────────────────────────────────────────────────────────────
Enabled modules:
  ✓ core.project
  ✓ api.fastify.openapi

Potentially unused modules:
  ⚠ observability.prometheus.grafana

Trim candidates:
  - grafana/dashboard.json
  - prometheus/metrics.yml
  ... and 45 more

Estimated savings: 850 KB

Trim Unused Artifacts

Remove unused compiler-generated bloat safely:

# Preview what will be removed
sunscript trim --dry-run

# Remove unused files (with automatic backup)
sunscript trim

# Include dependency cleanup
sunscript trim --deps

# Remove unused shadcn components
sunscript trim --shadcn

# Complete cleanup (files + dependencies + components)
sunscript trim --all

# Force removal of dangerous files (migrations, etc.)
sunscript trim --force

# Restore from backup
sunscript trim --undo <timestamp>

# List available backups
sunscript trim --list-backups

Safety Features:

• ✅ Automatic backups before deletion
• ✅ Dry-run mode for testing
• ✅ Protected paths (never deletes critical files)
• ✅ Undo capability
• ✅ Policy-based safe deletion

Compress Project for Production

Reduce footprint with intelligent module-based compression:

# Compress to minimal footprint
sunscript compress --profile minimal

# Standard balanced compression
sunscript compress --profile standard

# Enterprise with compliance features
sunscript compress --profile enterprise

# Native/mobile optimized
sunscript compress --profile native

# Combine with trim and ship mode
sunscript compress --profile minimal --trim --ship

# Preview changes without applying
sunscript compress --profile minimal --dry-run

Compression Profiles:

| Profile | Use Case | Modules Included | |---------|----------|------------------| | minimal | MVPs, small tools | Core, API, DB, Auth | | standard | Full web apps | + Admin, Docs, Landing, E2E | | enterprise | SaaS with compliance | + RBAC, Audit, Tracing | | native | Mobile/Capacitor apps | + Mobile UI, Native features |

Advanced Options:

# Remove specific artifact types
sunscript compress --remove-tests --remove-docs --remove-admin

# Keep specific modules
sunscript compress --profile minimal --keep "integration.stripe,integration.twilio"

# Drop specific modules
sunscript compress --profile standard --drop "admin.site"

# Full production pipeline
sunscript compress --profile minimal --trim --ship --report

Ship Mode (Production-Ready Static Code):

The --ship flag enables registry staticization - the killer feature:

sunscript compress --ship

Before Ship Mode (Dynamic):

import { buildRouteRegistry } from '@sunscript/runtime';
export const routes = buildRouteRegistry(enabledModules);

After Ship Mode (Static):

import { api_fastifyRoutes } from './routes/api';
import { auth_sessionRoutes } from './routes/auth';
export const routes = [...api_fastifyRoutes, ...auth_sessionRoutes];

Ship Mode Benefits:

• ✅ Zero runtime overhead - No dynamic module loading
• ✅ Perfect tree-shaking - Bundlers eliminate unused code
• ✅ No SunScript runtime - Pure TypeScript output
• ✅ Edge-compatible - Works in serverless/Cloudflare Workers
• ✅ -80% bundle size - Eliminates registry overhead

Recommended Production Workflow:

# 1. Analyze and fix issues
sunscript doctor
sunscript fix --auto

# 2. Compress with ship mode
sunscript compress --profile minimal --trim --ship

# 3. Optional: Completely remove SunScript metadata
sunscript shred --ship

# 4. Build for production
npm run build

Visualize Dependencies

Understand your project structure with dependency visualization:

# Show dependency statistics
sunscript visualize --stats

# Show dependency tree
sunscript visualize --tree

# Show tree from specific file
sunscript visualize --tree --root apps/api/src/index.ts

# Check for circular dependencies
sunscript visualize --cycles

# Generate Mermaid diagram
sunscript visualize --mermaid dependency-graph.mmd

Output:

📈 Dependency Statistics
────────────────────────────────────────────────────────────
Total files: 127
Total dependencies: 342
Root files: 3
Leaf files: 45

Top files by dependencies:
  apps/api/src/index.ts: 23 deps
  apps/web/src/App.tsx: 18 deps

✓ No circular dependencies

Eject from SunScript

Completely remove SunScript from your project:

# Keep code, remove SunScript management
sunscript shred --keep-code

# Trim first, then eject (recommended)
sunscript shred --lean

# Aggressive cleanup (removes all compiler-owned files)
sunscript shred --full --force

CI/CD Integration

Add bloat detection to your pipeline:

# .github/workflows/check-bloat.yml
name: Check Bloat
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: |
          sunscript analyze --json > analysis.json
          BLOAT=$(cat analysis.json | jq '.estimatedBytes')
          if [ "$BLOAT" -gt 1048576 ]; then
            echo "⚠️ Project has over 1MB of removable bloat!"
            exit 1
          fi

Documentation

For detailed documentation, see:

• Trim/Shred Basic Usage: TRIM_SHRED_README.md
• Trim/Shred Advanced Features: TRIM_SHRED_ADVANCED.md
• Trim/Shred Implementation: TRIM_SHRED_IMPLEMENTATION_SUMMARY.md
• Registry Staticization (Ship Mode): STATICIZER_README.md

Supported Features

✅ Core Features (Implemented)

• Natural Language Programming: Write intentions in plain English
• Claude Sonnet 4 Integration: Superior code generation with deep understanding
• Multiple Target Languages: JavaScript, TypeScript, Python, HTML
• Flex Syntax Mode: Free-form natural language input with @syntax flex
• Security Validation: Comprehensive input sanitization and path protection
• File Operations: Secure file I/O with atomic writes and permission management
• Error Recovery: Graceful error handling with detailed diagnostics
• CLI Interface: Rich command set with validation and help system
• Project Management: Trim/shred commands for bloat removal and dependency cleanup
• Dependency Visualization: Graph analysis and circular dependency detection
• Production Compression: Module-based footprint reduction with 4 optimization profiles
• Ship Mode: Registry staticization for zero-runtime-overhead production builds

✅ AI Provider Support

• Anthropic Claude: Primary provider (Claude Sonnet 4)
• OpenAI: GPT-4 and GPT-3.5 Turbo support
• Local LLM: Ollama integration for privacy-focused deployment
• Mock Provider: Testing and development support

✅ Security Features

• Input Validation: Blocks injection attacks and malicious patterns
• Path Sanitization: Prevents directory traversal attacks
• Content Filtering: Removes dangerous code patterns from AI output
• Secure File Operations: Atomic writes with permission validation
• API Key Protection: Secure handling of sensitive credentials

⚠️ Partially Implemented

• Genesis Projects: Basic project structure generation (parser issues remain)
• Multi-Prompt Generation: Architecture exists but needs refinement
• Template System: Framework present but templates not fully populated

❌ Not Yet Implemented

• Specialized Generators: FunctionGenerator, ComponentGenerator, APIGenerator classes are empty
• Advanced Language Constructs: Models, Pipelines, Behaviors, Tests
• Watch Mode: Automatic recompilation on file changes
• Package Management: SunScript module system
• IDE Integration: Language server protocol support

Architecture Overview

Current Implementation Status

src/
├── lexer/              ✅ Complete - Tokenization with error recovery
├── parser/             ✅ Complete - AST generation with validation
├── compiler/           ✅ Complete - Main compilation orchestration
├── generator/          ⚠️  Partial - Core generator works, specialized generators empty
│   ├── CodeGenerator   ✅ Complete - Main generation logic
│   ├── MultiPrompt     ✅ Complete - Complex app generation
│   └── [8 empty classes] ❌ Missing - Specialized construct generators
├── ai/                 ✅ Complete - 4 AI providers with full integration
├── validation/         ✅ Complete - Comprehensive validation system
├── security/           ✅ Complete - Production-ready security measures
├── cli/                ✅ Complete - Rich CLI interface
│   ├── commands/       ✅ Complete - 18 commands including trim/shred/compress
│   ├── lib/            ✅ Complete - 11 utility modules for project management
│   └── lib/compress/   ✅ Complete - Production compression & registry staticization
└── types/             ✅ Complete - Comprehensive type definitions

Test Coverage

tests/
├── unit/
│   ├── compiler/       ✅ Core compilation tests
│   ├── validation/     ✅ ConfigValidator tests  
│   ├── ai/            ✅ AI provider integration tests
│   ├── security/      ✅ Security validation tests
│   ├── cli/           ✅ CLI command tests
│   └── lexer/         ✅ Basic lexer tests
├── integration/       ✅ End-to-end compilation tests
└── helpers/           ✅ Test utilities and fixtures

Examples

Basic Function Generation

Input (hello.sun):

function greetUser {
  Create a greeting function that asks for the user's name.
  Display a personalized welcome message.
  Include the current time and make it friendly.
}

Output (dist/hello.greetUser.js):

function greetUser() {
  const name = prompt("What's your name?");
  const currentTime = new Date().toLocaleTimeString();
  const greeting = `Hello, ${name}! Welcome! The current time is ${currentTime}. Have a wonderful day!`;
  alert(greeting);
  return greeting;
}

HTML Application Generation

Input (calculator.sun):

@targets html

function createCalculator {
  Build a beautiful calculator with number buttons.
  Include add, subtract, multiply, and divide operations.
  Show results in a display area with smooth animations.
  Make it responsive and accessible.
}

Output (dist/calculator.html): Complete HTML page with embedded CSS and JavaScript.

Flex Syntax Mode

Input (natural.sun):

@syntax flex

Create a todo list app that lets users add, edit, and delete tasks.
Each task should have a checkbox to mark it complete.
Store everything in local storage so it persists.
Use a clean, modern design with smooth transitions.

Output: Complete web application with all requested functionality.

Environment Variables

Create a .env file with:

# Primary AI provider (recommended)
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here

# Alternative providers
OPENAI_API_KEY=sk-your-openai-api-key-here

# Optional configuration
NODE_ENV=development
SUNSCRIPT_LOG_LEVEL=INFO

Development

# Run comprehensive tests
npm test

# Run specific test suite
npm test tests/unit/compiler/Compiler.test.ts

# Development mode with watch
npm run dev

# Build and type checking
npm run build

# Linting and formatting
npm run lint
npm run format

# Clean build artifacts
rm -rf dist/

Known Issues

1. Genesis Parser: Syntax issues with project structure parsing
2. Generator Classes: 8 specialized generator classes need implementation
3. Template System: Language-specific templates need population
4. Watch Mode: File watching not yet implemented
5. Package Management: Module system for SunScript libraries

Security Considerations

SunScript includes comprehensive security measures:

• Input Sanitization: All user input is validated and sanitized
• Path Validation: Directory traversal attacks are prevented
• AI Output Filtering: Generated code is scanned for malicious patterns
• Secure File Operations: All file I/O uses secure, atomic operations
• API Key Protection: Sensitive credentials are handled securely

Performance

• Compilation Speed: ~2-5 seconds for simple functions
• AI Provider Support: Automatic retry with exponential backoff
• Memory Usage: Efficient with <100MB growth for multiple compilations
• Concurrent Operations: Supports parallel compilation jobs
• Project Analysis: < 200ms for bloat detection
• Dependency Visualization: < 150ms for graph analysis
• Trim Operations: < 300ms with automatic backups
• Compression Pipeline: < 2 seconds for full module analysis and planning
• Registry Staticization: < 200ms per registry file (ship mode)
• Bundle Size Reduction: -80% registry overhead with ship mode

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Run tests: npm test
4. Commit changes: git commit -m 'Add amazing feature'
5. Push to branch: git push origin feature/amazing-feature
6. Open a Pull Request

Development Priorities

High Priority:

1. Implement specialized generator classes (FunctionGenerator, ComponentGenerator, etc.)
2. Complete template system with language-specific templates
3. Fix genesis.sun parser syntax issues
4. Add watch mode for development

Medium Priority:

1. Implement advanced language constructs (Models, Pipelines, Behaviors)
2. Add package management system
3. Create VS Code extension
4. Performance optimization

Recently Completed:

1. ✅ Production compression with 4 optimization profiles
2. ✅ Registry staticization engine (ship mode)
3. ✅ Zero-runtime-overhead production builds
4. ✅ Trim/shred commands for project cleanup
5. ✅ Dependency visualization and analysis
6. ✅ Module-based bloat detection
7. ✅ Automatic backup/restore system
8. ✅ CI/CD integration for bloat prevention

License

MIT License - see LICENSE file for details.

Acknowledgments

• Anthropic Claude Sonnet 4: Primary AI provider for code generation
• TypeScript: Type-safe development environment
• Jest: Comprehensive testing framework
• Commander.js: CLI framework
• Winston: Logging system

Built with ❤️ by the SunScript team.