helix-lang 11.0.0

package/README.md

@@ -0,0 +1,168 @@
+# Helix v11.0
+
+**AI-Powered Full-Stack App Generator**
+
+Generate complete, working applications from natural language. Helix transforms a single prompt into a Next.js app with database, API routes, styled UI, and tests -- in about 60 seconds.
+
+```bash
+helix spawn "A recipe manager with ingredients and cook time"
+# -> Full app: database, API, React UI, tests, ready to run
+```
+
+---
+
+## Features
+
+- **Natural language to full-stack apps** -- Next.js + Prisma + Tailwind from a single prompt
+- **Self-healing builds** -- AI detects and auto-fixes build errors during generation
+- **Pre-flight validation** -- `helix preflight` catches blueprint issues before generation
+- **Theme engine** -- `--theme glassmorphism|professional|minimal|vibrant`
+- **API validation, rate limiting, pagination** -- built into every generated route
+- **Auto-generated test suites** -- Vitest tests included out of the box
+- **Docker support** -- `helix snapshot --docker` produces optimized multi-stage Dockerfiles
+- **Drift detection** -- `helix drift` shows what changed since generation
+- **Multi-page apps** -- PAGE DSL for multi-route applications
+- **Component library** -- `helix install` to pull reusable components
+- **Schema migrations** -- `helix evolve` to scan, suggest, and apply codebase changes
+- **Cost tracking** -- `helix cost` shows per-generation token usage and spend
+- **Flutter target** -- `helix spawn "..." --target flutter` for mobile apps
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g helix-lang
+```
+
+### Set up your API key
+
+```bash
+echo "OPENROUTER_API_KEY=sk-or-v1-..." > .env
+```
+
+### Generate an app
+
+```bash
+helix spawn "A project tracker with Tasks, Milestones, and Team Members"
+cd builds/a-project-tracker && npm run dev
+```
+
+### Verify your setup
+
+```bash
+helix doctor
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `helix spawn <prompt>` | Generate a complete app from natural language |
+| `helix new <name>` | Scaffold an empty Helix project |
+| `helix generate <file.helix>` | Generate stack from an existing `.helix` blueprint |
+| `helix run` | Start the dev server |
+| `helix preview` | Hot-reload preview with `.helix` file watching |
+| `helix deploy` | Deploy to Vercel, Firebase, or Netlify |
+| `helix preflight <file>` | Validate a `.helix` blueprint before generation |
+| `helix evolve [action]` | Scan, suggest, or apply codebase fixes and migrations |
+| `helix drift [project]` | Detect manual changes since generation |
+| `helix snapshot [project]` | Generate Dockerfile and docker-compose.yml |
+| `helix install [component]` | Browse and install from the component library |
+| `helix cost` | Show AI token usage and cost for the session |
+| `helix doctor` | System health check (Node, API key, deps) |
+| `helix list` | List all generated projects |
+| `helix research <topic>` | Generate domain research context |
+| `helix draft <idea>` | AI-draft a `.helix` blueprint from an idea |
+| `helix build <file>` | Compile `.helix` to a React component |
+| `helix pipeline <topic> <idea>` | Full pipeline: research, draft, build |
+| `helix models` | List available AI models |
+| `helix plugins` | List registered generator plugins |
+
+### Key Flags for `spawn`
+
+```
+--target <platform>    web (default) or flutter
+--theme <theme>        glassmorphism, professional, minimal, vibrant
+--db <database>        postgres, mongodb, redis, or comma-separated
+--constitution <file>  Provide a constitution.md for design guidance
+--components <ids>     Include Helix Library components (comma-separated)
+--ai-context           Enable AI context layer with Redis
+--cache                Add Redis caching layer
+--dry-run              Preview what would be generated without writing files
+```
+
+---
+
+## .helix DSL
+
+Helix blueprints use a declarative syntax with two core constructs: **STRAND** (data model) and **VIEW** (UI page).
+
+```helix
+STRAND Contact {
+  name: String
+  email: String
+  company: String
+  status: String    // Lead, Active, Churned
+}
+
+STRAND Deal {
+  title: String
+  value: Float
+  stage: String     // Discovery, Proposal, Closed
+  contact: Contact
+}
+
+VIEW Dashboard {
+  list: Contact.all
+  list: Deal.all
+}
+
+VIEW DealPipeline {
+  list: Deal.where(stage: "Discovery")
+  list: Deal.where(stage: "Proposal")
+  list: Deal.where(stage: "Closed")
+}
+```
+
+Each **STRAND** generates a Prisma model, full CRUD API routes, and a TypeScript interface. Each **VIEW** generates a React page with forms, lists, and delete confirmations.
+
+---
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| Framework | Next.js (App Router) |
+| Language | TypeScript |
+| Database | SQLite + Prisma ORM (Postgres/Mongo optional) |
+| Styling | Tailwind CSS |
+| Testing | Vitest |
+| AI | OpenRouter (Claude Sonnet) |
+| Containers | Docker (multi-stage builds) |
+
+---
+
+## Example Prompts
+
+```bash
+helix spawn "A warehouse inventory with Products, Locations, and Stock Movements"
+helix spawn "A course manager with Students, Courses, and Assignments"
+helix spawn "An expense tracker for small businesses" --theme professional
+helix spawn "A fitness app with Workouts and Exercises" --target flutter
+helix spawn "A CRM with Contacts, Companies, and Deals" --db postgres
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+> **"Describe it once, run it immediately."**

package/dist/architect.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Helix Architect - The Interviewer
+ * Converts vague user prompts into rigorous .helix specification files
+ * v11.0 - Now with context-aware drafting via OpenRouter
+ */
+/**
+ * Drafts a Helix blueprint from a user idea, optionally using research context
+ * @param userIdea - The user's idea/request to convert into Helix syntax
+ * @param contextFilePath - Optional path to a research context file
+ * @param model - Optional model override
+ * @returns The path to the generated .helix file
+ */
+export declare function draftBlueprint(userIdea: string, contextFilePath?: string, model?: string): Promise<string>;
+//# sourceMappingURL=architect.d.ts.map

package/dist/architect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"architect.d.ts","sourceRoot":"","sources":["../src/architect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH;;;;;;GAMG;AACH,wBAAsB,cAAc,CAChC,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,EACxB,KAAK,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CA+EjB"}

package/dist/architect.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Helix Architect - The Interviewer
+ * Converts vague user prompts into rigorous .helix specification files
+ * v11.0 - Now with context-aware drafting via OpenRouter
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.draftBlueprint = draftBlueprint;
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const openrouter_1 = require("./openrouter");
+const types_1 = require("./types");
+/**
+ * Drafts a Helix blueprint from a user idea, optionally using research context
+ * @param userIdea - The user's idea/request to convert into Helix syntax
+ * @param contextFilePath - Optional path to a research context file
+ * @param model - Optional model override
+ * @returns The path to the generated .helix file
+ */
+async function draftBlueprint(userIdea, contextFilePath, model) {
+    console.log(chalk_1.default.blue("\n🧬 Helix Architect initializing..."));
+    console.log(chalk_1.default.gray(`Processing idea: "${userIdea}"`));
+    let contextContent = "";
+    // Check if context file exists and read it
+    if (contextFilePath) {
+        const fullPath = path.isAbsolute(contextFilePath)
+            ? contextFilePath
+            : path.join(process.cwd(), contextFilePath);
+        if (fs.existsSync(fullPath)) {
+            contextContent = fs.readFileSync(fullPath, "utf-8");
+            console.log(chalk_1.default.yellow(`📚 Using context from: ${fullPath}`));
+        }
+        else {
+            console.log(chalk_1.default.yellow(`⚠️  Context file not found: ${fullPath}`));
+        }
+    }
+    else {
+        // Default: check for research.md in current directory
+        const defaultContext = path.join(process.cwd(), "research.md");
+        if (fs.existsSync(defaultContext)) {
+            contextContent = fs.readFileSync(defaultContext, "utf-8");
+            console.log(chalk_1.default.yellow(`📚 Auto-detected context: ${defaultContext}`));
+        }
+    }
+    try {
+        // Construct the prompt with or without context
+        let userMessage = "";
+        if (contextContent) {
+            userMessage = `**RESEARCH CONTEXT:**
+${contextContent}
+
+---
+
+**USER IDEA:**
+${userIdea}
+
+---
+
+**INSTRUCTIONS:**
+Use the Research Context above to inform the fields, data types, and logic of the Helix Blueprint.
+If the research mentions specific constraints (e.g., service intervals, regulatory limits, data schemas), incorporate them into the 'strand' definitions.
+Generate a comprehensive Helix blueprint that addresses the user's idea while respecting domain-specific requirements.`;
+        }
+        else {
+            userMessage = userIdea;
+        }
+        const helixCode = await (0, openrouter_1.createCompletion)(types_1.ARCHITECT_SYSTEM_PROMPT, userMessage, { model, maxTokens: 4096 });
+        // Generate output filename from the idea (sanitized)
+        const sanitizedName = userIdea
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .substring(0, 30)
+            .replace(/-+$/, "");
+        const outputPath = path.join(process.cwd(), `${sanitizedName}.helix`);
+        fs.writeFileSync(outputPath, helixCode, "utf-8");
+        console.log(chalk_1.default.blue("\n✨ Blueprint drafted successfully!"));
+        console.log(chalk_1.default.blue(`📄 Output: ${outputPath}`));
+        console.log(chalk_1.default.gray("\n--- Generated Helix Blueprint ---"));
+        console.log(chalk_1.default.cyan(helixCode));
+        console.log(chalk_1.default.gray("--- End of Blueprint ---\n"));
+        return outputPath;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(chalk_1.default.red(`❌ Architect Error: ${error.message}`));
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=architect.js.map

package/dist/architect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"architect.js","sourceRoot":"","sources":["../src/architect.ts"],"names":[],"mappings":"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"}

package/dist/bin/helix.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Helix CLI v11.0 - Complete Development Platform
+ * AI-Native Programming Language with Full-Stack Generation
+ *
+ * Commands:
+ *   spawn <prompt>        - ONE-SHOT: Full app from natural language
+ *   new <project>         - Scaffold a new Helix project
+ *   generate <blueprint>  - Generate Prisma + API + UI from .helix
+ *   run                   - Start the dev server
+ *   preview               - Hot-reload preview with file watching
+ *   deploy                - One-command deployment
+ *   research <topic>      - Generate domain research
+ *   draft <idea>          - Create a .helix blueprint
+ *   build <file>          - Compile .helix to React component
+ *   plugins               - List registered generator plugins
+ *   models                - List available AI models
+ */
+export {};
+//# sourceMappingURL=helix.d.ts.map

package/dist/bin/helix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helix.d.ts","sourceRoot":"","sources":["../../src/bin/helix.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG"}