future-lang 0.3.0

package/runtime/system.js

@@ -0,0 +1,101 @@
+// runtime/system.js — OS-level utilities: run commands, open files/URLs, notify, read/write files.
+
+import { execFile, spawn } from 'node:child_process';
+import { promisify }       from 'node:util';
+import { readFile, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Run a shell command. Uses execFile (no shell expansion) for safety.
+ * The command string is split on spaces; use exec(['cmd', 'arg with spaces']) for complex calls.
+ * @param {string|string[]} command  Command + args as a string or array.
+ * @returns {Promise<string>} stdout
+ */
+export async function exec(command) {
+  const parts = Array.isArray(command) ? command : String(command).trim().split(/\s+/);
+  const [cmd, ...args] = parts;
+  const { stdout, stderr } = await execFileAsync(cmd, args);
+  if (stderr) console.warn('[system.exec]', stderr.trim());
+  return stdout.trim();
+}
+
+/**
+ * Open a file path or URL with the OS default handler.
+ * Uses the platform's native launcher (start / open / xdg-open).
+ * @returns {Promise<string>} the target that was opened.
+ */
+export async function open(target) {
+  const str = String(target);
+  let cmd, args;
+  if (process.platform === 'win32') {
+    // `start` is a cmd built-in; spawn via cmd /c.
+    cmd = 'cmd'; args = ['/c', 'start', '', str];
+  } else if (process.platform === 'darwin') {
+    cmd = 'open'; args = [str];
+  } else {
+    cmd = 'xdg-open'; args = [str];
+  }
+  await new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    proc.once('error', reject);
+    proc.unref();
+    // Resolve immediately — the opened app runs independently.
+    resolve();
+  });
+  return str;
+}
+
+/**
+ * Send a desktop notification.
+ * macOS: AppleScript. Linux: notify-send. Windows: falls back to console.log.
+ * @returns {Promise<string>} the message text.
+ */
+export async function notify(message) {
+  const msg = String(message);
+  try {
+    if (process.platform === 'darwin') {
+      // Sanitise for AppleScript: remove quotes.
+      const safe = msg.replace(/['"\\]/g, '').slice(0, 200);
+      await execFileAsync('osascript', ['-e', `display notification "${safe}" with title "Future"`]);
+    } else if (process.platform === 'linux') {
+      await execFileAsync('notify-send', ['Future', msg]);
+    } else {
+      // Windows: log clearly; a real toast would need a packaged app identity.
+      console.log(`[notify] ${msg}`);
+    }
+  } catch {
+    console.log(`[notify] ${msg}`);
+  }
+  return msg;
+}
+
+/**
+ * Read a file and return its content as a string.
+ * @param {string} path  Absolute or relative file path.
+ * @returns {Promise<string>}
+ */
+export async function read(path) {
+  return readFile(String(path), 'utf8');
+}
+
+/**
+ * Write a string to a file (creates or overwrites).
+ * @param {string} path     Absolute or relative file path.
+ * @param {string} content  Content to write.
+ * @returns {Promise<string>} The path that was written.
+ */
+export async function write(path, content) {
+  await writeFile(String(path), String(content), 'utf8');
+  return String(path);
+}
+
+/**
+ * Read an environment variable. Returns null if not set.
+ * @param {string} name  Variable name, e.g. "VENICE_API_KEY".
+ * @returns {string|null}
+ */
+export function env(name) {
+  return process.env[String(name)] ?? null;
+}

package/runtime/tts.js

@@ -0,0 +1,38 @@
+// runtime/tts.js — text-to-speech.
+// Uses a system engine when present (macOS `say`, Windows SAPI, Linux espeak-ng)
+// and falls back to printing `[tts] ...` so it never crashes a program.
+
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+
+/** Speak text aloud. @returns {Promise<string>} the spoken text. */
+export async function speak(text) {
+  const str = String(text);
+  const ok = await trySpeak(str);
+  if (!ok) console.log(`[tts] ${str}`);
+  return str;
+}
+
+function trySpeak(str) {
+  return new Promise((resolve) => {
+    let cmd; let args;
+    if (process.platform === 'darwin') {
+      cmd = 'say'; args = [str];
+    } else if (process.platform === 'win32') {
+      const safe = str.replace(/'/g, "''");
+      cmd = 'powershell';
+      args = ['-NoProfile', '-Command',
+        `Add-Type -AssemblyName System.Speech; ` +
+        `(New-Object System.Speech.Synthesis.SpeechSynthesizer).Speak('${safe}')`];
+    } else {
+      cmd = 'espeak-ng'; args = [str];
+    }
+    try {
+      const p = spawn(cmd, args, { stdio: 'ignore' });
+      p.on('error', () => resolve(false));     // engine not installed
+      p.on('close', (code) => resolve(code === 0));
+    } catch {
+      resolve(false);
+    }
+  });
+}

package/runtime/vision.js

@@ -0,0 +1,85 @@
+// runtime/vision.js — Vision AI with pluggable provider.
+//
+// Uses the same AI provider configured for the rest of the runtime (FUTURE_AI_PROVIDER).
+// Both Anthropic (claude-3+) and OpenAI (gpt-4o) support vision natively.
+//
+// All functions accept:
+//   image — a URL (https://...) or base64 data-URI (data:image/jpeg;base64,...)
+
+import { resolveProvider } from './providers/index.js';
+
+/**
+ * Build the message payload for a vision request.
+ * Supports URLs and base64 data-URIs.
+ */
+function visionMessage(prompt, image) {
+  const img = String(image);
+  const isDataUri = img.startsWith('data:');
+  const content = [
+    {
+      type: 'image_url',
+      image_url: { url: isDataUri ? img : img },
+    },
+    { type: 'text', text: prompt },
+  ];
+  // Anthropic format differs slightly — provider.chat() receives the same
+  // OpenAI-style structure; the Anthropic provider does NOT reformat it
+  // because the Messages API v2 accepts this layout too.
+  return [{ role: 'user', content }];
+}
+
+async function callVision(prompt, image) {
+  const provider = resolveProvider();
+  if (!provider) {
+    return `[vision offline] Configure an AI provider to process: ${image}`;
+  }
+  try {
+    return await provider.chat(visionMessage(prompt, image));
+  } catch (e) {
+    return `[vision error] ${e.message}`;
+  }
+}
+
+/** Describe the contents of an image. @returns {Promise<string>} */
+export async function describe(image) {
+  return callVision('Describe this image in detail.', image);
+}
+
+/** Detect and list objects, people, or labels visible in the image. @returns {Promise<string>} */
+export async function detect(image) {
+  return callVision('List all objects, people, and notable elements you can detect in this image. Be concise.', image);
+}
+
+/** Extract all readable text from the image (OCR). @returns {Promise<string>} */
+export async function ocr(image) {
+  return callVision('Extract all text visible in this image exactly as it appears. Return only the text, nothing else.', image);
+}
+
+/** Classify the image into a category. @returns {Promise<string>} */
+export async function classify(image) {
+  return callVision('What is the primary category or type of this image? Reply with one or two words.', image);
+}
+
+/**
+ * Compare two images and describe the differences.
+ * @param {string} imageA
+ * @param {string} imageB
+ * @returns {Promise<string>}
+ */
+export async function compare(imageA, imageB) {
+  const provider = resolveProvider();
+  if (!provider) return '[vision offline] Configure an AI provider to compare images.';
+  try {
+    const messages = [{
+      role: 'user',
+      content: [
+        { type: 'image_url', image_url: { url: String(imageA) } },
+        { type: 'image_url', image_url: { url: String(imageB) } },
+        { type: 'text', text: 'Compare these two images. What are the key similarities and differences?' },
+      ],
+    }];
+    return await provider.chat(messages);
+  } catch (e) {
+    return `[vision error] ${e.message}`;
+  }
+}

package/server.js

@@ -0,0 +1,42 @@
+// server.js
+
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+
+const PORT = 3000;
+
+http.createServer((req, res) => {
+
+    let file = req.url === '/'
+        ? './examples/mini-app.html'
+        : '.' + req.url;
+
+    try {
+
+        const data = fs.readFileSync(file);
+
+        const ext = path.extname(file);
+
+        const types = {
+            '.html': 'text/html',
+            '.js': 'application/javascript',
+            '.css': 'text/css'
+        };
+
+        res.writeHead(200, {
+            'Content-Type': types[ext] || 'text/plain'
+        });
+
+        res.end(data);
+
+    } catch {
+
+        res.writeHead(404);
+        res.end('Not Found');
+
+    }
+
+}).listen(PORT);
+
+console.log(`http://localhost:${PORT}`);

package/src/ast.js

@@ -0,0 +1,202 @@
+// ast.js
+// AST node types and factory functions for Future.
+//
+// Design note: capabilities like HTTP/AI/MQTT/TTS are NOT special node types.
+// They are ordinary calls whose callee is a `MemberExpression` (e.g. http.get).
+// This keeps the AST tiny and means new capabilities (RAG, Vision AI, Home
+// Automation, ...) need ZERO grammar/AST changes — only a new runtime module.
+
+export const NodeType = Object.freeze({
+  Program: 'Program',
+  UseStatement: 'UseStatement',  // use "./file.future" [as alias]
+  PrintStatement: 'PrintStatement',
+  Assignment: 'Assignment',
+  IfStatement: 'IfStatement',
+  FunctionDeclaration: 'FunctionDeclaration',
+  ReturnStatement: 'ReturnStatement',
+  ExpressionStatement: 'ExpressionStatement',
+  // Event-oriented statements.
+  OnStatement: 'OnStatement',       // on <source> <channel> ... end
+  EveryStatement: 'EveryStatement', // every <interval> ... end
+  // Iteration.
+  ForStatement: 'ForStatement',     // for <var> in <expr> ... end
+  WhileStatement: 'WhileStatement', // while <condition> ... end
+  // Error handling.
+  TryStatement: 'TryStatement',     // try ... catch <var> ... end
+  // Streaming.
+  StreamStatement: 'StreamStatement', // stream <call> ... end
+  // Agent declaration — architecture support (parser implementation pending).
+  AgentDeclaration: 'AgentDeclaration', // agent <name> use <cap> ... end
+  // Literals.
+  ArrayLiteral: 'ArrayLiteral',     // [expr, expr, ...]
+  ObjectLiteral: 'ObjectLiteral',   // { key: expr  key: expr }
+  BinaryExpression: 'BinaryExpression',
+  UnaryExpression: 'UnaryExpression',
+  CallExpression: 'CallExpression',
+  MemberExpression: 'MemberExpression',
+  Identifier: 'Identifier',
+  NumberLiteral: 'NumberLiteral',
+  StringLiteral: 'StringLiteral',
+  BooleanLiteral: 'BooleanLiteral',
+  NullLiteral: 'NullLiteral',
+});
+
+// --- Statements ---
+export const Program = (body) => ({ type: NodeType.Program, body });
+
+/**
+ * `use "./file.future"` or `use "./file.future" as alias`
+ * Top-level file import. Compiles to an ES `import` statement.
+ * @param {string}      path   Relative path to the imported .future file.
+ * @param {string|null} alias  Namespace alias, or null for named imports.
+ */
+export const UseStatement = (path, alias, line, column) => ({
+  type: NodeType.UseStatement, path, alias, line, column,
+});
+
+export const PrintStatement = (expression, line, column) => ({
+  type: NodeType.PrintStatement, expression, line, column,
+});
+
+export const Assignment = (name, value, line, column) => ({
+  type: NodeType.Assignment, name, value, line, column,
+});
+
+export const IfStatement = (condition, consequent, alternate, line, column) => ({
+  type: NodeType.IfStatement, condition, consequent, alternate, line, column,
+});
+
+export const FunctionDeclaration = (name, params, body, line, column) => ({
+  type: NodeType.FunctionDeclaration, name, params, body, line, column,
+});
+
+export const ReturnStatement = (argument, line, column) => ({
+  type: NodeType.ReturnStatement, argument, line, column,
+});
+
+export const ExpressionStatement = (expression, line, column) => ({
+  type: NodeType.ExpressionStatement, expression, line, column,
+});
+
+/**
+ * `on <source> <channel> ... end`
+ * Subscribes to an event source (e.g. mqtt) on a channel. The body receives an
+ * implicit `message` binding containing the event payload.
+ * @param {string} source   Runtime module name, e.g. "mqtt".
+ * @param {object} channel  Expression node for the channel/topic string.
+ * @param {object[]} body   Statement list (callback body).
+ */
+export const OnStatement = (source, channel, body, line, column) => ({
+  type: NodeType.OnStatement, source, channel, body, line, column,
+});
+
+/**
+ * `every <interval> ... end`
+ * Runs the body on a recurring schedule. Compiles to schedule.every(interval, callback).
+ * @param {object} interval  Expression node (string or number literal).
+ * @param {object[]} body    Statement list (callback body).
+ */
+export const EveryStatement = (interval, body, line, column) => ({
+  type: NodeType.EveryStatement, interval, body, line, column,
+});
+
+/**
+ * `for <variable> in <iterable> ... end`
+ * Compiles to `for (const <variable> of <iterable>) { ... }`
+ */
+export const ForStatement = (variable, iterable, body, line, column) => ({
+  type: NodeType.ForStatement, variable, iterable, body, line, column,
+});
+
+/**
+ * `try ... catch <errorVar> ... end`
+ * Compiles to `try { ... } catch (<errorVar>) { ... }`
+ */
+export const TryStatement = (body, catchVar, catchBody, line, column) => ({
+  type: NodeType.TryStatement, body, catchVar, catchBody, line, column,
+});
+
+/**
+ * `while <condition> ... end`
+ * Compiles to `while (condition) { ... }`
+ */
+export const WhileStatement = (condition, body, line, column) => ({
+  type: NodeType.WhileStatement, condition, body, line, column,
+});
+
+/**
+ * `agent <name> ... end`
+ * Declares an agent with a set of capabilities and an optional body.
+ * Parser implementation is pending; this node supports architecture and tooling.
+ * @param {string}   name          Agent name identifier.
+ * @param {string[]} capabilities  List of runtime modules the agent uses (e.g. ['rag','ai']).
+ * @param {object[]} body          Statement list (agent body).
+ */
+export const AgentDeclaration = (name, capabilities, body, line, column) => ({
+  type: NodeType.AgentDeclaration, name, capabilities, body, line, column,
+});
+
+/**
+ * `stream <callExpr> ... end`
+ * Streams a response and binds each chunk to the implicit `chunk` variable in the body.
+ * Compiles to: await __rt.ai.stream(args, async (chunk) => { ... })
+ * Parser implementation is pending.
+ * @param {object}   call  CallExpression node representing the streaming call.
+ * @param {object[]} body  Statement list executed for each chunk.
+ */
+export const StreamStatement = (call, body, line, column) => ({
+  type: NodeType.StreamStatement, call, body, line, column,
+});
+
+// --- Expressions ---
+export const BinaryExpression = (operator, left, right, line, column) => ({
+  type: NodeType.BinaryExpression, operator, left, right, line, column,
+});
+
+export const UnaryExpression = (operator, argument, line, column) => ({
+  type: NodeType.UnaryExpression, operator, argument, line, column,
+});
+
+/** `callee` is any expression (an Identifier or a MemberExpression). */
+export const CallExpression = (callee, args, line, column) => ({
+  type: NodeType.CallExpression, callee, arguments: args, line, column,
+});
+
+/** `object.property` — e.g. http.get or todo.title. `property` is a string. */
+export const MemberExpression = (object, property, line, column) => ({
+  type: NodeType.MemberExpression, object, property, line, column,
+});
+
+export const Identifier = (name, line, column) => ({
+  type: NodeType.Identifier, name, line, column,
+});
+
+export const NumberLiteral = (value, line, column) => ({
+  type: NodeType.NumberLiteral, value, line, column,
+});
+
+export const StringLiteral = (value, line, column) => ({
+  type: NodeType.StringLiteral, value, line, column,
+});
+
+export const BooleanLiteral = (value, line, column) => ({
+  type: NodeType.BooleanLiteral, value, line, column,
+});
+
+export const NullLiteral = (line, column) => ({
+  type: NodeType.NullLiteral, line, column,
+});
+
+/** `[expr, expr, ...]` — array literal. */
+export const ArrayLiteral = (elements, line, column) => ({
+  type: NodeType.ArrayLiteral, elements, line, column,
+});
+
+/**
+ * `{ key: expr  key: expr }` — object literal.
+ * `properties` is an array of `{ key: string, value: node }`.
+ * No commas between properties — separator is whitespace/newline.
+ */
+export const ObjectLiteral = (properties, line, column) => ({
+  type: NodeType.ObjectLiteral, properties, line, column,
+});