tova 0.5.0 → 0.7.0

package/src/codegen/server-codegen.js

@@ -136,6 +136,69 @@ export class ServerCodegen extends BaseCodegen {
     return checks;
   }
 
+  // Generate validation checks from type-level validators (Phase 3)
+  // Returns an array of JS code lines for inline validation
+  _genTypeValidatorCode(paramName, typeInfo, indent = '  ') {
+    const checks = [];
+    for (const field of typeInfo.fields) {
+      if (!field.validators || field.validators.length === 0) continue;
+      const accessor = `${paramName}.${field.name}`;
+      for (const v of field.validators) {
+        // The last argument is typically the error message
+        const msgArg = v.args.length > 0 ? this.genExpression(v.args[v.args.length - 1]) : null;
+        switch (v.name) {
+          case 'required': {
+            const msg = msgArg || `"${field.name} is required"`;
+            checks.push(`${indent}if (${accessor} === undefined || ${accessor} === null || ${accessor} === "") __validationErrors.push({ field: "${field.name}", message: ${msg} });`);
+            break;
+          }
+          case 'email': {
+            const msg = msgArg || `"${field.name} must be a valid email"`;
+            checks.push(`${indent}if (${accessor} && !/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(${accessor})) __validationErrors.push({ field: "${field.name}", message: ${msg} });`);
+            break;
+          }
+          case 'min': {
+            const minVal = this.genExpression(v.args[0]);
+            const minMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} must be at least ${v.args[0].value || v.args[0].name}"`;
+            checks.push(`${indent}if (typeof ${accessor} === "number" && ${accessor} < ${minVal}) __validationErrors.push({ field: "${field.name}", message: ${minMsg} });`);
+            break;
+          }
+          case 'max': {
+            const maxVal = this.genExpression(v.args[0]);
+            const maxMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} must be at most ${v.args[0].value || v.args[0].name}"`;
+            checks.push(`${indent}if (typeof ${accessor} === "number" && ${accessor} > ${maxVal}) __validationErrors.push({ field: "${field.name}", message: ${maxMsg} });`);
+            break;
+          }
+          case 'minLength': {
+            const minLen = this.genExpression(v.args[0]);
+            const minLenMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} is too short"`;
+            checks.push(`${indent}if (typeof ${accessor} === "string" && ${accessor}.length < ${minLen}) __validationErrors.push({ field: "${field.name}", message: ${minLenMsg} });`);
+            break;
+          }
+          case 'maxLength': {
+            const maxLen = this.genExpression(v.args[0]);
+            const maxLenMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} is too long"`;
+            checks.push(`${indent}if (typeof ${accessor} === "string" && ${accessor}.length > ${maxLen}) __validationErrors.push({ field: "${field.name}", message: ${maxLenMsg} });`);
+            break;
+          }
+          case 'pattern': {
+            const regex = this.genExpression(v.args[0]);
+            const patMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} has invalid format"`;
+            checks.push(`${indent}if (typeof ${accessor} === "string" && !${regex}.test(${accessor})) __validationErrors.push({ field: "${field.name}", message: ${patMsg} });`);
+            break;
+          }
+          case 'oneOf': {
+            const vals = this.genExpression(v.args[0]);
+            const oneOfMsg = v.args.length >= 2 ? this.genExpression(v.args[1]) : `"${field.name} has invalid value"`;
+            checks.push(`${indent}if (!${vals}.includes(${accessor})) __validationErrors.push({ field: "${field.name}", message: ${oneOfMsg} });`);
+            break;
+          }
+        }
+      }
+    }
+    return checks;
+  }
+
   // Emit handler call, optionally wrapped in Promise.race for timeout
   _emitHandlerCall(lines, callExpr, timeoutMs) {
     if (timeoutMs) {
@@ -304,14 +367,19 @@ export class ServerCodegen extends BaseCodegen {
     }
 
     // Collect type declarations from shared blocks for model/ORM generation
-    const sharedTypes = new Map(); // typeName -> { fields: [{ name, type }] }
+    const sharedTypes = new Map(); // typeName -> { fields: [{ name, type, validators? }] }
     const _collectTypes = (stmts) => {
       for (const stmt of stmts) {
         if (stmt.type === 'TypeDeclaration' && stmt.variants) {
           const fields = [];
           for (const v of stmt.variants) {
             if (v.type === 'TypeField' && v.typeAnnotation) {
-              fields.push({ name: v.name, type: v.typeAnnotation.name || (v.typeAnnotation.type === 'ArrayTypeAnnotation' ? 'Array' : 'Any') });
+              const fieldInfo = { name: v.name, type: v.typeAnnotation.name || (v.typeAnnotation.type === 'ArrayTypeAnnotation' ? 'Array' : 'Any') };
+              // Capture type-level validators (Phase 3) if present
+              if (v.validators && v.validators.length > 0) {
+                fieldInfo.validators = v.validators;
+              }
+              fields.push(fieldInfo);
             }
           }
           if (fields.length > 0) {
@@ -2166,9 +2234,19 @@ export class ServerCodegen extends BaseCodegen {
             lines.push(`  const ${paramNames[pi]} = body.__args ? body.__args[${pi}] : body.${paramNames[pi]};`);
           }
           const validationChecks = this._genValidationCode(fn.params);
-          if (validationChecks.length > 0) {
+          // Phase 3: Also generate type-level validator checks for typed parameters
+          const typeValidatorChecks = [];
+          for (const p of fn.params) {
+            if (p.typeAnnotation && p.typeAnnotation.type === 'TypeAnnotation' && sharedTypes.has(p.typeAnnotation.name)) {
+              const typeInfo = sharedTypes.get(p.typeAnnotation.name);
+              const tvChecks = this._genTypeValidatorCode(p.name, typeInfo);
+              typeValidatorChecks.push(...tvChecks);
+            }
+          }
+          const allChecks = [...validationChecks, ...typeValidatorChecks];
+          if (allChecks.length > 0) {
             lines.push(`  const __validationErrors = [];`);
-            for (const check of validationChecks) {
+            for (const check of allChecks) {
               lines.push(check);
             }
             lines.push(`  if (__validationErrors.length > 0) return __errorResponse(400, "VALIDATION_FAILED", "Validation failed", __validationErrors);`);
@@ -2702,6 +2780,9 @@ export class ServerCodegen extends BaseCodegen {
           lines.push('  responses: { "200": { description: "Success" } },');
         }
 
+        // Close the OpenAPI path entry object
+        lines.push('};');
+
         // Auto-generate error responses based on route context
         const routeHasAuth = (route.decorators || []).some(d => d.name === 'auth');
         const routeHasRateLimit = (route.decorators || []).some(d => d.name === 'rate_limit');
@@ -2709,7 +2790,8 @@ export class ServerCodegen extends BaseCodegen {
         const routeHasTimeout = (route.decorators || []).some(d => d.name === 'timeout');
         const errRef = '{ "$ref": "#/components/schemas/ErrorResponse" }';
 
-        // Merge error responses into existing 200 response
+        // Merge error responses into existing 200 response (wrapped in block scope to avoid __r redeclaration)
+        lines.push('{');
         lines.push(`const __r = __openApiSpec.paths[${JSON.stringify(path)}][${JSON.stringify(method)}].responses;`);
         if (routeHasValidation || ['post', 'put', 'patch'].includes(method)) {
           lines.push(`__r["400"] = { description: "Validation Failed", content: { "application/json": { schema: ${errRef} } } };`);
@@ -2733,8 +2815,7 @@ export class ServerCodegen extends BaseCodegen {
           lines.push(`__r["504"] = { description: "Gateway Timeout", content: { "application/json": { schema: ${errRef} } } };`);
         }
         lines.push(`__r["500"] = { description: "Internal Server Error", content: { "application/json": { schema: ${errRef} } } };`);
-
-        lines.push('};');
+        lines.push('}');
       }
 
       // Add the /docs endpoint

package/src/diagnostics/error-codes.js

@@ -33,7 +33,7 @@ export const ErrorCode = {
   // === Context Errors (E300–E399) ===
   E300: { code: 'E300', title: 'Invalid context: await',         category: 'context' },
   E301: { code: 'E301', title: 'Invalid context: return',        category: 'context' },
-  E302: { code: 'E302', title: 'Invalid context: client-only',   category: 'context' },
+  E302: { code: 'E302', title: 'Invalid context: browser-only',  category: 'context' },
   E303: { code: 'E303', title: 'Invalid context: server-only',   category: 'context' },
   E304: { code: 'E304', title: 'Invalid context: function-only', category: 'context' },
 

package/src/docs/generator.js

@@ -25,7 +25,7 @@ export class DocGenerator {
           if (entry) docs.push(entry);
         }
         if (node.body && Array.isArray(node.body)) walk(node.body);
-        if ((node.type === 'ServerBlock' || node.type === 'ClientBlock' || node.type === 'SharedBlock') && node.body) {
+        if ((node.type === 'ServerBlock' || node.type === 'BrowserBlock' || node.type === 'SharedBlock') && node.body) {
           walk(node.body);
         }
       }

package/src/formatter/formatter.js

@@ -31,7 +31,7 @@ export class Formatter {
 
   _needsBlankLine(prevType, currType) {
     const declTypes = ['FunctionDeclaration', 'TypeDeclaration', 'InterfaceDeclaration',
-      'ImplDeclaration', 'TraitDeclaration', 'ServerBlock', 'ClientBlock', 'SharedBlock',
+      'ImplDeclaration', 'TraitDeclaration', 'ServerBlock', 'BrowserBlock', 'SharedBlock',
       'ComponentDeclaration', 'TestBlock'];
     return declTypes.includes(prevType) || declTypes.includes(currType);
   }
@@ -63,7 +63,7 @@ export class Formatter {
       case 'TraitDeclaration': return this.formatTraitDeclaration(node);
       case 'DeferStatement': return this.formatDeferStatement(node);
       case 'ServerBlock': return this.formatServerBlock(node);
-      case 'ClientBlock': return this.formatClientBlock(node);
+      case 'BrowserBlock': return this.formatBrowserBlock(node);
       case 'SharedBlock': return this.formatSharedBlock(node);
       case 'CompoundAssignment': return `${this.i()}${this.formatExpr(node.target)} ${node.operator} ${this.formatExpr(node.value)}`;
       case 'BlockStatement': return this.formatBlock(node);
@@ -424,9 +424,9 @@ export class Formatter {
     return code;
   }
 
-  formatClientBlock(node) {
+  formatBrowserBlock(node) {
     const name = node.name ? ` "${node.name}"` : '';
-    let code = `${this.i()}client${name} {\n`;
+    let code = `${this.i()}browser${name} {\n`;
     this.indent++;
     code += node.body.map(s => this.formatNode(s)).join('\n');
     this.indent--;

package/src/lexer/tokens.js

@@ -85,7 +85,8 @@ export const TokenType = {
 
   // Full-stack keywords
   SERVER: 'SERVER',
-  CLIENT: 'CLIENT',
+  BROWSER: 'BROWSER',
+  CLIENT: 'BROWSER',  // deprecated alias — both map to BROWSER
   SHARED: 'SHARED',
   ROUTE: 'ROUTE',
   STATE: 'STATE',
@@ -93,6 +94,10 @@ export const TokenType = {
   EFFECT: 'EFFECT',
   COMPONENT: 'COMPONENT',
   STORE: 'STORE',
+  FORM: 'FORM',
+  FIELD: 'FIELD',
+  GROUP: 'GROUP',
+  STEPS: 'STEPS',
   STYLE_BLOCK: 'STYLE_BLOCK',
 
   // HTTP methods (used in route declarations)
@@ -211,7 +216,8 @@ export const Keywords = {
   'is': TokenType.IS,
   'with': TokenType.WITH,
   'server': TokenType.SERVER,
-  'client': TokenType.CLIENT,
+  'browser': TokenType.BROWSER,
+  'client': TokenType.BROWSER,  // deprecated alias
   'shared': TokenType.SHARED,
   'route': TokenType.ROUTE,
   'state': TokenType.STATE,
@@ -219,6 +225,10 @@ export const Keywords = {
   'effect': TokenType.EFFECT,
   'component': TokenType.COMPONENT,
   'store': TokenType.STORE,
+  'form': TokenType.FORM,
+  'field': TokenType.FIELD,
+  'group': TokenType.GROUP,
+  'steps': TokenType.STEPS,
 };
 
 // Token class

package/src/lsp/server.js

@@ -475,7 +475,7 @@ class TovaLanguageServer {
     const keywords = [
       'fn', 'let', 'if', 'elif', 'else', 'for', 'while', 'loop', 'when', 'in',
       'return', 'match', 'type', 'import', 'from', 'true', 'false',
-      'nil', 'server', 'client', 'shared', 'pub', 'mut',
+      'nil', 'server', 'browser', 'client', 'shared', 'pub', 'mut',
       'try', 'catch', 'finally', 'break', 'continue', 'async', 'await',
       'guard', 'interface', 'derive', 'route', 'model', 'db',
     ];

package/src/parser/ast.js

@@ -27,14 +27,16 @@ export class ServerBlock {
   }
 }
 
-export class ClientBlock {
+export class BrowserBlock {
   constructor(body, loc, name = null) {
-    this.type = 'ClientBlock';
+    this.type = 'BrowserBlock';
     this.name = name;
     this.body = body;
     this.loc = loc;
   }
 }
+// Deprecated alias for backward compatibility
+export { BrowserBlock as ClientBlock };
 
 export class SharedBlock {
   constructor(body, loc, name = null) {
@@ -53,6 +55,24 @@ export class SecurityBlock {
   }
 }
 
+export class CliBlock {
+  constructor(config, commands, loc) {
+    this.type = 'CliBlock';
+    this.config = config;     // Array of CliConfigField
+    this.commands = commands;  // Array of CliCommandDeclaration
+    this.loc = loc;
+  }
+}
+
+export class EdgeBlock {
+  constructor(body, loc, name = null) {
+    this.type = 'EdgeBlock';
+    this.name = name;       // optional string name for named edge blocks
+    this.body = body;       // Array of edge statements (config, bindings, routes, functions, etc.)
+    this.loc = loc;
+  }
+}
+
 // ============================================================
 // Declarations
 // ============================================================
@@ -128,11 +148,12 @@ export class TypeVariant {
 }
 
 export class TypeField {
-  constructor(name, typeAnnotation, loc) {
+  constructor(name, typeAnnotation, loc, validators) {
     this.type = 'TypeField';
     this.name = name;
     this.typeAnnotation = typeAnnotation;
     this.loc = loc;
+    this.validators = validators || [];
   }
 }
 
@@ -665,7 +686,7 @@ export class RangePattern {
 }
 
 // ============================================================
-// Client-specific nodes (lazy-loaded from client-ast.js, re-exported for backward compat)
+// Browser-specific nodes (lazy-loaded from browser-ast.js, re-exported for backward compat)
 // ============================================================
 
 export {
@@ -673,7 +694,7 @@ export {
   ComponentDeclaration, ComponentStyleBlock, StoreDeclaration,
   JSXElement, JSXAttribute, JSXSpreadAttribute, JSXFragment,
   JSXText, JSXExpression, JSXFor, JSXIf, JSXMatch,
-} from './client-ast.js';
+} from './browser-ast.js';
 
 // ============================================================
 // Server-specific nodes (lazy-loaded from server-ast.js, re-exported for backward compat)
@@ -704,6 +725,25 @@ export {
   SecurityTrustProxyDeclaration, SecurityHstsDeclaration,
 } from './security-ast.js';
 
+// ============================================================
+// Edge-specific nodes (lazy-loaded from edge-ast.js, re-exported for backward compat)
+// ============================================================
+
+export {
+  EdgeConfigField, EdgeKVDeclaration, EdgeSQLDeclaration,
+  EdgeStorageDeclaration, EdgeQueueDeclaration, EdgeEnvDeclaration,
+  EdgeSecretDeclaration, EdgeScheduleDeclaration, EdgeConsumeDeclaration,
+} from './edge-ast.js';
+
+// ============================================================
+// Form-specific nodes (lazy-loaded from form-ast.js, re-exported for backward compat)
+// ============================================================
+
+export {
+  FormDeclaration, FormFieldDeclaration, FormGroupDeclaration,
+  FormArrayDeclaration, FormValidator, FormStepsDeclaration, FormStep,
+} from './form-ast.js';
+
 export class TestBlock {
   constructor(name, body, loc, options = {}) {
     this.type = 'TestBlock';

package/src/parser/{client-ast.js → browser-ast.js}

@@ -1,8 +1,8 @@
-// Client-specific AST Node definitions for the Tova language
-// Extracted from ast.js for lazy loading — only loaded when client { } blocks are used.
+// Browser-specific AST Node definitions for the Tova language
+// Extracted from ast.js for lazy loading — only loaded when browser { } blocks are used.
 
 // ============================================================
-// Client-specific nodes
+// Browser-specific nodes
 // ============================================================
 
 export class StateDeclaration {

package/src/parser/{client-parser.js → browser-parser.js}

@@ -1,42 +1,55 @@
-// Client-specific parser methods for the Tova language
-// Extracted from parser.js for lazy loading — only loaded when client { } blocks are encountered.
+// Browser-specific parser methods for the Tova language
+// Extracted from parser.js for lazy loading — only loaded when browser { } blocks are encountered.
 
 import { TokenType, Keywords } from '../lexer/tokens.js';
 import * as AST from './ast.js';
+import { installFormParser } from './form-parser.js';
 
-export function installClientParser(ParserClass) {
-  if (ParserClass.prototype._clientParserInstalled) return;
-  ParserClass.prototype._clientParserInstalled = true;
+export function installBrowserParser(ParserClass) {
+  if (ParserClass.prototype._browserParserInstalled) return;
+  ParserClass.prototype._browserParserInstalled = true;
 
-  ParserClass.prototype.parseClientBlock = function() {
+  installFormParser(ParserClass);
+
+  ParserClass.prototype.parseBrowserBlock = function() {
     const l = this.loc();
-    this.expect(TokenType.CLIENT);
-    // Optional block name: client "admin" { }
+    // Capture the keyword value before consuming for deprecation warning
+    const keyword = this.current().value;
+    this.expect(TokenType.BROWSER);
+    if (keyword === 'client') {
+      this.warnings = this.warnings || [];
+      this.warnings.push({
+        message: "`client` block is deprecated, use `browser` instead",
+        loc: l,
+      });
+    }
+    // Optional block name: browser "admin" { }
     let name = null;
     if (this.check(TokenType.STRING)) {
       name = this.advance().value;
     }
-    this.expect(TokenType.LBRACE, "Expected '{' after 'client'");
+    this.expect(TokenType.LBRACE, "Expected '{' after 'browser'");
     const body = [];
     while (!this.check(TokenType.RBRACE) && !this.isAtEnd()) {
       try {
-        const stmt = this.parseClientStatement();
+        const stmt = this.parseBrowserStatement();
         if (stmt) body.push(stmt);
       } catch (e) {
         this.errors.push(e);
         this._synchronizeBlock();
       }
     }
-    this.expect(TokenType.RBRACE, "Expected '}' to close client block");
-    return new AST.ClientBlock(body, l, name);
+    this.expect(TokenType.RBRACE, "Expected '}' to close browser block");
+    return new AST.BrowserBlock(body, l, name);
   };
 
-  ParserClass.prototype.parseClientStatement = function() {
+  ParserClass.prototype.parseBrowserStatement = function() {
     if (this.check(TokenType.STATE)) return this.parseState();
     if (this.check(TokenType.COMPUTED)) return this.parseComputed();
     if (this.check(TokenType.EFFECT)) return this.parseEffect();
     if (this.check(TokenType.COMPONENT)) return this.parseComponent();
     if (this.check(TokenType.STORE)) return this.parseStore();
+    if (this.check(TokenType.FORM)) return this.parseFormDeclaration();
     return this.parseStatement();
   };
 
@@ -125,6 +138,8 @@ export function installClientParser(ParserClass) {
         body.push(this.parseEffect());
       } else if (this.check(TokenType.COMPONENT)) {
         body.push(this.parseComponent());
+      } else if (this.check(TokenType.FORM)) {
+        body.push(this.parseFormDeclaration());
       } else {
         body.push(this.parseStatement());
       }
@@ -242,7 +257,13 @@ export function installClientParser(ParserClass) {
     const l = this.loc();
     this.expect(TokenType.LESS, "Expected '<'");
 
-    const tag = this.expect(TokenType.IDENTIFIER, "Expected tag name").value;
+    // Accept identifiers and keywords as JSX tag names (e.g., <form>, <label>)
+    let tag;
+    if (this.check(TokenType.IDENTIFIER) || (this.peek().value in Keywords)) {
+      tag = this.advance().value;
+    } else {
+      tag = this.expect(TokenType.IDENTIFIER, "Expected tag name").value;
+    }
 
     // Parse attributes (including spread: {...expr})
     const attributes = [];
@@ -330,7 +351,13 @@ export function installClientParser(ParserClass) {
       if (this.check(TokenType.LESS) && this.peek(1).type === TokenType.SLASH) {
         this.advance(); // <
         this.advance(); // /
-        const closeTag = this.expect(TokenType.IDENTIFIER, "Expected closing tag name").value;
+        // Accept identifiers and keywords as JSX closing tag names (e.g., </form>)
+        let closeTag;
+        if (this.check(TokenType.IDENTIFIER) || (this.peek().value in Keywords)) {
+          closeTag = this.advance().value;
+        } else {
+          closeTag = this.expect(TokenType.IDENTIFIER, "Expected closing tag name").value;
+        }
         if (closeTag !== parentTag) {
           this.error(`Mismatched closing tag: expected </${parentTag}>, got </${closeTag}>`);
         }

package/src/parser/cli-ast.js

@@ -0,0 +1,35 @@
+// CLI-specific AST Node definitions for the Tova language
+// Extracted for lazy loading — only loaded when cli { } blocks are used.
+
+export class CliConfigField {
+  constructor(key, value, loc) {
+    this.type = 'CliConfigField';
+    this.key = key;       // string — "name", "version", "description"
+    this.value = value;   // Expression (StringLiteral, etc.)
+    this.loc = loc;
+  }
+}
+
+export class CliCommandDeclaration {
+  constructor(name, params, body, isAsync, loc) {
+    this.type = 'CliCommandDeclaration';
+    this.name = name;       // string — command name
+    this.params = params;   // Array of CliParam
+    this.body = body;       // BlockStatement
+    this.isAsync = isAsync; // boolean
+    this.loc = loc;
+  }
+}
+
+export class CliParam {
+  constructor(name, typeAnnotation, defaultValue, isFlag, isOptional, isRepeated, loc) {
+    this.type = 'CliParam';
+    this.name = name;               // string — parameter name
+    this.typeAnnotation = typeAnnotation; // string or null — "String", "Int", "Float", "Bool"
+    this.defaultValue = defaultValue;     // Expression or null
+    this.isFlag = isFlag;           // boolean — prefixed with --
+    this.isOptional = isOptional;   // boolean — Type? suffix
+    this.isRepeated = isRepeated;   // boolean — [Type] array flag
+    this.loc = loc;
+  }
+}

package/src/parser/cli-parser.js

@@ -0,0 +1,140 @@
+// CLI-specific parser methods for the Tova language
+// Extracted from parser.js for lazy loading — only loaded when cli { } blocks are encountered.
+
+import { TokenType } from '../lexer/tokens.js';
+import * as AST from './ast.js';
+import { CliConfigField, CliCommandDeclaration, CliParam } from './cli-ast.js';
+
+// Valid config keys inside cli blocks
+const CLI_CONFIG_KEYS = new Set(['name', 'version', 'description']);
+
+export function installCliParser(ParserClass) {
+  if (ParserClass.prototype._cliParserInstalled) return;
+  ParserClass.prototype._cliParserInstalled = true;
+
+  ParserClass.prototype.parseCliBlock = function() {
+    const l = this.loc();
+    this.advance(); // consume 'cli'
+    this.expect(TokenType.LBRACE, "Expected '{' after 'cli'");
+    const config = [];
+    const commands = [];
+
+    while (!this.check(TokenType.RBRACE) && !this.isAtEnd()) {
+      try {
+        // fn or async fn → command
+        if (this.check(TokenType.FN) ||
+            (this.check(TokenType.ASYNC) && this.peek(1).type === TokenType.FN)) {
+          commands.push(this.parseCliCommand());
+        }
+        // identifier followed by colon → config field
+        else if (this.check(TokenType.IDENTIFIER) && this.peek(1).type === TokenType.COLON) {
+          config.push(this.parseCliConfigField());
+        }
+        else {
+          this.error("Expected config field (name: ...) or command (fn ...) inside cli block");
+        }
+      } catch (e) {
+        this.errors.push(e);
+        this._synchronizeBlock();
+      }
+    }
+
+    this.expect(TokenType.RBRACE, "Expected '}' to close cli block");
+    return new AST.CliBlock(config, commands, l);
+  };
+
+  ParserClass.prototype.parseCliConfigField = function() {
+    const l = this.loc();
+    const key = this.advance().value; // consume identifier
+    this.expect(TokenType.COLON, "Expected ':' after config key");
+    const value = this.parseExpression();
+    return new CliConfigField(key, value, l);
+  };
+
+  ParserClass.prototype.parseCliCommand = function() {
+    const l = this.loc();
+    let isAsync = false;
+    if (this.check(TokenType.ASYNC)) {
+      isAsync = true;
+      this.advance(); // consume 'async'
+    }
+    this.expect(TokenType.FN, "Expected 'fn' for cli command");
+    const name = this.expect(TokenType.IDENTIFIER, "Expected command name").value;
+    this.expect(TokenType.LPAREN, "Expected '(' after command name");
+    const params = this.parseCliParameterList();
+    this.expect(TokenType.RPAREN, "Expected ')' after parameters");
+
+    // Parse body
+    const body = this.parseBlock();
+
+    return new CliCommandDeclaration(name, params, body, isAsync, l);
+  };
+
+  ParserClass.prototype.parseCliParameterList = function() {
+    const params = [];
+    while (!this.check(TokenType.RPAREN) && !this.isAtEnd()) {
+      if (params.length > 0) {
+        this.expect(TokenType.COMMA, "Expected ',' between parameters");
+      }
+      params.push(this.parseCliParam());
+    }
+    return params;
+  };
+
+  ParserClass.prototype.parseCliParam = function() {
+    const l = this.loc();
+    let isFlag = false;
+
+    // Check for -- prefix (two MINUS tokens)
+    if (this.check(TokenType.MINUS) && this.peek(1).type === TokenType.MINUS) {
+      isFlag = true;
+      this.advance(); // consume first -
+      this.advance(); // consume second -
+    }
+
+    const name = this.expect(TokenType.IDENTIFIER, "Expected parameter name").value;
+
+    // Parse optional type annotation: param: Type, param: Type?, param: [Type]
+    let typeAnnotation = null;
+    let isOptional = false;
+    let isRepeated = false;
+
+    if (this.match(TokenType.COLON)) {
+      // [Type] → repeated
+      if (this.check(TokenType.LBRACKET)) {
+        isRepeated = true;
+        this.advance(); // consume [
+        typeAnnotation = this._parseCliTypeName();
+        this.expect(TokenType.RBRACKET, "Expected ']' after array type");
+      } else {
+        typeAnnotation = this._parseCliTypeName();
+        // Type? → optional
+        if (this.check(TokenType.QUESTION)) {
+          isOptional = true;
+          this.advance(); // consume ?
+        }
+      }
+    }
+
+    // Bool flags are implicitly optional (default false)
+    if (isFlag && typeAnnotation === 'Bool' && !isOptional) {
+      isOptional = true;
+    }
+
+    // Parse default value: = expr
+    let defaultValue = null;
+    if (this.match(TokenType.ASSIGN)) {
+      defaultValue = this.parseExpression();
+    }
+
+    return new CliParam(name, typeAnnotation, defaultValue, isFlag, isOptional, isRepeated, l);
+  };
+
+  // Helper to parse a simple type name (String, Int, Float, Bool, or IDENTIFIER)
+  ParserClass.prototype._parseCliTypeName = function() {
+    if (this.check(TokenType.IDENTIFIER) || this.check(TokenType.TYPE)) {
+      return this.advance().value;
+    }
+    this.error("Expected type name");
+  };
+}