@aksp/opencrew 1.6.2 → 1.7.0

package/src/commands/update.js

@@ -1,23 +1,37 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { templatesDir, packageJsonPath } from '../lib/paths.js';
-import { exists, writeFileSafe, readJson, writeBridgeFile, readFile } from '../lib/fsx.js';
-import { AGENTS_BRIDGE, LEAKED_STATUS_SECTION, ideById } from '../lib/ides.js';
-import { readManifest, writeManifest, newDelivery, deliverTree, deliverFile } from '../lib/manifest.js';
-import { compareVersions, detectInstalledIdes, refreshBridges, mergeMcp, findLegacyBridges } from '../lib/migrations.js';
+import { exists, writeFileSafe, readJson, readFile } from '../lib/fsx.js';
+import { AGENTS_BRIDGE, LEAKED_STATUS_SECTION } from '../lib/ides.js';
+import { readManifest, manifestUnreadable, UNREADABLE, writeManifest, newDelivery, deliverTree, deliverFile } from '../lib/manifest.js';
+import { deliverBlock, deliverBridges, blockHas } from '../lib/blocos.js';
+import { detectInstalledIdes } from '../lib/deteccao.js';
+import { withoutLegacy } from '../lib/legado.js';
+import { updateMcp } from '../lib/mcp.js';
+import { compareVersions, installedVersion, findLeftovers } from '../lib/migrations.js';
+import { say, recreatedLines, updateSummary, UNTOUCHED } from '../lib/resumo.js';
 import { c, log, info, ok, warn, err, step } from '../lib/ui.js';
 
+const tpl = (...p) => path.join(templatesDir, ...p);
+
 // `update` brings EVERY improvement to people who already use OpenCrew (AGENTS.md rule 14),
 // without losing what they made:
 //   - _opencrew/core and catalog skills are replaced — a file the user edited is copied to
 //     .opencrew-backup/<date>/ first (manifest of hashes; none = copy whatever differs);
-//   - new framework folders (agents, config, crew templates) arrive without overwriting;
-//   - bridges of the IDEs already installed are refreshed (never new IDEs);
-//   - crews/, _opencrew/_memory/, _opencrew/best-practices.local/ and .env are never touched.
+//   - new framework folders (agents, config, crew templates) arrive without overwriting — a
+//     crew template the user deleted comes back, and the output lists it;
+//   - bridges of the IDEs already installed are refreshed (never new IDEs — an IDE is proved by
+//     a file, src/lib/deteccao.js), and so are the opencrew blocks of AGENTS.md and .gitignore
+//     — a block the user edited is copied first; the text bridges had up to 1.2.2 leaves the
+//     outside of the block, with a copy, only when it is still exactly what was generated;
+//   - the Playwright server of .mcp.json is delivered once (the manifest records it) and never
+//     put back; the file is copied before any rewrite (src/lib/mcp.js);
+//   - the crews the user created, _opencrew/_memory/, _opencrew/best-practices.local/ and .env
+//     are never touched.
+// Every step returns what it did, and the summary only says that (src/lib/resumo.js).
 export async function update(opts = {}) {
   const target = process.cwd();
-  const pkg = await readJson(packageJsonPath);
-  const version = pkg.version;
+  const { version } = await readJson(packageJsonPath);
 
   if (!(await exists(path.join(target, '_opencrew', 'core')))) {
     warn('No opencrew workspace found here.');
@@ -25,15 +39,15 @@ export async function update(opts = {}) {
     return;
   }
 
-  const versionFile = path.join(target, '_opencrew', '.opencrew-version');
-  const current = (await exists(versionFile))
-    ? (await fs.readFile(versionFile, 'utf8')).trim()
-    : 'unknown';
-  const newer = current !== 'unknown' && compareVersions(current, version) > 0;
-
+  const current = (await installedVersion(target)) ?? 'unknown';
   log(`\n${c.bold(c.cyan('opencrew update'))}`);
   log(c.dim(`Installed: ${current}  →  Package: ${version}\n`));
+  if (canApply(opts, current, version)) await apply(target, version);
+}
 
+/** `--check` only reports, and a package older than the workspace stops: false = write nothing. */
+function canApply(opts, current, version) {
+  const newer = current !== 'unknown' && compareVersions(current, version) > 0;
   if (opts.check) {
     if (current === version) ok(`Up to date (v${version}).`);
     else if (newer) info(`A versão instalada (v${current}) é mais nova que este pacote (v${version}).`);
@@ -42,82 +56,82 @@ export async function update(opts = {}) {
       info(`Run ${c.cyan('npx @aksp/opencrew update')} to apply.`);
       process.exitCode = 1;
     }
-    return;
+    return false;
   }
-
   if (newer) {
     err(`Você tem a v${current} instalada e este pacote é a v${version} (mais antigo). Nada foi alterado.`);
     info(`Use ${c.cyan('npx @aksp/opencrew@latest update')}.`);
     process.exitCode = 1;
-    return;
   }
+  return !newer;
+}
 
+async function apply(target, version) {
+  // A manifest that exists but cannot be used is said so, then treated as none (R2 rule 12).
   const manifest = await readManifest(target);
+  const unreadable = !manifest && (await manifestUnreadable(target));
+  if (unreadable) warn(UNREADABLE.update);
   const ctx = newDelivery(target, manifest);
-  const tpl = (...p) => path.join(templatesDir, ...p);
-  const dest = (...p) => path.join(target, ...p);
 
   step('Refreshing framework');
-  await deliverTree(ctx, tpl('_opencrew', 'core'), dest('_opencrew', 'core'), { overwrite: true });
-  await deliverFile(ctx, dest('_opencrew', 'core', 'system.md'), await fs.readFile(tpl('AGENTS.md')), { overwrite: true });
-  await deliverTree(ctx, tpl('skills'), dest('skills'), { overwrite: true });
-  // New framework folders (e.g. base agents since 1.3.2): only what is missing.
-  for (const dir of ['agents', 'config', '_investigations']) {
-    await deliverTree(ctx, tpl('_opencrew', dir), dest('_opencrew', dir), { overwrite: false });
-  }
-  await deliverTree(ctx, tpl('crews'), dest('crews'), { overwrite: false });
+  const crews = await refreshFramework(ctx);
   ok(`Framework and catalog skills refreshed (${ctx.written} files written)`);
+  say(recreatedLines(crews));
 
   step('Refreshing IDE bridges');
-  await refreshAgentsBridge(target);
-  const ides = await detectInstalledIdes(target);
-  await refreshBridges(ctx, ides);
-  ok(ides.length ? `Bridges refreshed: ${ides.map((i) => i.label).join(', ')}` : 'No IDE bridges found to refresh');
-  await removeLeakedStatusSection(target);
-
-  const mcp = await mergeMcp(target, tpl('.mcp.json'));
-  if (mcp === 'updated' || mcp === 'created') ok(`.mcp.json (Playwright: ${mcp === 'created' ? 'created' : 'saída em _opencrew/logs/playwright/'})`);
-  if (mcp === 'invalid') warn('.mcp.json não é um JSON válido — não alterado. Confira o arquivo.');
-
-  for (const legacy of await findLegacyBridges(target)) {
-    warn(`Ponte antiga encontrada: ${legacy} (aponta para _opensquad/, que não existe neste projeto). Pode apagar com segurança.`);
-  }
-
-  if (ctx.copied.length) {
-    const rel = path.relative(target, ctx.backupDir).split(path.sep).join('/');
-    const what = manifest ? 'que você tinha editado' : 'diferentes do pacote novo';
-    warn(`${ctx.copied.length} arquivo(s) ${what} foram copiados para ${rel}/ antes de serem substituídos:`);
-    for (const f of ctx.copied.slice(0, 15)) log(`    ${f}`);
-    if (ctx.copied.length > 15) log(`    … e mais ${ctx.copied.length - 15}`);
-    if (!manifest) info('Primeira atualização com proteção: sem registro anterior, guardamos tudo o que diferia. Daqui em diante, só o que você editar.');
-  }
+  const done = { unreadable, ...(await refreshBridges(ctx)) };
+  done.mcp = await updateMcp(ctx, await readFile(tpl('.mcp.json')));
+  done.leftovers = await findLeftovers(target);
+  say(updateSummary(ctx, done));
 
   await writeManifest(target, version, ctx.files);
   // Stamp last: a crash above leaves the old version, so the next update retries.
-  await fs.writeFile(versionFile, version + '\n');
+  await fs.writeFile(path.join(target, '_opencrew', '.opencrew-version'), version + '\n');
   log(`\n${c.green(c.bold('Updated to v' + version))}.`);
-  log(c.dim('Your crews, memory, local best-practices and .env were left untouched.\n'));
+  log(c.dim(`${UNTOUCHED}\n`));
 }
 
-// Root AGENTS.md: create it if missing; a legacy full-system doc (pre-v1.3) is backed up
-// byte for byte and replaced by the thin bridge; otherwise only the marked block changes.
-async function refreshAgentsBridge(target) {
-  const agentsPath = path.join(target, 'AGENTS.md');
-  if (!(await exists(agentsPath))) {
-    await writeBridgeFile(agentsPath, AGENTS_BRIDGE);
-    ok('AGENTS.md (bridge created)');
-    return;
+/** @returns what `deliverTree` did to each crew template (only the missing ones are written). */
+async function refreshFramework(ctx) {
+  const dest = (...p) => path.join(ctx.target, ...p);
+  await deliverTree(ctx, tpl('_opencrew', 'core'), dest('_opencrew', 'core'), { overwrite: true });
+  await deliverFile(ctx, dest('_opencrew', 'core', 'system.md'), await fs.readFile(tpl('AGENTS.md')), { overwrite: true });
+  await deliverTree(ctx, tpl('skills'), dest('skills'), { overwrite: true });
+  // New framework folders (e.g. base agents since 1.3.2): only what is missing.
+  for (const dir of ['agents', 'config', '_investigations']) {
+    await deliverTree(ctx, tpl('_opencrew', dir), dest('_opencrew', dir), { overwrite: false });
   }
-  const existing = await readFile(agentsPath);
+  return deliverTree(ctx, tpl('crews'), dest('crews'), { overwrite: false });
+}
+
+/** AGENTS.md, .gitignore and the bridges of the IDEs installed: what happened to each. */
+async function refreshBridges(ctx) {
+  const agents = await refreshAgentsBridge(ctx);
+  // The copies in .opencrew-backup/ stay out of the user's git (R2 rule 7).
+  const gitignore = await deliverBlock(ctx, '.gitignore', await readFile(tpl('gitignore')));
+  const ides = await detectInstalledIdes(ctx.target);
+  // 1.4.0/1.4.1 shipped the maintainer's STATUS.md workflow inside CLAUDE.md's opencrew block.
+  // It leaves with the block; the same title outside the block is the user's and stays.
+  const leaked = () => blockHas(ctx.target, 'CLAUDE.md', LEAKED_STATUS_SECTION);
+  const hadLeak = await leaked();
+  const bridges = await withoutLegacy(ctx, ides, () => deliverBridges(ctx, ides)); // R2 rule 3 (src/lib/legado.js)
+  return { agents, gitignore, ides, bridges, leak: hadLeak && !(await leaked()) };
+}
+
+// Root AGENTS.md: a legacy full-system doc (pre-v1.3) is backed up byte for byte and replaced by
+// the thin bridge (said here; returns null); otherwise only the marked block is delivered (a
+// block the user edited is copied first — src/lib/blocos.js) and its result goes to the summary.
+async function refreshAgentsBridge(ctx) {
+  const agentsPath = path.join(ctx.target, 'AGENTS.md');
+  const existing = (await exists(agentsPath)) ? await readFile(agentsPath) : '';
   if (existing.includes('# opencrew Instructions') && !existing.includes('<!-- opencrew:start -->')) {
     const backup = await freeBackupPath(agentsPath);
     await fs.copyFile(agentsPath, backup);
     await writeFileSafe(agentsPath, AGENTS_BRIDGE);
     ok(`AGENTS.md (migrated from legacy full-system to thin bridge — backed up to ${path.basename(backup)})`);
-    return;
+    return null;
   }
-  await writeBridgeFile(agentsPath, AGENTS_BRIDGE);
-  ok('AGENTS.md refreshed');
+  return deliverBlock(ctx, 'AGENTS.md', AGENTS_BRIDGE);
 }
 
 async function freeBackupPath(file) {
@@ -125,14 +139,3 @@ async function freeBackupPath(file) {
   if (!(await exists(bak))) return bak;
   return `${file}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
 }
-
-// 1.4.0/1.4.1 shipped the maintainer's STATUS.md workflow inside CLAUDE.md's opencrew
-// block. Rewrite that block (only that block, only if the leak is there).
-async function removeLeakedStatusSection(target) {
-  const claudePath = path.join(target, 'CLAUDE.md');
-  if (!(await exists(claudePath))) return;
-  if (!(await readFile(claudePath)).includes(LEAKED_STATUS_SECTION)) return;
-  const bridge = ideById('claude-code').files.find((f) => f.path === 'CLAUDE.md');
-  await writeBridgeFile(claudePath, bridge.content);
-  ok('CLAUDE.md (removed the STATUS.md section shipped by mistake in 1.4.0/1.4.1)');
-}

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)));
+}