tangerine-lang 0.0.0-stage → 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Cambios
+
+## 3.1.0
+
+### Nuevo
+- **Errores que enseñan**: sugerencias "¿Quisiste decir…?" para variables, campos y métodos (también para nombres de otros lenguajes como `length`, `null` o `toUpperCase`), y rastro de llamadas con archivo y línea.
+- **Parámetros por defecto**: `fn saludar(nombre, saludo = "Hola")`, también en closures.
+- **Paquetes**: `tangerine add` (npm o GitHub `usuario/repo`), `remove` y `buscar`. Los imports sin `./` buscan en `node_modules`; `build` genera un mapa de paquetes para el navegador.
+- **Plantillas**: `tangerine new --con` react, vue, svelte, vite, angular, next, astro, expo, swift, flutter, consola y paquete.
+- **Instalador de herramientas**: `tangerine install` (node, git, swift, python, angular, typescript, vscode, deno, bun, pnpm, yarn) con winget, Homebrew o npm, y `tangerine doctor`.
+- **React en Tangerine**: plugin `tangerine-lang/react` (`h`, `fragment`, `use_state`, `use_effect`, `use_memo`, `use_ref`) y plugin de Vite `tangerine-lang/vite` para importar `.tng` desde JavaScript.
+- **Extensión de VS Code** con colores de sintaxis y fragmentos; se instala con `tangerine vscode`.
+- **Módulos**: `export` para `let`, `var`, `fn`, `class` y `struct`; `import { a, b as c } from "./x.tng"` e `import x from "./x"`. Cada módulo se ejecuta una vez y las importaciones circulares se detectan.
+- **Paquete de npm** `tangerine-lang` con builds ESM, CommonJS y un bundle global para el navegador, más tipos de TypeScript.
+- **CLI** `tangerine`: REPL multilínea, `run`, `check`, `new`, `build`, `dev` con recarga automática y `serve`.
+- **Instancias independientes**: `new Tangerine({ output, stepLimit, natives, plugins, modules })`. Ya no hay estado global, así que varios programas pueden convivir.
+- **Plugins**: `tng.use(plugin)` y `Tangerine.registerPlugin(plugin)`. Las funciones del navegador ahora son el plugin `dom`.
+- **Arranque automático en el navegador**: ejecuta `<script type="text/tangerine">`, registra módulos con `data-module` y descarga archivos con `src`.
+- Plugin `sistema` para Node.js: `read_file`, `write_file`, `file_exists`, `list_dir`, `args`, `env`, `exit`.
+- Funciones `to_json` y `from_json`.
+- Nuevas funciones del DOM: `query_all`, `remove`, `get_attr`, `set_style`, `after`. Los callbacks de `on` con un parámetro reciben `{ type, key, value, target }`.
+
+### Cambios
+- Todos los mensajes de error están en español e indican archivo, línea y, en errores de sintaxis, columna.
+- `==` compara mapas por su contenido, igual que las listas.
+- El límite de pasos es configurable; por defecto no hay límite (el playground usa 400 000).
+- Los identificadores aceptan más letras latinas (`ñ`, `ő`, etc.).
+- `sorted_by_key` calcula cada clave una sola vez y `unique` es lineal para valores simples.
+
+### Internos
+- El intérprete se dividió en `lexer`, `parser`, `valores` e `interprete`.
+- La web oficial se dividió en seis módulos de Tangerine y se construye con `tangerine build`.
+- Pruebas con Vitest, ESLint y CI en Linux y Windows con Node 18, 20 y 22.
+- La web oficial se publica en GitHub Pages en cada push a `main`.
+
+## 3.0.0
+
+- `match` con rangos, alternativas y guardas; closures al estilo de Rust; clases con `init`, `self` y `super`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Los autores de Tangerine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,296 @@
-# Temporary Holding Version
+# 🍊 Tangerine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tangerine es un lenguaje de programación pequeño con la sintaxis de Rust y Swift: llaves sin paréntesis, `match`, rangos, closures, clases y retorno implícito. Funciona en el navegador y en Node.js, y su intérprete no tiene dependencias.
+
+**Lo que lo hace distinto**
+
+- **Errores que enseñan, en español.** Dicen archivo, línea y columna, muestran el rastro de llamadas y sugieren el nombre correcto: `List no tiene un método llamado 'length'. ¿Quisiste decir 'len'?`
+- **Componentes de React en Tangerine.** `tangerine new app --con react` y escribe componentes con hooks en archivos `.tng`.
+- **Una sola herramienta.** `tangerine` crea proyectos (propios, React, Vue, Angular, Swift…), instala herramientas, maneja paquetes y empaqueta tu web en un solo HTML.
+
+```rust
+import { formato_precio } from "./tienda.tng"
+
+struct Canasta {
+  var items = []
+  fn add(fruta, kilos, precio) { self.items.push({ fruta, kilos, precio }); self }
+  fn total() { self.items.fold(0, |s, x| s + x.kilos * x.precio) }
+}
+
+let canasta = Canasta().add("mandarina", 2, 3200).add("limón", 1, 2800)
+
+for item in canasta.items {
+  let etiqueta = match item.kilos {
+    0 => "agotado",
+    1..=2 => "poco",
+    _ => "mucho",
+  }
+  println("{item.fruta}: {etiqueta}")
+}
+println("Total: {formato_precio(canasta.total())}")
+```
+
+## Instalar
+
+```bash
+npm install -g tangerine-lang      # el comando `tangerine` en tu terminal
+npm install tangerine-lang         # como biblioteca en tu proyecto
+```
+
+Requiere Node.js 18 o más reciente.
+
+## La terminal
+
+| Comando | Qué hace |
+| --- | --- |
+| `tangerine` | Abre el REPL. Las variables se conservan y los bloques sin cerrar siguen en la línea siguiente. |
+| `tangerine archivo.tng [args]` | Ejecuta un archivo. Los argumentos llegan en `args()`. |
+| `tangerine check *.tng` | Revisa la sintaxis sin ejecutar. |
+| `tangerine new mi-app [--con X]` | Crea un proyecto. Sin `--con` es una web en Tangerine; con `--con` usa otra plantilla (abajo). |
+| `tangerine dev` | Construye, sirve en `localhost:3000` y recarga al guardar. |
+| `tangerine build` | Empaqueta el proyecto en un solo `index.html`. |
+| `tangerine serve [carpeta]` | Sirve archivos estáticos en `localhost:8000`. |
+| `tangerine add <paquete>` | Instala un paquete de Tangerine desde npm, o desde GitHub con `usuario/repo`. |
+| `tangerine remove <paquete>`, `tangerine buscar [texto]` | Desinstala o busca paquetes. |
+| `tangerine install <herramienta>` | Instala `node`, `git`, `swift`, `python`, `angular`, `typescript`, `vscode`, `deno`, `bun`, `pnpm`, `yarn`… con winget, Homebrew o npm. Pregunta antes de ejecutar. |
+| `tangerine doctor` | Muestra qué herramientas tienes instaladas y qué falta. |
+| `tangerine vscode` | Instala la extensión de Tangerine en VS Code (colores y fragmentos). |
+
+Opciones: `--limite <n>` (máximo de pasos), `-p <puerto>`, `-o <salida>`, `--entrada <archivo>`, `--cdn`, `--con <plantilla>`, `--sin-tangerine`, `--si` (no preguntar), `--forzar`, `--dev`.
+
+### Plantillas de `tangerine new --con`
+
+| Plantilla | Qué crea |
+| --- | --- |
+| `web` | Página 100% en Tangerine (por defecto). |
+| `react` | React + Vite con componentes escritos en Tangerine. |
+| `consola` | Programa de terminal. |
+| `paquete` | Paquete de Tangerine listo para publicar en npm. |
+| `vue`, `svelte`, `vite` | Proyecto oficial de Vite, con el plugin de Tangerine ya agregado (`--sin-tangerine` para omitirlo). |
+| `angular`, `next`, `astro`, `expo` | Proyecto creado con el CLI oficial de cada framework. |
+| `swift`, `flutter` | Proyecto con `swift package init` o `flutter create` (necesitan Swift o Flutter instalados). |
+
+Los errores dicen dónde está el problema:
+
+```
+error: app.tng, línea 2, columna 1: Se esperaba ']' pero se encontró 'println'
+  2 │ println(x)
+    │ ^
+```
+
+Fuera del navegador hay funciones para trabajar con el sistema: `read_file`, `write_file`, `file_exists`, `list_dir`, `args()`, `env(nombre)` y `exit(código)`.
+
+## Proyectos web
+
+```bash
+tangerine new mi-app
+cd mi-app
+npm install
+npm run dev
+```
+
+La configuración vive en `tangerine.json`:
+
+```json
+{
+  "entry": "src/main.tng",
+  "out": "dist/index.html",
+  "title": "Mi app",
+  "styles": ["src/estilos.css"],
+  "scripts": []
+}
+```
+
+| Clave | Qué hace |
+| --- | --- |
+| `entry` | Archivo de entrada. Sus `import` se siguen solos. |
+| `out` | Dónde escribir el HTML. |
+| `title`, `lang`, `head`, `body` | Título, idioma, HTML extra en `<head>` y el contenido inicial de `<body>` (por defecto `<div id="app"></div>`). |
+| `styles` | Hojas de estilo que se incluyen en el HTML. |
+| `scripts` | Archivos JavaScript que se incluyen, por ejemplo plugins propios. |
+| `runtime` | `"inline"` (por defecto) incluye el intérprete; `"cdn"` lo carga de jsDelivr. |
+
+## Paquetes
+
+```bash
+tangerine add colores           # desde npm
+tangerine add manu/colores      # desde GitHub
+```
+
+```rust
+import { NARANJA, mezclar } from "colores"
+import paleta from "colores/paleta"
+```
+
+Un paquete es una carpeta con `package.json` y un archivo de entrada `.tng`, indicado en el campo `"tangerine"` (o `index.tng`). Crea uno con `tangerine new mi-paquete --con paquete` y publícalo con `npm publish`. `tangerine build` incluye los paquetes en el HTML final.
+
+## React y Vite
+
+```bash
+tangerine new mi-app --con react
+```
+
+```rust
+// src/Contador.tng
+export fn Contador(props) {
+  let (n, set_n) = use_state(props.inicio ?? 0)
+  h("button", { class: "boton", on_click: || set_n(|x| x + 1) }, "Clics: {n}")
+}
+```
+
+```jsx
+// src/main.jsx
+import { Contador } from "./Contador.tng";
+<Contador inicio={5} />
+```
+
+Funciones disponibles: `h(etiqueta, props, ...hijos)`, `fragment(...)`, `use_state`, `use_effect`, `use_memo`, `use_ref`. Los eventos van en `on_click`, `on_change`, `on_submit`… y reciben un mapa con `value`, `key`, `checked`, `prevent()` y `stop()`. `class` se convierte en `className` y `style` acepta un mapa.
+
+En cualquier proyecto de Vite basta con el plugin:
+
+```js
+// vite.config.js
+import tangerine from "tangerine-lang/vite";
+export default { plugins: [tangerine()] };
+```
+
+Sin Vite, el plugin de React se usa a mano: `new Tangerine({ plugins: [react(React)] })` con `import { react, wrapExport } from "tangerine-lang/react"`.
+
+## En una página, sin instalar nada
+
+```html
+<div id="app"></div>
+<script src="https://cdn.jsdelivr.net/npm/tangerine-lang@3.1.0/dist/tangerine.global.min.js"></script>
+<script type="text/tangerine">
+  let titulo = append(query("#app"), el("h1", nil, "Hola"))
+  let campo = append(query("#app"), el("input"))
+  on(campo, "input", |e| set_text(titulo, "Hola, {e.value}"))
+</script>
+```
+
+Al cargar la página se ejecutan los `<script type="text/tangerine">` en orden:
+
+- con `data-module="util.tng"` se registran como módulo para importarlos;
+- con `src="main.tng"` se descargan, junto con sus imports (necesita un servidor, por ejemplo `tangerine serve`);
+- sin atributos se ejecutan tal cual.
+
+Para arrancar a mano agrega `data-manual` al script del intérprete y llama a `Tangerine.start()`.
+
+## Como biblioteca
+
+```js
+import { Tangerine } from "tangerine-lang";
+
+const tng = new Tangerine({
+  output: (linea) => console.log(linea),
+  stepLimit: 100_000,                       // corta ciclos infinitos
+  natives: { doble: (x) => x * 2 },         // funciones de JavaScript visibles en Tangerine
+  modules: { "mate.tng": "export let IVA = 0.19" },
+});
+
+tng.run('import { IVA } from "./mate"\nprintln(doble(21), IVA)');   // 42 0.19
+
+const { output, error } = tng.runCode("println(1 / 0)");
+// output: [], error: "Línea 1: División entre cero"
+```
+
+Cada instancia es independiente: tiene su propia salida, sus funciones y su caché de módulos.
+
+| Método | Qué hace |
+| --- | --- |
+| `run(código, { file })` | Ejecuta y devuelve el valor de la última instrucción. Lanza `TngError` si falla. |
+| `runCode(código)` | Ejecuta sin lanzar y devuelve `{ output, error }`. |
+| `runModule(ruta)` | Ejecuta un módulo registrado o que `read` pueda leer. |
+| `define(nombre, valor)`, `defineAll(objeto)` | Agrega funciones o valores globales. |
+| `use(plugin)` | Instala un plugin. |
+| `addModule(ruta, código)` | Registra un módulo en memoria. |
+| `session()` | Crea una sesión cuyas variables persisten (para un REPL). |
+| `call(fn, args)`, `invoke(fn, args)` | Llama a una función de Tangerine. `invoke` envía los errores a `onError` en vez de lanzarlos. |
+| `message(error)` | Texto en español del error, con archivo, línea y columna. |
+| `trace(error)` | Rastro de llamadas del error, de la más interna a la más externa. |
+| `import(ruta)`, `forget(ruta)` | Carga un módulo y devuelve sus exports, u olvida uno ya cargado. |
+
+Opciones del constructor: `output`, `stepLimit`, `natives`, `plugins`, `modules`, `imports` (mapa de paquetes), `resolve`, `read`, `onError`, `globalPlugins`.
+
+En Node.js, `tangerine-lang/node` lee los imports del disco:
+
+```js
+import { runFile, createNodeTangerine } from "tangerine-lang/node";
+
+runFile("src/main.tng", { args: ["Ana"] });
+```
+
+### Plugins
+
+Un plugin agrega funciones nativas. Puede ser una función o un objeto con `install`:
+
+```js
+const reloj = {
+  name: "reloj",
+  install(tng) {
+    tng.defineAll({
+      hora: () => new Date().toLocaleTimeString("es"),
+      cada: (ms, f) => { setInterval(() => tng.invoke(f), ms); return null; },
+    });
+  },
+};
+
+new Tangerine({ plugins: [reloj] });
+Tangerine.registerPlugin(reloj); // para todas las instancias que se creen después
+```
+
+Los valores viajan así: los números, strings, booleanos y listas son los de JavaScript, `nil` es `null` y los mapas son objetos sin prototipo. `Tangerine.fromJS` y `Tangerine.toJS` convierten objetos completos.
+
+## El lenguaje en un vistazo
+
+| Tema | Ejemplo |
+| --- | --- |
+| Variables | `let fijo = 1`, `var cambia = 2`, `let (a, b) = (1, 2)` |
+| Strings | `"Hola, {nombre}"`, `'sin interpolar'` |
+| Control | `if x > 0 { "pos" } else { "neg" }` devuelve un valor |
+| Match | `match n { 0 => "cero", 1..=9 => "dígito", x if x < 0 => "neg", _ => "otro" }` |
+| Bucles | `for (i, x) in lista.enumerate() { }`, `while c { }`, `loop { break }` |
+| Funciones | `fn area(r: Float) -> Float { PI * r ** 2 }`, `fn saludar(n, s = "Hola") { }`, `\|x\| x * 2` |
+| Clases | `class Hija : Madre { init(x) { self.x = x } }`, `super.metodo()` |
+| Nil seguro | `usuario?.direccion?.ciudad ?? "sin ciudad"` |
+| Errores | `do { throw "falló" } catch e { println(e.message) }` |
+| Módulos | `export fn f() {}`, `import { f as g } from "./util"`, `import util from "./util"` |
+
+La guía completa, con ejemplos que se ejecutan en el navegador, está en el sitio (`sitio/`).
+
+## Desarrollo
+
+```bash
+npm install
+npm test           # construye dist/ y corre las pruebas
+npm run lint
+npm run sitio      # construye la web oficial en sitio/dist/index.html
+npm run sitio:dev  # la web con recarga automática en localhost:3000
+npm run vscode     # reempaqueta la extensión de VS Code
+```
+
+| Carpeta | Contenido |
+| --- | --- |
+| `src/lexer.js` | Texto a tokens. |
+| `src/parser.js` | Tokens a árbol de sintaxis. |
+| `src/interprete.js` | Recorre el árbol y lo ejecuta; métodos incorporados y módulos. |
+| `src/valores.js` | Ámbitos, funciones, clases y utilidades de valores. |
+| `src/index.js` | La clase `Tangerine` (API pública). |
+| `src/plugins/dom.js` | Funciones del navegador. |
+| `src/navegador.js` | Bundle global y arranque automático en la página. |
+| `src/sugerencias.js` | El "¿Quisiste decir…?" de los errores. |
+| `src/plugins/react.js`, `src/vite.js` | Componentes de React en Tangerine y el plugin de Vite. |
+| `src/node.js`, `src/construir.js`, `src/herramientas.js`, `bin/` | Node.js, paquetes, empaquetado, plantillas, instalador y CLI. |
+| `sitio/` | La web oficial, escrita en Tangerine. Se publica en GitHub Pages con `.github/workflows/sitio.yml`. |
+| `plantillas/` | Lo que copia `tangerine new`. |
+| `editores/vscode/` | La extensión de VS Code. |
+
+### Publicar una versión
+
+1. Sube la versión en `package.json` y en `VERSION` de `src/index.js` (una prueba verifica que coincidan) y anota los cambios en `CHANGELOG.md`.
+2. `npm login` y luego `npm publish`. `prepublishOnly` corre el lint, las pruebas y construye `dist/`.
+3. O crea un release en GitHub: el flujo `publicar.yml` publica con el secreto `NPM_TOKEN`.
+
+## Licencia
+
+MIT

package/bin/tangerine.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// CLI de Tangerine: ejecutar, revisar, crear, construir y servir proyectos.
+import fs from "node:fs";
+import path from "node:path";
+import http from "node:http";
+import readline from "node:readline";
+import { createNodeTangerine, nodeResolve } from "../src/node.js";
+import { parse, show, VERSION, TngError } from "../src/index.js";
+import { loadConfig, buildToDisk } from "../src/construir.js";
+import { cmdNew, cmdInstall, cmdDoctor, cmdAdd, cmdRemove, cmdBuscar, cmdVscode } from "../src/herramientas.js";
+
+const color = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const naranja = paint("38;5;208"), rojo = paint("31"), gris = paint("90"), verde = paint("32"), negrita = paint("1");
+
+const AYUDA = `
+${naranja("Tangerine")} ${VERSION}: un lenguaje pequeño con la sintaxis de Rust y Swift
+
+${negrita("Programar")}
+  tangerine                          abre el REPL interactivo
+  tangerine <archivo.tng> [args]     ejecuta un archivo (también: tangerine run)
+  tangerine check <archivos...>      revisa la sintaxis sin ejecutar
+
+${negrita("Proyectos")}
+  tangerine new <carpeta>            crea un proyecto web en Tangerine
+  tangerine new <carpeta> --con X    usa otra plantilla: react, vue, svelte, angular,
+                                     next, astro, expo, swift, flutter, consola, paquete
+  tangerine new --lista              muestra todas las plantillas
+  tangerine build                    empaqueta el proyecto en un solo HTML
+  tangerine dev                      construye, sirve y recarga al guardar
+  tangerine serve [carpeta]          sirve archivos estáticos
+
+${negrita("Paquetes de Tangerine")}
+  tangerine add <paquete...>         instala paquetes de npm o de GitHub (usuario/repo)
+  tangerine remove <paquete...>      los desinstala
+  tangerine buscar [texto]           busca paquetes de Tangerine en npm
+
+${negrita("Herramientas")}
+  tangerine install <nombre...>      instala node, git, swift, python, angular, vscode…
+  tangerine install --lista          muestra todo lo que puede instalar
+  tangerine doctor                   revisa qué tienes instalado
+  tangerine vscode                   instala la extensión de Tangerine en VS Code
+
+${negrita("Opciones")}
+  --limite <n>       máximo de pasos al ejecutar (por defecto, sin límite)
+  -p, --puerto <n>   puerto para dev y serve (por defecto 3000 y 8000)
+  -o, --salida <f>   archivo de salida de build
+  --entrada <f>      archivo de entrada de build
+  --cdn              build carga el intérprete desde jsDelivr en vez de incluirlo
+  --con <plantilla>  plantilla para new
+  --sin-tangerine    en plantillas de Vite, no agrega el plugin de Tangerine
+  --si               install no pregunta antes de ejecutar
+  --forzar           install reinstala aunque ya exista
+  --dev              add instala como dependencia de desarrollo
+  -v, --version      muestra la versión
+  -h, --ayuda        muestra esta ayuda
+`;
+
+function parseArgs(argv) {
+  const flags = {}, rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      if (i + 1 >= argv.length) fail(`Falta el valor de ${a}`);
+      return argv[++i];
+    };
+    if (a === "--") { rest.push(...argv.slice(i + 1)); break; }
+    else if (a === "--limite") flags.limite = Number(next());
+    else if (a === "-p" || a === "--puerto") flags.puerto = Number(next());
+    else if (a === "-o" || a === "--salida") flags.salida = next();
+    else if (a === "--entrada") flags.entrada = next();
+    else if (a === "--cdn") flags.cdn = true;
+    else if (a === "--con") flags.con = next().toLowerCase();
+    else if (a === "--lista") flags.lista = true;
+    else if (a === "--sin-tangerine") flags.sinTangerine = true;
+    else if (a === "--si" || a === "-y" || a === "--yes") flags.si = true;
+    else if (a === "--forzar") flags.forzar = true;
+    else if (a === "--dev" || a === "-D") flags.dev = true;
+    else if (a === "-v" || a === "--version") flags.version = true;
+    else if (a === "-h" || a === "--ayuda" || a === "--help") flags.ayuda = true;
+    else if (a.startsWith("-") && rest.length === 0) fail(`Opción desconocida: ${a}`);
+    else rest.push(a);
+  }
+  return { flags, rest };
+}
+
+function fail(msg, code = 1) {
+  console.error(rojo("error: ") + msg);
+  process.exit(code);
+}
+
+/** Muestra un error de Tangerine con la línea de código y una flecha en la columna. */
+function reportError(tng, err) {
+  if (err instanceof TngError && err.file && path.isAbsolute(err.file)) {
+    const abs = err.file;
+    err.file = path.relative(process.cwd(), abs) || abs;
+    console.error(rojo("error: ") + tng.message(err));
+    const src = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8").split(/\r?\n/) : null;
+    if (src && err.line && src[err.line - 1] !== undefined) {
+      const num = String(err.line);
+      console.error(gris(`  ${num} │ `) + src[err.line - 1]);
+      if (err.col) console.error(gris(`  ${" ".repeat(num.length)} │ `) + " ".repeat(err.col - 1) + rojo("^"));
+    }
+    printTrace(tng, err);
+    return;
+  }
+  console.error(rojo("error: ") + tng.message(err));
+  printTrace(tng, err);
+}
+
+function printTrace(tng, err) {
+  const rel = (t) => t.replace(/(^|llamada en )(\/[^,]+|[A-Za-z]:\\[^,]+)/, (_m, a, p) => a + (path.relative(process.cwd(), p) || p));
+  for (const linea of tng.trace(err)) console.error(gris("  " + rel(linea)));
+}
+
+function cmdRun(file, args, flags) {
+  if (!file) fail("Indica el archivo a ejecutar: tangerine run main.tng");
+  const full = nodeResolve(file, null);
+  if (!fs.existsSync(full)) fail(`No existe el archivo ${file}`);
+  const tng = createNodeTangerine({ args, stepLimit: flags.limite || 0 });
+  try {
+    tng.runModule(full);
+  } catch (err) {
+    reportError(tng, err);
+    process.exit(1);
+  }
+}
+
+function cmdCheck(files) {
+  if (!files.length) fail("Indica uno o más archivos: tangerine check main.tng");
+  let bad = 0;
+  const tng = createNodeTangerine();
+  for (const f of files) {
+    const full = path.resolve(f);
+    if (!fs.existsSync(full)) { console.error(rojo("✗ ") + `${f}: no existe`); bad++; continue; }
+    try {
+      parse(fs.readFileSync(full, "utf8"), full);
+      console.log(verde("✓ ") + f);
+    } catch (err) {
+      bad++;
+      reportError(tng, err);
+    }
+  }
+  if (bad) process.exit(1);
+}
+
+function cmdRepl() {
+  const tng = createNodeTangerine();
+  const session = tng.session();
+  console.log(`${naranja("Tangerine")} ${VERSION}. Escribe código y pulsa Enter. ${gris(".ayuda para ver comandos, .salir para terminar")}`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: naranja("tng> ") });
+  let buffer = "";
+  rl.prompt();
+  rl.on("line", (line) => {
+    if (!buffer) {
+      const cmd = line.trim();
+      if (cmd === ".salir" || cmd === ".exit") return rl.close();
+      if (cmd === ".ayuda" || cmd === ".help") {
+        console.log("  .salir     termina el REPL\n  .limpiar   descarta el código a medio escribir\n  Las variables se conservan entre líneas. Los bloques sin cerrar continúan en la línea siguiente.");
+        return rl.prompt();
+      }
+    }
+    if (line.trim() === ".limpiar") { buffer = ""; rl.setPrompt(naranja("tng> ")); return rl.prompt(); }
+    buffer += (buffer ? "\n" : "") + line;
+    try {
+      const value = session.run(buffer);
+      if (value !== null && value !== undefined) console.log(gris(show(value, true)));
+      buffer = "";
+      rl.setPrompt(naranja("tng> "));
+    } catch (err) {
+      if (err.incomplete) { rl.setPrompt(gris("...  ")); return rl.prompt(); }
+      buffer = "";
+      rl.setPrompt(naranja("tng> "));
+      console.error(rojo("error: ") + tng.message(err));
+    }
+    rl.prompt();
+  });
+  rl.on("close", () => { console.log(); process.exit(0); });
+}
+
+function buildConfig(flags) {
+  const config = loadConfig(process.cwd(), { entry: flags.entrada, out: flags.salida, runtime: flags.cdn ? "cdn" : undefined });
+  if (!fs.existsSync(path.resolve(config.root, config.entry)))
+    fail(`No existe el archivo de entrada ${config.entry}. Créalo o indica otro con --entrada (o en tangerine.json).`);
+  return config;
+}
+
+function cmdBuild(flags) {
+  const config = buildConfig(flags);
+  try {
+    const r = buildToDisk(config);
+    const kb = (Buffer.byteLength(r.html) / 1024).toFixed(1);
+    console.log(`${verde("✓")} ${path.relative(process.cwd(), r.out)} ${gris(`(${r.modules.length} módulos, ${kb} KB)`)}`);
+  } catch (err) {
+    fail(err.message);
+  }
+}
+
+const TIPOS = {
+  ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8", ".json": "application/json; charset=utf-8", ".tng": "text/plain; charset=utf-8",
+  ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
+  ".webp": "image/webp", ".ico": "image/x-icon", ".woff2": "font/woff2", ".txt": "text/plain; charset=utf-8",
+};
+
+function staticServer(dir, extra) {
+  const root = path.resolve(dir);
+  return http.createServer((req, res) => {
+    if (extra && extra(req, res)) return;
+    let pathname;
+    try { pathname = decodeURIComponent(new URL(req.url, "http://x").pathname); }
+    catch { res.writeHead(400); return res.end(); }
+    let file = path.join(root, pathname);
+    if (!file.startsWith(root)) { res.writeHead(403); return res.end(); }
+    if (fs.existsSync(file) && fs.statSync(file).isDirectory()) file = path.join(file, "index.html");
+    if (!fs.existsSync(file)) { res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" }); return res.end("No encontrado"); }
+    res.writeHead(200, { "Content-Type": TIPOS[path.extname(file).toLowerCase()] || "application/octet-stream", "Cache-Control": "no-cache" });
+    fs.createReadStream(file).pipe(res);
+  });
+}
+
+function listen(server, port, label) {
+  server.on("error", (e) => fail(e.code === "EADDRINUSE" ? `El puerto ${port} está ocupado. Usa otro con -p` : e.message));
+  server.listen(port, () => console.log(`${naranja("Tangerine")} ${label} en ${negrita(`http://localhost:${port}`)} ${gris("(Ctrl+C para detener)")}`));
+}
+
+function cmdServe(dir, flags) {
+  const folder = dir || ".";
+  if (!fs.existsSync(folder)) fail(`No existe la carpeta ${folder}`);
+  listen(staticServer(folder), flags.puerto || 8000, `sirviendo ${folder}`);
+}
+
+function cmdDev(flags) {
+  const config = buildConfig(flags);
+  const clients = new Set();
+  const rebuild = () => {
+    try {
+      const r = buildToDisk(config, { dev: true });
+      console.log(`${verde("✓")} ${gris(new Date().toLocaleTimeString("es"))} construido (${r.modules.length} módulos)`);
+    } catch (err) {
+      console.error(rojo("error: ") + err.message);
+    }
+    for (const c of clients) c.write("data: recarga\n\n");
+  };
+  rebuild();
+  const outDir = path.dirname(path.resolve(config.root, config.out));
+  const server = staticServer(outDir, (req, res) => {
+    if (req.url !== "/__tangerine_recarga") return false;
+    res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" });
+    res.write(": conectado\n\n");
+    clients.add(res);
+    req.on("close", () => clients.delete(res));
+    return true;
+  });
+  let timer = null;
+  try {
+    fs.watch(config.root, { recursive: true }, (_e, name) => {
+      if (!name) return;
+      const full = path.resolve(config.root, name);
+      if (full.startsWith(outDir + path.sep) || full.includes(`${path.sep}node_modules${path.sep}`)) return;
+      if (!/\.(tng|css|js|json)$/.test(name)) return;
+      clearTimeout(timer);
+      timer = setTimeout(rebuild, 80);
+    });
+  } catch {
+    console.warn(gris("Aviso: este sistema no permite vigilar carpetas; reconstruye con tangerine build."));
+  }
+  listen(server, flags.puerto || 3000, "dev");
+}
+
+const ui = { naranja, rojo, gris, verde, negrita, fail };
+const { flags, rest } = parseArgs(process.argv.slice(2));
+if (flags.version) { console.log(VERSION); process.exit(0); }
+if (flags.ayuda) { console.log(AYUDA); process.exit(0); }
+
+const [cmd, ...args] = rest;
+switch (cmd) {
+  case undefined: cmdRepl(); break;
+  case "repl": cmdRepl(); break;
+  case "run": cmdRun(args[0], args.slice(1), flags); break;
+  case "check": cmdCheck(args); break;
+  case "new": await cmdNew(args[0], flags, ui); break;
+  case "install": case "instalar": await cmdInstall(args, flags, ui); break;
+  case "doctor": cmdDoctor(ui); break;
+  case "vscode": case "editor": cmdVscode(ui); break;
+  case "add": case "agregar": cmdAdd(args, flags, ui); break;
+  case "remove": case "quitar": cmdRemove(args, ui); break;
+  case "buscar": case "search": cmdBuscar(args, ui); break;
+  case "build": cmdBuild(flags); break;
+  case "dev": cmdDev(flags); break;
+  case "serve": cmdServe(args[0], flags); break;
+  case "help": case "ayuda": console.log(AYUDA); break;
+  default:
+    if (cmd.endsWith(".tng") || fs.existsSync(cmd)) cmdRun(cmd, args, flags);
+    else fail(`Comando desconocido: ${cmd}. Usa tangerine --ayuda`);
+}