future-lang 0.4.0 → 0.4.1

package/FUTURE_FOR_LLMS.md

@@ -14,7 +14,7 @@ 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
+ai  http  mqtt  tts  rag  vision  home  memory  schedule  system  device  math  assert
 ```
 
 ---
@@ -176,6 +176,10 @@ embed   = ai.embed("text to embed")
 ai.configure("openai", "sk-...")
 ai.configure("ollama")
 
+# With options: temperature and max_tokens
+answer = ai.ask("Explain quantum physics", { temperature: 0.2  max_tokens: 200 })
+reply  = ai.chat(messages, { model: "gpt-4o"  temperature: 0.7 })
+
 stream ai.ask("Tell me a story")
     print chunk
 end
@@ -224,7 +228,36 @@ end
 # schedule.once and schedule.cron also available
 ```
 
-### `http`, `system`, `rag`, `vision`, `home`, `device`
+### `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
+
+# Global config (call once at the top of your program)
+http.configure({ headers: { Authorization: "Bearer {token}" }  timeout: 5000 })
+
+# Errors have .status, .code, .url, .body properties
+try
+    data = http.get("https://api.example.com/private")
+catch err
+    print "Status: {err.status}"
+    print "Code: {err.code}"
+end
+```
+
+### `assert` (use in *.test.future files)
+```
+assert.ok(value)
+assert.equal(actual, expected)
+assert.notEqual(a, b)
+assert.deepEqual(obj1, obj2)
+assert.fail("custom message")
+```
+
+### `system`, `rag`, `vision`, `home`, `device`
 See [README.md](README.md) for full API tables.
 
 ### `math`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "future-lang",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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

@@ -34,31 +34,42 @@ export function configure(baseUrlOrProvider, apiKey, model) {
   });
 }
 
-/** Ask a single question. @returns {Promise<string>} */
-export async function ask(prompt) {
-  return chat([{ role: 'user', content: String(prompt) }]);
+/**
+ * Ask a single question.
+ * @param {string} prompt
+ * @param {{ temperature?: number, max_tokens?: number, model?: string, system?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function ask(prompt, opts = {}) {
+  return chat([{ role: 'user', content: String(prompt) }], opts);
 }
 
-/** Multi-turn chat. messages = [{ role, content }, ...]. @returns {Promise<string>} */
-export async function chat(messages) {
+/**
+ * Multi-turn chat.
+ * @param {Array<{role,content}>} messages
+ * @param {{ temperature?: number, max_tokens?: number, model?: string, system?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function chat(messages, opts = {}) {
   const provider = resolveProvider();
   if (!provider) return offlineStub(messages);
-  return provider.chat(messages);
+  return provider.chat(messages, opts);
 }
 
 /**
  * Stream a response chunk-by-chunk.
  * @param {string|Array} promptOrMessages
- * @param {(chunk: string) => void} onChunk  Called with each text fragment.
+ * @param {(chunk: string) => void} onChunk
+ * @param {{ temperature?: number, max_tokens?: number, model?: string }} [opts]
  * @returns {Promise<void>}
  */
-export async function stream(promptOrMessages, onChunk) {
+export async function stream(promptOrMessages, onChunk, opts = {}) {
   const messages = Array.isArray(promptOrMessages)
     ? promptOrMessages
     : [{ role: 'user', content: String(promptOrMessages) }];
   const provider = resolveProvider();
   if (!provider) { onChunk(offlineStub(messages)); return; }
-  return provider.stream(messages, onChunk);
+  return provider.stream(messages, onChunk, opts);
 }
 
 /**

package/runtime/assert.js

@@ -0,0 +1,27 @@
+// runtime/assert.js — Test assertions for `future test`.
+// Wraps node:assert/strict with Future-friendly error messages.
+
+import nodeAssert from 'node:assert/strict';
+
+function wrap(fn, name) {
+  return (...args) => {
+    try {
+      fn(...args);
+    } catch (err) {
+      // Re-throw with the assert namespace tag so the test runner can identify it.
+      const e = new Error(err.message);
+      e.name = 'AssertionError';
+      e.namespace = 'assert';
+      e.operator = err.operator ?? name;
+      e.actual = err.actual;
+      e.expected = err.expected;
+      throw e;
+    }
+  };
+}
+
+export const ok        = wrap((val, msg)        => nodeAssert.ok(val, msg),                       'ok');
+export const equal     = wrap((a, b, msg)        => nodeAssert.equal(a, b, msg),                   'equal');
+export const notEqual  = wrap((a, b, msg)        => nodeAssert.notEqual(a, b, msg),                'notEqual');
+export const deepEqual = wrap((a, b, msg)        => nodeAssert.deepEqual(a, b, msg),               'deepEqual');
+export const fail      = (msg = 'assertion failed') => { throw Object.assign(new Error(msg), { name: 'AssertionError', namespace: 'assert' }); };

package/runtime/http.js

@@ -1,32 +1,78 @@
 // runtime/http.js — consume REST APIs.
 // Uses the global fetch (stable in Node 22). Returns parsed JSON or text.
 
+export class HttpError extends Error {
+  constructor(status, statusText, url, body) {
+    super(`HTTP ${status} ${statusText} — ${url}`);
+    this.name = 'HttpError';
+    this.status = status;
+    this.statusText = statusText;
+    this.url = url;
+    this.body = body;
+    this.namespace = 'http';
+    this.code = `HTTP_${status}`;
+  }
+}
+
+// Global config state — mutated by configure().
+let _config = {
+  headers: {},
+  timeout: 0,
+};
+
+/**
+ * Set global defaults for all HTTP requests.
+ * Useful for Authorization headers, base timeouts, etc.
+ * @param {{ headers?: Record<string,string>, timeout?: number }} opts
+ */
+export function configure(opts = {}) {
+  if (opts.headers) _config.headers = { ..._config.headers, ...opts.headers };
+  if (opts.timeout != null) _config.timeout = opts.timeout;
+}
+
 // Default headers — many public APIs (e.g. GitHub) reject requests without a
 // User-Agent. Callers can override any of these.
 const DEFAULT_HEADERS = {
-  'user-agent': 'future-lang/0.2 (+https://github.com/future-lang)',
+  'user-agent': 'future-lang/0.4 (+https://github.com/humolot/future-lang)',
   accept: 'application/json, text/*;q=0.9, */*;q=0.8',
 };
 
-async function parse(res) {
+async function parseBody(res) {
   const ct = res.headers.get('content-type') || '';
   return ct.includes('application/json') ? res.json() : res.text();
 }
 
+function buildSignal() {
+  if (!_config.timeout) return undefined;
+  return AbortSignal.timeout(_config.timeout);
+}
+
 /** GET a URL. @returns parsed JSON object/array, or text. */
 export async function get(url, headers = {}) {
-  const res = await fetch(url, { headers: { ...DEFAULT_HEADERS, ...headers } });
-  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText} for ${url}`);
-  return parse(res);
+  const res = await fetch(url, {
+    headers: { ...DEFAULT_HEADERS, ..._config.headers, ...headers },
+    signal: buildSignal(),
+  });
+  if (!res.ok) {
+    let body;
+    try { body = await parseBody(res); } catch { body = null; }
+    throw new HttpError(res.status, res.statusText, url, body);
+  }
+  return parseBody(res);
 }
 
 /** POST a JSON body to a URL. @returns parsed JSON or text. */
 export async function post(url, body, headers = {}) {
   const res = await fetch(url, {
     method: 'POST',
-    headers: { ...DEFAULT_HEADERS, 'content-type': 'application/json', ...headers },
+    headers: { ...DEFAULT_HEADERS, 'content-type': 'application/json', ..._config.headers, ...headers },
     body: typeof body === 'string' ? body : JSON.stringify(body),
+    signal: buildSignal(),
   });
-  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText} for ${url}`);
-  return parse(res);
+  if (!res.ok) {
+    let errBody;
+    try { errBody = await parseBody(res); } catch { errBody = null; }
+    throw new HttpError(res.status, res.statusText, url, errBody);
+  }
+  return parseBody(res);
 }

package/runtime/index.js

@@ -16,15 +16,16 @@ import * as schedule from './schedule.js';
 import * as system   from './system.js';
 import * as device   from './device.js';
 import * as math     from './math.js';
+import * as assert   from './assert.js';
 import readline from 'node:readline';
 
 // Canonical ordered list of capability module names.
 const MODULE_NAMES = [
   'ai', 'http', 'mqtt', 'tts', 'rag', 'vision', 'home',
-  'memory', 'schedule', 'system', 'device', 'math',
+  'memory', 'schedule', 'system', 'device', 'math', 'assert',
 ];
 
-const _base = { 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, assert };
 
 /**
  * When FUTURE_DEBUG=1, wrap every namespace method with timing/logging.
@@ -406,6 +407,14 @@ export const manifest = {
     pi:     { description: 'The mathematical constant π',     params: [], returns: 'number', async: false },
     e:      { description: "Euler's number",                  params: [], returns: 'number', async: false },
   },
+
+  assert: {
+    ok:        { description: 'Assert that value is truthy',                    params: [{ name: 'value', type: 'any' }, { name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+    equal:     { description: 'Assert that actual === expected',                params: [{ name: 'actual', type: 'any' }, { name: 'expected', type: 'any' }, { name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+    notEqual:  { description: 'Assert that actual !== expected',                params: [{ name: 'actual', type: 'any' }, { name: 'expected', type: 'any' }, { name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+    deepEqual: { description: 'Assert deep structural equality',                params: [{ name: 'actual', type: 'any' }, { name: 'expected', type: 'any' }, { name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+    fail:      { description: 'Unconditionally fail the test with a message',   params: [{ name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+  },
 };
 
 // --- Introspection API ---
@@ -425,7 +434,7 @@ runtime.listFunctions = (mod) => {
  * Suitable for AI agent discovery or documentation generation.
  */
 runtime.describe = () => ({
-  version: '0.4.0',
+  version: '0.4.1',
   modules: [...MODULE_NAMES],
   manifest,
 });

package/runtime/providers/anthropic.js

@@ -6,13 +6,26 @@ import { parseSSE, keywordVector } from './util.js';
 
 const BASE = 'https://api.anthropic.com/v1';
 
+export class AiError extends Error {
+  constructor(status, provider, body) {
+    const msg = body?.error?.message ?? body ?? `HTTP ${status}`;
+    super(`[ai:${provider}] ${msg}`);
+    this.name = 'AiError';
+    this.status = status;
+    this.code = `AI_HTTP_${status}`;
+    this.namespace = 'ai';
+    this.provider = provider;
+    this.body = body;
+  }
+}
+
 /**
  * Create an Anthropic provider instance.
  * @param {{ apiKey: string, model?: string }} config
  */
 export function create(config) {
-  const key   = config.apiKey;
-  const model = config.model ?? 'claude-sonnet-4-6';
+  const key          = config.apiKey;
+  const defaultModel = config.model ?? 'claude-sonnet-4-6';
 
   const headers = {
     'content-type':      'application/json',
@@ -20,28 +33,43 @@ export function create(config) {
     'anthropic-version': '2023-06-01',
   };
 
-  async function chat(messages) {
+  async function chat(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({ model, max_tokens: 1024, messages }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[anthropic] HTTP ${res.status}: ${await res.text()}`);
+    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();
     return (data.content ?? []).map((b) => b.text ?? '').join('').trim();
   }
 
-  async function ask(prompt) {
-    return chat([{ role: 'user', content: String(prompt) }]);
+  async function ask(prompt, opts = {}) {
+    return chat([{ role: 'user', content: String(prompt) }], opts);
   }
 
-  async function stream(messages, onChunk) {
+  async function stream(messages, onChunk, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, max_tokens, messages, stream: true };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
     const res = await fetch(`${BASE}/messages`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ model, max_tokens: 1024, messages, stream: true }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[anthropic] stream HTTP ${res.status}`);
+    if (!res.ok) throw new AiError(res.status, 'anthropic', `stream HTTP ${res.status}`);
     for await (const { event, data } of parseSSE(res.body)) {
       if (event === 'content_block_delta' || data?.type === 'content_block_delta') {
         onChunk(data.delta?.text ?? '');

package/runtime/providers/openai-compat.js

@@ -7,19 +7,20 @@
 // No separate SDK or special casing needed.
 
 import { parseSSE, keywordVector } from './util.js';
+import { AiError } from './anthropic.js';
 
 /**
  * Well-known provider presets. Used when FUTURE_AI_PROVIDER is set without FUTURE_AI_BASE_URL.
  * Users can always override by setting FUTURE_AI_BASE_URL directly.
  */
 export const PRESETS = {
-  openai:      { baseUrl: 'https://api.openai.com/v1',                         embedModel: 'text-embedding-3-small' },
-  ollama:      { baseUrl: 'http://localhost:11434/v1',                          embedModel: 'nomic-embed-text' },
-  openrouter:  { baseUrl: 'https://openrouter.ai/api/v1',                       embedModel: null },
+  openai:      { baseUrl: 'https://api.openai.com/v1',                              embedModel: 'text-embedding-3-small' },
+  ollama:      { baseUrl: 'http://localhost:11434/v1',                               embedModel: 'nomic-embed-text' },
+  openrouter:  { baseUrl: 'https://openrouter.ai/api/v1',                            embedModel: null },
   gemini:      { baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai', embedModel: 'text-embedding-004' },
-  venice:      { baseUrl: 'https://api.venice.ai/api/v1',                       embedModel: null },
-  groq:        { baseUrl: 'https://api.groq.com/openai/v1',                     embedModel: null },
-  together:    { baseUrl: 'https://api.together.xyz/v1',                        embedModel: 'togethercomputer/m2-bert-80M-8k-retrieval' },
+  venice:      { baseUrl: 'https://api.venice.ai/api/v1',                            embedModel: null },
+  groq:        { baseUrl: 'https://api.groq.com/openai/v1',                          embedModel: null },
+  together:    { baseUrl: 'https://api.together.xyz/v1',                             embedModel: 'togethercomputer/m2-bert-80M-8k-retrieval' },
 };
 
 /**
@@ -27,38 +28,53 @@ export const PRESETS = {
  * @param {{ baseUrl: string, apiKey: string, model?: string, embedModel?: string }} config
  */
 export function create(config) {
-  const baseUrl    = config.baseUrl.replace(/\/$/, '');
-  const apiKey     = config.apiKey;
-  const model      = config.model     ?? 'gpt-4o-mini';
-  const embedModel = config.embedModel ?? null;
+  const baseUrl      = config.baseUrl.replace(/\/$/, '');
+  const apiKey       = config.apiKey;
+  const defaultModel = config.model      ?? 'gpt-4o-mini';
+  const embedModel   = config.embedModel ?? null;
+  const providerTag  = `openai-compat(${baseUrl})`;
 
   const headers = {
     'content-type':  'application/json',
     'authorization': `Bearer ${apiKey}`,
   };
 
-  async function chat(messages) {
+  async function chat(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({ model, messages, max_tokens: 1024 }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[ai/${baseUrl}] HTTP ${res.status}: ${await res.text()}`);
+    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();
     return data.choices?.[0]?.message?.content?.trim() ?? '';
   }
 
-  async function ask(prompt) {
-    return chat([{ role: 'user', content: String(prompt) }]);
+  async function ask(prompt, opts = {}) {
+    return chat([{ role: 'user', content: String(prompt) }], opts);
   }
 
-  async function stream(messages, onChunk) {
+  async function stream(messages, onChunk, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, messages, max_tokens, stream: true };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
     const res = await fetch(`${baseUrl}/chat/completions`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ model, messages, max_tokens: 1024, stream: true }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[ai/${baseUrl}] stream HTTP ${res.status}`);
+    if (!res.ok) throw new AiError(res.status, providerTag, `stream HTTP ${res.status}`);
     for await (const { data } of parseSSE(res.body)) {
       const chunk = data.choices?.[0]?.delta?.content;
       if (chunk) onChunk(chunk);
@@ -81,5 +97,5 @@ export function create(config) {
     }
   }
 
-  return { name: `openai-compat(${baseUrl})`, ask, chat, stream, embed };
+  return { name: providerTag, ask, chat, stream, embed };
 }

package/src/cli.js

@@ -11,7 +11,7 @@
 //   future help | --help
 //   future version | --version
 
-import { readFileSync, writeFileSync, unlinkSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { tmpdir } from 'node:os';
@@ -20,8 +20,9 @@ import process from 'node:process';
 import { compile, tokenize, parse } from './index.js';
 import { format } from './formatter.js';
 import { FutureError } from './errors.js';
+import { buildSourceMap } from './sourcemap.js';
 
-const VERSION = '0.4.0';
+const VERSION = '0.4.1';
 const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const RUNTIME_INDEX = join(PROJECT_ROOT, 'runtime', 'index.js');
 
@@ -30,6 +31,7 @@ const USAGE = `Future ${VERSION} — a tiny language that compiles to JavaScript
 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 check <file.future>        Check for syntax errors
   future fmt <file.future>          Format source code in-place
@@ -45,16 +47,19 @@ Import system:
 
 Flags:
   future run --debug <file>         Show timing for every namespace call
+  future compile --sourcemap <file> Also emit a .js.map source map
 `;
 
 async function main(argv) {
-  const debug = argv.includes('--debug');
+  const debug     = argv.includes('--debug');
+  const sourcemap = argv.includes('--sourcemap');
   if (debug) process.env.FUTURE_DEBUG = '1';
-  const rest = argv.filter((a) => a !== '--debug');
+  const rest = argv.filter((a) => a !== '--debug' && a !== '--sourcemap');
   const [command, arg] = rest;
   switch (command) {
     case 'run':        return cmdRun(arg);
-    case 'compile':    return cmdCompile(arg);
+    case 'compile':    return cmdCompile(arg, { sourcemap });
+    case 'test':       return cmdTest(arg);
     case 'new':        return cmdNew(arg);
     case 'check':      return cmdCheck(arg);
     case 'fmt':        return cmdFmt(arg);
@@ -198,7 +203,7 @@ function compileDepModule(source, sourcePath, tempDir, pathMap) {
 // Commands
 // ---------------------------------------------------------------------------
 
-function cmdCompile(file) {
+function cmdCompile(file, { sourcemap = false } = {}) {
   let path, source;
   try { ({ path, source } = readSource(file)); }
   catch (err) { return fail(err, file); }
@@ -230,18 +235,30 @@ function cmdCompile(file) {
     console.log(`Compiled ${relPath} -> ${depOut}`);
   }
 
-  const js = compileOrReport(source, file, {
+  const rawJs = compileOrReport(source, file, {
     runtimeSpecifier: relativeRuntimeSpecifier(outDir),
+    sourceMaps: sourcemap,
     resolveSource: (relPath) => {
       const abs = resolve(outDir, relPath);
       return existsSync(abs) ? readFileSync(abs, 'utf8') : null;
     },
   });
-  if (js === null) return 1;
-
-  const outPath = join(outDir, `${basename(path, extname(path))}.js`);
-  writeFileSync(outPath, js, 'utf8');
-  console.log(`Compiled ${file} -> ${outPath}`);
+  if (rawJs === null) return 1;
+
+  const outBase = join(outDir, basename(path, extname(path)));
+  const outPath = `${outBase}.js`;
+
+  if (sourcemap) {
+    const mapFile = `${outBase}.js.map`;
+    const { code, map } = buildSourceMap(rawJs, basename(file), source);
+    writeFileSync(outPath, `${code}//# sourceMappingURL=${basename(mapFile)}\n`, 'utf8');
+    writeFileSync(mapFile, JSON.stringify(map), 'utf8');
+    console.log(`Compiled ${file} -> ${outPath}`);
+    console.log(`Source map   -> ${mapFile}`);
+  } else {
+    writeFileSync(outPath, rawJs, 'utf8');
+    console.log(`Compiled ${file} -> ${outPath}`);
+  }
   return 0;
 }
 
@@ -328,6 +345,88 @@ function cmdFmt(file) {
   return 0;
 }
 
+/** Recursively collect .future files matching a pattern or default test globs. */
+function findTestFiles(pattern) {
+  const cwd = process.cwd();
+  const files = [];
+
+  function walk(dir) {
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const entry of entries) {
+      if (entry === 'node_modules') continue;
+      const full = join(dir, entry);
+      const st = statSync(full);
+      if (st.isDirectory()) { walk(full); continue; }
+      if (!entry.endsWith('.future')) continue;
+      const rel = relative(cwd, full).split('\\').join('/');
+      if (pattern) {
+        if (rel.includes(pattern) || entry.includes(pattern)) files.push(full);
+      } else {
+        if (entry.endsWith('.test.future') || rel.startsWith('test/')) files.push(full);
+      }
+    }
+  }
+
+  walk(cwd);
+  return files;
+}
+
+/** Run *.test.future files and report results. */
+async function cmdTest(pattern) {
+  const testFiles = findTestFiles(pattern);
+  if (testFiles.length === 0) {
+    process.stderr.write('No test files found.\n');
+    process.stderr.write('  Naming: *.test.future or test/**/*.future\n');
+    return 1;
+  }
+
+  const tempDir = tmpdir();
+  let passed = 0;
+  let failed = 0;
+
+  for (const testFile of testFiles) {
+    const rel = relative(process.cwd(), testFile).split('\\').join('/');
+    let source;
+    try { source = readFileSync(testFile, 'utf8'); } catch (err) { process.stderr.write(`error reading ${rel}: ${err.message}\n`); failed++; continue; }
+
+    // Compile dependencies.
+    const pathMap = compileDepsToTemp(testFile, source, tempDir);
+    if (pathMap === null) { failed++; continue; }
+
+    const js = compileOrReport(source, rel, {
+      runtimeSpecifier: pathToFileURL(RUNTIME_INDEX).href,
+      pathMap,
+      resolveSource: (p) => {
+        const abs = resolve(dirname(testFile), p);
+        return existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+      },
+    });
+    if (js === null) { failed++; continue; }
+
+    const tmp = join(tempDir, `future-test-${process.pid}-${Date.now()}.mjs`);
+    writeFileSync(tmp, js, 'utf8');
+    const depTmps = [...pathMap.values()].map((u) => fileURLToPath(u));
+    try {
+      await import(pathToFileURL(tmp).href);
+      console.log(`  ✓ ${rel}`);
+      passed++;
+    } catch (err) {
+      const isAssert = err.name === 'AssertionError' || err.namespace === 'assert';
+      process.stderr.write(`  ✗ ${rel}\n`);
+      process.stderr.write(`    ${isAssert ? 'AssertionError' : err.name ?? 'Error'}: ${err.message}\n`);
+      failed++;
+    } finally {
+      try { unlinkSync(tmp); } catch { /* ignore */ }
+      for (const p of depTmps) { try { unlinkSync(p); } catch { /* ignore */ } }
+    }
+  }
+
+  const total = passed + failed;
+  console.log(`\n${passed}/${total} tests passed${failed > 0 ? `, ${failed} failed` : ''}`);
+  return failed > 0 ? 1 : 0;
+}
+
 /** Create a new project scaffold. */
 function cmdNew(name) {
   if (!name) {

package/src/generator.js

@@ -24,6 +24,7 @@ export const NAMESPACES = new Set([
   'rag', 'vision', 'home',              // AI / automation extension points
   'memory', 'schedule', 'system', 'device', // optional new modules
   'math',                               // general-purpose math
+  'assert',                             // test assertions
 ]);
 
 export class Generator {
@@ -36,6 +37,7 @@ export class Generator {
     this.runtimeSpecifier = options.runtimeSpecifier ?? 'future-lang/runtime';
     this.browserMode = options.browserMode ?? false;
     this.isModule = options.isModule ?? false;
+    this.sourceMaps = options.sourceMaps ?? false;
     // Map<importedFuturePath, string[]> — exported names for non-aliased use statements.
     this.importedNames = options.importedNames ?? new Map();
     // Map<importedFuturePath, resolvedJsPath> — path override for `future run` temp files.
@@ -79,7 +81,12 @@ export class Generator {
     }
     for (const stmt of program.body) {
       if (stmt.type === NodeType.UseStatement) continue; // already emitted above
-      lines.push(this.genStatement(stmt, 0, /* topLevel= */ true));
+      const code = this.genStatement(stmt, 0, /* topLevel= */ true);
+      if (this.sourceMaps && stmt.line != null) {
+        lines.push(`/*@FL:${stmt.line}*/${code}`);
+      } else {
+        lines.push(code);
+      }
     }
     return lines.join('\n') + '\n';
   }

package/src/parser.js

@@ -19,7 +19,7 @@ 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',
+  'memory', 'schedule', 'system', 'device', 'math', 'assert',
 ]);
 
 export class Parser {

package/src/sourcemap.js

@@ -0,0 +1,69 @@
+// src/sourcemap.js — Source map generation (Source Map v3).
+// The generator embeds @FL:N markers (inside block comments) at statement lines.
+// This module strips them and produces a v3 source map + clean JS.
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function encodeVlq(value) {
+  let vlq = value < 0 ? ((-value) << 1) | 1 : (value << 1);
+  let out = '';
+  do {
+    let digit = vlq & 0x1F;
+    vlq >>>= 5;
+    if (vlq > 0) digit |= 0x20;
+    out += B64[digit];
+  } while (vlq > 0);
+  return out;
+}
+
+const MARKER_RE = /^\/\*@FL:(\d+)\*\//;
+
+/**
+ * Strip @FL:N markers from generated JS and build a v3 source map.
+ *
+ * @param {string} js           Generated JS (possibly with @FL markers)
+ * @param {string} sourceFile   Original .future filename (for `sources` field)
+ * @param {string} futureSource Original .future source text (for `sourcesContent`)
+ * @returns {{ code: string, map: object }}
+ */
+export function buildSourceMap(js, sourceFile, futureSource) {
+  const jsLines   = js.split('\n');
+  const cleanLines = [];
+  const mappings   = [];
+
+  // Delta state for VLQ.
+  let prevSrcLine = 0;
+  let prevSrcCol  = 0;
+
+  for (const line of jsLines) {
+    const m = MARKER_RE.exec(line);
+    if (m) {
+      const srcLine = parseInt(m[1], 10) - 1; // 0-indexed
+      const srcCol  = 0;
+      // Segment: [genCol=0, sourceIdx=0, srcLine delta, srcCol delta]
+      const seg = encodeVlq(0)
+        + encodeVlq(0)
+        + encodeVlq(srcLine - prevSrcLine)
+        + encodeVlq(srcCol  - prevSrcCol);
+      mappings.push(seg);
+      prevSrcLine = srcLine;
+      prevSrcCol  = srcCol;
+      cleanLines.push(line.slice(m[0].length));
+    } else {
+      // No marker — emit an empty mapping for this line.
+      mappings.push('');
+      cleanLines.push(line);
+    }
+  }
+
+  const map = {
+    version: 3,
+    file: sourceFile.replace(/\.future$/, '.js'),
+    sources: [sourceFile],
+    sourcesContent: [futureSource],
+    names: [],
+    mappings: mappings.join(';'),
+  };
+
+  return { code: cleanLines.join('\n'), map };
+}