future-lang 0.4.1 → 0.4.2

package/ARCHITECTURE.md

@@ -15,22 +15,25 @@ future-lang/
 │   ├── index.js                    # Public API — compile(source, options)
 │   ├── lexer.js                    # Phase 1: source text → token list
 │   ├── parser.js                   # Phase 2: token list → AST
-│   ├── ast.js                      # AST node types and factory functions (23 types)
+│   ├── ast.js                      # AST node types and factory functions (24 types)
 │   ├── generator.js                # Phase 3: AST → JavaScript source
 │   ├── errors.js                   # FutureError with line/column tracking
-│   └── cli.js                      # CLI binary: future run / future compile
+│   ├── formatter.js                # Line-based auto-formatter (future fmt)
+│   ├── sourcemap.js                # VLQ encoder + Source Map v3 builder
+│   └── cli.js                      # CLI binary: 9 commands including future test
 │
 ├── runtime/                        # Capability modules (imported by generated JS)
 │   ├── index.js                    # Aggregator: runtime object + manifest + introspection
 │   │
-│   ├── ai.js                       # Text generation — pluggable provider architecture
-│   ├── http.js                     # REST API consumption (fetch-based)
+│   ├── ai.js                       # Text generation — ask/chat/stream accept opts {temperature, max_tokens, model}
+│   ├── http.js                     # REST API — HttpError class, configure() for global headers/timeout
 │   ├── mqtt.js                     # Pub/sub messaging (real broker or in-process loopback)
 │   ├── tts.js                      # Text-to-speech (system engine)
 │   ├── rag.js                      # RAG — chunk → embed → store → retrieve → answer
 │   ├── vision.js                   # Vision AI — describe, detect, ocr, classify, compare
 │   ├── home.js                     # Home automation (composes over MQTT)
 │   │
+│   ├── assert.js                   # Test assertions — ok/equal/notEqual/deepEqual/fail
 │   ├── memory.js                   # In-process key-value store (set/get/search/delete/forget)
 │   ├── schedule.js                 # Recurring / one-shot / cron scheduling
 │   ├── system.js                   # OS utilities: exec, open, notify, read, write
@@ -41,7 +44,7 @@ future-lang/
 │   │
 │   ├── providers/                  # AI provider implementations
 │   │   ├── index.js                # Provider factory + env-var resolution
-│   │   ├── anthropic.js            # Anthropic Messages API (native format)
+│   │   ├── anthropic.js            # Anthropic Messages API — AiError class, opts forwarding
 │   │   ├── openai-compat.js        # OpenAI-compatible (OpenAI, Ollama, Gemini, OpenRouter, …)
 │   │   └── util.js                 # SSE parser, keyword vector, cosine similarity
 │   │
@@ -69,6 +72,7 @@ future-lang/
 │
 ├── future-browser.js               # Browser entry point: window.Future + <script type="future">
 ├── future-playground.html          # In-browser editor (11 examples, live compile)
+├── FUTURE_FOR_LLMS.md              # BNF grammar + all APIs — quick-reference for AI assistants
 ├── package.json
 ├── ARCHITECTURE.md                 # This file
 ├── ROADMAP.md                      # Feature roadmap
@@ -114,7 +118,7 @@ In **browser mode** (`browserMode: true` option), the `import` statement is omit
 
 ## Lexer
 
-### Keywords (24)
+### Keywords (26)
 
 | Keyword | Token | Purpose |
 |---------|-------|---------|
@@ -136,7 +140,8 @@ In **browser mode** (`browserMode: true` option), the `import` statement is omit
 | `null` / `none` | NULL | Null literal (two spellings) |
 | `stream` | STREAM | Streaming statement |
 | `agent` | AGENT | Agent declaration |
-| `use` | USE | Capability declaration inside `agent` |
+| `use` | USE | Import statement / capability declaration inside `agent` |
+| `as` | AS | Alias in `use "..." as alias` |
 
 ### String escape
 
@@ -144,12 +149,13 @@ In **browser mode** (`browserMode: true` option), the `import` statement is omit
 
 ---
 
-## AST Node Types (23)
+## AST Node Types (24)
 
 | Category | Nodes |
 |----------|-------|
 | Program | `Program` |
 | Statements | `PrintStatement`, `Assignment`, `IfStatement`, `FunctionDeclaration`, `ReturnStatement`, `ExpressionStatement` |
+| Import | `UseStatement` — `use "path"` / `use "path" as alias` |
 | Control flow | `ForStatement`, `WhileStatement`, `TryStatement` |
 | Event statements | `OnStatement`, `EveryStatement` |
 | AI/IoT statements | `AgentDeclaration`, `StreamStatement` |
@@ -191,12 +197,37 @@ export const NAMESPACES = new Set([
   'ai', 'http', 'mqtt', 'tts',
   'rag', 'vision', 'home',
   'memory', 'schedule', 'system', 'device',
-  'math',
+  'math', 'assert',
 ]);
 ```
 
 Any identifier in this set, when used as the object of a `MemberExpression` or `CallExpression`, is routed through `__rt` in ASYNC mode. Adding a new capability is just a name in this set plus a matching runtime module — no grammar change.
 
+`use ... as alias` imports are tracked in a `useAliases` Set and explicitly excluded from namespace routing — `m.add()` never becomes `__rt.m.add()`.
+
+### Source maps (`sourceMaps` option)
+
+When `compile(source, { sourceMaps: true })` is used, the generator prefixes each top-level statement line with `/*@FL:N*/` (where N is the original `.future` line number). `src/sourcemap.js` post-processes this output:
+
+1. Scans the generated JS line by line.
+2. Strips `/*@FL:N*/` markers.
+3. Builds VLQ-encoded `mappings` in Source Map v3 format.
+4. Returns `{ code: cleanJS, map: { version: 3, sources, sourcesContent, mappings } }`.
+
+The CLI appends `//# sourceMappingURL=file.js.map` to the clean JS and writes the map as JSON.
+
+### Import system (UseStatement)
+
+`use "./file.future"` statements are emitted before all other code. At compile time, when `resolveSource` is provided, the compiler reads the imported file, parses it, and extracts top-level `FunctionDeclaration` names. This enables named imports:
+
+```js
+import { formatName, greet } from "./utils.js";   // named import (default)
+import * as m from "./math.js";                    // namespace import (alias)
+import * as df from "date-fns";                    // npm package (alias)
+```
+
+The `pathMap` option (a `Map<futurePath, fileURL>`) allows `future run` to redirect imports to temp `.mjs` files compiled in `tmpdir`.
+
 ### String interpolation
 
 String literals containing `{identifier}` or `{identifier.prop}` are emitted as JS template literals. Namespace references inside strings are correctly prefixed with `__rt.` in ASYNC mode:
@@ -227,7 +258,7 @@ In ASYNC mode, ALL call expressions where the callee is a `MemberExpression` are
 ```
 runtime/index.js
 │
-├── Imports 12 capability modules (+ readline for input())
+├── Imports 13 capability modules (+ readline for input())
 ├── Exports `runtime` object  →  used as `__rt` in generated JS
 ├── Exports `manifest`        →  structured metadata for every function
 └── Attaches introspection:
@@ -237,6 +268,8 @@ runtime/index.js
       runtime.input(prompt)       → Promise<string>  (stdin)
 ```
 
+When `FUTURE_DEBUG=1` (`future run --debug`), the runtime is wrapped by `wrapDebug()` which proxies every namespace method to log timing and arguments to stderr with ANSI colours.
+
 ### Manifest shape (per function)
 
 ```js
@@ -402,14 +435,15 @@ await __rt.ai.stream("Tell me a story", async (chunk) => {
 
 ---
 
-## Adding a New Capability (4 steps)
+## Adding a New Capability (5 steps)
 
 1. Create `runtime/mymodule.js` with named exports.
 2. Import it in `runtime/index.js`, add to `runtime` object, `MODULE_NAMES`, and `manifest`.
 3. Add the namespace name to `NAMESPACES` in `src/generator.js`.
-4. Add the module to `browserRuntime` in `runtime/browser.js` if browser support is wanted.
+4. Add the namespace name to `RESERVED_NAMESPACES` in `src/parser.js`.
+5. Add the module to `browserRuntime` in `runtime/browser.js` if browser support is wanted.
 
-No grammar, lexer, parser, or AST changes needed.
+No grammar, lexer, or AST changes needed.
 
 ---
 

package/FUTURE_FOR_LLMS.md

@@ -4,6 +4,19 @@ Future is a small language that compiles to JavaScript. It does NOT exist in you
 
 ---
 
+## Capability layers
+
+| Layer | Namespaces | Notes |
+|-------|-----------|-------|
+| **Core language** | *(none)* | variables, if/end, for/end, while/end, try/catch/end, functions, lists, objects, strings |
+| **Standard** | `math` `http` `memory` `system` `schedule` | General-purpose I/O; triggers async mode |
+| **Extended** | `ai` `rag` `vision` `mqtt` `tts` `home` `device` `agent` | AI, IoT, automation; triggers async mode |
+| **Testing** | `assert` | Use only in `*.test.future` files |
+
+Any call from Standard or Extended triggers ASYNC mode automatically.
+
+---
+
 ## Reserved words
 
 ```
@@ -176,10 +189,17 @@ embed   = ai.embed("text to embed")
 ai.configure("openai", "sk-...")
 ai.configure("ollama")
 
-# With options: temperature and max_tokens
+# With inference options
 answer = ai.ask("Explain quantum physics", { temperature: 0.2  max_tokens: 200 })
 reply  = ai.chat(messages, { model: "gpt-4o"  temperature: 0.7 })
 
+# Structured response: text + token counts + model + provider
+result = ai.complete("Summarise this in one line.")
+print result.text
+print result.tokens.total   # total tokens used
+print result.model          # e.g. "claude-sonnet-4-6"
+print result.provider       # e.g. "anthropic"
+
 stream ai.ask("Tell me a story")
     print chunk
 end

package/MIGRATION.md

@@ -4,7 +4,215 @@ All releases are **additive only**. No existing Future program has ever required
 
 ---
 
-## v0.3.1 → v0.3.2 (current — Phase 7: General-Purpose Programming)
+## v0.4.0 → v0.4.1 (current — Gemini improvements)
+
+**No breaking changes.**
+
+### AI inference options
+
+`ai.ask`, `ai.chat`, and `ai.stream` now accept an optional second argument with inference parameters:
+
+```future
+# temperature controls creativity (0.0 = deterministic, 1.0 = creative)
+precise  = ai.ask("List the planets.", { temperature: 0.1  max_tokens: 100 })
+creative = ai.chat(messages, { temperature: 0.9  model: "gpt-4o" })
+ai.stream(prompt, { temperature: 0.7 })
+```
+
+Supported fields: `temperature`, `max_tokens`, `model`, `system` (Anthropic only).
+Both providers (Anthropic native, OpenAI-compat) forward all opts to the API.
+
+### Structured errors
+
+`HttpError` and `AiError` replace generic `Error` objects. Catchable with `try/catch err`:
+
+```future
+try
+    data = http.get("https://api.example.com/private")
+catch err
+    print "{err.status}"    # 401
+    print "{err.code}"      # HTTP_401
+    print "{err.url}"       # https://api.example.com/private
+end
+
+try
+    reply = ai.ask("hello")
+catch err
+    print "{err.provider}"  # anthropic
+    print "{err.status}"    # 429
+    print "{err.code}"      # AI_HTTP_429
+end
+```
+
+Error classes are exported from `runtime/providers/anthropic.js` (`AiError`) and `runtime/http.js` (`HttpError`) for use in JS integrations.
+
+### `http.configure()` — global request defaults
+
+```future
+# Call once at the top of your program
+http.configure({ headers: { Authorization: "Bearer {token}" }  timeout: 5000 })
+
+# All subsequent http.get / http.post calls include the header and timeout automatically
+data = http.get("https://api.example.com/me")
+```
+
+Supported fields: `headers` (merged with per-call headers), `timeout` (ms, uses `AbortSignal.timeout`).
+
+### Source maps (`future compile --sourcemap`)
+
+```bash
+future compile --sourcemap program.future
+# Produces: program.js  +  program.js.map
+```
+
+The `.js.map` is a standard Source Map v3 file. Stack traces in Node.js, VS Code, and browser DevTools automatically map back to the original `.future` line numbers.
+
+The generator embeds `/*@FL:N*/` markers at each statement and `src/sourcemap.js` post-processes them into VLQ-encoded mappings.
+
+### `future test` command + `assert` namespace
+
+```bash
+future test            # finds and runs all *.test.future / test/**/*.future files
+future test myfeature  # filter by filename substring
+```
+
+Test files use the reserved `assert` namespace:
+
+```future
+# calculator.test.future
+assert.equal(1 + 1, 2)
+assert.ok(math.sqrt(16) == 4)
+assert.notEqual("hello", "world")
+assert.deepEqual([1, 2, 3], [1, 2, 3])
+```
+
+Exit code 0 when all pass, 1 when any fail. `assert.*` calls throw `AssertionError` on failure — the test runner catches them and reports per-file results.
+
+`assert` is a reserved namespace — it cannot be redefined by user code.
+
+### Internal changes
+
+- `runtime/assert.js` — new module, wraps `node:assert/strict`
+- `src/sourcemap.js` — new module, VLQ encoder + Source Map v3 builder
+- `runtime/providers/anthropic.js` — exports `AiError` class; `chat`/`stream` accept `opts`
+- `runtime/providers/openai-compat.js` — imports `AiError`; `chat`/`stream` accept `opts`
+- `runtime/http.js` — exports `HttpError` class; `get`/`post` throw it; adds `configure()`; uses `AbortSignal.timeout`
+- `runtime/index.js` — `assert` added to module list, `_base`, and `manifest`
+- `src/generator.js` — `assert` added to `NAMESPACES`; `sourceMaps` option emits `/*@FL:N*/` markers
+- `src/parser.js` — `assert` added to `RESERVED_NAMESPACES`
+- `src/cli.js` — `future test` command; `--sourcemap` flag in `future compile`; calls `buildSourceMap()` to strip markers and write `.js.map`
+
+---
+
+## v0.3.2 → v0.4.0 (CLI + Import system + Language improvements)
+
+**No breaking changes.**
+
+### CLI commands
+
+```bash
+future run <file.future>        # compile + run
+future compile <file.future>    # compile to .js next to source
+future new <name>               # scaffold a new project directory
+future check <file.future>      # syntax-check only, no output
+future fmt <file.future>        # auto-format source in-place
+future playground               # launch the interactive playground
+future doctor                   # check Node.js version, runtime, AI env, MQTT, etc.
+future --version                # show version
+future run --debug <file>       # print per-call timing to stderr (FUTURE_DEBUG=1)
+```
+
+### Import system (`use`)
+
+```future
+# Import all top-level functions by name
+use "./utils.future"
+print 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
+```
+
+Compiles to standard ES module imports:
+
+```js
+import { formatName } from "./utils.js";
+import * as m from "./math.js";
+import * as df from "date-fns";
+```
+
+The compiler reads imported `.future` files at compile time, parses them, and extracts top-level function names to generate named imports instead of wildcard imports. Dependencies are compiled recursively.
+
+`use ... as alias` aliases are excluded from `__rt` routing — `m.add()` does not become `__rt.m.add()`.
+
+### `else if` chains
+
+```future
+if score >= 90
+    print "A"
+else if score >= 80
+    print "B"
+else if score >= 70
+    print "C"
+else
+    print "F"
+end
+```
+
+One `end` closes the entire chain. Previously required nesting.
+
+### Reserved namespace protection
+
+Trying to reassign a namespace name now raises a compile-time error:
+
+```future
+math = 42   # error[parse]: 'math' is a reserved namespace
+http = {}   # error[parse]: 'http' is a reserved namespace
+```
+
+### Async handler error safety (`__safe`)
+
+Programs that use `on`, `every`, or `stream` now wrap their handlers in `__safe`. Errors inside handlers are logged to `stderr` with `[future:ns]` prefix instead of crashing the process silently:
+
+```js
+const __safe = (ns, fn) => async (...a) => {
+  try { return await fn(...a); }
+  catch (e) { console.error(`[future:${ns}]`, e.message); }
+};
+```
+
+### Better error messages
+
+Parse errors now show the source line and a `^` pointer:
+
+```
+error[parse]: Expected 'end' to close 'if' — did you forget 'end'?
+  --> hello.future:5:1
+   5 | x = 1
+      ^
+```
+
+### `FUTURE_FOR_LLMS.md`
+
+A complete quick-reference for AI assistants generating Future code: BNF grammar, all keywords, all namespace APIs, every construct with an example, common mistakes, and what-compiles-to-what pairs.
+
+### Internal changes
+
+- `src/lexer.js` — `as` keyword added (`AS` token)
+- `src/ast.js` — `UseStatement` node type and factory added
+- `src/parser.js` — `parseUse()`, `parseIf(isChained)` updated; `RESERVED_NAMESPACES` set added
+- `src/generator.js` — `genUseStatement()`, `useAliases` Set, `isModule` and `pathMap` options, `__safe` emission, `else if` chain detection
+- `src/index.js` — `compile()` accepts `resolveSource`, `isModule`, `pathMap`, `importedNames` options
+- `src/formatter.js` — new module: line-based indentation formatter
+- `src/cli.js` — full rewrite; `compileDepsToTemp()` for `future run`; all CLI commands implemented
+
+---
+
+## v0.3.1 → v0.3.2 (Phase 7: General-Purpose Programming)
 
 **No breaking changes.**
 

package/README.md

@@ -164,6 +164,18 @@ In the browser this uses `window.prompt()`. In a Node.js CLI program it reads fr
 
 Future programs talk to the outside world through **namespace calls**. The compiler detects them and automatically switches the program to async mode — you never write `async` or `await`.
 
+### Capability layers
+
+Future organises its built-ins into three layers. You only need to know the layer you're using.
+
+| Layer | What it includes | Typical use |
+|-------|-----------------|-------------|
+| **Core language** | variables, functions, `if/else/end`, `for`, `while`, `try/catch`, lists, objects, string interpolation | Any program — no external calls |
+| **Standard capabilities** | `math`, `http`, `memory`, `system`, `schedule` | General-purpose programs with I/O |
+| **Extended modules** | `ai`, `rag`, `vision`, `mqtt`, `tts`, `home`, `device`, `agent`, `assert` | AI, IoT, and automation programs |
+
+Any call from Standard or Extended triggers async mode — the compiler handles it automatically.
+
 ```future
 # HTTP
 todo = http.get("https://jsonplaceholder.typicode.com/todos/1")
@@ -182,8 +194,8 @@ mqtt.publish("home/livingroom/light", "on")
 
 | Namespace  | Functions | Notes |
 |------------|-----------|-------|
-| `http`     | `get(url)`, `post(url, body)` | Parses JSON automatically |
-| `ai`       | `ask(prompt)`, `chat(messages)`, `embed(text)`, `stream(prompt, cb)`, `configure(provider, key)` | Pluggable providers |
+| `http`     | `get(url)`, `post(url, body)`, `configure(opts)` | Parses JSON automatically; throws `HttpError` with `.status`, `.code`, `.body` |
+| `ai`       | `ask(prompt, opts?)`, `chat(messages, opts?)`, `embed(text)`, `stream(prompt, cb, opts?)`, `configure(provider, key)` | opts: `{ temperature, max_tokens, model }`; throws `AiError` |
 | `tts`      | `speak(text)` | System engine (`say` / SAPI / `espeak-ng`) |
 | `mqtt`     | `publish(topic, msg)`, `subscribe(topic, handler)` | Real broker or in-process loopback |
 | `memory`   | `set(key, v)`, `get(key)`, `delete(key)`, `search(q)`, `forget(pattern?)` | In-process key-value store |
@@ -194,6 +206,7 @@ mqtt.publish("home/livingroom/light", "on")
 | `home`     | `turnOn(device)`, `turnOff(device)`, `set(device, value)` | Home automation via MQTT |
 | `math`     | `round`, `floor`, `ceil`, `abs`, `sqrt`, `pow`, `log`, `random`, `min`, `max`, `pi`, `e` | Full Math wrapper |
 | `device`   | `register(config)`, `get(name)`, `list()` | IoT device registry |
+| `assert`   | `ok(val)`, `equal(a, b)`, `notEqual(a, b)`, `deepEqual(a, b)`, `fail(msg?)` | Use in `*.test.future` files |
 
 ### Configuration (environment variables)
 
@@ -211,12 +224,56 @@ FUTURE_VECTOR_DB=memory          # memory | file | qdrant
 ## AI configuration
 
 ```future
-# From code
+# Provider selection
 ai.configure("openai", "sk-...")
 ai.configure("ollama")           # local, no key needed
 
+# Basic usage
 answer = ai.ask("What is 2 + 2?")
 print answer
+
+# With inference options
+precise = ai.ask("List the planets.", { temperature: 0.1  max_tokens: 150 })
+creative = ai.chat(messages, { temperature: 0.9  model: "gpt-4o" })
+
+# Structured response — text + token counts + model + provider
+result = ai.complete("Explain recursion in one sentence.")
+print result.text
+print "Tokens used: {result.tokens.total}"
+print "Model: {result.model}"
+print "Provider: {result.provider}"
+```
+
+`ai.ask()` returns a plain string. `ai.complete()` returns `{ text, model, provider, tokens: { input, output, total } }` — useful when you need to track costs or log which model answered.
+
+## HTTP configuration
+
+```future
+# Set global headers and timeout once at the top of your program
+http.configure({ headers: { Authorization: "Bearer {token}" }  timeout: 5000 })
+
+data = http.get("https://api.example.com/me")   # Authorization header included automatically
+```
+
+## Structured errors
+
+HTTP and AI errors now carry structured data you can inspect:
+
+```future
+try
+    data = http.get("https://api.example.com/private")
+catch err
+    print "Status: {err.status}"     # e.g. 401
+    print "Code:   {err.code}"       # e.g. HTTP_401
+    print "URL:    {err.url}"
+end
+
+try
+    reply = ai.ask("hello")
+catch err
+    print "Provider: {err.provider}"  # e.g. anthropic
+    print "Status:   {err.status}"    # e.g. 429
+end
 ```
 
 ---
@@ -333,14 +390,49 @@ Open `future-playground.html` in any browser for a live editor with 11 built-in
 ```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       # 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
+future --version                         # show version
+future new myapp                         # create a new project
+future run program.future                # compile + run
+future run --debug program.future        # run with per-call timing logs
+future compile program.future            # compile to JavaScript
+future compile --sourcemap program.future  # compile + emit .js.map
+future test                              # run all *.test.future files
+future test myfeature                    # run matching test files
+future ast program.future                # print the AST as JSON
+future ast --pretty program.future       # indented JSON
+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
+```
+
+---
+
+## Testing
+
+Name your test files `*.test.future` (or put them in a `test/` folder) and use the `assert` namespace:
+
+```future
+# math.test.future
+
+assert.equal(math.round(3.7), 4)
+assert.equal(math.sqrt(16), 4)
+assert.ok(math.pi > 3.14)
+assert.notEqual(math.random(), math.random())
+print "math tests passed"
+```
+
+```bash
+future test            # runs all *.test.future files
+future test math       # runs files matching "math"
+```
+
+Output:
+```
+math tests passed
+  ✓ math.test.future
+
+1/1 tests passed
 ```
 
 ---

package/ROADMAP.md

@@ -1,6 +1,6 @@
 # Future — Roadmap
 
-**Version:** 0.3.0 · **Last updated:** 2026-06-13
+**Version:** 0.4.1 · **Last updated:** 2026-06-13
 
 Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 
@@ -18,7 +18,9 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 | Multi-line strings | 📋 | Strings must be single-line today |
 | String `+` concatenation | ✅ | Works via binary `+` operator |
 | Integer division / modulo | 📋 | `math.trunc(a / b)` workaround for now |
-| `use "other.future"` imports | 💡 | No cross-file composition yet |
+| `use "other.future"` imports | ✅ | Named + namespace imports; npm packages; recursive deps |
+| `else if` chains | ✅ | One `end` for the whole chain |
+| Reserved namespace protection | ✅ | Compile-time error if reserved name is reassigned |
 | REPL (`future repl`) | 💡 | Interactive shell with introspection |
 
 ---
@@ -28,11 +30,14 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 | Feature | Status | Notes |
 |---------|--------|-------|
 | `ai.ask(prompt)` | ✅ | Single-turn Q&A |
+| `ai.ask(prompt, opts)` | ✅ | `opts`: `temperature`, `max_tokens`, `model`, `system` |
 | `ai.chat(messages)` | ✅ | Multi-turn conversation |
+| `ai.chat(messages, opts)` | ✅ | Inference options forwarded to provider |
 | `ai.embed(text)` | ✅ | Real embeddings (OpenAI/Ollama) + keyword fallback |
-| `ai.stream(prompt, callback)` | ✅ | Streaming via SSE — runtime implemented |
+| `ai.stream(prompt, cb, opts?)` | ✅ | Streaming via SSE; opts forwarded |
 | `stream ai.ask() ... end` syntax | ✅ | Language-level streaming with implicit `chunk` variable |
 | `ai.configure(provider, key, model)` | ✅ | Pluggable provider from Future code |
+| Structured `AiError` (status, code, provider) | ✅ | Catchable with rich properties |
 | Provider: Anthropic | ✅ | Native Messages API |
 | Provider: OpenAI | ✅ | Via OpenAI-compat layer |
 | Provider: Ollama | ✅ | Local models, no key needed |
@@ -205,8 +210,11 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 | `len(x)` built-in | ✅ | Arrays, strings, objects — sync, no runtime needed |
 | `math.*` module | ✅ | Full JS Math wrapper |
 | `input(prompt)` built-in | ✅ | stdin (Node.js) / `window.prompt` (browser) |
+| `else if` chains | ✅ | One `end` closes the whole chain |
+| `use "./file.future"` imports | ✅ | Named or namespace imports, recursive deps |
+| `use "npm-pkg" as alias` | ✅ | Import npm packages as namespaces |
+| Reserved namespace protection | ✅ | Compile-time error on redefinition |
 | Multi-line strings | 📋 | Strings must be single-line |
-| `use "other.future"` — module imports | 💡 | No cross-file composition |
 | REPL (`future repl`) | 💡 | Interactive shell with introspection |
 
 ---
@@ -230,21 +238,57 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 
 ---
 
+## HTTP
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| `http.get(url, headers?)` | ✅ | Parses JSON or returns text |
+| `http.post(url, body, headers?)` | ✅ | JSON body; parses response |
+| `http.configure({ headers, timeout })` | ✅ | Global defaults for all requests |
+| Structured `HttpError` (status, code, url, body) | ✅ | Catchable with rich properties |
+| `http.put / patch / delete` | 📋 | Additional HTTP verbs |
+| Response headers access | 📋 | `res.headers.get("content-type")` |
+
+---
+
+## Testing
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| `future test` command | ✅ | Finds `*.test.future` / `test/**/*.future`, runs all |
+| `future test <pattern>` | ✅ | Filter by filename substring |
+| `assert` namespace | ✅ | `ok`, `equal`, `notEqual`, `deepEqual`, `fail` |
+| Per-file pass/fail reporting | ✅ | `✓` / `✗` with error message |
+| Exit code 1 on failure | ✅ | Integrates with CI |
+| Test isolation (separate process) | 📋 | Currently runs in same Node process |
+| `assert.throws(fn)` | 📋 | Assert that a function throws |
+| Coverage reporting | 💡 | Line coverage for `.future` files |
+
+---
+
 ## Tooling
 
 | Feature | Status | Notes |
 |---------|--------|-------|
 | CLI: `future run` | ✅ | |
 | CLI: `future compile` | ✅ | |
-| Structured manifest | ✅ | All 12 modules, 50+ functions fully described |
+| CLI: `future compile --sourcemap` | ✅ | Emits Source Map v3 `.js.map` |
+| CLI: `future run --debug` | ✅ | Per-call timing via `FUTURE_DEBUG=1` |
+| CLI: `future test` | ✅ | Test runner for `*.test.future` files |
+| CLI: `future new` | ✅ | Project scaffold |
+| CLI: `future check` | ✅ | Syntax-check without running |
+| CLI: `future fmt` | ✅ | Auto-formatter |
+| CLI: `future doctor` | ✅ | Environment health check |
+| CLI: `future playground` | ✅ | Launches browser playground server |
+| Source maps (`.js.map`) | ✅ | VLQ-encoded Source Map v3 |
+| Structured manifest | ✅ | All 13 modules, 50+ functions fully described |
 | Runtime introspection API | ✅ | `runtime.describe()` / `listModules()` / `listFunctions()` |
 | LSP metadata module | ✅ | Completions, hover, signatures |
 | Browser playground | ✅ | `future-playground.html` — 11 examples |
+| `FUTURE_FOR_LLMS.md` | ✅ | BNF grammar + all APIs for AI code assistants |
+| npm publish (`future-lang`) | ✅ | Public — `npm install -g future-lang` |
 | VSCode extension | 📋 | Syntax highlighting, completions, hover |
 | Language Server (LSP) | 📋 | Full editor integration |
-| `future fmt` | 📋 | Auto-formatter |
-| `future check` | 📋 | Lint / type check without running |
-| npm publish (`future-lang`) | 📋 | Public package registry |
 
 ---
 
@@ -252,12 +296,15 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 
 | Priority | Item | Why it matters |
 |----------|------|----------------|
-| 🔴 Critical | npm publish (`future-lang`) | Required to ship publicly |
 | 🔴 Critical | VSCode extension (syntax highlighting) | First impression for new users |
-| 🟠 High | `use "other.future"` imports | Cross-file composition for real projects |
-| 🟠 High | `system.env(name)` | Read env vars from Future code |
+| 🔴 Critical | Language Server (LSP) | Completions and hover for all IDEs |
+| 🟠 High | `ai.extract(text, schema)` | Structured output is the #1 AI use case |
+| 🟠 High | Test isolation (separate process) | Prevents test state leakage |
+| 🟠 High | `assert.throws(fn)` | Needed for error-handling tests |
 | 🟡 Medium | Home Assistant REST API | Most HA users don't run MQTT |
 | 🟡 Medium | Persistent memory / device registry | Most programs are stateless today |
 | 🟡 Medium | Agent tool-calling loop (ReAct) | True autonomous agents |
+| 🟡 Medium | `http.put / patch / delete` | Needed for full REST APIs |
 | 🟢 Low | `rag.delete(id)` | Selective document removal |
 | 🟢 Low | REPL | Nice-to-have for exploration |
+| 🟢 Low | Coverage reporting | `.future` line coverage |

package/package.json

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

package/runtime/ai.js

@@ -72,6 +72,40 @@ export async function stream(promptOrMessages, onChunk, opts = {}) {
   return provider.stream(messages, onChunk, opts);
 }
 
+/**
+ * Like ask(), but returns a structured result object instead of a plain string.
+ * Includes the generated text, model used, provider name, and token counts.
+ *
+ * @param {string|Array} prompt  String prompt or messages array
+ * @param {{ temperature?: number, max_tokens?: number, model?: string, system?: string }} [opts]
+ * @returns {Promise<{ text: string, model: string, provider: string, tokens: { input: number, output: number, total: number } }>}
+ */
+export async function complete(prompt, opts = {}) {
+  const messages = Array.isArray(prompt)
+    ? prompt
+    : [{ role: 'user', content: String(prompt) }];
+  const provider = resolveProvider();
+  if (!provider) {
+    return {
+      text:     offlineStub(messages),
+      model:    'none',
+      provider: 'offline',
+      tokens:   { input: 0, output: 0, total: 0 },
+    };
+  }
+  if (typeof provider.complete === 'function') {
+    return provider.complete(messages, opts);
+  }
+  // Fallback for providers that don't implement complete() yet.
+  const text = await provider.chat(messages, opts);
+  return {
+    text,
+    model:    opts.model ?? 'unknown',
+    provider: provider.name,
+    tokens:   { input: 0, output: 0, total: 0 },
+  };
+}
+
 /**
  * Generate a vector embedding for a piece of text.
  * With OpenAI/Ollama providers, returns real semantic embeddings.

package/runtime/index.js

@@ -83,10 +83,16 @@ export const manifest = {
     },
     ask: {
       description: 'Ask an AI model a question and get a text response',
-      params: [{ name: 'prompt', type: 'string' }],
+      params: [{ name: 'prompt', type: 'string' }, { name: 'opts', type: 'object', optional: true }],
       returns: 'string',
       async: true,
     },
+    complete: {
+      description: 'Like ask(), but returns a structured object: { text, model, provider, tokens: { input, output, total } }',
+      params: [{ name: 'prompt', type: 'string|array' }, { name: 'opts', type: 'object', optional: true }],
+      returns: '{ text: string, model: string, provider: string, tokens: { input: number, output: number, total: number } }',
+      async: true,
+    },
     chat: {
       description: 'Send a multi-turn message list to an AI model',
       params: [{ name: 'messages', type: 'array' }],
@@ -434,7 +440,7 @@ runtime.listFunctions = (mod) => {
  * Suitable for AI agent discovery or documentation generation.
  */
 runtime.describe = () => ({
-  version: '0.4.1',
+  version: '0.4.2',
   modules: [...MODULE_NAMES],
   manifest,
 });

package/runtime/providers/anthropic.js

@@ -77,11 +77,42 @@ export function create(config) {
     }
   }
 
+  async function complete(messages, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, max_tokens, messages };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+    if (opts.system)              body.system      = opts.system;
+
+    const res = await fetch(`${BASE}/messages`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      let errBody;
+      try { errBody = await res.json(); } catch { errBody = await res.text(); }
+      throw new AiError(res.status, 'anthropic', errBody);
+    }
+    const data = await res.json();
+    const text = (data.content ?? []).map((b) => b.text ?? '').join('').trim();
+    return {
+      text,
+      model: data.model ?? model,
+      provider: 'anthropic',
+      tokens: {
+        input:  data.usage?.input_tokens  ?? 0,
+        output: data.usage?.output_tokens ?? 0,
+        total:  (data.usage?.input_tokens ?? 0) + (data.usage?.output_tokens ?? 0),
+      },
+    };
+  }
+
   async function embed(text) {
     // Anthropic has no public embeddings endpoint — use keyword vector fallback.
     // For production semantic search, configure an OpenAI-compatible provider with an embed model.
     return keywordVector(String(text));
   }
 
-  return { name: 'anthropic', ask, chat, stream, embed };
+  return { name: 'anthropic', ask, chat, complete, stream, embed };
 }

package/runtime/providers/openai-compat.js

@@ -81,6 +81,36 @@ export function create(config) {
     }
   }
 
+  async function complete(messages, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, messages, max_tokens };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
+    const res = await fetch(`${baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      let errBody;
+      try { errBody = await res.json(); } catch { errBody = await res.text(); }
+      throw new AiError(res.status, providerTag, errBody);
+    }
+    const data = await res.json();
+    const text = data.choices?.[0]?.message?.content?.trim() ?? '';
+    return {
+      text,
+      model: data.model ?? model,
+      provider: providerTag,
+      tokens: {
+        input:  data.usage?.prompt_tokens     ?? 0,
+        output: data.usage?.completion_tokens ?? 0,
+        total:  data.usage?.total_tokens      ?? 0,
+      },
+    };
+  }
+
   async function embed(text) {
     if (!embedModel) return keywordVector(String(text));
     try {
@@ -97,5 +127,5 @@ export function create(config) {
     }
   }
 
-  return { name: providerTag, ask, chat, stream, embed };
+  return { name: providerTag, ask, chat, complete, stream, embed };
 }

package/src/cli.js

@@ -22,7 +22,7 @@ import { format } from './formatter.js';
 import { FutureError } from './errors.js';
 import { buildSourceMap } from './sourcemap.js';
 
-const VERSION = '0.4.1';
+const VERSION = '0.4.2';
 const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const RUNTIME_INDEX = join(PROJECT_ROOT, 'runtime', 'index.js');
 
@@ -32,13 +32,14 @@ Usage:
   future run <file.future>          Compile and run a program
   future compile <file.future>      Compile to JavaScript (<file>.js)
   future test [pattern]             Run *.test.future files
-  future new <name>                  Create a new project
+  future ast <file.future>          Print the AST as JSON
+  future new <name>                 Create a new project
   future check <file.future>        Check for syntax errors
   future fmt <file.future>          Format source code in-place
-  future playground                  Launch the interactive playground
-  future doctor                      Check your environment
-  future help                        Show this help
-  future --version                   Show the version
+  future playground                 Launch the interactive playground
+  future doctor                     Check your environment
+  future help                       Show this help
+  future --version                  Show the version
 
 Import system:
   use "./utils.future"              Import all functions from a file
@@ -48,18 +49,21 @@ Import system:
 Flags:
   future run --debug <file>         Show timing for every namespace call
   future compile --sourcemap <file> Also emit a .js.map source map
+  future ast --pretty <file>        Indented JSON output
 `;
 
 async function main(argv) {
   const debug     = argv.includes('--debug');
   const sourcemap = argv.includes('--sourcemap');
+  const pretty    = argv.includes('--pretty');
   if (debug) process.env.FUTURE_DEBUG = '1';
-  const rest = argv.filter((a) => a !== '--debug' && a !== '--sourcemap');
+  const rest = argv.filter((a) => a !== '--debug' && a !== '--sourcemap' && a !== '--pretty');
   const [command, arg] = rest;
   switch (command) {
     case 'run':        return cmdRun(arg);
     case 'compile':    return cmdCompile(arg, { sourcemap });
     case 'test':       return cmdTest(arg);
+    case 'ast':        return cmdAst(arg, { pretty });
     case 'new':        return cmdNew(arg);
     case 'check':      return cmdCheck(arg);
     case 'fmt':        return cmdFmt(arg);
@@ -345,6 +349,23 @@ function cmdFmt(file) {
   return 0;
 }
 
+/** Output the AST of a .future file as JSON. */
+function cmdAst(file, { pretty = false } = {}) {
+  let path, source;
+  try { ({ path, source } = readSource(file)); }
+  catch (err) { return fail(err, file); }
+
+  try {
+    const tokens = tokenize(source);
+    const ast    = parse(tokens);
+    process.stdout.write((pretty ? JSON.stringify(ast, null, 2) : JSON.stringify(ast)) + '\n');
+    return 0;
+  } catch (err) {
+    if (err instanceof FutureError) { reportFutureError(err, source, file); return 1; }
+    throw err;
+  }
+}
+
 /** Recursively collect .future files matching a pattern or default test globs. */
 function findTestFiles(pattern) {
   const cwd = process.cwd();