@nucleoabierto/teleprompter 0.1.1 → 0.2.0

package/src/execute.js

@@ -1,15 +1,33 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { hashPath } from './hash.js';
-import { resolvesUnder } from './paths.js';
+import { resolvesUnder, personalizationTarget } from './paths.js';
+
+// A failed execution reports what it already did: the thrown error
+// is a declared type carrying the applied actions and the original
+// error as `cause`, instead of mutating whatever the try happened
+// to catch.
+export class ExecutionError extends Error {
+  constructor(applied, cause) {
+    super(cause.message, { cause });
+    this.name = 'ExecutionError';
+    this.applied = applied;
+  }
+}
 
 const ACTION = {
   create: 'create',
   identical: 'identical',
   'managed-update': 'overwrite',
+  update: 'overwrite',
+  retire: 'remove',
   conflict: null, // taken from the resource's resolution
 };
 
+// A conflict marked `removal` resolves to remove or keep instead of
+// overwrite or skip — there is no incoming resource to write.
+const REMOVAL_RESOLUTION = { overwrite: 'remove', skip: 'keep' };
+
 function copyResource(source, dest) {
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   const stat = fs.lstatSync(source);
@@ -30,8 +48,8 @@ function copyResource(source, dest) {
 // 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.
+// If anything throws midway, the ExecutionError carries `applied` —
+// the actions already performed — so the caller can report them.
 export function executePlan(pkgDir, destDir, plan) {
   const applied = [];
   try {
@@ -43,13 +61,21 @@ export function executePlan(pkgDir, destDir, plan) {
       fs.mkdirSync(dest, { recursive: true });
       applied.push({ target: dir, action: 'mkdir' });
     }
-    for (const r of plan.resources) {
-      const action = ACTION[r.status] ?? r.resolution;
+    for (const r of [...plan.resources, ...(plan.retired ?? [])]) {
+      const action = r.removal === true
+        ? REMOVAL_RESOLUTION[r.resolution]
+        : 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 (action === 'remove') {
+        if (!resolvesUnder(destDir, path.dirname(dest))) {
+          throw new Error(`la ruta destino escapa de la raíz: ${dest}`);
+        }
+        fs.rmSync(dest, { recursive: true, force: true });
+        applied.push({ target: r.target, action });
+      } else if (action === 'create' || action === 'overwrite') {
         if (!resolvesUnder(destDir, path.dirname(dest))) {
           throw new Error(`la ruta destino escapa de la raíz: ${dest}`);
         }
@@ -67,8 +93,27 @@ export function executePlan(pkgDir, destDir, plan) {
       }
     }
   } catch (error) {
-    error.applied = applied;
-    throw error;
+    throw new ExecutionError(applied, error);
   }
   return applied;
 }
+
+// Materializes the declared personalization guide into the managed
+// namespace — not through the plan: the field already names the file,
+// and .teleprompter/ belongs to the tool, so the write is
+// unconditional apart from the same symlink-escape guard every write
+// gets. Returns the target it wrote, or null when the manifest
+// declares no guide.
+export function installPersonalization(pkgDir, destDir, manifest) {
+  if (!manifest.personalization) return null;
+  const target = personalizationTarget(manifest.name, manifest.personalization);
+  const dest = path.join(destDir, target);
+  if (!resolvesUnder(destDir, path.dirname(dest))) {
+    throw new Error(`la ruta destino escapa de la raíz: ${dest}`);
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  // rm first: copyFileSync would write through a symlink destination.
+  fs.rmSync(dest, { force: true, recursive: true });
+  fs.copyFileSync(path.join(pkgDir, manifest.personalization), dest);
+  return { target };
+}

package/src/fetch.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { extract } from 'tar';
+
+// A ref must be a plausible git ref: no whitespace, URL delimiters or
+// ".." (git itself forbids it); slashes are fine — tags like
+// "cli/v2.0.0" exist.
+export const isValidRef = (ref) =>
+  ref.length > 0 && !/[\s?#%]/.test(ref) && !ref.includes('..');
+
+// Parses "owner/repo[@ref]". Owner and repo follow GitHub naming:
+// alphanumerics, hyphen, underscore and dots, single slash — and
+// neither may be a dot segment, which would confuse the extraction
+// path. The spec splits on the first "@" because refs may contain
+// slashes.
+export function parseRepoSpec(spec) {
+  const at = spec.indexOf('@');
+  const repo = at === -1 ? spec : spec.slice(0, at);
+  const ref = at === -1 ? null : spec.slice(at + 1);
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) return null;
+  if (ref !== null && !isValidRef(ref)) return null;
+  const [owner, name] = repo.split('/');
+  if (/^\.{1,2}$/.test(owner) || /^\.{1,2}$/.test(name)) return null;
+  return { owner, name, ref };
+}
+
+function repoUrls({ owner, name, ref }) {
+  const o = encodeURIComponent(owner);
+  const r = encodeURIComponent(name);
+  return [
+    `https://codeload.github.com/${o}/${r}/tar.gz/${ref ?? 'HEAD'}`,
+    `https://api.github.com/repos/${o}/${r}/tarball${ref ? `/${ref}` : ''}`,
+  ];
+}
+
+// Downloads the public archive of a GitHub repository — no git, no
+// credentials — and extracts it under a temp dir as {tmp}/{repo},
+// so the package directory basename matches the manifest name rule.
+// The fetch implementation comes from the caller (the CLI injects
+// it for tests); the extracted tree is remote content, so `tar`
+// sanitization (no "..", no absolute paths, no symlink escapes) is
+// the security boundary, not a courtesy.
+// Returns { ok: true, dir, cleanup } or { ok: false, error }.
+export async function fetchRepoTree(spec, { fetch: fetchImpl, tmpBase }) {
+  if (fetchImpl === undefined) {
+    return { ok: false, error: 'no hay implementación de fetch disponible' };
+  }
+  const root = fs.mkdtempSync(path.join(tmpBase ?? os.tmpdir(), 'teleprompter-fetch-'));
+  const cleanup = () => fs.rmSync(root, { recursive: true, force: true });
+  const dir = path.join(root, spec.name);
+
+  let response = null;
+  let unreachable = true;
+  for (const url of repoUrls(spec)) {
+    try {
+      const res = await fetchImpl(url);
+      if (res.ok) {
+        response = res;
+        break;
+      }
+      unreachable = false;
+    } catch {
+      // A failed request says nothing about the next endpoint:
+      // codeload may be down while the API is reachable.
+    }
+  }
+  if (response === null) {
+    cleanup();
+    const why = unreachable ? 'no se pudo contactar con GitHub' : 'repositorio o referencia no encontrados';
+    return { ok: false, error: `${why}: ${spec.owner}/${spec.name}${spec.ref ? `@${spec.ref}` : ''}` };
+  }
+
+  try {
+    const archive = path.join(root, 'repo.tar.gz');
+    fs.writeFileSync(archive, Buffer.from(await response.arrayBuffer()));
+    fs.mkdirSync(dir);
+    await extract({ file: archive, cwd: dir, strip: 1 });
+    fs.rmSync(archive);
+  } catch (error) {
+    cleanup();
+    return { ok: false, error: `no se pudo extraer el archivo: ${error.message}` };
+  }
+  return { ok: true, dir, cleanup };
+}

package/src/lock.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { hashPath } from './hash.js';
+import { personalizationTarget } from './paths.js';
 
 const CORRUPT_WARNING = 'teleprompter-lock.json ilegible o corrupto: se ignora';
 const EMPTY = () => ({ packages: {}, warnings: [] });
@@ -21,6 +23,17 @@ export function readLock(destDir) {
   return { packages: data.packages ?? {}, warnings: [] };
 }
 
+// The lock is the module that owns the registry's shape: readers ask
+// for an entry by name or walk the entries, never `lock.packages`
+// directly, so the internal structure can change in one place.
+export function lockEntry(lock, name) {
+  return lock.packages[name];
+}
+
+export function lockEntries(lock) {
+  return Object.entries(lock.packages);
+}
+
 // 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.
@@ -36,7 +49,21 @@ function isValidLock(data) {
     && Array.isArray(p.files)
     && p.files.every((f) => f !== null && typeof f === 'object'
       && typeof f.target === 'string'
-      && (f.sha256 === undefined || typeof f.sha256 === 'string')));
+      && (f.sha256 === undefined || typeof f.sha256 === 'string'))
+    && (p.origin === undefined || isValidOrigin(p.origin)));
+}
+
+// `origin` is optional — locks written before it existed stay
+// valid — but when present it must name the re-fetchable source:
+// a GitHub repo with its optional ref, or a local path.
+function isValidOrigin(o) {
+  if (o === null || typeof o !== 'object' || Array.isArray(o)) return false;
+  if (o.type === 'github') {
+    return typeof o.repo === 'string'
+      && (o.ref === undefined || typeof o.ref === 'string');
+  }
+  if (o.type === 'path') return typeof o.path === 'string';
+  return false;
 }
 
 // Merges the new install into the existing history: other packages'
@@ -45,18 +72,33 @@ function isValidLock(data) {
 // `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) {
+// installed files. `origin` is the source the install came from, in
+// lock shape: a later operation can re-fetch the package without
+// asking for it again.
+export function writeLock(destDir, lock, manifest, actions, origin) {
   const previous = new Map(
-    (lock.packages[manifest.name]?.files ?? []).map((f) => [f.target, f]),
+    (lockEntry(lock, manifest.name)?.files ?? []).map((f) => [f.target, f]),
   );
   const files = actions.flatMap(({ target, action, sha256 }) => {
-    if (action === 'identical' || action === 'mkdir') {
+    if (action === 'remove') return [];
+    if (action === 'identical' || action === 'mkdir' || action === 'keep') {
       const prev = previous.get(target);
       return prev === undefined ? [] : [prev];
     }
     return [sha256 === undefined ? { target, action } : { target, action, sha256 }];
   });
+  // The managed guide never appears among the install actions — the
+  // manifest field already names it — but it is recorded like any
+  // other file the tool wrote.
+  let personalization;
+  if (manifest.personalization) {
+    personalization = personalizationTarget(manifest.name, manifest.personalization);
+    files.push({
+      target: personalization,
+      action: previous.has(personalization) ? 'overwrite' : 'create',
+      sha256: hashPath(path.join(destDir, personalization)),
+    });
+  }
   const data = {
     packages: {
       ...lock.packages,
@@ -64,11 +106,23 @@ export function writeLock(destDir, lock, manifest, actions) {
         version: manifest.version,
         installedAt: new Date().toISOString(),
         files,
+        ...(personalization === undefined ? {} : { personalization }),
+        origin,
       },
     },
   };
-  fs.writeFileSync(
-    path.join(destDir, 'teleprompter-lock.json'),
-    `${JSON.stringify(data, null, 2)}\n`,
-  );
+  // Atomic write: the serialized lock goes to a temp file in the
+  // same directory — rename is only atomic within one filesystem —
+  // and is then renamed over the real name, so a crash mid-write
+  // leaves the old lock or the new one, never a truncated file. The
+  // pid suffix keeps the temp name unique across concurrent runs;
+  // the finally removes it whether the write or the rename failed.
+  const lockPath = path.join(destDir, 'teleprompter-lock.json');
+  const tmpPath = `${lockPath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, `${JSON.stringify(data, null, 2)}\n`);
+    fs.renameSync(tmpPath, lockPath);
+  } finally {
+    fs.rmSync(tmpPath, { force: true, recursive: true });
+  }
 }

package/src/manifest.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { isSafeRelative, hasEntry } from './paths.js';
+import { isSafeRelative, hasEntry, MANAGED_DIR } from './paths.js';
 
 const KNOWN_FORMAT = 'teleprompter-package@1';
 const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -63,7 +63,11 @@ function checkRequiresEntry(entry, index, errors) {
     return;
   }
   checkKeys(entry, OBJECT_KEYS.requiresPath, where, errors);
-  checkRelativePath(entry.path, `${where}.path`, errors);
+  if (!checkRelativePath(entry.path, `${where}.path`, errors)) return;
+  const t = path.normalize(entry.path);
+  if (t === MANAGED_DIR || t.startsWith(`${MANAGED_DIR}/`)) {
+    errors.push(`${where}.path: "${MANAGED_DIR}/" es un prefijo reservado`);
+  }
   if (entry.create !== undefined && typeof entry.create !== 'boolean') {
     errors.push(`${where}.create: debe ser booleano`);
   }
@@ -121,9 +125,11 @@ const VALIDATORS = [
     for (const t of targets) {
       if (t === 'teleprompter-lock.json') {
         errors.push('install: "teleprompter-lock.json" es un target reservado');
+      } else if (t === MANAGED_DIR || t.startsWith(`${MANAGED_DIR}/`)) {
+        errors.push(`install: "${MANAGED_DIR}/" es un prefijo reservado`);
       } else if (seen.has(t)) {
         errors.push(`install: target duplicado "${t}"`);
-      } else if (seen.has([...seen].find((o) => t.startsWith(`${o}/`)))) {
+      } else if ([...seen].some((o) => t.startsWith(`${o}/`))) {
         errors.push(`install: target "${t}" queda dentro de otro target`);
       }
       seen.add(t);
@@ -154,9 +160,30 @@ const VALIDATORS = [
       errors.push('author.name: obligatorio dentro de author');
     }
   },
-  function checkPersonalization(manifest, _ctx, errors) {
+  function checkPersonalization(manifest, { pkgDir }, errors) {
     if (manifest.personalization === undefined) return;
-    checkRelativePath(manifest.personalization, 'personalization', errors);
+    if (!checkRelativePath(manifest.personalization, 'personalization', errors)) return;
+    const full = path.join(pkgDir, manifest.personalization);
+    if (!hasEntry(full)) {
+      errors.push(`personalization: no existe "${manifest.personalization}" dentro del paquete`);
+      return;
+    }
+    // A guide must be a file: directories cannot be displayed, and a
+    // dangling symlink resolves to nothing. statSync follows links.
+    let isFile = false;
+    try {
+      isFile = fs.statSync(full).isFile();
+    } catch { /* dangling link or unreadable entry */ }
+    if (!isFile) {
+      errors.push(`personalization: "${manifest.personalization}" no es un archivo`);
+      return;
+    }
+    // A symlink inside the package is fine, but its target must stay
+    // inside: materializing the guide copies real content.
+    const pkgReal = fs.realpathSync(pkgDir);
+    if (!fs.realpathSync(full).startsWith(`${pkgReal}${path.sep}`)) {
+      errors.push(`personalization: "${manifest.personalization}" apunta fuera del paquete`);
+    }
   },
   function checkMetadata(manifest, _ctx, errors) {
     if (manifest.metadata !== undefined && !isPlainObject(manifest.metadata)) {

package/src/paths.js

@@ -1,6 +1,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+// Reserved managed namespace: the tool, not the package, owns where
+// its own files land — same rule as teleprompter-lock.json. Install
+// targets may not point inside it; the personalization guide is
+// materialized under it as <name>/<basename of the declared file>.
+export const MANAGED_DIR = '.teleprompter';
+
+export function personalizationTarget(name, declaredPath) {
+  return `${MANAGED_DIR}/${name}/${path.basename(declaredPath)}`;
+}
+
 // "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.
@@ -45,3 +55,34 @@ export function resolvesUnder(root, dir) {
     return false;
   }
 }
+
+// A recorded path is the lock's data, not trusted input: it is
+// re-validated before use at the level the operation needs. The
+// chain level suffices when the leaf is treated atomically — lstat,
+// rm, hashing a link as a link — so only the parent chain must stay
+// inside the root.
+export function recordedChainSafe(root, rel) {
+  return isSafeRelative(rel)
+    && resolvesUnder(root, path.dirname(path.join(root, rel)));
+}
+
+// The leaf level of the recorded-path defense: for reads that follow
+// the leaf itself a parent-chain proof is not enough — a recorded
+// symlink pointing outside must not disclose its target, so the whole
+// path is resolved and the result must land inside the root. The
+// discriminated result keeps "unsafe" apart from "unreadable" because
+// callers report them differently.
+export function resolveRecordedPath(root, rel) {
+  if (!isSafeRelative(rel)) return { ok: false, reason: 'unsafe' };
+  let real;
+  try {
+    real = fs.realpathSync(path.join(root, rel));
+    const rootReal = fs.realpathSync(root);
+    if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+      return { ok: false, reason: 'unsafe' };
+    }
+  } catch {
+    return { ok: false, reason: 'unreadable' };
+  }
+  return { ok: true, real };
+}

package/src/plan.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { hashPath } from './hash.js';
-import { hasEntry, resolvesUnder } from './paths.js';
+import { classifyResource } from './drift.js';
+import { lockEntry } from './lock.js';
+import { hasEntry, personalizationTarget, resolvesUnder } from './paths.js';
 
 // Classifies each install entry by comparing the destination with the
 // package resource and the recorded history:
@@ -11,8 +13,10 @@ import { hasEntry, resolvesUnder } from './paths.js';
 //                    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 record = lockEntry(lock, manifest.name);
+  const recorded = new Map(
+    (record?.files ?? []).map((f) => [path.normalize(f.target), f.sha256]),
+  );
   const updatesAllowed = semverAtLeast(manifest.version, record?.version);
   const resources = manifest.install.map(({ source, target }) => {
     const dest = path.join(destDir, target);
@@ -24,7 +28,8 @@ export function buildPlan(pkgDir, manifest, destDir, creates, lock) {
     }
     const destHash = hashPath(dest);
     const status = destHash === hashPath(path.join(pkgDir, source)) ? 'identical'
-      : updatesAllowed && recorded.get(target) === destHash ? 'managed-update'
+      : updatesAllowed && recorded.get(path.normalize(target)) === destHash
+        ? 'managed-update'
         : 'conflict';
     if (status !== 'identical' && status !== 'conflict'
         && !resolvesUnder(destDir, path.dirname(dest))) {
@@ -39,6 +44,115 @@ export function buildPlan(pkgDir, manifest, destDir, creates, lock) {
   };
 }
 
+// The update plan adds a third comparison to the install plan: the
+// incoming content against the recorded hash tells whether the
+// version itself changed the resource, so each entry classifies by
+// what the version brings and what the user did with it:
+//   create    - the destination does not exist: a resource new in
+//               the version or one the user deleted — it is written
+//               again either way
+//   identical - the destination already holds the incoming content
+//   update    - the version changed the resource (incoming differs
+//               from the recorded hash) and the destination is still
+//               intact, so overwriting it is safe
+//   conflict  - the destination holds content that is not provably
+//               ours (a local edit or foreign) and differs from what
+//               the version offers — the user decides
+// Recorded targets the incoming manifest no longer ships are
+// retired: intact ones are removed (`retire`) — what is ours and
+// untouched is managed — while modified or unverifiable ones
+// degrade to conflicts marked `removal`, where `overwrite` means
+// remove and `skip` means keep; removal conflicts carry no `source`
+// — the executor must check `removal` before any copy. A retired
+// target already gone leaves the plan silently. Entries never
+// written (`skip`) and the managed guide — rewritten on every
+// install — never retire. One exception to removal conflicts: a
+// recorded guide the incoming version replaces — it declares its
+// own personalization — retires even with drift, because it stops
+// being the guide and keeping it would leave a file `guide` can
+// never show; an unverifiable one stays a conflict, since forcing
+// removal of an unsafe path would turn a resolvable decision into
+// an execution error.
+export function buildUpdatePlan(pkgDir, manifest, destDir, creates, lock) {
+  const record = lockEntry(lock, manifest.name);
+  if (record !== undefined && record.version === manifest.version) {
+    return {
+      upToDate: true, mkdirs: [], resources: [], conflicts: [], retired: [],
+    };
+  }
+  // Targets compare normalized: `./a.txt` and `a.txt` resolve to the
+  // same file, so a shipped target can never masquerade as retired.
+  const recorded = new Map(
+    (record?.files ?? []).map((f) => [path.normalize(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)) {
+      const status = resolvesUnder(destDir, path.dirname(dest)) ? 'create' : 'conflict';
+      return { source, target, status };
+    }
+    const destHash = hashPath(dest);
+    const pkgHash = hashPath(path.join(pkgDir, source));
+    const recHash = recorded.get(path.normalize(target));
+    let status;
+    if (destHash === pkgHash) status = 'identical';
+    else if (updatesAllowed && destHash === recHash && pkgHash !== recHash) {
+      status = 'update';
+    } else status = 'conflict';
+    if (status !== 'identical' && status !== 'conflict'
+        && !resolvesUnder(destDir, path.dirname(dest))) {
+      return { source, target, status: 'conflict' };
+    }
+    return { source, target, status };
+  });
+  const shipped = new Set(manifest.install.map(({ target }) => path.normalize(target)));
+  // The managed guide is excluded from retirements only while the
+  // incoming manifest still declares it — the incoming target is the
+  // one that gets rewritten; when the version drops the field —or
+  // renames the file— the old guide retires like any other file.
+  const guideTarget = manifest.personalization === undefined
+    ? undefined
+    : path.normalize(personalizationTarget(manifest.name, manifest.personalization));
+  // The lock is untrusted data: a hand-edited `personalization` that
+  // is not a string must not crash the plan.
+  const replacedGuide = guideTarget === undefined || typeof record?.personalization !== 'string'
+    ? undefined
+    : path.normalize(record.personalization);
+  const retired = [];
+  const removals = (record?.files ?? [])
+    .filter((f) => f.action !== 'skip' && path.normalize(f.target) !== guideTarget
+      && !shipped.has(path.normalize(f.target)))
+    .flatMap((f) => {
+      const drift = classifyResource(destDir, f);
+      if (drift === 'intact') return [{ target: f.target, status: 'retire' }];
+      if (drift === 'missing') return [];
+      if (drift === 'modified' && path.normalize(f.target) === replacedGuide) {
+        return [{ target: f.target, status: 'retire' }];
+      }
+      return [{ target: f.target, status: 'conflict', removal: true }];
+    });
+  for (const entry of removals) {
+    (entry.status === 'retire' ? retired : resources).push(entry);
+  }
+  return {
+    upToDate: false,
+    mkdirs: creates,
+    resources,
+    conflicts: resources.filter((r) => r.status === 'conflict'),
+    retired,
+  };
+}
+
+// Resolving is the plan's own operation: a conflict admits exactly
+// `overwrite` or `skip` and the assignment lives here so callers
+// decide per conflict — flag, prompt, whatever asks — without
+// touching the entries. `decide` answers one conflict at a time, in
+// plan order, and may return a promise.
+export async function resolveConflicts(plan, decide) {
+  for (const r of plan.conflicts) r.resolution = await decide(r);
+}
+
 // Downgrades are not managed updates: writing older content over a
 // newer recorded install must surface as a conflict, not silently
 // pass as safe.