@nucleoabierto/teleprompter 0.1.1 → 0.2.0

package/manual/guia-de-uso.md

@@ -5,11 +5,11 @@ Cómo instalar un paquete Teleprompter en un repositorio, paso a paso.
 ## Requisitos
 
 - Node.js 22 o superior.
-- Un paquete: un directorio con un manifiesto `teleprompter.json` en su
-  raíz. Este repositorio incluye uno de referencia en
-  `packages/ciclo-tareas/`.
+- Un paquete: un repositorio público de GitHub o un directorio con un
+  manifiesto `teleprompter.json` en su raíz. Este repositorio incluye
+  uno de referencia en `packages/ciclo-tareas/`.
 - El directorio del repositorio destino donde se instalarán los
-  recursos.
+  recursos —por defecto, el directorio de trabajo.
 
 ## Instalar un paquete
 
@@ -17,7 +17,18 @@ Desde la raíz del repositorio destino —o dando su ruta como segundo
 argumento—:
 
 ```sh
-npx @nucleoabierto/teleprompter install /ruta/al/paquete .
+npx @nucleoabierto/teleprompter nucleoabierto/ciclo-tareas .
+```
+
+`user/repo` descarga el tarball público del repositorio de GitHub y
+usa su raíz como paquete —el `name` del manifiesto debe coincidir con
+el nombre del repositorio, como exige la especificación—;
+`user/repo@v1.0.0` o `--ref v1.0.0` eligen
+la referencia (rama, tag o commit), y sin indicación se usa la rama
+por defecto. Para un paquete en disco se usa `--path`:
+
+```sh
+npx @nucleoabierto/teleprompter --path /ruta/al/paquete .
 ```
 
 El instalador trabaja en cuatro fases: verificación, plan, ejecución y
@@ -28,6 +39,7 @@ registro. Las dos primeras no escriben nada.
    aborta antes de tocar el disco. Si todo va bien, verás:
 
 ```text
+obteniendo: nucleoabierto/ciclo-tareas
 verificado: ciclo-tareas@1.0.0
 ```
 
@@ -60,6 +72,9 @@ resultado:
  create         .agents/skills/crear-tareas/
  create         .agents/skills/ejecutar-tareas/
  create         .agents/skills/commit/
+personalización (.teleprompter/ciclo-tareas/PERSONALIZE.md):
+# Personalización de ciclo-tareas
+…
 instalado: ciclo-tareas@1.0.0
 ```
 
@@ -67,13 +82,76 @@ instalado: ciclo-tareas@1.0.0
    repositorio: es lo que permite a Teleprompter distinguir lo que él
    instaló de lo que ya existía.
 
+   Si el paquete declara instrucciones de personalización, su
+   contenido se entrega tal cual al final del resultado —el bloque
+   `personalización` anterior— y queda copiado en
+   `.teleprompter/<paquete>/` dentro del destino.
+
+## Consultar la guía de personalización
+
+Las instrucciones que la instalación entregó se releen después con
+`guide`, ejecutado desde la raíz del repositorio destino:
+
+```sh
+npx @nucleoabierto/teleprompter guide
+npx @nucleoabierto/teleprompter guide ciclo-tareas   # solo ese paquete
+```
+
+Muestra el mismo contenido del archivo materializado —no reinstala ni
+descarga nada—. Véase la [referencia de `guide`](referencia-guide.md).
+
+## Listar los paquetes instalados
+
+Desde la raíz del repositorio destino, `list` muestra qué paquetes
+instaló Teleprompter —nombre, versión, fecha y recursos escritos—
+leyendo el registro:
+
+```sh
+npx @nucleoabierto/teleprompter list
+```
+
+Véase la [referencia de `list`](referencia-list.md).
+
+## Verificar el estado de los recursos instalados
+
+Desde la raíz del repositorio destino, `check` confronta el registro
+con el disco y muestra por cada recurso instalado si sigue `intacto`,
+fue `modificado`, está `ausente` o es `no verificable`:
+
+```sh
+npx @nucleoabierto/teleprompter check
+```
+
+Véase la [referencia de `check`](referencia-check.md).
+
+## Actualizar un paquete
+
+Desde la raíz del repositorio destino, `update` lleva un paquete
+instalado a la versión que publica su origen —el registrado al
+instalarlo, salvo que se indique otro—:
+
+```sh
+npx @nucleoabierto/teleprompter update ciclo-tareas
+npx @nucleoabierto/teleprompter update ciclo-tareas --ref v2.0.0
+npx @nucleoabierto/teleprompter update ciclo-tareas otra/repo@main
+```
+
+El plan de actualización decide recurso a recurso: lo intacto que la
+versión cambió se sobrescribe (`update`), lo nuevo se crea, lo que la
+versión ya no trae se retira si sigue intacto (`retire`), y las
+ediciones locales se resuelven como las colisiones de `install` —
+interactiva, `--force`, `--skip` o aborto sin consola—. Si la versión
+ya es la registrada, responde que ya está en esa versión.
+
+Véase la [referencia de `update`](referencia-update.md).
+
 ## Inspeccionar sin instalar
 
 `--dry-run` ejecuta solo la verificación y el plan, y termina sin
 escribir ni registrar nada:
 
 ```sh
-npx @nucleoabierto/teleprompter install /ruta/al/paquete . --dry-run
+npx @nucleoabierto/teleprompter nucleoabierto/ciclo-tareas . --dry-run
 ```
 
 Es la forma de ver qué haría una instalación —incluidas las colisiones

package/manual/index.md

@@ -15,8 +15,24 @@ colisiones con lo que ya existe y registra la instalación en
 - [Referencia de `install`](referencia-install.md) — la operación
   completa: fases, marcas del plan, resolución de colisiones, registro
   y códigos de salida.
+- [Referencia de `guide`](referencia-guide.md) — consultar las
+  instrucciones de personalización de los paquetes instalados.
+- [Referencia de `list`](referencia-list.md) — listar los paquetes
+  instalados con su versión, fecha y recursos.
+- [Referencia de `check`](referencia-check.md) — verificar el estado
+  de los recursos instalados.
+- [Referencia de `update`](referencia-update.md) — actualizar un
+  paquete instalado a la versión que publica su origen.
 - [Instalar un paquete](001-instalar-un-paquete.md) — la funcionalidad
   y los escenarios que la suite de pruebas verifica.
+- [Listar los paquetes instalados](002-listar-paquetes-instalados.md)
+  — la consulta del registro y los escenarios que la suite verifica.
+- [Verificar el estado de los recursos instalados](003-verificar-recursos-instalados.md)
+  — la verificación de la instalación y los escenarios que la suite
+  verifica.
+- [Actualizar un paquete](004-actualizar-un-paquete.md) — la
+  actualización consciente de la deriva y los escenarios que la
+  suite verifica.
 
 ## En el repositorio
 

package/manual/referencia-check.md

@@ -0,0 +1,47 @@
+# Referencia de `check`
+
+```text
+teleprompter check
+```
+
+Verifica el estado de los recursos que Teleprompter instaló en el
+repositorio destino. Se ejecuta desde la raíz del destino —no acepta
+argumentos ni opciones— y contrasta `teleprompter-lock.json` con lo
+que el disco contiene: no reinstala ni vuelve a descargar nada.
+
+Por cada paquete instalado muestra su `nombre@version` y una línea
+por recurso registrado con una marca de estado:
+
+```text
+estado de los recursos:
+  ciclo-tareas@1.0.0
+    intacto         .agents/skills/crear-tareas/SKILL.md
+    modificado      .agents/skills/ejecutar-tareas/SKILL.md
+    ausente         .agents/skills/commit/SKILL.md
+    no verificable  .teleprompter/ciclo-tareas/PERSONALIZE.md
+```
+
+- `intacto` — el recurso sigue conteniendo lo que la instalación
+  escribió.
+- `modificado` — el recurso existe pero su contenido difiere de lo
+  registrado.
+- `ausente` — la ruta registrada ya no existe en el destino.
+- `no verificable` — el registro no guardó una referencia con la que
+  comparar, el recurso no se puede leer, o la ruta registrada no es
+  segura —sale del destino por un `..` o un enlace—.
+
+Los recursos que la instalación omitió por colisión no se verifican
+—la herramienta no escribió nada ahí— y el informe no muestra hashes
+ni acciones internas. Encontrar deriva no es un fallo: el informe
+termina con código `0` haya o no recursos modificados o ausentes.
+
+Sin instalaciones registradas responde `no hay paquetes
+instalados`: es una respuesta, no un fallo. Un registro ilegible o
+corrupto añade un `aviso:` y responde lo mismo —como el resto de
+lecturas del lock, la corrupción degrada a «sin historia»—.
+
+## Errores
+
+| Situación                               | Código |
+|-----------------------------------------|--------|
+| Argumentos u opciones de cualquier tipo | `4`    |

package/manual/referencia-guide.md

@@ -0,0 +1,33 @@
+# Referencia de `guide`
+
+```text
+teleprompter guide [<paquete>]
+```
+
+Muestra las instrucciones de personalización que los paquetes
+instalados declararon. Se ejecuta desde la raíz del repositorio
+destino —no acepta un argumento de destino ni ninguna opción de
+instalación— y lee el archivo que la instalación materializó en
+`.teleprompter/<paquete>/<archivo>`: no reinstala ni vuelve a
+descargar nada.
+
+- Sin `<paquete>`: muestra la guía de cada paquete instalado que la
+  declara, un bloque por paquete.
+- Con `<paquete>`: muestra solo la de ese paquete.
+
+La salida es el mismo bloque que la instalación entregó al final de
+su resultado —`personalización (<ruta>):` seguido del contenido del
+archivo tal cual, que es texto libre del mantenedor: nunca se valida
+ni se ejecuta—. La ruta que cada bloque muestra es la registrada en
+`teleprompter-lock.json` bajo `personalization`.
+
+## Errores
+
+| Situación                                                   | Código |
+|-------------------------------------------------------------|--------|
+| Ningún paquete instalado declara guía, o no hay instalaciones | `4`    |
+| `<paquete>` no está instalado en el directorio de trabajo   | `4`    |
+| `<paquete>` está instalado pero no declaró guía             | `4`    |
+| Argumentos de más u opciones de instalación                 | `4`    |
+| El archivo registrado no existe o no se puede leer          | `3`    |
+| La ruta registrada escapa del destino (`..` o enlaces)      | `3`    |

package/manual/referencia-install.md

@@ -1,11 +1,32 @@
 # Referencia de `install`
 
 ```text
-teleprompter install <paquete> <destino> [--force|--skip] [--dry-run]
+teleprompter [install] <user/repo[@ref]> [destino] [--ref <ref>]
+teleprompter [install] --path <paquete> [destino]
+
+Opciones comunes: [--force|--skip] [--dry-run]
 ```
 
-Instala el paquete del directorio `<paquete>` en el repositorio cuya
-raíz es `<destino>`. Ambos argumentos deben ser directorios existentes.
+Instala un paquete en el repositorio cuya raíz es `destino` —por
+defecto, el directorio de trabajo—. `install` es un alias opcional de
+la forma corta.
+
+## El origen
+
+- `<user/repo>`: descarga el tarball público del repositorio de
+  GitHub por HTTP —sin git ni credenciales—, lo extrae en un
+  directorio temporal y usa la raíz del árbol como paquete. El
+  temporal se elimina al terminar, también en error y en `--dry-run`.
+  La referencia se elige con `@ref` o `--ref` —declarar ambas es un
+  error de invocación—; sin indicación se descarga la rama por
+  defecto. Un repositorio inaccesible o una referencia inexistente
+  abortan con código `5`.
+- `--path <paquete>`: usa el directorio local como origen y el
+  argumento posicional `user/repo` no se procesa —de declararse, se
+  interpreta como `destino`.
+
+`destino` y el directorio de `--path` deben ser directorios
+existentes.
 
 ## Fases
 
@@ -86,7 +107,8 @@ destino: un JSON pensado para versionarse con el repositorio:
           "action": "create",
           "sha256": "…"
         }
-      ]
+      ],
+      "origin": { "type": "github", "repo": "nucleoabierto/ciclo-tareas" }
     }
   }
 }
@@ -95,7 +117,11 @@ destino: un JSON pensado para versionarse con el repositorio:
 `packages` se indexa por el `name` del manifiesto y cada entrada
 contiene `version`, `installedAt` y `files`: una entrada por recurso
 con su `target`, la acción realizada (`create`, `overwrite`, `skip`) y
-el SHA-256 del contenido escrito —las entradas `skip` no llevan hash.
+el SHA-256 del contenido escrito —las entradas `skip` no llevan hash—.
+La entrada registra además el `origin` de la instalación: el
+repositorio `owner/name` con el ref usado —o sin él, si se obtuvo la
+rama por defecto— o la ruta absoluta de `--path`; los registros
+escritos antes de este campo carecen de él.
 Los registros de otros paquetes instalados en el mismo destino se
 conservan. Un registro ausente no bloquea la operación: se ignora en
 silencio y se trata como si no hubiera instalaciones previas; un
@@ -104,10 +130,19 @@ un aviso.
 
 ## Personalización
 
-Si el manifiesto declara `personalization`, la salida final informa de
-la ubicación de las instrucciones dentro del paquete. La instalación
-las entrega y presenta; no decide su contenido ni las instala salvo que
-también figuren en `install`.
+Si el manifiesto declara `personalization`, el instalador copia el
+archivo de instrucciones a `.teleprompter/<paquete>/<archivo>` dentro
+del destino —un espacio gestionado por la herramienta, igual que el
+registro—, recuerda su ubicación en `teleprompter-lock.json` y entrega
+su contenido tal cual al final del resultado, bajo el encabezado
+`personalización (<ruta>):`. El contenido es texto libre del
+mantenedor: nunca se valida ni se ejecuta. Ningún `target` de
+`install` ni ninguna ruta de `requires` puede apuntar dentro de
+`.teleprompter/`.
+
+El mismo contenido se consulta después con
+[`teleprompter guide`](referencia-guide.md), ejecutado dentro del
+repositorio destino.
 
 ## Códigos de salida
 
@@ -118,3 +153,4 @@ también figuren en `install`.
 | `2`    | Plan no ejecutable: precondiciones incumplidas o colisiones     |
 | `3`    | Error de ejecución (informa de lo ya aplicado antes de fallar)  |
 | `4`    | Error de invocación: argumentos ausentes o rutas que no existen |
+| `5`    | Error de obtención: repositorio inaccesible, referencia inexistente o archivo corrupto |

package/manual/referencia-list.md

@@ -0,0 +1,42 @@
+# Referencia de `list`
+
+```text
+teleprompter list
+```
+
+Muestra los paquetes instalados en el repositorio destino. Se
+ejecuta desde la raíz del destino —no acepta argumentos ni
+opciones— y lee `teleprompter-lock.json`: no reinstala ni vuelve a
+descargar nada.
+
+Por cada paquete instalado muestra una entrada con su
+`nombre@version`, el instante en que se instaló y una línea por
+recurso que la instalación escribió:
+
+```text
+paquetes instalados:
+  ciclo-tareas@1.0.0 — instalado 2026-09-28T10:00:00.000Z
+    guía: teleprompter guide ciclo-tareas
+    .agents/skills/crear-tareas/SKILL.md
+    .agents/skills/ejecutar-tareas/SKILL.md
+    .agents/skills/commit/SKILL.md
+    .teleprompter/ciclo-tareas/PERSONALIZE.md
+```
+
+La línea `guía:` solo aparece cuando el paquete declaró
+instrucciones de personalización, consultables con
+[`guide`](referencia-guide.md). Los recursos que la instalación
+omitió por colisión no se listan —el registro anota la decisión,
+pero la herramienta no escribió nada ahí— y tampoco se muestran los
+hashes ni las acciones internas del registro.
+
+Sin instalaciones registradas responde `no hay paquetes
+instalados`: es una respuesta, no un fallo. Un registro ilegible o
+corrupto añade un `aviso:` y responde lo mismo —como el resto de
+lecturas del lock, la corrupción degrada a «sin historia»—.
+
+## Errores
+
+| Situación                               | Código |
+|-----------------------------------------|--------|
+| Argumentos u opciones de cualquier tipo | `4`    |

package/manual/referencia-update.md

@@ -0,0 +1,49 @@
+# Referencia de `update`
+
+```text
+teleprompter update <paquete> [<user/repo[@ref]>] [--ref <ref>]
+teleprompter update <paquete> --path <paquete>
+teleprompter update <paquete> [--force | --skip] [--dry-run]
+```
+
+Lleva un paquete instalado a la versión que publica su origen. Se
+ejecuta desde la raíz del repositorio destino —no acepta destino— y
+nombra el paquete por su `name` en `teleprompter-lock.json`.
+
+## El origen
+
+- Sin indicación, reobtiene el paquete desde el origen que la
+  instalación registró: el repositorio con su `ref` —o la rama por
+  defecto— o el directorio de `--path`.
+- Un posicional `user/repo[@ref]` o `--path <dir>` lo sobrescribe y
+  queda registrado como nuevo origen.
+- `--ref` sobrescribe el ref de un origen de repositorio; con un
+  origen local es un error de invocación.
+
+## Qué hace
+
+Verifica la versión entrante y presenta el plan de actualización
+completo antes de escribir nada: `create`, `identical`, `update`
+—la versión cambió el recurso y el destino sigue intacto— y
+`retire` —la versión retira un recurso intacto—. Lo que la versión
+cambió sobre una edición local, y los retirados modificados, se
+resuelven como las colisiones de `install`: pregunta interactiva,
+`--force`, `--skip` o aborto sin consola —para un retirado la
+pregunta es quitarlo, no sobrescribirlo—.
+
+Si el paquete ya está en la versión que publica el origen, responde
+`ya está en esa versión` sin escribir nada. Terminada la ejecución,
+el registro queda a la versión nueva con el origen efectivo.
+
+## Errores
+
+| Situación                                              | Código |
+|--------------------------------------------------------|--------|
+| El paquete no está instalado                           | `4`    |
+| No hay origen registrado ni se indica uno              | `4`    |
+| El origen obtenido publica otro paquete                | `4`    |
+| `--ref` con un origen local, `--ref` con `--path`, o argumentos de más | `4` |
+| Manifiesto del origen inválido                         | `1`    |
+| Precondición incumplida o decisiones pendientes sin consola | `2` |
+| Error de ejecución                                     | `3`    |
+| Origen remoto inaccesible                              | `5`    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nucleoabierto/teleprompter",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Instalador de paquetes de configuración Teleprompter",
   "license": "MIT",
   "repository": {
@@ -24,5 +24,8 @@
   },
   "scripts": {
     "test": "node --test --experimental-test-coverage --test-coverage-include='**/src/**' --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-branches=100"
+  },
+  "dependencies": {
+    "tar": "^7.5.22"
   }
 }