Bloques (.lnb)

Un paquete de Bloques es una carpeta cuyo nombre termina en .lnb, tratada como un único elemento en el árbol (doble clic abre). Cada bloque es un archivo real en disco; el orden vive en un blocks.json en la raíz del paquete. Funciona como un cuaderno: celdas apiladas de código o texto. Un notebook de Jupyter entra por aquí: haz clic derecho en un .ipynb del árbol y elige Importar como Bloques (.lnb). Cada celda se convierte en un archivo real — versionable y leído por la búsqueda —, y el .ipynb se queda donde estaba, porque importar no es convertir. Las salidas guardadas en el notebook no vienen: ejecutar la celda aquí genera el resultado de verdad, con instante y comando. Si el blocks.json es ilegible (un conflicto de Git o una escritura interrumpida), el cuaderno avisa y no lo vuelve a escribir: el orden, la conexión y la sesión solo se vuelven a guardar después de que lo corrija.

Celdas, barra del cuaderno y atajos

Cada celda tiene nombre, botón de tipo (markdown, python, javascript, sql, shell, powershell, bat, r, julia, http, ia, mermaid, latex y los de texto) y botones para copiar, insertar (clic: abajo; la flechita: arriba y duplicar), borrar, mover arriba y abajo y ejecutar (la flechita ofrece Ejecutar hasta aquí). La celda nueva hereda el tipo de la vecina. El botón de la derecha pliega la celda, dejando solo la primera línea en la cabecera, y el contador [n] indica el orden en que las celdas se ejecutaron en esta sesión. Crea un cuaderno desde el árbol (Nuevo) o en Archivo → Nuevo.

La barra del cuaderno, arriba, actúa sobre todo el cuaderno: Ejecutar todo ejecuta las celdas de código en orden; Detener interrumpe la que está en marcha y vacía la cola (la ejecución va al historial con salida -1); Limpiar salidas cierra los paneles sin borrar nada; el menú Más exporta el cuaderno y borra el historial. La clave timeoutSec del blocks.json fija un tiempo límite por celda (0, el valor por defecto, es sin límite).

Atajos, con el foco en la celda: Ctrl+Enter ejecuta y se queda; Shift+Enter ejecuta y pasa a la siguiente (en la última, crea una nueva); Alt+Enter ejecuta e inserta una celda justo debajo. En una celda de texto, ejecutar es renderizar: se abre renderizada cuando tiene contenido, y un doble clic (o Enter sobre ella) vuelve a editar.

Resultado guardado, adjuntos e historial

El resultado queda guardado (como en un cuaderno de laboratorio): al terminar, cada ejecución se convierte en un archivo .md dentro de saida/<celda>/, en el propio paquete — con el instante, el código de salida, la duración, el comando y la salida en sí. Como es Markdown, se puede leer en cualquier editor, versionar en Git junto al cuaderno y recuperar por la búsqueda en las notas. Reabrir el paquete trae de vuelta la franja Última ejecución sobre el panel: haz clic en ella para ver el resultado sin volver a ejecutar.

Adjuntos: cada ejecución recibe una carpeta propia, junto al .md, y su ruta llega al programa en la variable de entorno LN_RUN_DIR. Lo que la celda escriba ahí — un gráfico de matplotlib, un CSV — aparece debajo de la salida (las imágenes dibujadas, el resto como enlace a la carpeta) y queda listado en el archivo del historial. La salida que ya es Markdown (la tabla de un SELECT, la respuesta de la IA, un diagrama) se abre renderizada; el botón Texto/Renderizar de la franja alterna.

Historial: el botón Historial junto a esa franja lista las ejecuciones anteriores de esa celda (instante y código de salida) — útil para comparar lo que la misma celda devolvió a lo largo del tiempo. Guardamos las 10 más recientes por celda; para cambiarlo, edita la clave historyLimit en el blocks.json del paquete (0 desactiva el guardado, y con él los adjuntos). Una salida muy grande se recorta (el archivo dice truncated: true). Renombrar la celda o cambiar su tipo se lleva el historial; borrar la celda envía el historial a la Papelera.

Sesión persistente

Por defecto cada celda es un proceso nuevo: lo que una define, la siguiente no lo ve. Con la sesión persistente activada (botón Sesión de la barra; la clave session del blocks.json), las celdas de Python, JavaScript, shell y PowerShell se ejecutan en un proceso que sigue vivo entre ejecuciones — variables, funciones e importaciones de una celda valen en las siguientes, como en Jupyter. En Python, las figuras de matplotlib abiertas al final de la celda se guardan solas en la carpeta de adjuntos. Reiniciar sesión lo olvida todo; Detener también, porque interrumpir es terminar el proceso. En JavaScript, declara con var (o sin declaración): let, const y class en el nivel superior no pueden declararse de nuevo — ni siquiera ejecutando la misma celda otra vez.

Celdas SQL

Sin conexión apuntada, la celda sql se ejecuta en el DuckDB del propio cuaderno (en memoria): las tablas creadas en una celda valen en las siguientes, y read_csv('datos/ventas.csv') lee los archivos de la carpeta del cuaderno — guarda los datos en una subcarpeta, porque cada archivo suelto en la carpeta del cuaderno es una celda. Para una base de datos de verdad, apunta el cuaderno a una conexión .lnc desde la barra de conexión (lista las conexiones del espacio de trabajo): las celdas pasan a ejecutarse en la base de datos, por la misma conexión del panel Conexiones — contraseña recordada, túnel SSH, relectura del .lnc y la confirmación de producción antes de cualquier escritura. El resultado de un SELECT se convierte en una tabla en el archivo de salida; INSERT/UPDATE y similares informan cuántas filas cambiaron, y un error interrumpe el script y registra la instrucción que falló. Traemos hasta 100 filas por consulta (sqlMaxRows en el blocks.json; el archivo avisa cuando hay más).

@set nombre = valor define una variable con ámbito de cuaderno, y :nombre (o ?) es un parámetro que se pregunta al ejecutar, como en el editor SQL. El último SELECT también escribe resultado.csv en la carpeta de adjuntos (las mismas filas de la tabla, hasta sqlMaxRows), y las celdas siguientes reciben la ruta en LN_LAST_SQL — en Python, pd.read_csv(os.environ["LN_LAST_SQL"]). La conexión queda en el blocks.json como ruta relativa; un .lnc guardado dentro del paquete cuenta como configuración, no se convierte en celda.

HTTP, IA, Mermaid y LaTeX

Cuatro tipos se ejecutan en el propio LightNote, sin intérprete: la celda http es una prueba .lnh ejecutada por el mismo ejecutor del probador de API (el informe va al historial; el entorno es el que indica la clave httpEnv del blocks.json, y un archivo que la solicitud envía debe estar dentro del espacio de trabajo); la celda ai envía el prompt al asistente predeterminado con el contexto del cuaderno — el código de las celdas anteriores y la última salida de cada una, menos las celdas http, que pueden llevar credenciales —, y la respuesta llega renderizada; las celdas mermaid y latex dibujan el diagrama o la fórmula en una imagen en los adjuntos. Detener cancela las dos primeras.

Exportar el cuaderno

El menú Más de la barra exporta el cuaderno entero: como Markdown (las celdas de texto en línea, el código en cercas con el lenguaje, la última salida justo debajo y las imágenes enlazadas) o como notebook de Jupyter (.ipynb, con la última salida de cada celda y las imágenes incrustadas; una celda de otro lenguaje lleva la marca que VS Code lee). Es una copia para compartir — el cuaderno sigue siendo la carpeta.