@nucleoabierto/teleprompter 0.1.1

package/src/manifest.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isSafeRelative, hasEntry } from './paths.js';
+
+const KNOWN_FORMAT = 'teleprompter-package@1';
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+const TOP_LEVEL_FIELDS = new Set([
+  'format', 'name', 'version', 'description', 'license', 'author',
+  'collection', 'packages', 'install', 'requires', 'personalization',
+  'metadata',
+]);
+
+const OBJECT_KEYS = {
+  author: new Set(['name', 'email', 'url']),
+  requires: new Set(['paths']),
+  requiresPath: new Set(['path', 'create']),
+  installEntry: new Set(['source', 'target']),
+};
+
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+
+function checkKeys(obj, allowed, where, errors) {
+  for (const key of Object.keys(obj)) {
+    if (!allowed.has(key)) errors.push(`${where}: campo desconocido "${key}"`);
+  }
+}
+
+// Returns whether the value survives validation so callers can gate
+// downstream checks (e.g. existence) on a well-formed path.
+function checkRelativePath(value, label, errors) {
+  if (!isNonEmptyString(value)) {
+    errors.push(`${label}: debe ser una cadena no vacía`);
+    return false;
+  }
+  if (!isSafeRelative(value)) {
+    errors.push(`${label}: ruta absoluta o con ".." no permitida`);
+    return false;
+  }
+  return true;
+}
+
+function checkInstallEntry(entry, index, pkgDir, errors) {
+  const where = `install[${index}]`;
+  if (!isPlainObject(entry)) {
+    errors.push(`${where}: debe ser un objeto { "source", "target" }`);
+    return;
+  }
+  checkKeys(entry, OBJECT_KEYS.installEntry, where, errors);
+  const sourceOk = checkRelativePath(entry.source, `${where}.source`, errors);
+  checkRelativePath(entry.target, `${where}.target`, errors);
+  if (sourceOk && !hasEntry(path.join(pkgDir, entry.source))) {
+    errors.push(`${where}.source: no existe "${entry.source}" dentro del paquete`);
+  }
+}
+
+function checkRequiresEntry(entry, index, errors) {
+  const where = `requires.paths[${index}]`;
+  if (!isPlainObject(entry)) {
+    errors.push(`${where}: debe ser un objeto { "path", "create"? }`);
+    return;
+  }
+  checkKeys(entry, OBJECT_KEYS.requiresPath, where, errors);
+  checkRelativePath(entry.path, `${where}.path`, errors);
+  if (entry.create !== undefined && typeof entry.create !== 'boolean') {
+    errors.push(`${where}.create: debe ser booleano`);
+  }
+}
+
+// Each validator owns one field of the manifest. They receive the
+// parsed object, the package directory and the error sink, so adding
+// a field means adding one entry to VALIDATORS, not touching control
+// flow.
+const VALIDATORS = [
+  function checkCollection(manifest, _ctx, errors) {
+    if (manifest.collection === true) {
+      errors.push('el manifiesto describe una colección; las colecciones no son instalables');
+    } else if (manifest.collection !== undefined && manifest.collection !== false) {
+      errors.push('collection: debe ser booleano');
+    }
+  },
+  function checkFormat(manifest, _ctx, errors) {
+    if (manifest.format !== undefined && manifest.format !== KNOWN_FORMAT) {
+      errors.push(`format: desconocido "${manifest.format}" (esperado "${KNOWN_FORMAT}")`);
+    }
+  },
+  function checkName(manifest, { pkgDir }, errors) {
+    if (!isNonEmptyString(manifest.name)) {
+      errors.push('name: obligatorio, cadena no vacía');
+      return;
+    }
+    if (manifest.name.length > 64 || !NAME_RE.test(manifest.name)) {
+      errors.push('name: debe ser kebab-case (minúsculas, números y guiones, máx. 64)');
+    }
+    if (manifest.name !== path.basename(path.resolve(pkgDir))) {
+      errors.push(`name: "${manifest.name}" no coincide con el nombre del directorio`);
+    }
+  },
+  function checkVersion(manifest, _ctx, errors) {
+    if (!isNonEmptyString(manifest.version) || !SEMVER_RE.test(manifest.version)) {
+      errors.push('version: obligatoria, semver explícita x.y.z');
+    }
+  },
+  function checkInstall(manifest, { pkgDir }, errors) {
+    if (!Array.isArray(manifest.install) || manifest.install.length === 0) {
+      errors.push('install: obligatorio, lista no vacía de { "source", "target" }');
+      return;
+    }
+    manifest.install.forEach((entry, index) => checkInstallEntry(entry, index, pkgDir, errors));
+    // Target collisions make the plan ambiguous: two entries writing
+    // the same path, one nested under the other, or the lock file
+    // itself would let the second silently overwrite the first.
+    const targets = manifest.install
+      .map((e) => (typeof e?.target === 'string'
+        ? path.normalize(e.target).replace(/\/+$/, '')
+        : null))
+      .filter((t) => t !== null);
+    const seen = new Set();
+    for (const t of targets) {
+      if (t === 'teleprompter-lock.json') {
+        errors.push('install: "teleprompter-lock.json" es un target reservado');
+      } else if (seen.has(t)) {
+        errors.push(`install: target duplicado "${t}"`);
+      } else if (seen.has([...seen].find((o) => t.startsWith(`${o}/`)))) {
+        errors.push(`install: target "${t}" queda dentro de otro target`);
+      }
+      seen.add(t);
+    }
+  },
+  function checkRequires(manifest, _ctx, errors) {
+    if (manifest.requires === undefined) return;
+    if (!isPlainObject(manifest.requires)) {
+      errors.push('requires: debe ser un objeto');
+      return;
+    }
+    checkKeys(manifest.requires, OBJECT_KEYS.requires, 'requires', errors);
+    if (manifest.requires.paths === undefined) return;
+    if (!Array.isArray(manifest.requires.paths)) {
+      errors.push('requires.paths: debe ser una lista');
+      return;
+    }
+    manifest.requires.paths.forEach((entry, index) => checkRequiresEntry(entry, index, errors));
+  },
+  function checkAuthor(manifest, _ctx, errors) {
+    if (manifest.author === undefined) return;
+    if (!isPlainObject(manifest.author)) {
+      errors.push('author: debe ser un objeto { "name", "email"?, "url"? }');
+      return;
+    }
+    checkKeys(manifest.author, OBJECT_KEYS.author, 'author', errors);
+    if (!isNonEmptyString(manifest.author.name)) {
+      errors.push('author.name: obligatorio dentro de author');
+    }
+  },
+  function checkPersonalization(manifest, _ctx, errors) {
+    if (manifest.personalization === undefined) return;
+    checkRelativePath(manifest.personalization, 'personalization', errors);
+  },
+  function checkMetadata(manifest, _ctx, errors) {
+    if (manifest.metadata !== undefined && !isPlainObject(manifest.metadata)) {
+      errors.push('metadata: debe ser un objeto');
+    }
+  },
+  ...['description', 'license'].map((field) => (manifest, _ctx, errors) => {
+    if (manifest[field] !== undefined && typeof manifest[field] !== 'string') {
+      errors.push(`${field}: debe ser una cadena`);
+    }
+  }),
+];
+
+// Never throws: every problem lands in errors so the CLI can report
+// them all in one pass instead of failing on the first one.
+export function loadManifest(pkgDir) {
+  const warnings = [];
+  const errors = [];
+  const manifestPath = path.join(pkgDir, 'teleprompter.json');
+
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, 'utf8');
+  } catch {
+    return { manifest: null, warnings, errors: [`no existe ${manifestPath}`] };
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch (error) {
+    return { manifest: null, warnings, errors: [`JSON inválido en ${manifestPath}: ${error.message}`] };
+  }
+  if (!isPlainObject(manifest)) {
+    return { manifest: null, warnings, errors: ['el manifiesto debe ser un objeto JSON'] };
+  }
+
+  for (const key of Object.keys(manifest)) {
+    if (!TOP_LEVEL_FIELDS.has(key)) {
+      warnings.push(`campo desconocido ignorado: "${key}"`);
+    }
+  }
+  for (const validate of VALIDATORS) validate(manifest, { pkgDir }, errors);
+
+  return { manifest: errors.length === 0 ? manifest : null, warnings, errors };
+}

package/src/paths.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// "Exists" means a directory entry is present, whatever it points
+// at: existsSync follows links, so a dangling symlink would report
+// the path as free and a later write could escape through it.
+export function hasEntry(p) {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Rejects anything that could escape the package or the destination
+// root: absolute paths and ".." segments, plus Windows-style absolute
+// ("C:\...") and UNC ("\\...") paths, which path.isAbsolute does not
+// detect on POSIX.
+export function isSafeRelative(p) {
+  if (path.isAbsolute(p)) return false;
+  if (/^[a-zA-Z]:[\\/]/.test(p) || p.startsWith('\\\\')) return false;
+  return !p.split('/').concat(p.split('\\')).includes('..');
+}
+
+// A relative path can still escape the root through a symlink in its
+// parent chain: existsSync-style checks follow links, so the deepest
+// existing ancestor must resolve — after dereferencing — to a
+// directory inside the root. Anything else (dangling ancestor, an
+// ancestor that is a file, a link pointing outside) means the write
+// would not land where the plan claims.
+export function resolvesUnder(root, dir) {
+  let probe = dir;
+  while (!hasEntry(probe)) {
+    const parent = path.dirname(probe);
+    if (parent === probe) return false;
+    probe = parent;
+  }
+  try {
+    const real = fs.realpathSync(probe);
+    if (!fs.statSync(real).isDirectory()) return false;
+    const rootReal = fs.realpathSync(root);
+    return real === rootReal || real.startsWith(`${rootReal}${path.sep}`);
+  } catch {
+    return false;
+  }
+}

package/src/plan.js

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import { hashPath } from './hash.js';
+import { hasEntry, resolvesUnder } from './paths.js';
+
+// Classifies each install entry by comparing the destination with the
+// package resource and the recorded history:
+//   create         - the destination does not exist
+//   identical      - same content, nothing to do
+//   managed-update - the destination still holds what a previous
+//                    install wrote and the package offers an equal or
+//                    later version, so overwriting it is safe
+//   conflict       - different content not owned by the tool
+export function buildPlan(pkgDir, manifest, destDir, creates, lock) {
+  const record = lock.packages[manifest.name];
+  const recorded = new Map((record?.files ?? []).map((f) => [f.target, f.sha256]));
+  const updatesAllowed = semverAtLeast(manifest.version, record?.version);
+  const resources = manifest.install.map(({ source, target }) => {
+    const dest = path.join(destDir, target);
+    if (!hasEntry(dest)) {
+      // A write whose parent chain escapes the root cannot be a
+      // create: the path may be free here but not where it lands.
+      const status = resolvesUnder(destDir, path.dirname(dest)) ? 'create' : 'conflict';
+      return { source, target, status };
+    }
+    const destHash = hashPath(dest);
+    const status = destHash === hashPath(path.join(pkgDir, source)) ? 'identical'
+      : updatesAllowed && recorded.get(target) === destHash ? 'managed-update'
+        : 'conflict';
+    if (status !== 'identical' && status !== 'conflict'
+        && !resolvesUnder(destDir, path.dirname(dest))) {
+      return { source, target, status: 'conflict' };
+    }
+    return { source, target, status };
+  });
+  return {
+    mkdirs: creates,
+    resources,
+    conflicts: resources.filter((r) => r.status === 'conflict'),
+  };
+}
+
+// Downgrades are not managed updates: writing older content over a
+// newer recorded install must surface as a conflict, not silently
+// pass as safe.
+function semverAtLeast(version, recordedVersion) {
+  const parse = (v) => /^(\d+)\.(\d+)\.(\d+)$/.exec(v ?? '')?.slice(1).map(Number);
+  const a = parse(version);
+  const b = parse(recordedVersion);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return true;
+}

package/src/prompt.js

@@ -0,0 +1,16 @@
+import readline from 'node:readline/promises';
+
+// readline wrapper kept apart from the CLI so conflict resolution is
+// testable with fake streams. Answers accept the usual affirmative
+// spellings; anything else means skip, because the safe default for
+// overwriting someone else's work must be "no".
+export function createAsker(input = process.stdin, output = process.stdout) {
+  const rl = readline.createInterface({ input, output });
+  return {
+    ask: async (question) => {
+      const answer = await rl.question(question);
+      return ['s', 'si', 'sí', 'y', 'yes'].includes(answer.trim().toLowerCase());
+    },
+    close: () => rl.close(),
+  };
+}

package/src/requires.js

@@ -0,0 +1,19 @@
+import path from 'node:path';
+import { hasEntry, resolvesUnder } from './paths.js';
+
+// Splits missing precondition paths into hard failures and deferred
+// creations: `create: true` entries become plan actions rather than
+// aborting the operation — unless their parent chain escapes the
+// destination root through a link, which makes the precondition
+// unmeetable rather than deferrable.
+export function checkRequires(manifest, destDir) {
+  const failures = [];
+  const creates = [];
+  for (const entry of manifest.requires?.paths ?? []) {
+    const p = path.join(destDir, entry.path);
+    if (hasEntry(p)) continue;
+    if (entry.create === true && resolvesUnder(destDir, p)) creates.push(entry.path);
+    else failures.push(entry.path);
+  }
+  return { failures, creates };
+}

package/src/verify.js

@@ -0,0 +1,17 @@
+import { loadManifest } from './manifest.js';
+import { checkRequires } from './requires.js';
+
+// Returns a structured result so the plan phase can consume the
+// verification outcome without revalidating the manifest.
+// kind: 'ok' | 'manifest' | 'requires'.
+export function verifyPackage(pkgDir, destDir) {
+  const { manifest, warnings, errors } = loadManifest(pkgDir);
+  if (errors.length > 0) {
+    return { kind: 'manifest', warnings, errors, manifest: null, creates: [], failures: [] };
+  }
+  const { failures, creates } = checkRequires(manifest, destDir);
+  if (failures.length > 0) {
+    return { kind: 'requires', warnings, errors: [], manifest, creates, failures };
+  }
+  return { kind: 'ok', warnings, errors: [], manifest, creates, failures: [] };
+}