@vibe-lang/runtime 0.2.9 → 0.2.10

package/src/runtime/stdlib/index.ts

@@ -1,16 +1,12 @@
-// Standard library functions for Vibe scripts
-// Import with: import { uuid } from "system"
+// System module - re-exports utility functions for convenience
+// Prefer importing from "system/utils" directly.
+//
+// Import with: import { uuid, random, now } from "system"
+// Or directly: import { uuid, random, now } from "system/utils"
 //
-// These are TypeScript functions that can be called directly from Vibe scripts.
 // For AI tools, use: import { allTools } from "system/tools"
 //
 // NOTE: print() and env() are auto-imported core functions.
-// They are available everywhere without import and CANNOT be imported from "system".
+// They are available everywhere without import.
 
-/**
- * Generate a UUID v4.
- * @returns A new UUID string
- */
-export function uuid(): string {
-  return crypto.randomUUID();
-}
+export { uuid, now, random, jsonParse, jsonStringify } from './utils';

package/src/runtime/stdlib/tools/index.ts

@@ -2,7 +2,7 @@
 // Import with: import { allTools, readFile, writeFile, ... } from "system/tools"
 //
 // These are tools that AI models can use via the tools parameter.
-// For direct script use, import functions from "system" instead.
+// For utility functions (uuid, random, now, etc.), use: import { ... } from "system/utils"
 
 import type { VibeToolValue, ToolContext } from '../../tools/types';
 import { validatePathInSandbox } from '../../tools/security';
@@ -386,117 +386,6 @@ export const dirExists: VibeToolValue = {
   },
 };
 
-// =============================================================================
-// Utility Tools
-// =============================================================================
-
-export const env: VibeToolValue = {
-  __vibeTool: true,
-  name: 'env',
-  schema: {
-    name: 'env',
-    description: 'Get an environment variable.',
-    parameters: [
-      { name: 'name', type: { type: 'string' }, description: 'The environment variable name', required: true },
-      { name: 'defaultValue', type: { type: 'string' }, description: 'Default value if not set', required: false },
-    ],
-    returns: { type: 'string' },
-  },
-  executor: async (args: Record<string, unknown>) => {
-    const name = args.name as string;
-    const defaultValue = args.defaultValue as string | undefined;
-    return process.env[name] ?? defaultValue ?? '';
-  },
-};
-
-export const now: VibeToolValue = {
-  __vibeTool: true,
-  name: 'now',
-  schema: {
-    name: 'now',
-    description: 'Get the current timestamp in milliseconds.',
-    parameters: [],
-    returns: { type: 'number' },
-  },
-  executor: async () => {
-    return Date.now();
-  },
-};
-
-export const jsonParse: VibeToolValue = {
-  __vibeTool: true,
-  name: 'jsonParse',
-  schema: {
-    name: 'jsonParse',
-    description: 'Parse a JSON string into an object.',
-    parameters: [
-      { name: 'text', type: { type: 'string' }, description: 'The JSON string to parse', required: true },
-    ],
-    returns: { type: 'object', additionalProperties: true },
-  },
-  executor: async (args: Record<string, unknown>) => {
-    const text = args.text as string;
-    return JSON.parse(text);
-  },
-};
-
-export const jsonStringify: VibeToolValue = {
-  __vibeTool: true,
-  name: 'jsonStringify',
-  schema: {
-    name: 'jsonStringify',
-    description: 'Convert an object to a JSON string.',
-    parameters: [
-      { name: 'value', type: { type: 'object', additionalProperties: true }, description: 'The value to stringify', required: true },
-      { name: 'pretty', type: { type: 'boolean' }, description: 'Whether to format with indentation', required: false },
-    ],
-    returns: { type: 'string' },
-  },
-  executor: async (args: Record<string, unknown>) => {
-    const value = args.value;
-    const pretty = args.pretty as boolean | undefined;
-    return pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
-  },
-};
-
-export const random: VibeToolValue = {
-  __vibeTool: true,
-  name: 'random',
-  schema: {
-    name: 'random',
-    description: 'Generate a random number. Without arguments, returns 0-1. With min/max, returns integer in range.',
-    parameters: [
-      { name: 'min', type: { type: 'number' }, description: 'Minimum value (inclusive)', required: false },
-      { name: 'max', type: { type: 'number' }, description: 'Maximum value (inclusive)', required: false },
-    ],
-    returns: { type: 'number' },
-  },
-  executor: async (args: Record<string, unknown>) => {
-    const min = args.min as number | undefined;
-    const max = args.max as number | undefined;
-
-    if (min !== undefined && max !== undefined) {
-      return Math.floor(Math.random() * (max - min + 1)) + min;
-    }
-
-    return Math.random();
-  },
-};
-
-export const uuid: VibeToolValue = {
-  __vibeTool: true,
-  name: 'uuid',
-  schema: {
-    name: 'uuid',
-    description: 'Generate a UUID v4.',
-    parameters: [],
-    returns: { type: 'string' },
-  },
-  executor: async () => {
-    return crypto.randomUUID();
-  },
-};
-
 // =============================================================================
 // System Tools
 // =============================================================================
@@ -659,8 +548,8 @@ console.log('__VIBE_RESULT__' + JSON.stringify(__result));
 // =============================================================================
 
 /**
- * All tools - the complete set of standard tools.
- * Includes all file, search, directory, utility, and system tools.
+ * All tools - the complete set of standard AI tools.
+ * Includes file, search, directory, and system tools.
  */
 export const allTools: VibeToolValue[] = [
   // File tools
@@ -669,8 +558,6 @@ export const allTools: VibeToolValue[] = [
   glob, grep,
   // Directory tools
   mkdir, dirExists,
-  // Utility tools
-  env, now, jsonParse, jsonStringify, random, uuid,
   // System tools
   bash, runCode,
 ];
@@ -686,8 +573,6 @@ export const readonlyTools: VibeToolValue[] = [
   glob, grep,
   // Directory tools (read-only)
   dirExists,
-  // Utility tools
-  env, now, jsonParse, jsonStringify, random, uuid,
 ];
 
 /**
@@ -701,7 +586,5 @@ export const safeTools: VibeToolValue[] = [
   glob, grep,
   // Directory tools
   mkdir, dirExists,
-  // Utility tools
-  env, now, jsonParse, jsonStringify, random, uuid,
 ];
 

package/src/runtime/stdlib/utils/index.ts

@@ -0,0 +1,58 @@
+// System utility functions for Vibe scripts
+// Import with: import { uuid, now, random, jsonParse, jsonStringify } from "system/utils"
+//
+// These are utility functions that can be called directly from Vibe scripts.
+// For AI tools, use: import { readFile, writeFile, ... } from "system/tools"
+//
+// NOTE: print() and env() are auto-imported core functions.
+// They are available everywhere without import.
+
+/**
+ * Generate a UUID v4.
+ * @returns A new UUID string
+ */
+export function uuid(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Get the current timestamp in milliseconds.
+ * @returns Unix timestamp in milliseconds
+ */
+export function now(): number {
+  return Date.now();
+}
+
+/**
+ * Generate a random number.
+ * Without arguments, returns a float between 0 and 1.
+ * With min/max, returns an integer in the range [min, max] inclusive.
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (inclusive)
+ * @returns Random number
+ */
+export function random(min?: number, max?: number): number {
+  if (min !== undefined && max !== undefined) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+  return Math.random();
+}
+
+/**
+ * Parse a JSON string into an object.
+ * @param text - The JSON string to parse
+ * @returns Parsed object
+ */
+export function jsonParse(text: string): unknown {
+  return JSON.parse(text);
+}
+
+/**
+ * Convert a value to a JSON string.
+ * @param value - The value to stringify
+ * @param pretty - Whether to format with indentation
+ * @returns JSON string
+ */
+export function jsonStringify(value: unknown, pretty?: boolean): string {
+  return pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+}

package/src/runtime/step.ts

@@ -10,6 +10,7 @@ import {
   execStatement,
   execStatements,
   execReturnValue,
+  execThrowError,
   execIfBranch,
   execEnterBlock,
   execExitBlock,
@@ -317,6 +318,9 @@ function executeInstruction(state: RuntimeState, instruction: Instruction): Runt
     case 'return_value':
       return execReturnValue(state);
 
+    case 'throw_error':
+      return execThrowError(state, instruction.location);
+
     case 'enter_block':
       return execEnterBlock(state, instruction.savedKeys);
 

package/src/runtime/test/core-functions.test.ts

@@ -176,22 +176,22 @@ if true {
   });
 
   describe('core functions cannot be imported', () => {
-    test('importing env from system fails', async () => {
+    test('importing env from system/utils fails (env is core function)', async () => {
       const ast = parse(`
-import { env } from "system"
+import { env } from "system/utils"
 let x = 1
 `);
       const runtime = new Runtime(ast, createMockProvider());
-      await expect(runtime.run()).rejects.toThrow("'env' is not exported from 'system'");
+      await expect(runtime.run()).rejects.toThrow("'env' is not exported from 'system/utils'");
     });
 
-    test('importing print from system fails', async () => {
+    test('importing print from system/utils fails (print is core function)', async () => {
       const ast = parse(`
-import { print } from "system"
+import { print } from "system/utils"
 let x = 1
 `);
       const runtime = new Runtime(ast, createMockProvider());
-      await expect(runtime.run()).rejects.toThrow("'print' is not exported from 'system'");
+      await expect(runtime.run()).rejects.toThrow("'print' is not exported from 'system/utils'");
     });
 
     test('importing from system/core is blocked', async () => {
@@ -202,10 +202,19 @@ let x = 1
       const runtime = new Runtime(ast, createMockProvider());
       await expect(runtime.run()).rejects.toThrow("'system/core' cannot be imported");
     });
+
+    test('importing from bare "system" fails (not a valid module)', async () => {
+      const ast = parse(`
+import { uuid } from "system"
+let x = 1
+`);
+      const runtime = new Runtime(ast, createMockProvider());
+      await expect(runtime.run()).rejects.toThrow("Unknown system module: 'system'");
+    });
   });
 
-  describe('library functions still require import', () => {
-    test('uuid requires import from system', async () => {
+  describe('utility functions require import from system/utils', () => {
+    test('uuid requires import', async () => {
       const ast = parse(`
 let id = uuid()
 `);
@@ -213,9 +222,9 @@ let id = uuid()
       await expect(runtime.run()).rejects.toThrow("'uuid' is not defined");
     });
 
-    test('uuid works when imported from system', async () => {
+    test('uuid works when imported from system/utils', async () => {
       const ast = parse(`
-import { uuid } from "system"
+import { uuid } from "system/utils"
 let id = uuid()
 `);
       const runtime = new Runtime(ast, createMockProvider());

package/src/runtime/test/throw.test.ts

@@ -0,0 +1,220 @@
+// Tests for throw statement - throw "message" returns immediately with error value
+
+import { describe, expect, test } from 'bun:test';
+import { parse } from '../../parser/parse';
+import { Runtime } from '../index';
+import type { AIProvider, AIResponse } from '../types';
+import { isVibeValue } from '../types';
+
+// Mock provider for tests that don't need AI
+function createMockProvider(): AIProvider {
+  return {
+    async chat(): Promise<AIResponse> {
+      return { content: 'mock response', toolCalls: [] };
+    },
+  };
+}
+
+describe('Throw Statement', () => {
+  test('throw with string literal creates error value', async () => {
+    const ast = parse(`
+function fail(): text {
+  throw "Something went wrong"
+  return "never reached"
+}
+
+let result = fail()
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    const result = runtime.getRawValue('result');
+    expect(isVibeValue(result)).toBe(true);
+    if (isVibeValue(result)) {
+      expect(result.err).toBe(true);
+      expect(result.errDetails?.message).toBe('Something went wrong');
+    }
+  });
+
+  test('throw returns immediately from function', async () => {
+    const ast = parse(`
+let sideEffect = 0
+
+function testThrow(): number {
+  sideEffect = 1
+  throw "error"
+  sideEffect = 2
+  return 42
+}
+
+let result = testThrow()
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    // Side effect should only be 1 (before throw)
+    expect(runtime.getValue('sideEffect')).toBe(1);
+
+    const result = runtime.getRawValue('result');
+    expect(isVibeValue(result)).toBe(true);
+    if (isVibeValue(result)) {
+      expect(result.err).toBe(true);
+    }
+  });
+
+  test('throw with expression evaluates message', async () => {
+    const ast = parse(`
+function divide(a: number, b: number): number {
+  if b == 0 {
+    throw "Cannot divide " + a + " by zero"
+  }
+  return a / b
+}
+
+let result = divide(10, 0)
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    const result = runtime.getRawValue('result');
+    expect(isVibeValue(result)).toBe(true);
+    if (isVibeValue(result)) {
+      expect(result.err).toBe(true);
+      expect(result.errDetails?.message).toBe('Cannot divide 10 by zero');
+    }
+  });
+
+  test('successful function call returns normal value', async () => {
+    const ast = parse(`
+function divide(a: number, b: number): number {
+  if b == 0 {
+    throw "Division by zero"
+  }
+  return a / b
+}
+
+let result = divide(10, 2)
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    const result = runtime.getRawValue('result');
+    expect(isVibeValue(result)).toBe(true);
+    if (isVibeValue(result)) {
+      expect(result.err).toBe(false);
+      expect(result.value).toBe(5);
+    }
+  });
+
+  test('error propagates through expressions', async () => {
+    const ast = parse(`
+function fail(): number {
+  throw "error"
+}
+
+let a = fail()
+let b = a + 10
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    const a = runtime.getRawValue('a');
+    const b = runtime.getRawValue('b');
+
+    expect(isVibeValue(a)).toBe(true);
+    expect(isVibeValue(b)).toBe(true);
+
+    if (isVibeValue(a) && isVibeValue(b)) {
+      expect(a.err).toBe(true);
+      expect(b.err).toBe(true);  // Error propagates
+      expect(b.errDetails?.message).toBe('error');
+    }
+  });
+
+  test('caller can check for error with .err', async () => {
+    const ast = parse(`
+function mayFail(shouldFail: boolean): text {
+  if shouldFail {
+    throw "Failed!"
+  }
+  return "Success"
+}
+
+let result1 = mayFail(true)
+let hasError1 = result1.err
+
+let result2 = mayFail(false)
+let hasError2 = result2.err
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    expect(runtime.getValue('hasError1')).toBe(true);
+    expect(runtime.getValue('hasError2')).toBe(false);
+  });
+
+  test('throw at top level completes with error', async () => {
+    const ast = parse(`
+let x = 1
+throw "Top level error"
+let y = 2
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    expect(runtime.getValue('x')).toBe(1);
+    // y should not be set because throw exits
+    expect(runtime.getValue('y')).toBeUndefined();
+
+    // lastResult should be the error
+    const lastResult = runtime.getState().lastResult;
+    expect(isVibeValue(lastResult)).toBe(true);
+    if (isVibeValue(lastResult)) {
+      expect(lastResult.err).toBe(true);
+      expect(lastResult.errDetails?.message).toBe('Top level error');
+    }
+  });
+
+  test('throw in nested function unwinds correctly', async () => {
+    const ast = parse(`
+function inner(): number {
+  throw "inner error"
+}
+
+function outer(): number {
+  let x = inner()
+  return x + 1
+}
+
+let result = outer()
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    const result = runtime.getRawValue('result');
+    expect(isVibeValue(result)).toBe(true);
+    if (isVibeValue(result)) {
+      expect(result.err).toBe(true);
+      expect(result.errDetails?.message).toBe('inner error');
+    }
+  });
+
+  test('throw with variable message', async () => {
+    const ast = parse(`
+function failWith(msg: text): text {
+  throw msg
+}
+
+let result = failWith("custom error message")
+`);
+    const runtime = new Runtime(ast, createMockProvider());
+    await runtime.run();
+
+    const result = runtime.getRawValue('result');
+    expect(isVibeValue(result)).toBe(true);
+    if (isVibeValue(result)) {
+      expect(result.err).toBe(true);
+      expect(result.errDetails?.message).toBe('custom error message');
+    }
+  });
+});