@nucleoabierto/teleprompter 0.1.1

package/manual/guia-de-uso.md

@@ -0,0 +1,90 @@
+# Guía de uso
+
+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/`.
+- El directorio del repositorio destino donde se instalarán los
+  recursos.
+
+## Instalar un paquete
+
+Desde la raíz del repositorio destino —o dando su ruta como segundo
+argumento—:
+
+```sh
+npx @nucleoabierto/teleprompter install /ruta/al/paquete .
+```
+
+El instalador trabaja en cuatro fases: verificación, plan, ejecución y
+registro. Las dos primeras no escriben nada.
+
+1. **Verificación.** Lee y valida el manifiesto del paquete y comprueba
+   sus precondiciones sobre el destino. Si algo falla, la operación
+   aborta antes de tocar el disco. Si todo va bien, verás:
+
+```text
+verificado: ciclo-tareas@1.0.0
+```
+
+2. **Plan.** Se calculan todas las acciones antes de escribir y se
+   muestran recurso a recurso con una marca por línea (`create`,
+   `identical`, `conflict`, `managed-update`):
+
+```text
+plan de instalación:
+ mkdir          .agents/skills/
+ create         .agents/skills/crear-tareas/
+ create         .agents/skills/ejecutar-tareas/
+ create         .agents/skills/commit/
+```
+
+3. **Ejecución.** Si el plan no tiene colisiones, se ejecuta tal como se
+   presentó. Si las hay, se resuelven antes de escribir: en una consola
+   interactiva el instalador pregunta por cada recurso en conflicto;
+   en una ejecución no interactiva la operación aborta. `--force` y
+   `--skip` resuelven todas las colisiones por adelantado (véase la
+   [referencia](referencia-install.md#colisiones)).
+
+4. **Registro.** Terminada la ejecución se escribe
+   `teleprompter-lock.json` en la raíz del destino y se informa del
+   resultado:
+
+```text
+resultado:
+ mkdir          .agents/skills/
+ create         .agents/skills/crear-tareas/
+ create         .agents/skills/ejecutar-tareas/
+ create         .agents/skills/commit/
+instalado: ciclo-tareas@1.0.0
+```
+
+   El archivo de registro está pensado para versionarse con el
+   repositorio: es lo que permite a Teleprompter distinguir lo que él
+   instaló de lo que ya existía.
+
+## 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
+```
+
+Es la forma de ver qué haría una instalación —incluidas las colisiones
+que habría que resolver— antes de decidir.
+
+## Reinstalar
+
+Reinstalar un paquete ya instalado es una operación válida e inocua:
+los recursos que siguen idénticos se marcan `identical` y no se
+escriben; los que difieren en contenido se actualizan
+(`managed-update`) solo si el paquete ofrece una versión igual o
+posterior a la registrada y el destino sigue conteniendo lo que la
+instalación anterior escribió. Si un recurso instalado se modificó a
+mano, se trata como colisión y pide resolución.

package/manual/index.md

@@ -0,0 +1,27 @@
+# Teleprompter
+
+Instalador de paquetes de configuración para repositorios.
+
+Teleprompter lleva un paquete —un directorio con un manifiesto
+`teleprompter.json` y sus recursos— a un repositorio con trabajo
+previo: calcula el plan completo antes de escribir nada, resuelve las
+colisiones con lo que ya existe y registra la instalación en
+`teleprompter-lock.json`.
+
+## Empieza aquí
+
+- [Guía de uso](guia-de-uso.md) — instalar un paquete paso a paso, con
+  el paquete de referencia del repositorio como ejemplo.
+- [Referencia de `install`](referencia-install.md) — la operación
+  completa: fases, marcas del plan, resolución de colisiones, registro
+  y códigos de salida.
+- [Instalar un paquete](001-instalar-un-paquete.md) — la funcionalidad
+  y los escenarios que la suite de pruebas verifica.
+
+## En el repositorio
+
+- [Especificación del formato de paquete](https://github.com/nucleoabierto/teleprompter/blob/master/docs/especificacion-paquete.md)
+  — cómo escribir el manifiesto `teleprompter.json` de un paquete
+  propio.
+- [Documentación de dominio](https://github.com/nucleoabierto/teleprompter/tree/master/docs/domains)
+  — el modelo del producto: qué es un paquete y qué es una instalación.

package/manual/referencia-install.md

@@ -0,0 +1,120 @@
+# Referencia de `install`
+
+```text
+teleprompter install <paquete> <destino> [--force|--skip] [--dry-run]
+```
+
+Instala el paquete del directorio `<paquete>` en el repositorio cuya
+raíz es `<destino>`. Ambos argumentos deben ser directorios existentes.
+
+## Fases
+
+La operación ejecuta cuatro fases en orden:
+
+1. **Verificación.** Valida el manifiesto `teleprompter.json` contra la
+   [especificación](https://github.com/nucleoabierto/teleprompter/blob/master/docs/especificacion-paquete.md); un manifiesto
+   inválido aborta con código `1`. Después comprueba las
+   precondiciones `requires.paths` sobre el destino: cada ruta que no
+   existe y no declara `create: true` aborta con código `2`; las que
+   declaran `create: true` aparecen en el plan como acciones `mkdir`.
+2. **Plan.** Calcula el conjunto completo de acciones y lo presenta
+   antes de escribir nada. Un plan no ejecutable —precondición
+   incumplida o colisión sin resolver— aborta la operación entera:
+   ni recursos ni registro.
+3. **Ejecución.** Solo se ejecuta un plan válido, en el orden
+   presentado.
+4. **Registro.** Escribe `teleprompter-lock.json` en la raíz del
+   destino. Es parte de la operación, no un efecto secundario.
+
+## Marcas del plan
+
+Una marca por línea, antes de cualquier escritura:
+
+- `mkdir` — creación de una ruta de precondición con `create: true`.
+- `create` — el destino no existe; se instalará el recurso.
+- `identical` — el destino ya contiene exactamente el recurso del
+  paquete; no hay nada que escribir.
+- `conflict` — el destino existe con contenido distinto y no consta
+  instalado por Teleprompter, o consta pero fue modificado localmente
+  desde entonces. Requiere resolución.
+- `managed-update` — el destino existe con contenido distinto, pero el
+  registro lo reconoce como propio (su contenido coincide con el hash
+  anotado) y el paquete ofrece una versión igual o posterior a la
+  registrada. Se sobrescribe sin preguntar.
+
+En el resultado final, `conflict` y `managed-update` aparecen como
+`overwrite` cuando se escribieron, y `skip` cuando se omitieron.
+
+## Colisiones
+
+Una colisión es un `conflict` del plan. La primera respuesta es la
+resolución interactiva: en una consola interactiva se pregunta por cada
+recurso si se sobrescribe o se omite. En una invocación no interactiva
+sin opciones, la operación lista los conflictos y aborta con código `2`
+sin escribir nada.
+
+Dos opciones excluyentes resuelven todas las colisiones por adelantado:
+
+- `--force` — el recurso del paquete sobrescribe el destino en cada
+  colisión. Es destructivo y nunca es el comportamiento por defecto.
+- `--skip` — el recurso en conflicto no se instala; el resto del plan
+  se ejecuta y la omisión queda en el registro como `skip`.
+
+Declarar ambas es un error de invocación (código `4`). La resolución
+decide por recurso completo: el contenido no se fusiona.
+
+## `--dry-run`
+
+Ejecuta las fases de verificación y plan —incluida, si procede, la
+resolución de colisiones— y termina con código `0` sin escribir
+recursos ni registro.
+
+## El registro
+
+Cada instalación escribe `teleprompter-lock.json` en la raíz del
+destino: un JSON pensado para versionarse con el repositorio:
+
+```json
+{
+  "packages": {
+    "ciclo-tareas": {
+      "version": "1.0.0",
+      "installedAt": "2026-09-28T10:00:00.000Z",
+      "files": [
+        {
+          "target": ".agents/skills/ejecutar-tareas/SKILL.md",
+          "action": "create",
+          "sha256": "…"
+        }
+      ]
+    }
+  }
+}
+```
+
+`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.
+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
+registro existente pero ilegible o malformado se ignora igualmente, con
+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`.
+
+## Códigos de salida
+
+| Código | Significado                                                     |
+|--------|-----------------------------------------------------------------|
+| `0`    | Éxito                                                           |
+| `1`    | Manifiesto inválido                                             |
+| `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 |

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@nucleoabierto/teleprompter",
+  "version": "0.1.1",
+  "description": "Instalador de paquetes de configuración Teleprompter",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nucleoabierto/teleprompter.git"
+  },
+  "type": "module",
+  "bin": {
+    "teleprompter": "bin/teleprompter.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "manual/",
+    "docs/domains/",
+    "docs/especificacion-paquete.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test --experimental-test-coverage --test-coverage-include='**/src/**' --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-branches=100"
+  }
+}

package/src/cli.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import { verifyPackage } from './verify.js';
+import { readLock, writeLock } from './lock.js';
+import { buildPlan } from './plan.js';
+import { executePlan } from './execute.js';
+
+export const EXIT_OK = 0;
+export const EXIT_MANIFEST = 1;
+export const EXIT_PLAN = 2;
+export const EXIT_EXECUTION = 3;
+export const EXIT_USAGE = 4;
+
+const USAGE = 'uso: teleprompter install <paquete> <destino> [--force|--skip] [--dry-run]';
+const KNOWN_FLAGS = new Set(['--force', '--skip', '--dry-run']);
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const args = [];
+  const flags = new Set();
+  for (const arg of rest) {
+    if (arg.startsWith('--')) flags.add(arg);
+    else args.push(arg);
+  }
+  const unknown = [...flags].find((f) => !KNOWN_FLAGS.has(f));
+  const invalid = command !== 'install' || args.length !== 2
+    || unknown !== undefined || (flags.has('--force') && flags.has('--skip'));
+  return invalid ? null : { args, flags };
+}
+
+function printPlan(plan, out) {
+  out('plan de instalación:');
+  for (const dir of plan.mkdirs) out(`  ${'mkdir'.padEnd(15)}${dir}`);
+  for (const r of plan.resources) out(`  ${r.status.padEnd(15)}${r.target}`);
+}
+
+// Invocation layer only: parses arguments, delegates to src/ and maps
+// the result to output and exit codes. Keeping it thin is what lets
+// the test suite exercise the CLI without spawning processes.
+// io: { out, err, interactive, createAsker } — injectable for tests.
+export async function main(argv, io = {}) {
+  const out = io.out ?? console.log;
+  const err = io.err ?? console.error;
+
+  const parsed = parseArgs(argv);
+  if (parsed === null) {
+    err(USAGE);
+    return EXIT_USAGE;
+  }
+  const { args, flags } = parsed;
+  const [pkgDir, destDir] = args;
+  const isDir = (p) => fs.existsSync(p) && fs.statSync(p).isDirectory();
+  if (!isDir(pkgDir) || !isDir(destDir)) {
+    for (const arg of args) {
+      if (!isDir(arg)) err(`la ruta no es un directorio: ${arg}`);
+    }
+    return EXIT_USAGE;
+  }
+
+  const result = verifyPackage(pkgDir, destDir);
+  for (const warning of result.warnings) out(`aviso: ${warning}`);
+  if (result.kind === 'manifest') {
+    for (const error of result.errors) err(`manifiesto inválido: ${error}`);
+    return EXIT_MANIFEST;
+  }
+  if (result.kind === 'requires') {
+    for (const p of result.failures) {
+      err(`precondición incumplida: "${p}" no existe en el destino`);
+    }
+    return EXIT_PLAN;
+  }
+  out(`verificado: ${result.manifest.name}@${result.manifest.version}`);
+
+  const lock = readLock(destDir);
+  for (const warning of lock.warnings) out(`aviso: ${warning}`);
+  const plan = buildPlan(pkgDir, result.manifest, destDir, result.creates, lock);
+  printPlan(plan, out);
+
+  if (plan.conflicts.length > 0) {
+    if (flags.has('--force')) {
+      for (const r of plan.conflicts) r.resolution = 'overwrite';
+    } else if (flags.has('--skip')) {
+      for (const r of plan.conflicts) r.resolution = 'skip';
+    } else if (io.interactive && io.createAsker) {
+      const asker = io.createAsker();
+      try {
+        for (const r of plan.conflicts) {
+          const overwrite = await asker.ask(`colisión en ${r.target}: ¿sobrescribir? [s/N] `);
+          r.resolution = overwrite ? 'overwrite' : 'skip';
+        }
+      } finally {
+        asker.close();
+      }
+    } else {
+      for (const r of plan.conflicts) err(`conflicto sin resolver: ${r.target}`);
+      err('plan no ejecutable: colisiones sin resolver');
+      return EXIT_PLAN;
+    }
+    for (const r of plan.conflicts) out(`  ${r.target} → ${r.resolution}`);
+  }
+
+  if (flags.has('--dry-run')) {
+    out('fin del plan (--dry-run): nada se escribió');
+    return EXIT_OK;
+  }
+
+  let actions;
+  try {
+    actions = executePlan(pkgDir, destDir, plan);
+    writeLock(destDir, lock, result.manifest, actions);
+  } catch (error) {
+    for (const a of error.applied ?? actions) {
+      out(`  ${a.action.padEnd(15)}${a.target}`);
+    }
+    err(`error de ejecución: ${error.message}`);
+    return EXIT_EXECUTION;
+  }
+  out('resultado:');
+  for (const a of actions) out(`  ${a.action.padEnd(15)}${a.target}`);
+  if (result.manifest.personalization) {
+    out(`personalización: instrucciones en "${result.manifest.personalization}" del paquete`);
+  }
+  out(`instalado: ${result.manifest.name}@${result.manifest.version}`);
+  return EXIT_OK;
+}

package/src/execute.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hashPath } from './hash.js';
+import { resolvesUnder } from './paths.js';
+
+const ACTION = {
+  create: 'create',
+  identical: 'identical',
+  'managed-update': 'overwrite',
+  conflict: null, // taken from the resource's resolution
+};
+
+function copyResource(source, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const stat = fs.lstatSync(source);
+  if (stat.isSymbolicLink()) {
+    fs.symlinkSync(fs.readlinkSync(source), dest);
+  } else if (stat.isDirectory()) {
+    // verbatimSymlinks keeps links as links: dereferencing them would
+    // make the written copy hash differently from the package, and the
+    // next install would report a phantom conflict.
+    fs.cpSync(source, dest, { recursive: true, verbatimSymlinks: true });
+  } else {
+    fs.copyFileSync(source, dest);
+  }
+}
+
+// Materializes a resolved plan: creates the precondition directories,
+// then applies exactly the action each resource was assigned. Every
+// write —including the rm that precedes an overwrite— first proves the
+// parent chain resolves under the destination root, so a symlinked
+// directory can never redirect a write outside it.
+// If a copy throws midway, the error carries `applied` — the actions
+// already performed — so the caller can report them.
+export function executePlan(pkgDir, destDir, plan) {
+  const applied = [];
+  try {
+    for (const dir of plan.mkdirs) {
+      const dest = path.join(destDir, dir);
+      if (!resolvesUnder(destDir, dest)) {
+        throw new Error(`la ruta destino escapa de la raíz: ${dest}`);
+      }
+      fs.mkdirSync(dest, { recursive: true });
+      applied.push({ target: dir, action: 'mkdir' });
+    }
+    for (const r of plan.resources) {
+      const action = ACTION[r.status] ?? r.resolution;
+      if (action === undefined) {
+        throw new Error(`plan sin resolver: ${r.target}`);
+      }
+      const dest = path.join(destDir, r.target);
+      if (action === 'create' || action === 'overwrite') {
+        if (!resolvesUnder(destDir, path.dirname(dest))) {
+          throw new Error(`la ruta destino escapa de la raíz: ${dest}`);
+        }
+        if (action === 'overwrite') {
+          fs.rmSync(dest, { recursive: true, force: true });
+        }
+        // Pushed before the copy so a failed write still reports the
+        // destructive half it already ran.
+        const entry = { target: r.target, action };
+        applied.push(entry);
+        copyResource(path.join(pkgDir, r.source), dest);
+        entry.sha256 = hashPath(dest);
+      } else {
+        applied.push({ target: r.target, action });
+      }
+    }
+  } catch (error) {
+    error.applied = applied;
+    throw error;
+  }
+  return applied;
+}

package/src/hash.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Each node kind hashes in its own domain ("file"/"link"/"dir"
+// seeds) so two resources of different kinds can never collide.
+function hashFile(file) {
+  return crypto.createHash('sha256')
+    .update('file\n')
+    .update(fs.readFileSync(file))
+    .digest('hex');
+}
+
+function collect(root, rel, entries) {
+  for (const name of fs.readdirSync(path.join(root, rel))) {
+    const childRel = rel ? `${rel}/${name}` : name;
+    const child = path.join(root, childRel);
+    const stat = fs.lstatSync(child);
+    if (stat.isSymbolicLink()) {
+      entries.push(`${childRel} -> ${fs.readlinkSync(child)}`);
+    } else if (stat.isDirectory()) {
+      // Directory markers keep empty subtrees significant: two trees
+      // that differ only in an empty directory must not hash equal.
+      entries.push(`${childRel}/`);
+      collect(root, childRel, entries);
+    } else {
+      entries.push(`${childRel}:${hashFile(child)}`);
+    }
+  }
+}
+
+// Hashes a file, symlink, or directory tree so resources can be
+// compared regardless of shape. lstat is deliberate: following links
+// would crash on dangling targets and could recurse forever through
+// a link back to a parent. The "dir" seed keeps an empty directory
+// from hashing equal to an empty file, and sorting the entry list
+// keeps the digest independent of traversal order.
+export function hashPath(target) {
+  const stat = fs.lstatSync(target);
+  if (stat.isSymbolicLink()) {
+    return crypto.createHash('sha256')
+      .update(`link\n${fs.readlinkSync(target)}`)
+      .digest('hex');
+  }
+  if (stat.isDirectory()) {
+    const entries = [];
+    collect(target, '', entries);
+    const hash = crypto.createHash('sha256').update('dir\n');
+    for (const entry of entries.sort()) hash.update(`${entry}\n`);
+    return hash.digest('hex');
+  }
+  return hashFile(target);
+}

package/src/lock.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CORRUPT_WARNING = 'teleprompter-lock.json ilegible o corrupto: se ignora';
+const EMPTY = () => ({ packages: {}, warnings: [] });
+
+// A missing or corrupt lock means "no recorded history": the install
+// proceeds as if nothing was ever installed. Corruption surfaces as a
+// warning because collision detection degrades to treating everything
+// as foreign.
+export function readLock(destDir) {
+  const lockPath = path.join(destDir, 'teleprompter-lock.json');
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return EMPTY();
+    return { packages: {}, warnings: [CORRUPT_WARNING] };
+  }
+  if (!isValidLock(data)) return { packages: {}, warnings: [CORRUPT_WARNING] };
+  return { packages: data.packages ?? {}, warnings: [] };
+}
+
+// A lock is only trustworthy if every package entry holds a files
+// array of {target, sha256?} records — anything else is corrupt even
+// when it parses as JSON.
+function isValidLock(data) {
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) return false;
+  if (data.packages === undefined) return true;
+  const { packages } = data;
+  if (typeof packages !== 'object' || packages === null || Array.isArray(packages)) {
+    return false;
+  }
+  return Object.values(packages).every((p) => p !== null && typeof p === 'object'
+    && typeof p.version === 'string'
+    && Array.isArray(p.files)
+    && p.files.every((f) => f !== null && typeof f === 'object'
+      && typeof f.target === 'string'
+      && (f.sha256 === undefined || typeof f.sha256 === 'string')));
+}
+
+// Merges the new install into the existing history: other packages'
+// records survive untouched, while this package's entry is replaced
+// wholesale because it describes the installation just performed.
+// `identical` keeps any previous record — the content is still ours
+// and the recorded hash still matches — but creates none for a
+// resource we never wrote. `mkdir` actions are plan bookkeeping, not
+// installed files.
+export function writeLock(destDir, lock, manifest, actions) {
+  const previous = new Map(
+    (lock.packages[manifest.name]?.files ?? []).map((f) => [f.target, f]),
+  );
+  const files = actions.flatMap(({ target, action, sha256 }) => {
+    if (action === 'identical' || action === 'mkdir') {
+      const prev = previous.get(target);
+      return prev === undefined ? [] : [prev];
+    }
+    return [sha256 === undefined ? { target, action } : { target, action, sha256 }];
+  });
+  const data = {
+    packages: {
+      ...lock.packages,
+      [manifest.name]: {
+        version: manifest.version,
+        installedAt: new Date().toISOString(),
+        files,
+      },
+    },
+  };
+  fs.writeFileSync(
+    path.join(destDir, 'teleprompter-lock.json'),
+    `${JSON.stringify(data, null, 2)}\n`,
+  );
+}