@rlabs-cl/arketum 0.0.0-stage → 1.0.0

package/catalogo-de-ejemplo/stacks/python.yaml

@@ -0,0 +1,167 @@
+# Stack: Python, con la biblioteca estándar y pytest.
+#
+# Un stack no es un arquetipo: no tiene niveles ni tipos propios. Dice dónde vive
+# cada tipo de pieza que declaran los componentes de las formas, las reglas del
+# oficio para quien construye y sus comandos (informativos). Arketum lo compone
+# con el componente de la variante de la forma del proyecto en un arquetipo
+# efectivo.
+#
+# Cambios:
+# - 1.1.0: un solo paquete con una subcarpeta por tipo y varios ficheros en
+#   cada una (`<paquete>/dominio/<nombre>.py`), como en Go; `pyproject.toml` en
+#   la raíz del artefacto; las plantillas y los estáticos de la interfaz;
+#   `conftest.py`, los ayudantes y los grupos anidados de `tests/`; los módulos
+#   sueltos del paquete, `py.typed` y `README.md`; las carpetas generadas.
+# - 1.2.0: las fijaciones (los suelos de `juego-terminal` y de
+#   `aplicacion-por-capas` y la ayuda e2e por terminal), sus comandos (`suelo`
+#   y `e2e`, que las invocan por ruta) y `arrancar.sh` como arranque, el
+#   contrato de arranque de las formas.
+# - 1.3.0: la ubicación `configura-pruebas` (`conftest.py`, `pytest.ini`,
+#   `setup.cfg`, `tox.ini`, `pyproject.toml`): lo que el cierre enseña cuando
+#   cambia, porque puede saltarse pruebas sin tocarlas. Antes lo sabía Arketum
+#   por el nombre; ahora lo dice el stack. TRANSICIÓN: la huella del stack y la
+#   del efectivo cambian; los descensos certificados con la anterior dan
+#   `stale_policy` hasta recertificarlos. Desde el catálogo oficial, con la
+#   versión nueva, la política fijada de una unidad viva no lo cuenta como cambio
+#   de política (lo vigila `stale_policy`); desde un catálogo de otra confianza,
+#   sí sale como cambio de la huella del stack. Un stack propio, o una copia de
+#   la 1.2.0, sin `configura-pruebas` deja de enseñar al cerrar los cambios a lo
+#   que configura las pruebas: `status` de una unidad lo avisa una vez.
+#   Y `noEjecutan`: los argumentos con que pytest no ejecuta ninguna prueba,
+#   que antes sabía Arketum.
+name: python
+version: 1.3.0
+description: >-
+  Python con la biblioteca estándar y pytest: un paquete por artefacto, con una subcarpeta por tipo de pieza (dominio, almacén, servicios, interfaz, API, clientes) y varios ficheros en cada una, `pyproject.toml` en la raíz del artefacto y las pruebas en `tests/<grupo>/`, unitarias y de extremo a extremo.
+
+# Rutas relativas a la raíz del artefacto. `<paquete>` casa con cualquier nombre
+# de carpeta: se usa como UN paquete, no una carpeta por tipo (Arketum no comprueba
+# que sea el mismo en todo el artefacto). Un tipo que vive en varios sitios lleva una
+# lista en `pattern`. Las exclusiones evitan que un grupo de pruebas que se llama
+# como un tipo (`tests/dominio/`) lo reclame ese tipo.
+ubicaciones:
+  # Los módulos sueltos del paquete (`config.py`, `errores.py`), su `__init__.py`
+  # y `py.typed`, el manifiesto y el README del artefacto. Un fichero suelto con
+  # el nombre de un tipo (`dominio.py`) no es un módulo: es código fusionado, y su
+  # sitio es la subcarpeta del tipo.
+  modulo:
+    pattern: ["<paquete>/<nombre>.py", "<paquete>/py.typed", "pyproject.toml", "README.md"]
+    excluding:
+      - "<paquete>/__main__.py"
+      - "<paquete>/dominio.py"
+      - "<paquete>/almacen.py"
+      - "<paquete>/servicios.py"
+      - "<paquete>/interfaz.py"
+      - "<paquete>/api.py"
+      - "<paquete>/clientes.py"
+      - "tests/<nombre>.py"
+      - "tests/py.typed"
+  dominio: { pattern: "<paquete>/dominio/<nombre>.py", excluding: ["tests/dominio/<nombre>.py"] }
+  almacen: { pattern: "<paquete>/almacen/<nombre>.py", excluding: ["tests/almacen/<nombre>.py"] }
+  servicio: { pattern: "<paquete>/servicios/<nombre>.py", excluding: ["tests/servicios/<nombre>.py"] }
+  interfaz:
+    pattern:
+      - "<paquete>/interfaz/<nombre>.py"
+      - "<paquete>/interfaz/plantillas/<nombre>.<ext>"
+      - "<paquete>/interfaz/plantillas/<carpeta>/<nombre>.<ext>"
+      - "<paquete>/interfaz/estaticos/<nombre>.<ext>"
+      - "<paquete>/interfaz/estaticos/<carpeta>/<nombre>.<ext>"
+    excluding:
+      - "tests/interfaz/<nombre>.py"
+      - "tests/interfaz/plantillas/<nombre>.<ext>"
+      - "tests/interfaz/plantillas/<carpeta>/<nombre>.<ext>"
+      - "tests/interfaz/estaticos/<nombre>.<ext>"
+      - "tests/interfaz/estaticos/<carpeta>/<nombre>.<ext>"
+  api: { pattern: "<paquete>/api/<nombre>.py", excluding: ["tests/api/<nombre>.py"] }
+  cliente: { pattern: "<paquete>/clientes/<nombre>.py", excluding: ["tests/clientes/<nombre>.py"] }
+  # `arrancar.sh` en la raíz del artefacto: el contrato de arranque de las formas (lo lanzan el suelo y la ayuda e2e).
+  arranque: { pattern: ["<paquete>/__main__.py", "arrancar.sh"], excluding: ["tests/__main__.py"] }
+  # Lo de `tests/`, hasta tres carpetas por debajo: pruebas, `conftest.py`,
+  # ayudantes (`helpers.py`, `fixtures.py`), `__init__.py`, grupos anidados y datos
+  # de prueba (`tests/datos/pedidos.json`). Un patrón por profundidad: un
+  # contenedor (`tests/`) clasificaría también las carpetas.
+  prueba:
+    pattern: ["tests/<nombre>.<ext>", "tests/<grupo>/<nombre>.<ext>", "tests/<grupo>/<carpeta>/<nombre>.<ext>", "tests/<grupo>/<carpeta>/<sub>/<nombre>.<ext>"]
+  # Lo que configura cómo se ejecutan las pruebas: no es un tipo de pieza (un
+  # `conftest.py` es también una prueba y `pyproject.toml` un módulo). El cierre
+  # lo enseña a la persona cuando cambia: puede saltarse pruebas sin tocarlas
+  # (de `pyproject.toml` y `setup.cfg` no se sabe si cambió su sección de pytest:
+  # salen siempre que cambian).
+  configura-pruebas:
+    pattern:
+      - pyproject.toml
+      - setup.cfg
+      - tox.ini
+      - pytest.ini
+      - conftest.py
+      - tests/conftest.py
+      - tests/<grupo>/conftest.py
+      - tests/<grupo>/<carpeta>/conftest.py
+      - tests/<grupo>/<carpeta>/<sub>/conftest.py
+
+# Cada muestra tiene que derivar exactamente su tipo: es la comprobación de solape.
+muestras:
+  modulo: [tienda/__init__.py, tienda/config.py, tienda/errores.py, tienda/py.typed, pyproject.toml, README.md]
+  dominio: [tienda/dominio/__init__.py, tienda/dominio/producto.py, tienda/dominio/pedido.py]
+  almacen: [tienda/almacen/__init__.py, tienda/almacen/repositorio.py]
+  servicio: [tienda/servicios/__init__.py, tienda/servicios/carrito.py, tienda/servicios/admin.py]
+  interfaz: [tienda/interfaz/__init__.py, tienda/interfaz/web.py, tienda/interfaz/plantillas/carrito.html, tienda/interfaz/plantillas/parciales/cabecera.html, tienda/interfaz/estaticos/estilo.css, tienda/interfaz/estaticos/css/estilo.css]
+  api: [tienda/api/__init__.py, tienda/api/rutas.py]
+  cliente: [tienda/clientes/__init__.py, tienda/clientes/pagos.py]
+  arranque: [tienda/__main__.py, arrancar.sh]
+  prueba:
+    - tests/conftest.py
+    - tests/__init__.py
+    - tests/helpers.py
+    - tests/test_humo.py
+    - tests/unidad/__init__.py
+    - tests/unidad/fixtures.py
+    - tests/unidad/test_carrito.py
+    - tests/unidad/dominio/test_pedido.py
+    - tests/dominio/test_pedido.py
+    - tests/interfaz/test_web.py
+    - tests/interfaz/plantillas/a.html
+    - tests/interfaz/estaticos/b.css
+    - tests/interfaz/estaticos/css/a.css
+    - tests/interfaz/plantillas/parciales/c.html
+    - tests/datos/pedidos.json
+    - tests/pedidos.json
+    - tests/e2e/conftest.py
+    - tests/e2e/test_compra.py
+  configura-pruebas: [pyproject.toml, pytest.ini, tox.ini, setup.cfg, tests/conftest.py, tests/e2e/conftest.py]
+
+# Lo que generan Python y pytest: no se reclama ni cuenta como cambio.
+generados: [__pycache__/, .pytest_cache/]
+
+oficio:
+  - Solo la biblioteca estándar; las pruebas con pytest. Una dependencia nueva se declara en `pyproject.toml` y se justifica.
+  - Un fichero por concepto dentro de la subcarpeta de su tipo (`dominio/pedido.py`, `servicios/carrito.py`); no se junta todo en uno.
+  - El dominio no lee ficheros, ni la terminal, ni el reloj ni la red; el instante entra como parámetro.
+  - Un fallo al leer lo guardado no se traga - se avisa y se para; nunca se sigue con vacío ni se sobrescribe.
+  - Las rutas a ficheros del propio código se resuelven desde `__file__`, nunca desde el directorio de trabajo.
+  - La carpeta de datos sale del entorno (`DATOS_DIR`), y las pruebas la ponen en una carpeta temporal.
+  - '`arrancar.sh` lanza el paquete con el intérprete del entorno (`exec python3 -m <paquete> "$@"`): es lo que lanzan el suelo y las pruebas e2e.'
+  - Las pruebas e2e (`tests/e2e/`) arrancan la aplicación con el lanzador `app` de la fijación e2e y la usan por la interfaz real, como una persona; nunca importan el paquete. Las fijaciones necesitan `pyte` y `pytest` (`python3 -m pip install -r arketum/fijaciones/e2e/requirements.txt`), que son de las pruebas, no del producto.
+
+# Fijas del catálogo: se copian tal cual en `arketum/fijaciones/<nombre>/` del
+# artefacto y no se editan (el cierre compara su checksum). Una por forma y cosa.
+fijaciones:
+  - { de: stacks/python/suelo-juego-terminal, nombre: suelo, para: suelo, formas: [juego-terminal] }
+  - { de: stacks/python/suelo-aplicacion-por-capas, nombre: suelo, para: suelo, formas: [aplicacion-por-capas] }
+  - { de: stacks/python/e2e-terminal, nombre: e2e, para: e2e, formas: [juego-terminal, aplicacion-por-capas] }
+
+# Los argumentos con los que su ejecutor de pruebas (pytest) no ejecuta ninguna: una
+# ejecución de la suite e2e con uno de ellos no cuenta como e2e.
+noEjecutan: [--co, --collect-only, --collectonly, --trace-config, --help, -h, --version, -V, --fixtures, --fixtures-per-test, --markers, --setup-plan, --setup-only]
+
+comandos:
+  pruebas: python3 -m pytest -q --ignore=tests/e2e
+  suelo: python3 -B arketum/fijaciones/suelo/suelo.py .
+  e2e: PYTHONPATH=arketum/fijaciones/e2e python3 -B -m pytest -q -c arketum/fijaciones/e2e/pytest.ini --rootdir=. tests/e2e
+
+
+selfReview:
+  criteria:
+    - check: Ninguna prueba depende de la red, del reloj de la máquina ni de una carpeta fuera de la temporal
+      how: Lee las fijaciones y las llamadas a `datetime.now`, `time.time` y `urllib` desde las pruebas.
+      evidence: medida

package/catalogo-de-ejemplo/stacks/typescript/e2e-node/app.mjs

@@ -0,0 +1,182 @@
+/**
+ * AYUDA E2E (fijación del catálogo de Arketum: se copia tal cual en
+ * `arketum/fijaciones/e2e/` y no se edita; el cierre compara su checksum).
+ *
+ * Arranca el artefacto por el camino real, con su contrato de arranque
+ * (`sh arrancar.sh` desde su raíz), con datos nuevos: `HOME` y `DATOS_DIR` en
+ * una carpeta temporal propia y `PUERTO` libre. Las pruebas de `src/e2e/`:
+ *
+ *   import { arrancar } from '../../arketum/fijaciones/e2e/app.mjs'
+ *   const app = await arrancar()               // sin esperar a nada
+ *   await app.servidor('/')                    // espera a que responda en PUERTO; devuelve la URL
+ *   const r = await fetch(`${app.url}/`)       // HTTP con el fetch de Node
+ *   app.escribir('q\n')                        // la entrada de la aplicación
+ *   await app.esperarSalida('Hasta luego')     // lo que escribe, hasta que aparezca
+ *   await app.cerrar()                         // y `app.reabrir()`, con los mismos datos
+ *
+ * Para un programa de terminal, `abrirTerminal` (más abajo) lo arranca en una
+ * terminal emulada.
+ *
+ * Una prueba e2e recorre lo que haría una persona por la interfaz real: nunca
+ * importa el código del artefacto ni llama a sus funciones por dentro. `arrancar`
+ * solo usa Node; `abrirTerminal` necesita `python3` con `pyte`.
+
+ */
+
+import { spawn } from 'node:child_process'
+import { mkdtempSync } from 'node:fs'
+import { createServer } from 'node:net'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const libre = () =>
+  new Promise((resolver, rechazar) => {
+    const s = createServer()
+    s.unref()
+    s.on('error', rechazar)
+    s.listen(0, '127.0.0.1', () => {
+      const { port } = s.address()
+      s.close(() => resolver(port))
+    })
+  })
+
+const esperar = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/**
+ * El artefacto en una terminal emulada (para un programa de terminal, como un
+ * juego): por el puente de Python de esta fijación, que necesita `python3` con
+ * `pyte`. Mismo arranque y mismas variables que `arrancar`.
+ *
+ *   const t = await abrirTerminal({ columnas: 80, filas: 24 })
+ *   await t.esperar(1); await t.tecla('ARRIBA'); const texto = await t.pantalla()
+ *   await t.tecla('q'); await t.esperar(1); expect(await t.vivo()).toBe(false)
+ *   await t.cerrar()
+ */
+export async function abrirTerminal(opciones = {}) {
+  const casa = opciones.casa ?? mkdtempSync(join(tmpdir(), 'e2e-'))
+  const puerto = opciones.puerto ?? (await libre())
+  const raiz = opciones.raiz ?? process.cwd()
+  const puente = join(dirname(fileURLToPath(import.meta.url)), 'terminal_puente.py')
+  const hijo = spawn('python3', ['-B', puente, String(opciones.columnas ?? 80), String(opciones.filas ?? 24)], {
+    cwd: raiz,
+    env: { ...process.env, HOME: casa, DATOS_DIR: join(casa, 'datos'), PUERTO: String(puerto) },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })
+  let resto = ''
+  let errores = ''
+  const esperando = []
+  hijo.stderr.on('data', (d) => (errores += d))
+  hijo.stdout.on('data', (d) => {
+    resto += d
+    let i
+    while ((i = resto.indexOf('\n')) >= 0) {
+      const linea = resto.slice(0, i)
+      resto = resto.slice(i + 1)
+      const r = JSON.parse(linea)
+      const espera = esperando.shift()
+      // Una orden que el puente no pudo cumplir es un error de la prueba, no una respuesta.
+      if (espera !== undefined) r.ok === false ? espera.rechazar(new Error(`el puente de terminal no pudo: ${r.error ?? JSON.stringify(r)}`)) : espera.resolver(r)
+    }
+  })
+  const fin = new Promise((r) => hijo.on('exit', r))
+  // Si el puente termina con órdenes sin contestar, son errores: la prueba no se queda esperando.
+  hijo.on('exit', () => {
+    for (const e of esperando.splice(0)) e.rechazar(new Error(`el puente de terminal terminó: ${errores}`))
+  })
+  const pedir = (orden) =>
+    new Promise((resolver, rechazar) => {
+      if (hijo.exitCode !== null) return rechazar(new Error(`el puente de terminal terminó: ${errores}`))
+      esperando.push({ resolver, rechazar })
+      hijo.stdin.write(`${JSON.stringify(orden)}\n`)
+    })
+  const estado = async () => pedir({ op: 'pantalla' })
+  return {
+    datos: join(casa, 'datos'),
+    tecla: async (k) => void (await pedir({ op: 'tecla', k })),
+    esperar: async (s) => void (await pedir({ op: 'esperar', s })),
+    pantalla: async () => (await estado()).pantalla,
+    vivo: async () => (await estado()).vivo,
+    codigo: async () => (await estado()).codigo,
+    async cerrar() {
+      if (hijo.exitCode === null) {
+        await pedir({ op: 'cerrar' }).catch(() => undefined)
+        await Promise.race([fin, esperar(3000)])
+      }
+    },
+  }
+}
+
+export async function arrancar(opciones = {}) {
+  const casa = opciones.casa ?? mkdtempSync(join(tmpdir(), 'e2e-'))
+  const puerto = opciones.puerto ?? (await libre())
+  const datos = join(casa, 'datos')
+  const raiz = opciones.raiz ?? process.cwd()
+  const hijo = spawn('sh', ['arrancar.sh'], {
+    cwd: raiz,
+    env: { ...process.env, HOME: casa, DATOS_DIR: datos, PUERTO: String(puerto) },
+    stdio: ['pipe', 'pipe', 'pipe'],
+    detached: true,
+  })
+  let salida = ''
+  hijo.stdout.on('data', (d) => (salida += d))
+  hijo.stderr.on('data', (d) => (salida += d))
+  let codigo = null
+  const termino = new Promise((r) => hijo.on('exit', (c) => r((codigo = c))))
+  const app = {
+    url: `http://127.0.0.1:${puerto}`,
+    puerto,
+    datos,
+    get codigo() {
+      return codigo
+    },
+    salida: () => salida,
+    vivo: () => codigo === null,
+    escribir: (texto) => hijo.stdin.write(texto),
+    async esperarSalida(texto, ms = 10000) {
+      const fin = Date.now() + ms
+      while (Date.now() < fin) {
+        if (salida.includes(texto)) return salida
+        if (codigo !== null) break
+        await esperar(50)
+      }
+      throw new Error(`no apareció «${texto}» en la salida de \`sh arrancar.sh\`:\n${salida}`)
+    },
+    async servidor(ruta = '/', ms = 25000) {
+      const fin = Date.now() + ms
+      while (Date.now() < fin) {
+        if (codigo !== null) throw new Error(`\`sh arrancar.sh\` terminó con código ${codigo} antes de responder en ${app.url}:\n${salida}`)
+        try {
+          await fetch(`${app.url}${ruta}`)
+          return app.url
+        } catch {
+          await esperar(200)
+        }
+      }
+      throw new Error(`\`sh arrancar.sh\` no respondió en ${app.url}${ruta}`)
+    },
+    async cerrar() {
+      if (codigo === null) {
+        try {
+          process.kill(-hijo.pid, 'SIGTERM')
+        } catch {}
+        await Promise.race([termino, esperar(5000)])
+        if (codigo === null) {
+          try {
+            process.kill(-hijo.pid, 'SIGKILL')
+          } catch {}
+        }
+      }
+      return codigo
+    },
+    async esperarFin(ms = 5000) {
+      await Promise.race([termino, esperar(ms)])
+      return codigo
+    },
+    async reabrir() {
+      await app.cerrar()
+      return arrancar({ ...opciones, casa, puerto })
+    },
+  }
+  return app
+}

package/catalogo-de-ejemplo/stacks/typescript/e2e-node/requirements.txt

@@ -0,0 +1 @@
+pyte

package/catalogo-de-ejemplo/stacks/typescript/e2e-node/terminal_prueba.py

@@ -0,0 +1,118 @@
+"""
+TERMINAL DE PRUEBA (fijación del catálogo de Arketum: se copia tal cual y no se
+edita). Prueba un programa de terminal como lo usaría una persona, en una
+pseudo-terminal emulada con pyte (`python3 -m pip install pyte`).
+
+    from terminal_prueba import Terminal
+
+    with Terminal(['sh', 'arrancar.sh'], cwd='.', columnas=80, filas=24) as t:
+        t.esperar(2)                 # deja correr el programa
+        t.tecla('ARRIBA')            # ARRIBA, ABAJO, IZQUIERDA, DERECHA, ENTER, ESC o un carácter
+        t.esperar(0.5)
+        texto = t.pantalla()         # lo que se ve, una cadena con una línea por fila
+        assert t.vivo()              # sigue corriendo
+        assert 'Traceback' not in texto
+
+`t.lineas()` da la lista de filas y `t.codigo` el código de salida cuando termina.
+"""
+
+import fcntl, os, pty, select, signal, struct, termios, time
+
+import pyte
+
+TECLAS = {'ARRIBA': b'\x1b[A', 'ABAJO': b'\x1b[B', 'DERECHA': b'\x1b[C', 'IZQUIERDA': b'\x1b[D', 'ENTER': b'\r', 'ESC': b'\x1b'}
+
+
+class Terminal:
+    def __init__(self, comando, cwd='.', columnas=80, filas=24, env=None):
+        self._pantalla = pyte.Screen(columnas, filas)
+        self._flujo = pyte.ByteStream(self._pantalla)
+        pid, fd = pty.fork()
+        if pid == 0:
+            entorno = dict(os.environ, LANG='en_US.UTF-8', LC_ALL='en_US.UTF-8', TERM='xterm-256color', COLUMNS=str(columnas), LINES=str(filas))
+            entorno.update(env or {})
+            os.chdir(cwd)
+            os.execvpe(comando[0], comando, entorno)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack('HHHH', filas, columnas, 0, 0))
+        self.pid, self.fd, self._vivo, self.codigo = pid, fd, True, None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.cerrar()
+
+    def esperar(self, segundos):
+        fin = time.time() + segundos
+        while time.time() < fin:
+            r, _, _ = select.select([self.fd], [], [], 0.05)
+            if r:
+                try:
+                    datos = os.read(self.fd, 65536)
+                except OSError:
+                    datos = b''
+                if datos:
+                    self._flujo.feed(datos)
+                else:
+                    time.sleep(0.05)
+            self._comprobar()
+        self._comprobar()
+
+    def tecla(self, nombre):
+        datos = TECLAS.get(nombre, nombre.encode() if isinstance(nombre, str) else nombre)
+        # Como un terminal real: si el programa activó el modo de cursor de aplicación (DECCKM, el modo privado 1, que pyte guarda como 1 << 5; curses
+        # con keypad), las flechas van como ESC O x en vez de ESC [ x.
+        if datos[:2] == b'\x1b[' and len(datos) == 3 and datos[2:] in b'ABCD' and (1 << 5) in self._pantalla.mode:
+            datos = b'\x1bO' + datos[2:]
+        try:
+            os.write(self.fd, datos)
+        except OSError:
+            pass
+
+    def pantalla(self):
+        return '\n'.join(self._pantalla.display)
+
+    def lineas(self):
+        return list(self._pantalla.display)
+
+    def pintadas(self):
+        """Cuántas celdas se ven: con carácter, en vídeo inverso o con un fondo distinto del
+        dominante (al borrar, pyte rellena con el fondo del cursor: ese no cuenta)."""
+        from collections import Counter
+        filas, cols = self._pantalla.lines, self._pantalla.columns
+        celdas = [self._pantalla.buffer[y][x] for y in range(filas) for x in range(cols)]
+        fondo = Counter(c.bg for c in celdas).most_common(1)[0][0]
+        return sum(1 for c in celdas if c.data.strip() or c.reverse or c.bg != fondo)
+
+    def foto(self):
+        """Lo que se ve, con forma: el texto y dónde hay celdas en vídeo inverso o con fondo distinto del dominante."""
+        from collections import Counter
+        filas, cols = self._pantalla.lines, self._pantalla.columns
+        fondo = Counter(self._pantalla.buffer[y][x].bg for y in range(filas) for x in range(cols)).most_common(1)[0][0]
+        marcas = tuple((y, x) for y in range(filas) for x in range(cols) if self._pantalla.buffer[y][x].reverse or self._pantalla.buffer[y][x].bg != fondo)
+        return (self.pantalla(), marcas)
+
+    def vivo(self):
+        self._comprobar()
+        return self._vivo
+
+    def _comprobar(self):
+        if not self._vivo:
+            return
+        p, estado = os.waitpid(self.pid, os.WNOHANG)
+        if p != 0:
+            self._vivo = False
+            self.codigo = os.waitstatus_to_exitcode(estado)
+
+    def cerrar(self):
+        if self._vivo:
+            try:
+                os.kill(self.pid, signal.SIGKILL)
+                os.waitpid(self.pid, 0)
+            except OSError:
+                pass
+            self._vivo = False
+        try:
+            os.close(self.fd)
+        except OSError:
+            pass

package/catalogo-de-ejemplo/stacks/typescript/e2e-node/terminal_puente.py

@@ -0,0 +1,51 @@
+"""
+PUENTE DE TERMINAL (fijación del catálogo de Arketum: no se edita). Lo lanza
+`app.mjs` (`abrirTerminal`): arranca el artefacto con `sh arrancar.sh` en una
+terminal emulada (`terminal_prueba`, con pyte) y obedece órdenes en JSON, una
+por línea, por su entrada; contesta una línea JSON por orden:
+
+  {"op": "tecla", "k": "ARRIBA"}   →  {"ok": true}
+  {"op": "esperar", "s": 0.5}      →  {"ok": true}
+  {"op": "pantalla"}               →  {"ok": true, "pantalla": "...", "vivo": true, "codigo": null}
+  {"op": "cerrar"}                 →  {"ok": true, "codigo": ...}
+
+Uso: python3 -B terminal_puente.py <columnas> <filas>  (desde la raíz del artefacto)
+"""
+
+import json, os, sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from terminal_prueba import Terminal  # noqa: E402
+
+
+def main():
+    columnas, filas = int(sys.argv[1]), int(sys.argv[2])
+    t = Terminal(['sh', 'arrancar.sh'], cwd=os.getcwd(), columnas=columnas, filas=filas)
+    try:
+        for linea in sys.stdin:
+            orden = json.loads(linea)
+            op = orden.get('op')
+            if op == 'tecla':
+                t.tecla(orden['k'])
+                r = {'ok': True}
+            elif op == 'esperar':
+                t.esperar(float(orden.get('s', 0.1)))
+                r = {'ok': True}
+            elif op == 'pantalla':
+                vivo = t.vivo()
+                r = {'ok': True, 'pantalla': t.pantalla(), 'vivo': vivo, 'codigo': t.codigo}
+            elif op == 'cerrar':
+                t.cerrar()
+                r = {'ok': True, 'codigo': t.codigo}
+            else:
+                r = {'ok': False, 'error': f'orden desconocida: {op}'}
+            sys.stdout.write(json.dumps(r) + '\n')
+            sys.stdout.flush()
+            if op == 'cerrar':
+                break
+    finally:
+        t.cerrar()
+
+
+if __name__ == '__main__':
+    main()

package/catalogo-de-ejemplo/stacks/typescript/e2e-node/vitest.config.mjs

@@ -0,0 +1,12 @@
+// Fijación del catálogo de Arketum: no se edita. La suite e2e se corre desde la
+// raíz del artefacto con:
+//   npx vitest run --config arketum/fijaciones/e2e/vitest.config.mjs
+// Solo las pruebas de `src/e2e/`, que arrancan el artefacto con `app.mjs`.
+export default {
+  root: process.cwd(),
+  test: {
+    include: ['src/e2e/**/*.test.ts'],
+    testTimeout: 60000,
+    hookTimeout: 60000,
+  },
+}

package/catalogo-de-ejemplo/stacks/typescript/suelo-aplicacion-por-capas/requirements.txt

@@ -0,0 +1 @@
+pyte

package/catalogo-de-ejemplo/stacks/typescript/suelo-aplicacion-por-capas/suelo.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+SUELO FIJO de la forma `aplicacion-por-capas` (fijación del catálogo de Arketum:
+se copia tal cual en `arketum/fijaciones/suelo/` y no se edita; el cierre compara
+su checksum). Las comprobaciones de uso que no escribe quien construye: que la
+aplicación vive, se puede usar y cerrar, y vuelve a arrancar con sus datos; no
+que haga bien lo que pide el encargo.
+
+Arranca el artefacto por su contrato de arranque: `sh arrancar.sh` desde su raíz,
+en una terminal, con `DATOS_DIR` (la carpeta de sus datos), `HOME` y `PUERTO` (un
+puerto libre, por si sirve HTTP) en una carpeta temporal propia.
+
+  arranca    a 80x24, a los 3 s pinta algo y sin traza (vivo, o esperando órdenes)
+  responde   tras Enter y unas flechas sigue sin traza
+  sale       termina limpio (código 0) con `q`, con la orden `salir`/`q`/`exit` + Enter, con la opción de salir del menú, o con fin de entrada
+  rearranca  con los mismos datos (mismo HOME y DATOS_DIR) vuelve a arrancar sin traza
+
+Uso: python3 arketum/fijaciones/suelo/suelo.py <raíz del artefacto>  →  JSON; código 0 si pasa, 1 si no.
+Necesita `pyte` (`python3 -m pip install -r arketum/fijaciones/suelo/requirements.txt`).
+"""
+
+import faulthandler, json, os, re, socket, sys, tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from terminal_prueba import Terminal  # noqa: E402
+
+ARRANQUE = ['sh', 'arrancar.sh']
+SALIDAS = [b'q', b'\r', b'salir\r', b'q\r', b'exit\r']
+# Una opción de menú para salir, la que se vea en pantalla: «5. Salir», «[0] Exit»…
+OPCION_DE_SALIR = re.compile(r'[\[(]?\s*(\w)\s*[\])\.:-]\s*(?:salir|exit|quit|terminar|cerrar)\b', re.I)
+
+
+def libre():
+    with socket.socket() as s:
+        s.bind(('127.0.0.1', 0))
+        return s.getsockname()[1]
+
+
+def pintadas(t):
+    n = 0
+    for _ in range(5):
+        t.esperar(0.15)
+        n = max(n, t.pintadas())
+    return n
+
+
+def evaluar(raiz):
+    if not os.path.isfile(os.path.join(raiz, 'arrancar.sh')):
+        return {'ok': False, 'fallo': 'no hay `arrancar.sh` en la raíz del artefacto: es su contrato de arranque', 'pantalla': ''}
+    r = {'comando': ' '.join(ARRANQUE)}
+    casa = tempfile.mkdtemp(prefix='suelo-')
+    env = {'HOME': casa, 'DATOS_DIR': os.path.join(casa, 'datos'), 'PUERTO': str(libre())}
+    with Terminal(ARRANQUE, cwd=raiz, columnas=80, filas=24, env=env) as t:
+        t.esperar(3)
+        n = pintadas(t)
+        texto = t.pantalla()
+        r['arranca'] = 'Traceback' not in texto and n >= 10 and (t.vivo() or t.codigo == 0)
+        if not r['arranca'] or not t.vivo():
+            return {**r, 'ok': False, 'fallo': 'a 80x24 no arranca: muere, saca una traza o no pinta nada', 'pantalla': texto}
+        t.tecla('ENTER')
+        for k in ('ABAJO', 'ARRIBA'):
+            t.tecla(k)
+            t.esperar(0.3)
+        t.esperar(1)
+        texto = t.pantalla()
+        r['responde'] = 'Traceback' not in texto and (t.vivo() or t.codigo == 0)
+        if not r['responde']:
+            return {**r, 'ok': False, 'fallo': 'tras Enter y unas flechas saca una traza o muere con error', 'pantalla': texto}
+        for b in SALIDAS:
+            if not t.vivo():
+                break
+            t.tecla(b)
+            t.esperar(1.5)
+        for _ in range(2):  # la opción de salir del menú que se vea, y como último recurso, fin de entrada
+            m = OPCION_DE_SALIR.search(t.pantalla())
+            if not t.vivo() or m is None:
+                break
+            t.tecla(f'{m.group(1)}\r')
+            t.esperar(1.5)
+        if t.vivo():
+            t.tecla(b'\x04')
+            t.esperar(1.5)
+        texto = t.pantalla()
+        r['sale'] = not t.vivo() and t.codigo == 0 and 'Traceback' not in texto
+        if not r['sale']:
+            return {**r, 'ok': False, 'fallo': 'no termina limpio con `q`, ni con `salir`/`q`/`exit` + Enter, ni con fin de entrada' if t.vivo() else 'al salir saca una traza o termina con error', 'pantalla': texto}
+    env['PUERTO'] = str(libre())
+    with Terminal(ARRANQUE, cwd=raiz, columnas=80, filas=24, env=env) as t:
+        t.esperar(3)
+        texto = t.pantalla()
+        r['rearranca'] = 'Traceback' not in texto and (t.vivo() or t.codigo == 0)
+        if not r['rearranca']:
+            return {**r, 'ok': False, 'fallo': 'con los datos de la primera vez, al volver a abrir saca una traza o muere', 'pantalla': texto}
+    return {**r, 'ok': True}
+
+
+if __name__ == '__main__':
+    # Un suelo nunca se queda colgado: a los 150 s escribe dónde estaba y termina con error (1).
+    faulthandler.dump_traceback_later(150, exit=True)
+    resultado = evaluar(os.path.abspath(sys.argv[1] if len(sys.argv) > 1 else '.'))
+    print(json.dumps(resultado, ensure_ascii=False, indent=1))
+    sys.exit(0 if resultado['ok'] else 1)