codexivo 0.0.0-stage → 0.2.0

package/docs/guia-aprender-desde-el-codigo.md

@@ -0,0 +1,91 @@
+# Guía práctica: entender Codexivo desde su código
+
+Actividades para mirar debajo del capó: cada una toma el mismo programa y lo observa en una etapa distinta del intérprete. Lee
+antes la [arquitectura](./arquitectura.md).
+
+## Programa semilla
+
+```codexivo
+variable saludo = "Codexivo";
+variable arma_mensaje = procedimiento(nombre) {
+  variable prefijo = "Hola, ";
+  regresa prefijo + nombre;
+};
+arma_mensaje(saludo);
+```
+
+Guárdalo en `semilla.cdx` y ejecútalo con `bun run src/cli.ts semilla.cdx`, o pégalo en el REPL.
+
+## 1. Tokens
+
+```ts
+import { readFileSync } from 'node:fs';
+import { tokenize } from './src';
+
+const { tokens } = tokenize(readFileSync('semilla.cdx', 'utf8'));
+console.table(
+  tokens.map(t => ({ tipo: t.type, texto: t.lexeme, línea: t.span.start.line, columna: t.span.start.column })),
+);
+```
+
+- Ubica en `src/syntax/lexer.ts` dónde se reconocen los nombres y cómo se decide si son palabras reservadas (`KEYWORDS` en
+  `src/syntax/token.ts`).
+- **Ejercicio:** agrega `#` al programa y observa el error léxico y su posición.
+
+## 2. Árbol
+
+```ts
+import { parse, walk } from './src';
+
+const { program } = parse(codigo);
+walk(program, (nodo, padre) => console.log(`${padre?.kind ?? '—'} → ${nodo.kind}`));
+```
+
+- En `src/syntax/parser.ts`, busca la tabla `INFIX_PRECEDENCE` y explica por qué `1 + 2 * 3` se agrupa como `1 + (2 * 3)`.
+- **Ejercicio:** escribe `1 < x < 5` y lee el error. ¿Por qué el lenguaje prefiere no encadenar comparaciones?
+
+## 3. Instrucciones
+
+```ts
+import { compile, parse } from './src';
+
+const chunk = compile(parse(codigo).program);
+console.log(chunk.code.map(i => i.op).join(' '));
+```
+
+- Encuentra la instrucción `closure`: guarda el código del procedimiento junto con el alcance donde se creó.
+- **Ejercicio:** compila `si (a) { } si_no { }` y dibuja a dónde salta cada `branch` y `jump`.
+
+## 4. Ejecución paso a paso
+
+```ts
+import { prepare } from './src';
+
+const { machine } = prepare(codigo);
+while (machine && !machine.done) {
+  machine.step();
+  const foto = machine.snapshot();
+  console.log(
+    foto.span?.start.line,
+    foto.frames.map(f => f.name).join(' > '),
+    JSON.stringify(foto.frames.at(-1)?.scopes),
+  );
+}
+```
+
+- Observa cómo aparece el marco `arma_mensaje` mientras se ejecuta el procedimiento, con `nombre` y `prefijo`.
+- **Ejercicio:** cambia el programa para que `arma_mensaje` se llame a sí mismo sin caso base. ¿Qué error aparece y por qué no
+  truena JavaScript?
+
+## 5. La biblioteca
+
+- Lee cómo está definido `longitud` en `src/runtime/builtins.ts`: declara cuántos argumentos acepta y valida sus tipos.
+- **Ejercicio:** agrega `mayúsculas(texto)` con su test en `tests/builtins.test.ts`. Comprueba que `mayusculas` también
+  funcione sin acento.
+
+## Autoevaluación
+
+- [ ] Puedo explicar qué hace cada etapa: tokens, árbol, instrucciones, máquina.
+- [ ] Sé dónde se decide la precedencia de un operador.
+- [ ] Puedo leer una fotografía de la máquina e identificar en qué paso cambió una variable.
+- [ ] Sé agregar un procedimiento a la biblioteca y probarlo.

package/docs/lenguaje.md

@@ -0,0 +1,162 @@
+# El lenguaje Codexivo, hoy
+
+Esta guía describe **lo que funciona hoy** en el intérprete. Todos los ejemplos se ejecutan tal cual. El diseño completo hacia
+donde va el lenguaje está en la [especificación v1](./especificacion-v1.md); lo que aquí no aparece, todavía no existe.
+
+## Un programa
+
+Un programa es una lista de sentencias. El punto y coma al final de cada sentencia es opcional si la siguiente empieza en otra
+línea. El valor de un programa es el de su última expresión, o lo que regrese con `regresa`.
+
+El mismo lenguaje funciona mediante la biblioteca ESM `codexivo`, el comando npm `codexivo` (sin instalar Bun) y los ejecutables
+autónomos de cada sistema. Consulta [REPL y terminal](./repl.md) para ejecutar archivos y proporcionar entrada estándar.
+
+```codexivo
+// comentario de una línea
+/* comentario
+   de varias líneas */
+variable nombre = "Ana"
+imprimir("Hola,", nombre)
+```
+
+## Palabras reservadas
+
+```
+variable  procedimiento  regresa
+si  pero_si  si_no  mientras  hacer  hasta_que  para
+verdadero  falso  nulo  y  o  no
+```
+
+## Valores
+
+| Tipo          | Ejemplos                                                                      |
+| ------------- | ----------------------------------------------------------------------------- |
+| número        | `10`, `3.14`, `.5`, `-2`                                                      |
+| texto         | `"hola"`, `'mundo'`, `"línea\nnueva"` (escapes: `\n`, `\t`, `\\`, `\"`, `\'`) |
+| lógico        | `verdadero`, `falso`                                                          |
+| nulo          | `nulo`                                                                        |
+| lista         | `[1, "a", verdadero]`                                                         |
+| procedimiento | `procedimiento(x) { regresa x * 2; }`                                         |
+
+Las listas se comparten: si dos variables apuntan a la misma lista, un cambio se ve desde las dos.
+
+## Variables
+
+```codexivo
+variable contador = 0;
+contador = contador + 1;
+contador += 5;   // también -=, *=, /=
+```
+
+- Toda variable se declara una vez con `variable` y un valor inicial.
+- Asignar a una variable sin declararla es un error.
+- Lo que se declara dentro de un bloque `{ }` solo existe dentro de él.
+
+Los nombres pueden llevar `ñ`, acentos y diéresis: `año`, `canción`, `pingüino`.
+
+## Operadores
+
+De menor a mayor precedencia:
+
+| Operadores                          | Notas                                                                    |
+| ----------------------------------- | ------------------------------------------------------------------------ |
+| `o`                                 | Cortocircuito                                                            |
+| `y`                                 | Cortocircuito                                                            |
+| `no`, `!`                           |                                                                          |
+| `==` `!=` `<` `>` `<=` `>=`         | No se pueden encadenar: `1 < x < 5` es un error; escribe `1 < x y x < 5` |
+| `+` `-`                             | `+` también une dos textos                                               |
+| `*` `/`                             | `/` es división real; dividir entre cero es un error                     |
+| `-` (signo)                         |                                                                          |
+| llamadas `f(x)`, índices `lista[i]` |                                                                          |
+
+- `==` compara por valor, también listas: `[1, 2] == [1, 2]` es `verdadero`.
+- `+` no mezcla textos y números: `"Total: " + 5` es un error. Usa `texto(5)` o `imprimir("Total:", 5)`.
+- `y`, `o`, `no` y las condiciones solo aceptan `verdadero` o `falso`. `si (1)` es un error con una pista.
+
+## Condiciones y bucles
+
+```codexivo
+variable edad = 15;
+si (edad >= 18) {
+  imprimir("adulto");
+} pero_si (edad >= 13) {
+  imprimir("adolescente");
+} si_no {
+  imprimir("niño");
+}
+
+variable i = 0;
+mientras (i < 3) {
+  i += 1;
+}
+
+hacer {
+  i -= 1;
+} hasta_que (i == 0);
+
+para (variable j = 0; j < 3; j += 1) {
+  imprimir(j);
+}
+```
+
+- `hacer … hasta_que` ejecuta el bloque al menos una vez y repite **hasta que** la condición sea verdadera.
+- La variable de un `para` solo existe dentro del bucle.
+
+## Procedimientos
+
+```codexivo
+variable saludar = procedimiento(nombre) {
+  regresa "Hola, " + nombre;
+};
+saludar("Uriel");
+```
+
+- Se crean con `procedimiento(parámetros) { … }` y se guardan en variables.
+- Hay que llamarlos con exactamente tantos valores como parámetros.
+- Sin `regresa`, un procedimiento regresa `nulo`.
+- Recuerdan las variables de donde se crearon (closures) y pueden llamarse a sí mismos.
+
+Los procedimientos con nombre (`procedimiento saludar(nombre) { … }`) llegarán con la v1.
+
+## Listas y textos
+
+```codexivo
+variable números = [10, 20, 30];
+números[0];    // 10
+números[-1];   // 30, desde el final
+"hola"[1];     // "o"
+```
+
+Los índices son enteros desde 0; un índice fuera de rango es un error que dice cuántos elementos hay.
+
+## Biblioteca
+
+Los nombres con acento también se aceptan sin él (`máximo` o `maximo`).
+
+| Procedimiento                     | Qué hace                                                                   |
+| --------------------------------- | -------------------------------------------------------------------------- |
+| `imprimir(a, b, …)`               | Escribe los valores separados por un espacio y termina la línea            |
+| `leer()`                          | Siguiente línea de entrada como texto, o `nulo` si ya no hay               |
+| `leer_número()`                   | Siguiente línea de entrada como número                                     |
+| `tipo(x)`                         | `"número"`, `"texto"`, `"lógico"`, `"nulo"`, `"lista"` o `"procedimiento"` |
+| `texto(x)`, `número(x)`           | Conversiones explícitas                                                    |
+| `longitud(x)`                     | Caracteres de un texto o elementos de una lista                            |
+| `absoluto(x)`                     | Valor absoluto                                                             |
+| `máximo(…)`, `mínimo(…)`          | De varios números o de una lista                                           |
+| `redondear(x, decimales?)`        | Redondea; los `.5` se alejan del cero                                      |
+| `agregar(lista, x)`               | Agrega al final (cambia la lista)                                          |
+| `primero(lista)`, `último(lista)` | Primer y último elemento                                                   |
+
+## Errores
+
+Cada error dice de qué tipo es (léxico, sintaxis, ejecución o límite), qué pasó, dónde y, casi siempre, una pista:
+
+```
+Error de ejecución en la línea 2, columna 5: No se puede dividir entre cero.
+Pista: Revisa que el divisor no valga 0 antes de dividir.
+```
+
+## Límites
+
+Para que un error nunca congele la página, la ejecución se detiene con un error de límite al superar 10 000 000 de
+operaciones, 10 000 llamadas anidadas o 1 000 000 de caracteres impresos. Los tres se pueden configurar.

package/docs/recetario.md

@@ -0,0 +1,159 @@
+# Recetario de programas Codexivo
+
+Esta colección de programas ilustra patrones útiles del lenguaje. Cada ejemplo está listo para copiarse en el REPL o en un
+archivo `.codexivo`.
+
+## 1. Hola mundo personalizado
+
+```codexivo
+variable saludar = procedimiento(nombre) {
+  regresa "Hola " + nombre + "!";
+};
+
+saludar("Codexivo");
+```
+
+Demuestra cómo declarar un procedimiento, concatenar cadenas y retornar un valor.
+
+## 2. Clasificador por edades
+
+```codexivo
+variable clasificar = procedimiento(edad) {
+  si (edad >= 18) {
+    regresa "adulto";
+  } pero_si (edad >= 13) {
+    regresa "adolescente";
+  } si_no {
+    regresa "niño";
+  }
+};
+
+clasificar(16);
+```
+
+Ilustra el encadenamiento `si`/`pero_si`/`si_no` y el uso de operadores relacionales.
+
+## 3. Promedio simple
+
+```codexivo
+variable promedio = procedimiento(a, b, c) {
+  variable total = a + b + c;
+  regresa total / 3;
+};
+
+promedio(8, 7.5, 9);
+```
+
+Combina números enteros y decimales con operaciones aritméticas.
+
+## 4. Valor absoluto
+
+```codexivo
+variable valorAbsoluto = procedimiento(n) {
+  si (n < 0) {
+    regresa -n;
+  } si_no {
+    regresa n;
+  }
+};
+
+valorAbsoluto(-42);
+```
+
+Ejemplo de uso del operador prefijo `-` y del comportamiento truthy/falsy en condicionales.
+
+## 5. Contador recursivo
+
+```codexivo
+variable cuentaRegresiva = procedimiento(n) {
+  si (n == 0) {
+    regresa "¡Despegue!";
+  }
+
+  regresa cuentaRegresiva(n - 1);
+};
+
+cuentaRegresiva(3);
+```
+
+Muestra cómo las funciones en Codexivo soportan recursión gracias a que conservan su entorno de definición.
+
+## 6. Validación de longitud
+
+```codexivo
+variable esNombreValido = procedimiento(nombre) {
+  variable tamaño = longitud(nombre);
+  si (tamaño >= 3 y tamaño <= 15) {
+    regresa verdadero;
+  }
+  regresa falso;
+};
+
+esNombreValido("Ana");
+```
+
+Ejemplo de uso del builtin `longitud` junto con operadores de comparación y booleanos.
+
+## 7. Suma con bucle for
+
+```codexivo
+variable sumarHasta = procedimiento(n) {
+  variable suma = 0;
+  para (variable i = 1; i <= n; i += 1) {
+    suma += i;
+  }
+  regresa suma;
+};
+
+sumarHasta(10); // Suma de 1 a 10 = 55
+```
+
+Demuestra el uso de bucles `para` con operadores de asignación compuesta.
+
+## 8. Búsqueda en arreglo
+
+```codexivo
+variable buscar = procedimiento(arreglo, elemento) {
+  para (variable i = 0; i < longitud(arreglo); i += 1) {
+    si (arreglo[i] == elemento) {
+      regresa i;
+    }
+  }
+  regresa -1;
+};
+
+variable numeros = [10, 20, 30, 40];
+buscar(numeros, 30); // Regresa 2
+```
+
+Combina bucles, acceso a arreglos, condicionales y funciones built-in.
+
+## 9. Trabajo con funciones matemáticas
+
+```codexivo
+variable estadisticas = procedimiento(datos) {
+  variable suma = 0;
+  variable mayor = primero(datos);
+  variable menor = primero(datos);
+  
+  para (variable i = 0; i < longitud(datos); i += 1) {
+    suma += datos[i];
+    si (datos[i] > mayor) {
+      mayor = datos[i];
+    }
+    si (datos[i] < menor) {
+      menor = datos[i];
+    }
+  }
+  variable promedio = suma / longitud(datos);
+  
+  regresa [redondear(promedio), mayor, menor];
+};
+
+estadisticas([5, 2, 8, 1, 9]); // [5, 9, 1]
+```
+
+Muestra el uso de las funciones matemáticas built-in y manipulación de arreglos.
+
+Todos los ejemplos de este recetario se ejecutan con la versión actual del intérprete. Consulta [qué funciona hoy](./lenguaje.md)
+y [hacia dónde va el lenguaje](./especificacion-v1.md).

package/docs/repl.md

@@ -0,0 +1,64 @@
+# REPL y ejecución desde la terminal
+
+Instala el principal con `npm install -g codexivo` o `bun add -g --trust codexivo`. El gestor selecciona el paquete nativo
+compatible mediante `os`, `cpu` y `libc`; `postinstall` verifica la versión y coloca el ejecutable en la ruta `bin` del
+principal. Una vez instalado, `codexivo` abre el REPL y `codexivo programa.cdx` ejecuta archivos sin necesitar Node.js ni Bun.
+
+Si omites scripts, la biblioteca sigue disponible; para preparar el CLI tras una instalación local, ejecuta
+`node node_modules/codexivo/postinstall.mjs` una vez. Los ejecutables de
+[Releases](https://github.com/UrielCuriel/codexivo/releases) funcionan directamente sin gestores ni runtimes externos.
+En Linux/macOS, aplica `chmod +x` al ejecutable descargado. Se admiten x64 y ARM64 en Linux, macOS y Windows; para Alpine
+Linux elige la variante `musl`.
+
+## REPL
+
+```sh
+bun install
+bun run repl
+```
+
+Escribe código y presiona Enter. Las variables se conservan entre entradas. Si una línea deja un bloque `{` abierto, el REPL
+sigue leyendo (con el prompt `..`) hasta que lo cierres. Para salir escribe `salir`.
+
+```
+>> variable saludar = procedimiento(nombre) { regresa "Hola, " + nombre; };
+>> saludar("Codexivo")
+"Hola, Codexivo"
+>> si (verdadero) {
+..   imprimir("dentro del bloque")
+.. }
+dentro del bloque
+>> salir
+¡Adiós!
+```
+
+En el REPL se puede volver a declarar una variable (`variable x = …` dos veces) para experimentar; en un programa normal es un
+error.
+
+## Ejecutar un archivo
+
+```sh
+bun run src/cli.ts programa.cdx
+```
+
+Lo que llegue por la entrada estándar alimenta a `leer()` y `leer_número()`:
+
+```sh
+echo 21 | bun run src/cli.ts doble.cdx
+```
+
+## Ver la ejecución desde código
+
+```ts
+import { prepare, run } from 'codexivo';
+
+// Todos los eventos de una ejecución
+const { events } = run('variable x = 1; x += 1;', { trace: true });
+
+// Paso a paso
+const { machine } = prepare('variable x = 1;\nx += 1;');
+while (machine && !machine.done) {
+  machine.step();
+  console.log(machine.snapshot().span?.start.line, machine.snapshot().frames[0]?.scopes);
+}
+```

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "codexivo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Lenguaje de programación en español para practicar lógica y algoritmos, que se ejecuta en el navegador.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "src/index.ts",
+  "files": [
+    "bin/codexivo.exe",
+    "postinstall.mjs",
+    "dist/index.js",
+    "dist/index.js.map",
+    "src",
+    "!src/cli.ts",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "check": "bun check",
+    "repl": "bun run src/cli.ts",
+    "build": "bun run build:lib && bun run build:binary",
+    "build:lib": "bun build ./src/index.ts --target browser --format esm --outdir=dist --minify --sourcemap=linked",
+    "build:binary": "bun run scripts/build-binaries.ts",
+    "build:binaries": "bun run scripts/build-binaries.ts --all",
+    "test:package": "bun run scripts/test-package.ts",
+    "prepack": "bun run build:lib",
+    "version": "bun run scripts/sync-native-versions.ts && git add package.json bun.lock packages/*/package.json",
+    "publish:native": "bun run scripts/publish-native.ts",
+    "format": "bun fmt",
+    "format:check": "bun fmt --check",
+    "postinstall": "node ./postinstall.mjs"
+  },
+  "keywords": [
+    "lenguaje de programación",
+    "español",
+    "educación",
+    "intérprete"
+  ],
+  "author": "Uriel Curiel",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UrielCuriel/codexivo.git"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.3"
+  },
+  "packageManager": "bun@1.4.4",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "optionalDependencies": {
+    "codexivo-linux-x64": "0.2.0",
+    "codexivo-linux-x64-musl": "0.2.0",
+    "codexivo-linux-arm64": "0.2.0",
+    "codexivo-linux-arm64-musl": "0.2.0",
+    "codexivo-darwin-x64": "0.2.0",
+    "codexivo-darwin-arm64": "0.2.0",
+    "codexivo-windows-x64": "0.2.0",
+    "codexivo-windows-arm64": "0.2.0"
+  },
+  "bin": {
+    "codexivo": "./bin/codexivo.exe"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,38 @@
+import { chmodSync, copyFileSync, existsSync, linkSync, readFileSync, unlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const directory = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+// Development checkouts build their executables after installing dependencies.
+if (existsSync(join(directory, 'src/cli.ts')) && existsSync(join(directory, 'packages'))) process.exit(0);
+
+const root = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'));
+const platform = process.platform === 'win32' ? 'windows' : process.platform;
+const musl = platform === 'linux' && !process.report.getReport().header.glibcVersionRuntime;
+const name = `codexivo-${platform}-${process.arch}${musl ? '-musl' : ''}`;
+
+try {
+  if (!root.optionalDependencies[name]) throw new Error(`No hay un ejecutable para ${platform}/${process.arch}.`);
+  const manifest = require.resolve(`${name}/package.json`);
+  const native = JSON.parse(readFileSync(manifest, 'utf8'));
+  if (native.version !== root.version || native.version !== root.optionalDependencies[name]) {
+    throw new Error(`La versión de ${name} (${native.version}) debe ser ${root.version}.`);
+  }
+  const source = join(dirname(manifest), 'bin', platform === 'windows' ? 'codexivo.exe' : 'codexivo');
+  if (!existsSync(source)) throw new Error(`No se encontró el ejecutable de ${name}.`);
+  const destination = resolve(directory, root.bin.codexivo);
+  if (existsSync(destination)) unlinkSync(destination);
+  try {
+    linkSync(source, destination);
+  } catch {
+    copyFileSync(source, destination);
+  }
+  chmodSync(destination, 0o755);
+} catch (error) {
+  console.error(`No se pudo instalar Codexivo: ${error.message}`);
+  console.error('Reinstala el paquete con las dependencias opcionales y los scripts de instalación habilitados.');
+  process.exit(1);
+}

package/src/engine.ts

@@ -0,0 +1,97 @@
+import type { CodexivoError, ErrorInfo } from './errors';
+import type * as ast from './syntax/ast';
+import { parse } from './syntax/parser';
+import type { Token } from './syntax/token';
+import { compile } from './runtime/compiler';
+import { Machine } from './runtime/machine';
+import type { MachineEvent, MachineOptions, MachineStatus } from './runtime/machine';
+import { repr, Scope } from './runtime/values';
+import type { Value } from './runtime/values';
+
+export interface PreparedProgram {
+  program: ast.Program;
+  tokens: Token[];
+  /** Errores léxicos y sintácticos. Si hay alguno, `machine` no existe. */
+  errors: CodexivoError[];
+  machine?: Machine;
+}
+
+/** Analiza el código y, si no tiene errores, prepara una máquina lista para ejecutarlo paso a paso. */
+export const prepare = (source: string, options: MachineOptions = {}): PreparedProgram => {
+  const { program, tokens, errors } = parse(source);
+  if (errors.length > 0) return { program, tokens, errors };
+  return { program, tokens, errors, machine: new Machine(compile(program), options) };
+};
+
+export interface RunOptions extends Omit<MachineOptions, 'onEvent'> {
+  /** Guarda los eventos de la ejecución en `events`. */
+  trace?: boolean;
+  /** Máximo de eventos a guardar con `trace`. Por defecto 100 000. */
+  maxEvents?: number;
+}
+
+export interface RunResult {
+  status: MachineStatus;
+  /** `true` si el programa terminó sin errores. */
+  ok: boolean;
+  /** Valor de la última expresión del programa, o lo que regresó con `regresa`. */
+  result: Value;
+  /** `result` como se escribiría en código. */
+  resultText: string;
+  output: string;
+  errors: ErrorInfo[];
+  operations: number;
+  events?: MachineEvent[];
+  /** `true` si se guardaron menos eventos de los que ocurrieron. */
+  eventsTruncated?: boolean;
+}
+
+/** Ejecuta un programa completo. */
+export const run = (source: string, options: RunOptions = {}): RunResult => {
+  const { trace, maxEvents = 100_000, ...machineOptions } = options;
+  const events: MachineEvent[] = [];
+  let eventsTruncated = false;
+  const onEvent = trace
+    ? (event: MachineEvent) => {
+        if (events.length < maxEvents) events.push(event);
+        else eventsTruncated = true;
+      }
+    : undefined;
+
+  const { errors, machine } = prepare(source, { ...machineOptions, onEvent });
+  if (!machine) {
+    return {
+      status: 'error',
+      ok: false,
+      result: null,
+      resultText: 'nulo',
+      output: '',
+      errors: errors.map(error => error.toJSON()),
+      operations: 0,
+      ...(trace ? { events, eventsTruncated } : {}),
+    };
+  }
+
+  machine.run();
+  return {
+    status: machine.status,
+    ok: machine.status === 'terminada',
+    result: machine.result,
+    resultText: repr(machine.result),
+    output: machine.output,
+    errors: machine.error ? [machine.error.toJSON()] : [],
+    operations: machine.operations,
+    ...(trace ? { events, eventsTruncated } : {}),
+  };
+};
+
+/** Varias ejecuciones que comparten variables, como en el REPL. */
+export class Session {
+  private readonly globals = new Scope();
+
+  constructor(private readonly options: Omit<RunOptions, 'globals' | 'allowRedeclare'> = {}) {}
+
+  run(source: string): RunResult {
+    return run(source, { ...this.options, globals: this.globals, allowRedeclare: true });
+  }
+}