@aksp/opencrew 1.6.2 → 1.6.3

package/src/lib/blocos.js

@@ -0,0 +1,148 @@
+// Marked blocks (R2 rule 4). `deliverBlock` is the ONE writer of every `opencrew:start … end`
+// block — IDE bridges, AGENTS.md, .gitignore, .env.example — for init, update and repair.
+// The manifest records each block (`<file>#opencrew` → sha256 of the block, markers included,
+// with LF), so a block the user edited is told apart from one that is just older: the whole
+// file is copied to .opencrew-backup/ before a block that differs from its record (or has
+// none) is rewritten. CRLF/LF is never a difference, and what is written follows the file.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { exists } from './fsx.js';
+import { deliverFile, backupFile, hashOf } from './manifest.js';
+
+// The file is handled byte by byte (latin1 goes there and back unchanged): whatever its encoding,
+// no byte of the user outside the block changes. `bytesOf` = UTF-8 text in that same form.
+const bytesOf = (text) => Buffer.from(text, 'utf8').toString('latin1');
+const BOM = bytesOf(String.fromCharCode(0xfeff));
+const isUtf16 = (raw) => (raw[0] === 0xff && raw[1] === 0xfe) || (raw[0] === 0xfe && raw[1] === 0xff);
+
+// Files of the user where the block goes at the END, between `#` comment markers.
+const AT_END = new Set(['.gitignore', '.env.example']);
+const ONLY_THE_BLOCK = '(só o bloco do OpenCrew foi regravado; o resto do arquivo não mudou)';
+
+/** Key of a block in the manifest (`file` = path relative to the project root, with `/`). */
+export const blockKey = (file) => `${file}#opencrew`;
+
+const markersOf = (file) => (AT_END.has(file)
+  ? ['# opencrew:start', '# opencrew:end']
+  : ['<!-- opencrew:start -->', '<!-- opencrew:end -->']);
+
+/**
+ * Complete blocks of `text`, as [from, to) ranges. Innermost start only: an orphan start
+ * marker (its end deleted by hand) never makes a block swallow the user lines after it.
+ */
+export function blockRanges(text, file) {
+  const [start, end] = markersOf(file);
+  const found = [];
+  let pos = 0;
+  for (let e = text.indexOf(end); e !== -1; e = text.indexOf(end, pos)) {
+    const s = text.lastIndexOf(start, e - start.length);
+    if (s >= pos && s + start.length <= e) found.push([s, e + end.length]);
+    pos = e + end.length;
+  }
+  return found;
+}
+
+/** True when a marked block of `file` contains `needle`; text outside the blocks never counts. */
+export async function blockHas(target, file, needle) {
+  const dest = path.join(target, file);
+  if (!(await exists(dest))) return false;
+  const text = await fs.readFile(dest, 'utf8');
+  return blockRanges(text, file).some(([from, to]) => text.slice(from, to).includes(needle));
+}
+
+function replaceRanges(text, ranges, block) {
+  let out = '';
+  let pos = 0;
+  for (const [from, to] of ranges) {
+    out += text.slice(pos, from) + block;
+    pos = to;
+  }
+  return out + text.slice(pos);
+}
+
+/**
+ * What delivering `marked` does to a file whose content is `text` (null = no file):
+ * the action, the new content (none when kept) and the hash of each block found.
+ */
+function planBlock(file, text, marked) {
+  if (text === null) return { action: 'created', text: `${bytesOf(marked)}\n`, hashes: [] };
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const block = bytesOf(marked).replace(/\n/g, eol);
+  const ranges = blockRanges(text, file);
+  if (!ranges.length) {
+    const bom = text.startsWith(BOM) ? BOM : '';
+    const added = AT_END.has(file)
+      ? `${text.replace(/[ \t\r\n]+$/, '')}${eol}${eol}${block}${eol}`
+      : `${bom}${block}${eol}${eol}${text.slice(bom.length).replace(/^[ \t\r\n]+/, '')}`;
+    return { action: 'added', text: added, hashes: [] };
+  }
+  const hashes = ranges.map(([from, to]) => hashOf(Buffer.from(text.slice(from, to), 'latin1').toString('utf8')));
+  if (hashes.every((h) => h === hashOf(marked))) return { action: 'kept', hashes };
+  return { action: 'updated', text: replaceRanges(text, ranges, block), hashes };
+}
+
+/**
+ * Put `content` between the opencrew markers of `file` (path relative to the project root,
+ * with `/`) and record the block in `ctx.files`.
+ * - no file → `created`; file with no block → `added` at the top (at the end in .gitignore
+ *   and .env.example), the user's content kept, no copy;
+ * - block equal to the new one → `kept`, nothing written;
+ * - otherwise → `updated`: only the block is rewritten, in the line ending of the file. The
+ *   whole file is copied first unless the block is exactly what the manifest recorded.
+ * @returns {Promise<{file:string, action:'created'|'added'|'updated'|'kept', copied:boolean, block:true}>}
+ *   also pushed to `ctx.blocks`. `copied` = this call made the backup copy.
+ */
+export async function deliverBlock(ctx, file, content) {
+  const [start, end] = markersOf(file);
+  const marked = `${start}\n${content.replace(/\r\n/g, '\n').trimEnd()}\n${end}`;
+  const dest = path.join(ctx.target, file);
+  const raw = (await exists(dest)) ? await fs.readFile(dest) : null;
+  const plan = planBlock(file, raw && raw.toString('latin1'), marked);
+  const record = ctx.manifest?.files?.[blockKey(file)];
+  const edited = plan.action === 'updated' && !plan.hashes.every((h) => h === record);
+  // A UTF-16 file cannot take a UTF-8 block without damage: the whole file is copied first.
+  const risky = raw && plan.text !== undefined && isUtf16(raw);
+  const copied = (edited || risky) && (await backupFile(ctx, file));
+  if (plan.text !== undefined) {
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.writeFile(dest, Buffer.from(plan.text, 'latin1'));
+  }
+  ctx.files[blockKey(file)] = hashOf(marked);
+  const result = { file, action: plan.action, copied, block: true };
+  ctx.blocks.push(result);
+  return result;
+}
+
+/**
+ * Write the bridge files of `ides`, each path once: a file with frontmatter is delivered whole
+ * (replaced only when `overwrite`), the others by marked block.
+ * @returns {Promise<Array<{ide:object, file:string, action:string, copied:boolean, block?:true, shared?:true}>>}
+ *   one entry per file of each IDE, in order. `shared` = the path had already been written for
+ *   an earlier IDE of the list (same action; count copies by `ctx.copied`, not by these entries).
+ */
+export async function deliverBridges(ctx, ides, { overwrite = true } = {}) {
+  const byPath = new Map();
+  const results = [];
+  for (const ide of ides) {
+    for (const f of ide.files) {
+      if (byPath.has(f.path)) {
+        results.push({ ide, ...byPath.get(f.path), shared: true });
+        continue;
+      }
+      const result = f.content.startsWith('---')
+        ? await deliverFile(ctx, path.join(ctx.target, f.path), f.content, { overwrite })
+        : await deliverBlock(ctx, f.path, f.content);
+      byPath.set(f.path, result);
+      results.push({ ide, ...result });
+    }
+  }
+  return results;
+}
+
+/**
+ * Line of a list of backup copies: a file copied because of its block says that only the
+ * block was rewritten. `shown` = how the caller prints the file (default: its path).
+ */
+export function copyLine(ctx, file, shown = file) {
+  return ctx.blocks.some((b) => b.copied && b.file === file) ? `${shown} ${ONLY_THE_BLOCK}` : shown;
+}

package/src/lib/deteccao.js

@@ -0,0 +1,69 @@
+// Which IDEs are installed in a project (spec R2, rules 1 and 2) — shared by `update` and
+// `init --repair-bridges`. An IDE is proved by a FILE, never by the word "opencrew" somewhere:
+//   (a) a bridge file that only this IDE writes, on a path that has "opencrew" in it: it exists;
+//   (b) an instruction file the IDE shares with the user (no "opencrew" in the path): it has
+//       the start marker of the block, or the line of the title OpenCrew generates in it.
+// An IDE with no file of its own (today, the Codex) counts only when its file is there and no
+// detected IDE writes the same path. A user file that only cites the word proves nothing.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { exists } from './fsx.js';
+import { IDES } from './ides.js';
+
+const START = '<!-- opencrew:start -->';
+
+/**
+ * The instruction files shared with the user and the title generated in each since 1.0.0.
+ * Fixed here on purpose, never read from today's bridge content: a title changed in ides.js
+ * must not hide the installs made by the versions that wrote the old one (up to 1.2.2 the
+ * file had no marker — the title is all there is). Pinned by R2-01d in tests/ides.test.js.
+ */
+export const USER_FILE_TITLES = Object.freeze({
+  'CLAUDE.md': '# opencrew — Project Instructions',
+  '.github/copilot-instructions.md': '# opencrew — Copilot Instructions',
+  'GEMINI.md': '# opencrew — Gemini CLI',
+  'QWEN.md': '# opencrew — Qwen Code',
+});
+
+const BOM = String.fromCharCode(0xfeff);
+
+/** A line of a file as OpenCrew compares it: no BOM in front, no CR at the end. */
+export function plainLine(raw) {
+  const line = raw.startsWith(BOM) ? raw.slice(1) : raw;
+  return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+
+const writersOf = (file) => IDES.filter((ide) => ide.files.some((f) => f.path === file));
+const ownFiles = (ide) => ide.files.filter((f) => writersOf(f.path).length === 1);
+
+/** True when the bridge file `file` (path relative to the root, with `/`) proves its IDE. */
+async function proves(target, file) {
+  const dest = path.join(target, file);
+  if (!(await exists(dest))) return false;
+  if (file.includes('opencrew')) return true;
+  const text = await fs.readFile(dest, 'utf8');
+  return text.includes(START) || text.split('\n').map(plainLine).includes(USER_FILE_TITLES[file]);
+}
+
+async function provesAny(target, files) {
+  for (const f of files) if (await proves(target, f.path)) return true;
+  return false;
+}
+
+/**
+ * IDEs installed in `target`, in the order of `IDES`.
+ * @param {string} target project root
+ * @returns {Promise<Array<object>>} entries of `IDES`
+ */
+export async function detectInstalledIdes(target) {
+  const byOwnFile = [];
+  for (const ide of IDES) if (await provesAny(target, ownFiles(ide))) byOwnFile.push(ide);
+  // Rule 2: a path that a detected IDE writes proves nothing about an IDE with no own file.
+  const free = (f) => !writersOf(f.path).some((ide) => byOwnFile.includes(ide));
+  const found = [];
+  for (const ide of IDES) {
+    const alone = !ownFiles(ide).length && (await provesAny(target, ide.files.filter(free)));
+    if (alone || byOwnFile.includes(ide)) found.push(ide);
+  }
+  return found;
+}

package/src/lib/fsx.js

@@ -50,61 +50,7 @@ export async function writeFileSafe(p, content, { overwrite = true } = {}) {
   return true;
 }
 
-/**
- * Write a bridge file using marked-block strategy.
- * - File doesn't exist → creates with content wrapped in HTML markers
- * - File exists with markers → replaces only the block between markers
- * - File exists without markers → adds the marked block (prepend or append), preserving
- *   existing content byte for byte
- *
- * @param {string}   p       File path
- * @param {string}   block   Content to place between markers
- * @param {object}   opts
- * @param {string}   opts.marker    Marker name (default: 'opencrew')
- * @param {'html'|'hash'} opts.comment  `<!-- x:start -->` (markdown) or `# x:start` (.gitignore, .env)
- * @param {'prepend'|'append'} opts.position  Where a new block goes in an unmarked file
- * @returns {Promise<{written: boolean, merged: boolean}>}
- */
-export async function writeBridgeFile(p, block, { marker = 'opencrew', comment = 'html', position = 'prepend' } = {}) {
-  const [start, end] = comment === 'hash'
-    ? [`# ${marker}:start`, `# ${marker}:end`]
-    : [`<!-- ${marker}:start -->`, `<!-- ${marker}:end -->`];
-  const marked = `${start}\n${block.trimEnd()}\n${end}`;
-
-  if (!(await exists(p))) {
-    await ensureDir(path.dirname(p));
-    await fs.writeFile(p, marked + '\n');
-    return { written: true, merged: false };
-  }
-
-  const existing = await fs.readFile(p, 'utf8');
-
-  // Already has markers → replace just the block, keep everything else
-  if (existing.includes(start) && existing.includes(end)) {
-    // Innermost block only: an orphan start marker (end deleted by hand) must never make
-    // the match swallow the user lines between it and the real block.
-    const updated = existing.replace(
-      new RegExp(`${escapeRx(start)}(?:(?!${escapeRx(start)})[\\s\\S])*?${escapeRx(end)}`, 'g'),
-      () => marked,
-    );
-    if (updated !== existing) {
-      await fs.writeFile(p, updated);
-      return { written: true, merged: false };
-    }
-    return { written: false, merged: false };
-  }
-
-  // User content exists → add the block, preserve everything
-  const merged = position === 'append'
-    ? `${existing.trimEnd()}\n\n${marked}\n`
-    : `${marked}\n\n${existing.trimStart()}`;
-  await fs.writeFile(p, merged);
-  return { written: true, merged: true };
-}
-
-function escapeRx(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
+// Marked blocks (`opencrew:start … opencrew:end`) are written by `deliverBlock`, in ./blocos.js.
 
 export async function readFile(p) {
   return fs.readFile(p, 'utf8');

package/src/lib/ides.js

@@ -56,6 +56,10 @@ export const AGENTS_BRIDGE = `# opencrew\n\n${ACTIVATION}\n\nType \`/opencrew\`
 // Marker that identifies the maintainer STATUS.md section leaked into CLAUDE.md by 1.4.0/1.4.1.
 export const LEAKED_STATUS_SECTION = '## STATUS.md (gestão de sessão)';
 
+// The title of CLAUDE.md, GEMINI.md, QWEN.md and copilot-instructions.md (files shared with
+// the user) is how `update` recognizes a bridge written up to 1.2.2, which has no marker. The
+// four titles are fixed in ./deteccao.js and pinned by R2-01d (tests/ides.test.js): to change
+// one here, keep the old one there.
 const render = (title, extra = '') =>
   `# ${title}\n\n${BRIDGE}${extra ? `\n\n${extra}` : ''}\n`;
 

package/src/lib/legado.js

@@ -0,0 +1,142 @@
+// Old text of the bridges (spec R2, rule 3). Up to 1.2.2 the five bridges with no frontmatter
+// were written as WHOLE files, telling the AI to adopt the OpenCrew role always. Since 1.3.0
+// the bridge lives in a marked block, and a file that kept the old text outside the block
+// keeps giving that order. `update` and `init --repair-bridges` take it out — only when it
+// is exactly what was generated (CRLF tolerated), and after copying the whole file. An edited
+// one (only the title or the "adopt" sentence is left) is never touched: it is reported.
+// `src/lib/ides.js` wrote ONE text per file from v1.0.0 to v1.2.2; they are fixed below.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { exists } from './fsx.js';
+import { backupFile } from './manifest.js';
+import { blockRanges } from './blocos.js';
+import { USER_FILE_TITLES, plainLine } from './deteccao.js';
+
+const OLD_BRIDGE = `Read \`AGENTS.md\` at the project root and adopt the opencrew system role.
+Follow all initialization, command routing, and workflow instructions defined there.
+
+If invoked with arguments (e.g. \`/opencrew create ...\`, \`/opencrew run ...\`),
+route to the matching action from the Command Routing table in AGENTS.md.
+If invoked without arguments, show the Main Menu.`;
+
+const OLD_CLAUDE_MD = `This project uses **opencrew**, a multi-agent orchestration framework.
+The full system definition lives in \`AGENTS.md\` — read it and adopt that role.
+
+Type \`/opencrew\` to open the main menu.
+
+## Notes for Claude Code
+
+- All checkpoint questions use \`AskUserQuestion\`.
+- opencrew ships its own Playwright MCP (\`.mcp.json\`); disable the native Playwright plugin.
+- Do not manually edit files under \`_opencrew/core/\` unless you know what you're doing.`;
+
+const TITLES = { ...USER_FILE_TITLES, '.trae/rules/opencrew.md': '# opencrew — Trae' };
+
+// path → the lines of the old text of that file: title, blank line, body.
+const OLD_LINES = Object.fromEntries(Object.entries(TITLES).map(([file, title]) =>
+  [file, [title, '', ...(file === 'CLAUDE.md' ? OLD_CLAUDE_MD : OLD_BRIDGE).split('\n')]]));
+
+const REMOVED = (file, copy) => `${file}: removi o texto antigo do OpenCrew (instalações até a 1.2.2), que mandava adotar o papel do OpenCrew sempre. O bloco novo ficou no lugar e o resto do arquivo não mudou. Cópia em ${copy}.`;
+const EDITED = (file) => `${file} ainda tem um texto antigo do OpenCrew, alterado depois da instalação, que manda adotar o papel do OpenCrew sempre. Não mexi nele. Para o OpenCrew só agir quando chamado, apague à mão o trecho que começa em \`# opencrew — …\` fora do bloco \`opencrew:start\` / \`opencrew:end\`.`;
+
+/**
+ * Lines of `text` — where each starts and ends (line break included), its content with no
+ * BOM and no CR, and whether it is outside every marked block of `file`.
+ */
+function linesOf(text, file) {
+  const blocks = blockRanges(text, file);
+  const lines = [];
+  let from = 0;
+  for (const raw of text.split('\n')) {
+    const to = Math.min(from + raw.length + 1, text.length);
+    const outside = !blocks.some(([start, end]) => from < end && to > start);
+    lines.push({ from, to, outside, text: plainLine(raw) });
+    from = to;
+  }
+  return lines;
+}
+
+/** [from, to) of the first exact copy of the old text of `file` outside the blocks, or null. */
+function findExact(text, file) {
+  const old = OLD_LINES[file];
+  const lines = linesOf(text, file);
+  for (let i = 0; i + old.length <= lines.length; i++) {
+    const run = lines.slice(i, i + old.length);
+    if (run.every((line, k) => line.outside && line.text === old[k])) return [run[0].from, run.at(-1).to];
+  }
+  return null;
+}
+
+/** `text` up to its last character that is not a line break. */
+function withoutEndBreaks(text) {
+  let end = text.length;
+  while (end > 0 && (text[end - 1] === '\n' || text[end - 1] === '\r')) end -= 1;
+  return text.slice(0, end);
+}
+
+/**
+ * `text` with every exact copy of the old text of `file` taken out; the rest stays byte for
+ * byte. Old text that was the end of the file takes the blank lines above it along: the file
+ * ends where the text before it ends (as a new install, when only the block is left).
+ */
+function strip(text, file) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  let out = text;
+  for (let cut = findExact(out, file); cut; cut = findExact(out, file)) {
+    const [before, after] = [out.slice(0, cut[0]), out.slice(cut[1])];
+    out = after.trim() ? before + after : `${withoutEndBreaks(before)}${eol}`;
+  }
+  return out;
+}
+
+/** True when the title or the "adopt" sentence of the old text of `file` is outside the blocks. */
+function hasTraces(text, file) {
+  const [title] = OLD_LINES[file];
+  const adopt = OLD_LINES[file].find((line) => line.includes('adopt'));
+  return linesOf(text, file).some((line) => line.outside && (line.text === title || line.text.includes(adopt)));
+}
+
+/**
+ * Take the old text out of `file`, or just copy the file when `write` is false. A file in
+ * which only traces of the old text are left is not touched: it goes to `ctx.legacy`.
+ */
+async function clean(ctx, file, write) {
+  const dest = path.join(ctx.target, file);
+  if (!(await exists(dest))) return;
+  const text = await fs.readFile(dest, 'utf8');
+  const stripped = strip(text, file);
+  if (stripped !== text) await backupFile(ctx, file); // once per run: the file as it was
+  if (!write) return;
+  if (stripped !== text) {
+    await fs.writeFile(dest, stripped);
+    ctx.legacy.push({ file, action: 'removed' });
+  }
+  if (hasTraces(stripped, file)) ctx.legacy.push({ file, action: 'edited' });
+}
+
+/**
+ * Run `write` — what delivers the bridges of `ides` (`deliverBridges`, ./blocos.js) — with
+ * rule 3 around it. Before: a file with the exact old text outside its block is copied whole,
+ * so the copy holds the file as it was and the block written next does not claim that copy as
+ * "only the block was rewritten". After, with the new block in place: the old text leaves.
+ * What happened to each file goes to `ctx.legacy` (`{file, action: 'removed' | 'edited'}`).
+ * @param {object} ctx delivery context (`newDelivery`, ./manifest.js)
+ * @param {Array<object>} ides entries of `IDES` whose bridges `write` delivers
+ * @param {() => Promise<T>} write
+ * @returns {Promise<T>} what `write` returned
+ * @template T
+ */
+export async function withoutLegacy(ctx, ides, write) {
+  const paths = new Set(ides.flatMap((ide) => ide.files.map((f) => f.path)));
+  const files = [...paths].filter((file) => OLD_LINES[file]);
+  for (const file of files) await clean(ctx, file, false);
+  const result = await write();
+  for (const file of files) await clean(ctx, file, true);
+  return result;
+}
+
+/** One line to print per entry of `ctx.legacy` (spec R2, §6), with where the copy is. */
+export function legacyLines(ctx) {
+  const dir = path.relative(ctx.target, ctx.backupDir).split(path.sep).join('/');
+  return ctx.legacy.map(({ file, action }) => (action === 'removed' ? REMOVED(file, `${dir}/${file}`) : EDITED(file)));
+}

package/src/lib/manifest.js

@@ -14,76 +14,117 @@ const normalize = (buf) => {
   const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
   return b.includes(0) ? b : Buffer.from(b.toString('utf8').replace(/\r\n/g, '\n'));
 };
-const sha = (buf) => createHash('sha256').update(normalize(buf)).digest('hex');
+/** sha256 of a file or text as the manifest records it (text with LF line endings). */
+export const hashOf = (buf) => createHash('sha256').update(normalize(buf)).digest('hex');
 const rel = (target, abs) => path.relative(target, abs).split(path.sep).join('/');
 
-/** @returns {Promise<{files: Record<string,string>} | null>} null = no (or unreadable) manifest */
+/** A JSON object: not null, not an array. */
+export const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The manifest, when it can be used: valid JSON whose `files` is an object with at least one
+ * entry. @returns {Promise<{files: Record<string,string>} | null>} null = none, or unreadable
+ */
 export async function readManifest(target) {
   try {
     const data = JSON.parse(await fs.readFile(path.join(target, MANIFEST), 'utf8'));
-    return data && typeof data.files === 'object' ? data : null;
+    return isRecord(data?.files) && Object.keys(data.files).length ? data : null;
   } catch {
     return null;
   }
 }
 
+/**
+ * R2 rule 12: the manifest file exists but `readManifest` cannot use it (a merge conflict, a
+ * file cut short). The run goes on as in a project with no record — whatever differs from the
+ * package is copied first — and says so with UNREADABLE. A missing manifest is not unreadable.
+ */
+export async function manifestUnreadable(target) {
+  return (await exists(path.join(target, MANIFEST))) && !(await readManifest(target));
+}
+
+/** Spec R2 §6: `update` before it rewrites, `summary` in its list of copies, `repair` in the repair. */
+export const UNREADABLE = {
+  update: 'O registro de arquivos (`_opencrew/manifest.json`) está ilegível. Vou tratar esta atualização como a de um projeto sem registro: todo arquivo diferente do pacote novo é copiado para `.opencrew-backup/` antes de ser substituído. O registro é refeito no fim.',
+  summary: 'O registro estava ilegível: guardamos tudo o que diferia do pacote novo. Daqui em diante, só o que você editar.',
+  repair: 'O registro de arquivos (`_opencrew/manifest.json`) está ilegível; o reparo não o refaz. Rode `npx @aksp/opencrew@latest update` para refazer.',
+};
+
 export async function writeManifest(target, version, files) {
   const sorted = Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)));
   await fs.writeFile(path.join(target, MANIFEST), JSON.stringify({ version, files: sorted }, null, 2) + '\n');
 }
 
 /**
- * Delivery context shared by one init/update run.
+ * Delivery context shared by one init/update/repair run. `files` = what goes into the next
+ * manifest; `copied` = files copied to `backupDir`; `blocks` = one result per marked block
+ * written by `deliverBlock` (src/lib/blocos.js); `legacy` = one entry per bridge file where
+ * the old text of ≤ 1.2.2 was removed or found edited (src/lib/legado.js).
  * @param {string} target project root
- * @param {{files:Record<string,string>}|null} manifest previous manifest (null = none)
+ * @param {{files:Record<string,string>}|null} manifest previous manifest (null = none, or unreadable)
  */
 export function newDelivery(target, manifest) {
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-  return { target, manifest, backupDir: path.join(target, '.opencrew-backup', stamp), files: {}, copied: [], written: 0 };
+  const backupDir = path.join(target, '.opencrew-backup', stamp);
+  return { target, manifest, backupDir, files: {}, copied: [], blocks: [], legacy: [], written: 0 };
+}
+
+/**
+ * Copy the file `key` (path relative to the project root, with `/`) to the backup dir before it
+ * is changed. Once per run: a second change to the same file must not replace the copy of how
+ * the file was. @returns {Promise<boolean>} true when this call made the copy
+ */
+export async function backupFile(ctx, key) {
+  if (ctx.copied.includes(key)) return false;
+  const copy = path.join(ctx.backupDir, key);
+  await fs.mkdir(path.dirname(copy), { recursive: true });
+  await fs.copyFile(path.join(ctx.target, key), copy);
+  ctx.copied.push(key);
+  return true;
 }
 
 /**
  * Put `content` at `dest`. Missing → write. Equal → nothing. Different → only if `overwrite`,
  * copying the current file to the backup dir first when the user edited it.
+ * @returns {Promise<{file:string, action:'created'|'updated'|'kept', copied:boolean}>}
  */
 export async function deliverFile(ctx, dest, content, { overwrite }) {
-  const key = rel(ctx.target, dest);
-  const fresh = sha(content);
+  const file = rel(ctx.target, dest);
+  const fresh = hashOf(content);
   if (!(await exists(dest))) {
     await fs.mkdir(path.dirname(dest), { recursive: true });
     await fs.writeFile(dest, content);
-    ctx.files[key] = fresh;
+    ctx.files[file] = fresh;
     ctx.written += 1;
-    return;
-  }
-  const current = sha(await fs.readFile(dest));
-  if (current === fresh) {
-    ctx.files[key] = fresh;
-    return;
-  }
-  if (!overwrite) return; // the user's version stays (and is not tracked)
-  const edited = ctx.manifest ? ctx.manifest.files[key] !== current : true;
-  if (edited) {
-    const copy = path.join(ctx.backupDir, key);
-    await fs.mkdir(path.dirname(copy), { recursive: true });
-    await fs.copyFile(dest, copy);
-    ctx.copied.push(key);
+    return { file, action: 'created', copied: false };
   }
+  const current = hashOf(await fs.readFile(dest));
+  if (current === fresh) ctx.files[file] = fresh;
+  // Different and no `overwrite`: the user's version stays (and is not tracked).
+  if (current === fresh || !overwrite) return { file, action: 'kept', copied: false };
+  const edited = ctx.manifest ? ctx.manifest.files[file] !== current : true;
+  const copied = edited && (await backupFile(ctx, file));
   await fs.writeFile(dest, content);
-  ctx.files[key] = fresh;
+  ctx.files[file] = fresh;
   ctx.written += 1;
+  return { file, action: 'updated', copied };
 }
 
-/** deliverFile for every file under `src`, mirrored into `dest`. */
+/**
+ * deliverFile for every file under `src`, mirrored into `dest`.
+ * @returns {Promise<Array<{file:string, action:string, copied:boolean}>>} one result per file
+ */
 export async function deliverTree(ctx, src, dest, { overwrite, skip = () => false }) {
+  const results = [];
   async function walk(dir) {
     for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
       const from = path.join(dir, entry.name);
       const relPath = path.relative(src, from).split(path.sep).join('/');
       if (skip(relPath)) continue;
       if (entry.isDirectory()) await walk(from);
-      else await deliverFile(ctx, path.join(dest, relPath), await fs.readFile(from), { overwrite });
+      else results.push(await deliverFile(ctx, path.join(dest, relPath), await fs.readFile(from), { overwrite }));
     }
   }
   await walk(src);
+  return results;
 }