future-lang 0.3.1 → 0.4.0

package/FUTURE_FOR_LLMS.md

@@ -0,0 +1,331 @@
+# Future — Reference for LLMs
+
+Future is a small language that compiles to JavaScript. It does NOT exist in your training data. Read this file before generating Future code.
+
+---
+
+## Reserved words
+
+```
+print  if  else  end  function  return  true  false  null  none
+and  or  not  for  in  while  try  catch  on  every  stream
+agent  use  as
+```
+
+Reserved namespaces (cannot be reassigned or used as function names):
+```
+ai  http  mqtt  tts  rag  vision  home  memory  schedule  system  device  math
+```
+
+---
+
+## Grammar (simplified BNF)
+
+```
+program     = statement*
+statement   = print | assignment | if | function | return
+            | for | while | try | on | every | stream | agent | use | expr_stmt
+
+print       = "print" expression
+assignment  = IDENTIFIER "=" expression
+if          = "if" expression block ("else if" expression block)* ("else" block)? "end"
+function    = "function" IDENTIFIER "(" params ")" block "end"
+return      = "return" expression?
+for         = "for" IDENTIFIER "in" expression block "end"
+while       = "while" expression block "end"
+try         = "try" block "catch" IDENTIFIER block "end"
+on          = "on" IDENTIFIER expression block "end"
+every       = "every" expression block "end"
+stream      = "stream" call_expr block "end"
+agent       = "agent" IDENTIFIER ("use" IDENTIFIER)* block "end"
+use         = "use" STRING ("as" IDENTIFIER)?
+
+block       = statement*
+params      = (IDENTIFIER ("," IDENTIFIER)*)?
+expression  = or_expr
+call_expr   = IDENTIFIER "(" args ")"
+            | IDENTIFIER "." IDENTIFIER "(" args ")"
+args        = (expression ("," expression)*)?
+```
+
+---
+
+## Syntax rules
+
+- Blocks end with `end` — NO curly braces, NO semicolons
+- `#` starts a line comment
+- Strings: `"double"` or `'single'`
+- String interpolation: `"Hello, {name}!"` — any `{identifier}` or `{identifier.prop}`
+- Escape literal brace: `\{`
+- `null` and `none` are the same
+- Commas in lists: required — `[1, 2, 3]`
+- Commas in objects: optional — `{ name: "Alice"  age: 30 }` or `{ name: "Alice", age: 30 }`
+
+---
+
+## Every construct with example
+
+### Variables
+```
+name = "Alice"
+age  = 30
+ok   = true
+data = null
+```
+
+### Print
+```
+print "Hello, {name}!"
+print age
+```
+
+### If / else if / else
+```
+if score >= 90
+    print "A"
+else if score >= 80
+    print "B"
+else if score >= 70
+    print "C"
+else
+    print "F"
+end
+```
+
+### Function
+```
+function add(a, b)
+    return a + b
+end
+
+result = add(3, 4)
+print result
+```
+
+### For loop
+```
+fruits = ["apple", "banana", "cherry"]
+for fruit in fruits
+    print "I like {fruit}"
+end
+```
+
+### While loop
+```
+count = 0
+while count < 5
+    count = count + 1
+end
+```
+
+### Try / catch
+```
+try
+    data = http.get("https://api.example.com/data")
+    print data.title
+catch err
+    print "Error: {err}"
+end
+```
+
+### Objects and lists
+```
+user   = { name: "João"  age: 30  city: "Lisbon" }
+scores = [85, 92, 78]
+print user.name
+print scores.length
+```
+
+### String interpolation
+```
+msg = "Name: {user.name}, Age: {user.age}"
+print msg
+print "Pi is {math.pi}"
+```
+
+---
+
+## Import system
+
+```
+# Import all functions from a file by name
+use "./utils.future"
+result = formatName("Alice")
+
+# Import as a namespace
+use "./math.future" as m
+result = m.add(10, 20)
+
+# Import an npm package as a namespace
+use "date-fns" as df
+```
+
+Imported `.future` files must contain only top-level function declarations. They compile to ES module exports automatically.
+
+---
+
+## Capability namespaces
+
+No `async`/`await` needed — the compiler handles it. Any namespace call switches the program to async mode automatically.
+
+### `ai`
+```
+answer  = ai.ask("What is the capital of France?")
+reply   = ai.chat([{ role: "user"  content: "Hello" }])
+embed   = ai.embed("text to embed")
+ai.configure("openai", "sk-...")
+ai.configure("ollama")
+
+stream ai.ask("Tell me a story")
+    print chunk
+end
+```
+
+### `http`
+```
+data = http.get("https://api.example.com/todos/1")
+print data.title
+
+res = http.post("https://api.example.com/items", { name: "Widget"  price: 9.99 })
+print res.id
+```
+
+### `mqtt`
+```
+mqtt.publish("home/light", "on")
+
+on mqtt "home/temp"
+    print "Temperature: {message}"
+end
+```
+
+### `tts`
+```
+tts.speak("Hello from Future!")
+```
+
+### `memory`
+```
+memory.set("key", "value")
+val = memory.get("key")
+memory.delete("key")
+results = memory.search("query")
+memory.forget()          # clear all
+memory.forget("prefix")  # clear matching keys
+```
+
+### `schedule`
+```
+every "30m"
+    data = http.get("https://api.example.com/stats")
+    print data.count
+end
+
+# schedule.once and schedule.cron also available
+```
+
+### `http`, `system`, `rag`, `vision`, `home`, `device`
+See [README.md](README.md) for full API tables.
+
+### `math`
+```
+print math.round(3.7)    # 4
+print math.sqrt(16)      # 4
+print math.pi            # 3.14159…
+print math.random()      # 0–1
+print math.max(1, 5, 3)  # 5
+```
+
+### `len` (built-in, not a namespace)
+```
+print len([1, 2, 3])          # 3
+print len("hello")            # 5
+print len({ a: 1  b: 2 })     # 2
+```
+
+---
+
+## Agents
+
+```
+agent support
+    use rag
+    use memory
+
+    docs = rag.query(goal)
+    memory.set("last", goal)
+    return docs
+end
+
+answer = support("How do I reset the device?")
+print answer
+```
+
+`goal` is the implicit parameter. `use` inside an agent declares capabilities (documentation only — no generated code).
+
+---
+
+## Common mistakes
+
+| Wrong | Correct |
+|-------|---------|
+| `if (x > 0) {` | `if x > 0` |
+| `end if` | `end` |
+| `elif` | `else if` |
+| `&&` / `\|\|` / `!` | `and` / `or` / `not` |
+| `x++` | `x = x + 1` |
+| `x += 1` | `x = x + 1` |
+| `// comment` | `# comment` |
+| `import "./utils.js"` | `use "./utils.future"` |
+| `let x = 5` | `x = 5` |
+| `function f() { }` | `function f()` + body + `end` |
+
+---
+
+## What compiles to what
+
+```future
+x = 1
+```
+```js
+let x;
+x = 1;
+```
+
+```future
+if x > 0
+    print "positive"
+else if x < 0
+    print "negative"
+else
+    print "zero"
+end
+```
+```js
+if (x > 0) {
+  console.log("positive");
+} else if (x < 0) {
+  console.log("negative");
+} else {
+  console.log("zero");
+}
+```
+
+```future
+answer = ai.ask("Hello?")
+```
+```js
+import { runtime as __rt } from "future-lang/runtime";
+let answer;
+answer = await __rt.ai.ask("Hello?");
+```
+
+```future
+use "./utils.future"
+name = formatName("Alice")
+```
+```js
+import { formatName } from "./utils.js";
+let name;
+name = formatName("Alice");
+```

package/README.md

@@ -9,7 +9,7 @@ Future reads like plain English, runs on Node.js, and gives every program built-
 ## Quick start
 
 ```bash
-npm install future-lang
+npm install -g future-lang
 ```
 
 ```future
@@ -331,8 +331,49 @@ Open `future-playground.html` in any browser for a live editor with 11 built-in
 ## CLI
 
 ```bash
+npm install -g future-lang
+
+future --version                    # show version
+future new myapp                    # create a new project
 future run program.future           # compile + run
-future compile program.future       # print generated JavaScript
+future compile program.future       # compile to JavaScript
+future check program.future         # syntax check only
+future fmt program.future           # format source in-place
+future playground                   # launch the interactive playground
+future doctor                       # check your environment
+```
+
+---
+
+## Import system
+
+Split code across files with `use`:
+
+```future
+# utils.future
+function formatName(name)
+    return "User: {name}"
+end
+```
+
+```future
+# main.future
+
+# import all functions by name
+use "./utils.future"
+print formatName("Alice")
+
+# import as a namespace
+use "./math.future" as m
+result = m.add(10, 20)
+print result
+```
+
+Compiles to standard ES module imports:
+
+```js
+import { formatName } from "./utils.js";
+import * as m from "./math.js";
 ```
 
 ---
@@ -365,6 +406,6 @@ Source (.future)  →  Lexer  →  Parser  →  Generator  →  JavaScript
 
 ## Documentation
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) — compiler pipeline, folder structure, AST node types
-- [ROADMAP.md](ROADMAP.md) — feature status and priorities
-- [MIGRATION.md](MIGRATION.md) — changelog, what changed between versions
+- [ARCHITECTURE.md](https://github.com/humolot/future-lang/blob/main/ARCHITECTURE.md) — compiler pipeline, folder structure, AST node types
+- [ROADMAP.md](https://github.com/humolot/future-lang/blob/main/ROADMAP.md) — feature status and priorities
+- [MIGRATION.md](https://github.com/humolot/future-lang/blob/main/MIGRATION.md) — changelog, what changed between versions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "future-lang",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Future — a small programming language that transpiles to JavaScript, with a capability runtime (HTTP/AI/MQTT/TTS).",
   "type": "module",
   "bin": {

package/runtime/index.js

@@ -24,7 +24,37 @@ const MODULE_NAMES = [
   'memory', 'schedule', 'system', 'device', 'math',
 ];
 
-export const runtime = { ai, http, mqtt, tts, rag, vision, home, memory, schedule, system, device, math };
+const _base = { ai, http, mqtt, tts, rag, vision, home, memory, schedule, system, device, math };
+
+/**
+ * When FUTURE_DEBUG=1, wrap every namespace method with timing/logging.
+ * Non-function properties (constants like math.pi) pass through unchanged.
+ */
+function wrapDebug(base) {
+  const wrapped = {};
+  for (const [ns, mod] of Object.entries(base)) {
+    wrapped[ns] = {};
+    for (const [key, val] of Object.entries(mod)) {
+      if (typeof val !== 'function') { wrapped[ns][key] = val; continue; }
+      wrapped[ns][key] = async (...args) => {
+        const preview = args.length ? String(JSON.stringify(args[0])).slice(0, 60) : '';
+        process.stderr.write(`\x1b[90m[debug] ${ns}.${key}(${preview}) …\x1b[0m\n`);
+        const t = Date.now();
+        try {
+          const result = await val(...args);
+          process.stderr.write(`\x1b[90m[debug] ${ns}.${key} ✓ ${Date.now() - t}ms\x1b[0m\n`);
+          return result;
+        } catch (err) {
+          process.stderr.write(`\x1b[31m[debug] ${ns}.${key} ✗ ${Date.now() - t}ms — ${err.message}\x1b[0m\n`);
+          throw err;
+        }
+      };
+    }
+  }
+  return wrapped;
+}
+
+export const runtime = process.env.FUTURE_DEBUG === '1' ? wrapDebug(_base) : _base;
 
 // input(prompt) — reads a line from stdin (CLI programs).
 runtime.input = async (prompt = '') => {
@@ -395,7 +425,7 @@ runtime.listFunctions = (mod) => {
  * Suitable for AI agent discovery or documentation generation.
  */
 runtime.describe = () => ({
-  version: '0.2.0',
+  version: '0.4.0',
   modules: [...MODULE_NAMES],
   manifest,
 });

package/src/cli.js

@@ -21,7 +21,7 @@ import { compile, tokenize, parse } from './index.js';
 import { format } from './formatter.js';
 import { FutureError } from './errors.js';
 
-const VERSION = '0.3.1';
+const VERSION = '0.4.0';
 const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const RUNTIME_INDEX = join(PROJECT_ROOT, 'runtime', 'index.js');
 
@@ -41,10 +41,17 @@ Usage:
 Import system:
   use "./utils.future"              Import all functions from a file
   use "./math.future" as math       Import as a namespace (math.add, math.pi …)
+  use "lodash" as _                 Import an npm package as a namespace
+
+Flags:
+  future run --debug <file>         Show timing for every namespace call
 `;
 
 async function main(argv) {
-  const [command, arg] = argv;
+  const debug = argv.includes('--debug');
+  if (debug) process.env.FUTURE_DEBUG = '1';
+  const rest = argv.filter((a) => a !== '--debug');
+  const [command, arg] = rest;
   switch (command) {
     case 'run':        return cmdRun(arg);
     case 'compile':    return cmdCompile(arg);
@@ -138,6 +145,7 @@ function compileDepsToTemp(sourcePath, sourceText, tempDir, pathMap = new Map())
   const uses = findUseStatements(sourceText);
   for (const { path: relPath } of uses) {
     if (pathMap.has(relPath)) continue; // already compiled
+    if (!relPath.startsWith('./') && !relPath.startsWith('../')) continue; // npm module
     const depAbsPath = resolve(dirname(sourcePath), relPath);
     if (!existsSync(depAbsPath)) continue;
     const depSource = readFileSync(depAbsPath, 'utf8');
@@ -163,6 +171,7 @@ function compileDepModule(source, sourcePath, tempDir, pathMap) {
   // Ensure transitive deps are compiled first so pathMap is populated.
   for (const { path: relPath } of uses) {
     if (pathMap.has(relPath)) continue;
+    if (!relPath.startsWith('./') && !relPath.startsWith('../')) continue; // npm module
     const depAbsPath = resolve(dirname(sourcePath), relPath);
     if (!existsSync(depAbsPath)) continue;
     const depSrc = readFileSync(depAbsPath, 'utf8');
@@ -199,6 +208,7 @@ function cmdCompile(file) {
   // Compile each imported .future dep as a module next to its source.
   const uses = findUseStatements(source);
   for (const { path: relPath } of uses) {
+    if (!relPath.startsWith('./') && !relPath.startsWith('../')) continue; // npm module
     const depAbsPath = resolve(outDir, relPath);
     if (!existsSync(depAbsPath)) {
       process.stderr.write(`warning: imported file not found: ${relPath}\n`);

package/src/generator.js

@@ -62,6 +62,12 @@ export class Generator {
       lines.push('');
     }
 
+    // __safe wraps async event handlers so errors are logged instead of crashing silently.
+    if (usesHandlers(program)) {
+      lines.push('const __safe = (ns, fn) => async (...a) => { try { return await fn(...a); } catch (e) { console.error(`[future:${ns}]`, e.message); } };');
+      lines.push('');
+    }
+
     // Emit __len helper only when len() is actually used — keeps simple programs clean.
     if (usesBuiltin(program, 'len')) {
       lines.push('function __len(x) { return x == null ? 0 : (x.length ?? Object.keys(x).length); }');
@@ -80,11 +86,17 @@ export class Generator {
 
   /** Emit an ES `import` for a `use` statement. */
   genUseStatement(node) {
-    const jsPath = node.path.replace(/\.future$/, '.js');
+    const isRelative = node.path.startsWith('./') || node.path.startsWith('../');
+    const jsPath  = isRelative ? node.path.replace(/\.future$/, '.js') : node.path;
     const resolved = this.pathMap.get(node.path) ?? jsPath;
+
     if (node.alias) {
       return `import * as ${node.alias} from ${JSON.stringify(resolved)};`;
     }
+    if (!isRelative) {
+      // npm module without alias — side-effect import
+      return `import ${JSON.stringify(resolved)};`;
+    }
     const names = this.importedNames.get(node.path) ?? [];
     if (names.length > 0) {
       return `import { ${names.join(', ')} } from ${JSON.stringify(resolved)};`;
@@ -111,7 +123,13 @@ export class Generator {
         out += this.genBody(node.consequent, depth + 1);
         out += `\n${pad}}`;
         if (node.alternate) {
-          out += ` else {\n${this.genBody(node.alternate, depth + 1)}\n${pad}}`;
+          // Single chained IfStatement → `else if (...)` without extra braces.
+          if (node.alternate.length === 1 && node.alternate[0].type === NodeType.IfStatement) {
+            const elseIf = this.genStatement(node.alternate[0], depth);
+            out += ` else ${elseIf.trimStart()}`;
+          } else {
+            out += ` else {\n${this.genBody(node.alternate, depth + 1)}\n${pad}}`;
+          }
         }
         return out;
       }
@@ -172,7 +190,7 @@ export class Generator {
         const args = call.arguments.map((a) => this.genExpression(a)).join(', ');
         const sep  = args ? ', ' : '';
         const inner = this.genBody(node.body, depth + 1);
-        return `${pad}await __rt.${ns}.stream(${args}${sep}async (chunk) => {\n${inner}\n${pad}});`;
+        return `${pad}await __rt.${ns}.stream(${args}${sep}__safe("stream", async (chunk) => {\n${inner}\n${pad}}));`;
       }
 
       case NodeType.TryStatement: {
@@ -201,18 +219,19 @@ export class Generator {
 
       case NodeType.OnStatement: {
         // `on mqtt "topic" ... end`
-        // Compiles to: await __rt.<source>.subscribe(<channel>, async (message) => { ... })
+        // → await __rt.<source>.subscribe(<channel>, __safe("<source>", async (message) => { ... }))
         const inner = this.genBody(node.body, depth + 1);
         const chan  = this.genExpression(node.channel);
-        return `${pad}await __rt.${node.source}.subscribe(${chan}, async (message) => {\n${inner}\n${pad}});`;
+        const ns    = JSON.stringify(node.source);
+        return `${pad}await __rt.${node.source}.subscribe(${chan}, __safe(${ns}, async (message) => {\n${inner}\n${pad}}));`;
       }
 
       case NodeType.EveryStatement: {
         // `every "30m" ... end`
-        // Compiles to: await __rt.schedule.every(<interval>, async () => { ... })
+        // → await __rt.schedule.every(<interval>, __safe("schedule", async () => { ... }))
         const inner    = this.genBody(node.body, depth + 1);
         const interval = this.genExpression(node.interval);
-        return `${pad}await __rt.schedule.every(${interval}, async () => {\n${inner}\n${pad}});`;
+        return `${pad}await __rt.schedule.every(${interval}, __safe("schedule", async () => {\n${inner}\n${pad}}));`;
       }
 
       default:
@@ -390,6 +409,22 @@ function usesRuntime(node, useAliases = new Set()) {
   return false;
 }
 
+/** True if the program has any async event handlers (on/every/stream). */
+function usesHandlers(node) {
+  if (!node || typeof node !== 'object') return false;
+  if (
+    node.type === NodeType.OnStatement ||
+    node.type === NodeType.EveryStatement ||
+    node.type === NodeType.StreamStatement
+  ) return true;
+  for (const key of Object.keys(node)) {
+    const v = node[key];
+    if (Array.isArray(v)) { if (v.some(usesHandlers)) return true; }
+    else if (v && typeof v === 'object' && v.type) { if (usesHandlers(v)) return true; }
+  }
+  return false;
+}
+
 /** Walk the AST and check if a specific built-in function name is called. */
 function usesBuiltin(node, name) {
   if (!node || typeof node !== 'object') return false;

package/src/index.js

@@ -31,6 +31,8 @@ export function compile(source, options = {}) {
   if (options.resolveSource) {
     for (const stmt of ast.body) {
       if (stmt.type !== 'UseStatement' || stmt.alias) continue;
+      // Skip npm module imports — no source to resolve.
+      if (!stmt.path.startsWith('./') && !stmt.path.startsWith('../')) continue;
       try {
         const importedSrc = options.resolveSource(stmt.path);
         if (importedSrc) {

package/src/parser.js

@@ -16,6 +16,12 @@ import * as AST from './ast.js';
  */
 const EXPR_TERMINATORS = new Set(['END', 'ELSE', 'CATCH', 'EOF']);
 
+/** Built-in namespace names that cannot be redefined by user code. */
+const RESERVED_NAMESPACES = new Set([
+  'ai', 'http', 'mqtt', 'tts', 'rag', 'vision', 'home',
+  'memory', 'schedule', 'system', 'device', 'math',
+]);
+
 export class Parser {
   /** @param {import('./lexer.js').Token[]} tokens */
   constructor(tokens) {
@@ -113,27 +119,51 @@ export class Parser {
 
   parseAssignment() {
     const name = this.advance(); // IDENTIFIER
+    if (RESERVED_NAMESPACES.has(name.value)) {
+      throw new FutureError(
+        `'${name.value}' is a reserved namespace and cannot be reassigned`,
+        name.line, name.column, 'parse',
+      );
+    }
     this.expect('ASSIGN', "'='");
     const value = this.parseExpression();
     return AST.Assignment(name.value, value, name.line, name.column);
   }
 
-  parseIf() {
+  /**
+   * `if cond ... [else if cond ...]* [else ...] end`
+   * @param {boolean} isChained  True when parsing an `else if` branch — the
+   *   outer `if` owns the single `end`, so this call must NOT consume it.
+   */
+  parseIf(isChained = false) {
     const kw = this.advance(); // IF
     const condition = this.parseExpression();
-    const consequent = this.parseBlock(['ELSE', 'END']);
+    const consequent = this.parseBlock(['ELSE', 'END'], 'if');
     let alternate = null;
     if (this.check('ELSE')) {
-      this.advance();
-      alternate = this.parseBlock(['END']);
+      this.advance(); // ELSE
+      if (this.check('IF')) {
+        // else if — recurse; the chained call skips its own `end`
+        alternate = [this.parseIf(true)];
+      } else {
+        alternate = this.parseBlock(['END'], 'else');
+      }
+    }
+    if (!isChained) {
+      this.expect('END', "'end' to close 'if'");
     }
-    this.expect('END', "'end'");
     return AST.IfStatement(condition, consequent, alternate, kw.line, kw.column);
   }
 
   parseFunction() {
     const kw = this.advance(); // FUNCTION
     const name = this.expect('IDENTIFIER', 'function name');
+    if (RESERVED_NAMESPACES.has(name.value)) {
+      throw new FutureError(
+        `'${name.value}' is a reserved namespace and cannot be used as a function name`,
+        name.line, name.column, 'parse',
+      );
+    }
     this.expect('LPAREN', "'('");
     const params = [];
     if (!this.check('RPAREN')) {
@@ -142,8 +172,8 @@ export class Parser {
       } while (this.match('COMMA'));
     }
     this.expect('RPAREN', "')'");
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'function');
+    this.expect('END', "'end' to close 'function'");
     return AST.FunctionDeclaration(name.value, params, body, kw.line, kw.column);
   }
 
@@ -169,8 +199,8 @@ export class Parser {
     const variable = this.expect('IDENTIFIER', 'loop variable name');
     this.expect('IN', "'in'");
     const iterable = this.parseExpression();
-    const body     = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body     = this.parseBlock(['END'], 'for');
+    this.expect('END', "'end' to close 'for'");
     return AST.ForStatement(variable.value, iterable, body, kw.line, kw.column);
   }
 
@@ -179,11 +209,11 @@ export class Parser {
    */
   parseTry() {
     const kw      = this.advance(); // TRY
-    const body    = this.parseBlock(['CATCH']);
-    this.expect('CATCH', "'catch'");
+    const body    = this.parseBlock(['CATCH'], 'try');
+    this.expect('CATCH', "'catch' after 'try' block");
     const errVar  = this.expect('IDENTIFIER', 'error variable name');
-    const catchBody = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const catchBody = this.parseBlock(['END'], 'catch');
+    this.expect('END', "'end' to close 'try'");
     return AST.TryStatement(body, errVar.value, catchBody, kw.line, kw.column);
   }
 
@@ -211,7 +241,7 @@ export class Parser {
         body.push(this.parseStatement());
       }
     }
-    this.expect('END', "'end'");
+    this.expect('END', "'end' to close 'agent'");
     return AST.AgentDeclaration(name.value, capabilities, body, kw.line, kw.column);
   }
 
@@ -221,8 +251,8 @@ export class Parser {
   parseWhile() {
     const kw = this.advance(); // WHILE
     const condition = this.parseExpression();
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'while');
+    this.expect('END', "'end' to close 'while'");
     return AST.WhileStatement(condition, body, kw.line, kw.column);
   }
 
@@ -235,8 +265,8 @@ export class Parser {
   parseStream() {
     const kw = this.advance(); // STREAM
     const call = this.parseExpression();
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'stream');
+    this.expect('END', "'end' to close 'stream'");
     return AST.StreamStatement(call, body, kw.line, kw.column);
   }
 
@@ -249,8 +279,8 @@ export class Parser {
     const kw = this.advance(); // ON
     const source = this.expect('IDENTIFIER', 'event source name (e.g. mqtt)');
     const channel = this.parseExpression();
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'on');
+    this.expect('END', "'end' to close 'on'");
     return AST.OnStatement(source.value, channel, body, kw.line, kw.column);
   }
 
@@ -262,8 +292,8 @@ export class Parser {
   parseEvery() {
     const kw = this.advance(); // EVERY
     const interval = this.parseExpression();
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'every');
+    this.expect('END', "'end' to close 'every'");
     return AST.EveryStatement(interval, body, kw.line, kw.column);
   }
 
@@ -271,7 +301,7 @@ export class Parser {
    * Collect statements until one of `terminators` (or EOF) is next.
    * Throws if EOF is reached before a terminator (e.g. a missing `end`).
    */
-  parseBlock(terminators) {
+  parseBlock(terminators, openedBy = null) {
     const statements = [];
     while (!this.check('EOF') && !terminators.includes(this.peek().type)) {
       statements.push(this.parseStatement());
@@ -279,8 +309,9 @@ export class Parser {
     if (this.check('EOF')) {
       const tok = this.peek();
       const expected = terminators.map((t) => `'${t.toLowerCase()}'`).join(' or ');
+      const hint = openedBy ? ` to close '${openedBy}'` : '';
       throw new FutureError(
-        `Unexpected end of file, expected ${expected}`,
+        `Unexpected end of file — expected ${expected}${hint}`,
         tok.line, tok.column, 'parse',
       );
     }