@aksp/opencrew 1.6.2 → 1.7.0

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

package/src/lib/mcp.js

@@ -0,0 +1,131 @@
+// The project's .mcp.json (R2 rules 8 to 11). The Playwright server OpenCrew ships is delivered
+// ONCE, and the manifest records it (`.mcp.json` → sha256 of the text, like any delivered file):
+// `init` records when it creates the file; `update` without the record creates the file or adds
+// the server — whichever is missing — and records. With the record, `update` never creates the
+// file nor puts the server back: removing it is the user's choice. Every rewrite copies the
+// whole file to .opencrew-backup/ first and keeps its indentation and line ending. The pinned
+// version is never changed, and a file out of the expected format is left as it is.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { exists } from './fsx.js';
+import { backupFile, hashOf, isRecord } from './manifest.js';
+
+/** Path of the file, relative to the project root: also its key in the manifest. */
+export const MCP_FILE = '.mcp.json';
+
+// The entry that is OpenCrew's own is the one that uses its Playwright config.
+const CONFIG = '_opencrew/config/playwright.config.json';
+const OUTPUT_DIR = ['--output-dir', '_opencrew/logs/playwright'];
+const SKILLS = 'as skills image-creator e image-fetcher';
+
+const hasOutputDir = (args) => args.some((a) => a === '--output-dir' || String(a).startsWith('--output-dir='));
+const lacksOutputDir = (args) => Array.isArray(args) && args.some((a) => String(a).includes(CONFIG)) && !hasOutputDir(args);
+
+/**
+ * `init`: write the template when the project has no .mcp.json, and record the delivery. An
+ * existing file is the user's: it stays as it is and nothing is recorded.
+ * @returns {Promise<boolean>} true when the file was created
+ */
+export async function createMcp(ctx, template) {
+  const dest = path.join(ctx.target, MCP_FILE);
+  if (await exists(dest)) return false;
+  await fs.writeFile(dest, template);
+  ctx.files[MCP_FILE] = hashOf(template);
+  return true;
+}
+
+/** Indentation of the first indented line of `text`; 2 spaces when no line is indented. */
+function indentOf(text) {
+  for (let nl = text.indexOf('\n'); nl !== -1; nl = text.indexOf('\n', nl + 1)) {
+    let end = nl + 1;
+    while (text[end] === ' ' || text[end] === '\t') end += 1;
+    if (end > nl + 1 && end < text.length && text[end] !== '\r' && text[end] !== '\n') return text.slice(nl + 1, end);
+  }
+  return '  ';
+}
+
+const BOM = String.fromCharCode(0xfeff); // some editors on Windows save JSON with it
+
+/** `data` as JSON in the indentation, line ending and final line break of `text`. */
+function formatLike(text, data) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const json = (text.startsWith(BOM) ? BOM : '') + JSON.stringify(data, null, indentOf(text)).replace(/\n/g, eol);
+  return text.endsWith('\n') ? json + eol : json;
+}
+
+/**
+ * What `update` does to a .mcp.json whose content is `text`. `delivered` = the manifest has the
+ * record. `data` (what to write) comes only with the two actions that change the file.
+ */
+function planMcp(text, template, delivered) {
+  let data;
+  try { data = JSON.parse(text.startsWith(BOM) ? text.slice(1) : text); } catch { return { action: 'not-json' }; }
+  // An object with no `mcpServers` counts as one with no server; any other shape is left alone.
+  const servers = isRecord(data) && data.mcpServers === undefined ? {} : data?.mcpServers;
+  if (!isRecord(servers)) return { action: 'bad-format' };
+  if (!Object.hasOwn(servers, 'playwright')) {
+    if (delivered) return { action: 'no-server' };
+    data.mcpServers = { ...servers, playwright: JSON.parse(template).mcpServers.playwright };
+    return { action: 'added', data };
+  }
+  const args = servers.playwright?.args;
+  if (!lacksOutputDir(args)) return { action: 'kept' };
+  args.push(...OUTPUT_DIR);
+  return { action: 'output-dir', data };
+}
+
+/**
+ * `update`: deliver the Playwright server once and send the output of the OpenCrew entry to
+ * _opencrew/logs/playwright/. The record always goes on to the next manifest (`ctx.files`).
+ * - `created` / `added`: no record — the missing file was written, or the missing server added;
+ * - `missing` / `no-server`: recorded before — not created, not put back;
+ * - `output-dir`: the OpenCrew entry had neither `--output-dir` nor `--output-dir=…`;
+ * - `not-json` / `bad-format`: the file is left alone, and no record is made (nothing was
+ *   delivered: once the file is fixed, the server can still arrive);
+ * - `kept`: nothing to do — without a record, this is what gets recorded.
+ * @param {string} template text of templates/.mcp.json
+ * @returns {Promise<{action:string, copied:boolean}>} `copied` = the file was copied before the rewrite
+ */
+export async function updateMcp(ctx, template) {
+  const dest = path.join(ctx.target, MCP_FILE);
+  const record = ctx.manifest?.files?.[MCP_FILE];
+  if (record) ctx.files[MCP_FILE] = record;
+  if (!(await exists(dest))) {
+    if (!record) await createMcp(ctx, template);
+    return { action: record ? 'missing' : 'created', copied: false };
+  }
+  const text = await fs.readFile(dest, 'utf8');
+  const plan = planMcp(text, template, Boolean(record));
+  if (!plan.data) {
+    if (plan.action === 'kept' && !record) ctx.files[MCP_FILE] = hashOf(text); // nothing was missing
+    return { action: plan.action, copied: false };
+  }
+  const copied = await backupFile(ctx, MCP_FILE);
+  const rewritten = formatLike(text, plan.data);
+  await fs.writeFile(dest, rewritten);
+  ctx.files[MCP_FILE] = hashOf(rewritten);
+  return { action: plan.action, copied };
+}
+
+// Spec R2 §6. `copy` = where the copy of the file is, for the two actions that rewrite it.
+const MESSAGES = {
+  created: () => `\`.mcp.json\` criado com o servidor Playwright do OpenCrew (${SKILLS} precisam dele). Se você apagou esse arquivo de propósito, pode apagar de novo: o \`update\` não recria mais.`,
+  added: (copy) => `Servidor Playwright acrescentado ao \`.mcp.json\` ${copy}. Se você o removeu de propósito, pode remover de novo: o \`update\` não repõe mais.`,
+  'output-dir': (copy) => `\`.mcp.json\`: a saída do Playwright agora vai para \`_opencrew/logs/playwright/\` ${copy}.`,
+  missing: () => `O \`.mcp.json\` não existe e não foi recriado. Sem o servidor Playwright, ${SKILLS} não funcionam.`,
+  'no-server': () => `O \`.mcp.json\` está sem o servidor Playwright do OpenCrew e ficou como está. Sem ele, ${SKILLS} não funcionam.`,
+  'bad-format': () => 'O `.mcp.json` não tem o formato esperado (um objeto com `mcpServers`) e não foi alterado. Confira o arquivo.',
+  'not-json': () => '.mcp.json não é um JSON válido — não alterado. Confira o arquivo.',
+};
+const DONE = new Set(['created', 'added', 'output-dir']);
+
+/**
+ * The line `update` prints for an action of `updateMcp`; null when there is nothing to say.
+ * @returns {{text:string, warn:boolean}|null} `warn` = a warning, not something that was done
+ */
+export function mcpMessage(ctx, action) {
+  if (!MESSAGES[action]) return null;
+  const dir = path.relative(ctx.target, ctx.backupDir).split(path.sep).join('/');
+  const text = MESSAGES[action](`(cópia do arquivo anterior em \`${dir}/${MCP_FILE}\`)`);
+  return { text, warn: !DONE.has(action) };
+}

package/src/lib/migrations.js

@@ -1,11 +1,14 @@
 // What `update` does beyond refreshing _opencrew/core and the catalog skills, so that every
-// improvement reaches people who already use OpenCrew (AGENTS.md rule 14). The IDE detection
-// is shared with `init --repair-bridges`, whose helpers live here too.
+// improvement reaches people who already use OpenCrew (AGENTS.md rule 14). The helpers of
+// `init --repair-bridges` live here too, with the version guard the two commands share.
+// The IDE detection itself is in ./deteccao.js.
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { exists, writeBridgeFile } from './fsx.js';
-import { IDES, allIdeIds } from './ides.js';
-import { deliverFile, writeManifest } from './manifest.js';
+import { exists } from './fsx.js';
+import { allIdeIds } from './ides.js';
+import { writeManifest } from './manifest.js';
+import { copyLine } from './blocos.js';
+import { detectInstalledIdes } from './deteccao.js';
 
 /** Semver compare (no pre-release tags): >0 if a > b, <0 if a < b, 0 if equal. */
 export function compareVersions(a, b) {
@@ -18,33 +21,27 @@ export function compareVersions(a, b) {
   return 0;
 }
 
-const sharedPaths = (() => {
-  const count = new Map();
-  for (const ide of IDES) for (const f of ide.files) count.set(f.path, (count.get(f.path) ?? 0) + 1);
-  return new Set([...count].filter(([, n]) => n > 1).map(([p]) => p));
-})();
-
-async function hasOpencrew(file) {
-  return (await exists(file)) && /opencrew/i.test(await fs.readFile(file, 'utf8'));
+/** Version stamped in the workspace by the last init or update that finished; null = no stamp. */
+export async function installedVersion(target) {
+  const stamp = path.join(target, '_opencrew', '.opencrew-version');
+  return (await exists(stamp)) ? (await fs.readFile(stamp, 'utf8')).trim() : null;
 }
 
+const RUN_UPDATE = 'Nada foi alterado. Rode `npx @aksp/opencrew@latest update`: ele já atualiza as pontes. Para a ponte de uma IDE nova, repita este comando depois.';
+
 /**
- * IDEs installed in `target`, detected by their own bridge files (a path shared by several
- * IDEs only counts for an IDE that has no file of its own — e.g. Codex).
+ * Spec R2, rule 6: `init --repair-bridges` only rewrites with the package at the version
+ * stamped in the workspace. An older package would bring old bridges back; a newer one would
+ * point them to files the project does not have yet. No stamp (interrupted install): it runs.
+ * @returns {Promise<string|null>} the message that stops the repair, or null to go on
  */
-export async function detectInstalledIdes(target) {
-  const found = [];
-  for (const ide of IDES) {
-    const own = ide.files.filter((f) => !sharedPaths.has(f.path));
-    const probes = own.length ? own : ide.files;
-    for (const f of probes) {
-      if (await hasOpencrew(path.join(target, f.path))) {
-        found.push(ide);
-        break;
-      }
-    }
-  }
-  return found;
+export async function repairVersionGuard(target, version) {
+  const installed = await installedVersion(target);
+  const diff = installed ? compareVersions(installed, version) : 0;
+  if (!diff) return null;
+  return diff > 0
+    ? `Você tem a v${installed} instalada e este pacote é a v${version} (mais antigo). ${RUN_UPDATE}`
+    : `Este projeto está na v${installed} e este pacote é a v${version} (mais novo). O reparo não atualiza o projeto. ${RUN_UPDATE}`;
 }
 
 /**
@@ -79,57 +76,35 @@ export function backupSummary(ctx) {
   const dir = path.relative(ctx.target, ctx.backupDir).split(path.sep).join('/');
   return [
     `${ctx.copied.length} cópia(s) de segurança feita(s) antes de regravar:`,
-    ...ctx.copied.map((file) => `    ${dir}/${file}`),
+    ...ctx.copied.map((file) => `    ${copyLine(ctx, file, `${dir}/${file}`)}`),
   ];
 }
 
-/** Rewrite the bridges of the installed IDEs only (frontmatter files whole, others by block). */
-export async function refreshBridges(ctx, ides) {
-  const done = new Set();
-  for (const ide of ides) {
-    for (const f of ide.files) {
-      if (done.has(f.path)) continue;
-      done.add(f.path);
-      const file = path.join(ctx.target, f.path);
-      if (f.content.startsWith('---')) await deliverFile(ctx, file, f.content, { overwrite: true });
-      else await writeBridgeFile(file, f.content);
-    }
-  }
-}
+// The bridges themselves are written by `deliverBridges` (./blocos.js), for init, update and
+// repair; the project's .mcp.json is handled in ./mcp.js.
 
-const OUTPUT_DIR = ['--output-dir', '_opencrew/logs/playwright'];
+// ── What an old OpenSquad install left behind (R2 rule 16): only reported, never touched ──
 
-/**
- * Merge the Playwright server of the template into the project's .mcp.json without touching
- * other servers. @returns 'created' | 'updated' | 'unchanged' | 'invalid'
- */
-export async function mergeMcp(target, templateFile) {
-  const file = path.join(target, '.mcp.json');
-  const template = JSON.parse(await fs.readFile(templateFile, 'utf8'));
-  if (!(await exists(file))) {
-    await fs.writeFile(file, JSON.stringify(template, null, 2) + '\n');
-    return 'created';
-  }
-  let current;
-  try {
-    current = JSON.parse(await fs.readFile(file, 'utf8'));
-  } catch {
-    return 'invalid';
-  }
-  current.mcpServers ??= {};
-  const pw = current.mcpServers.playwright;
-  if (!pw) current.mcpServers.playwright = template.mcpServers.playwright;
-  else if (Array.isArray(pw.args) && !pw.args.includes('--output-dir')) pw.args.push(...OUTPUT_DIR);
-  else return 'unchanged';
-  await fs.writeFile(file, JSON.stringify(current, null, 2) + '\n');
-  return 'updated';
-}
+const OLD_DIR = '_opensquad/';
+// Folders where a `.md` that cites `_opensquad/` is reported, down to two subfolders.
+const LEFTOVER_ROOTS = ['.gemini/skills', '.claude/skills', '.agents/skills', '.agent/workflows', '.agent/rules'];
+// Bridges of the OpenSquad reported by their exact path (checked with `opensquad` 0.1.15).
+const LEFTOVER_BRIDGES = [
+  '.cursor/rules/opensquad.mdc',
+  '.cursor/commands/opensquad.md',
+  '.opencode/commands/opensquad.md',
+  '.qwen/skills/opensquad/SKILL.md',
+  '.trae/rules/opensquad.md',
+  '.github/prompts/opensquad.prompt.md',
+  '.agents/skills/opensquad/SKILL.md',
+];
 
-const LEGACY_ROOTS = ['.gemini/skills', '.claude/skills', '.agents/skills', '.agent/workflows', '.agent/rules'];
+/** A folder `opensquad/` or a file `opensquad.*` in the path: a bridge of the OpenSquad. */
+const namedOpensquad = (file) => file.split('/').some((part, i, parts) => (
+  i < parts.length - 1 ? part === 'opensquad' : part.startsWith('opensquad.')));
 
-/** Old bridges that point to a system no longer installed (e.g. `_opensquad/`). Never deleted. */
-export async function findLegacyBridges(target) {
-  if (await exists(path.join(target, '_opensquad'))) return [];
+/** The `.md` files under `root` (two subfolders deep) that cite `_opensquad/`. */
+async function citingOldDir(target, root) {
   const found = [];
   async function walk(dir, depth) {
     let entries;
@@ -137,11 +112,39 @@ export async function findLegacyBridges(target) {
     for (const e of entries) {
       const p = path.join(dir, e.name);
       if (e.isDirectory() && depth < 2) await walk(p, depth + 1);
-      else if (e.isFile() && e.name.endsWith('.md') && /_opensquad\//.test(await fs.readFile(p, 'utf8'))) {
+      else if (e.isFile() && e.name.endsWith('.md') && (await fs.readFile(p, 'utf8')).includes(OLD_DIR)) {
         found.push(path.relative(target, p).split(path.sep).join('/'));
       }
     }
   }
-  for (const root of LEGACY_ROOTS) await walk(path.join(target, root), 0);
+  await walk(path.join(target, root), 0);
   return found;
 }
+
+/** The file of `_opensquad/` the `playwright` server of .mcp.json points to; null when none. */
+async function oldPlaywrightConfig(target) {
+  let args;
+  try {
+    args = JSON.parse(await fs.readFile(path.join(target, '.mcp.json'), 'utf8')).mcpServers.playwright.args;
+  } catch { return null; }
+  if (!Array.isArray(args)) return null;
+  const values = args.map((a) => String(a)).map((a) => (a.startsWith('--') && a.includes('=') ? a.slice(a.indexOf('=') + 1) : a));
+  return values.find((v) => v.replace(/\\/g, '/').replace(/^\.\//, '').startsWith(OLD_DIR)) ?? null;
+}
+
+/**
+ * Leftovers of an OpenSquad install that is no longer there. With `_opensquad` at the project
+ * root nothing is reported (the system is still installed). Nothing is deleted nor changed.
+ * @returns {Promise<{files: Array<{file:string, bridge:boolean}>, config: string|null}>}
+ *   `files`, sorted by path: `bridge` = recognised by its name; false = it only cites
+ *   `_opensquad/` and may be the user's. `config` = the path of `_opensquad/` (so, missing)
+ *   that the `playwright` server of .mcp.json uses.
+ */
+export async function findLeftovers(target) {
+  if (await exists(path.join(target, '_opensquad'))) return { files: [], config: null };
+  const found = new Set();
+  for (const root of LEFTOVER_ROOTS) for (const file of await citingOldDir(target, root)) found.add(file);
+  for (const file of LEFTOVER_BRIDGES) if (await exists(path.join(target, file))) found.add(file);
+  const files = [...found].sort().map((file) => ({ file, bridge: namedOpensquad(file) }));
+  return { files, config: await oldPlaywrightConfig(target) };
+}

package/src/lib/node-version.js

@@ -0,0 +1,43 @@
+// Node floor (spec R2, rule 27): the lowest Node the package accepts, read from the
+// `engines.node` of package.json, and the decision to stop when the machine is below it.
+// Lives outside cli.js so the rule can be tested without touching `process.versions`.
+
+/** a < b, comparing major.minor.patch as numbers (no prerelease tags). */
+function lt(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const na = pa[i] || 0;
+    const nb = pb[i] || 0;
+    if (na !== nb) return na < nb;
+  }
+  return false; // equal
+}
+
+/**
+ * Lowest version an engines.node range accepts: the first version of each `||` alternative,
+ * then the smallest of them. Handles ">=20.17.0", "^20.5", ">=18.0.0 || >=20.0.0", "20.0.0".
+ * @returns {string | null} null when the range names no version
+ */
+export function minNodeVersion(range) {
+  let lowest = null;
+  for (const part of String(range ?? '').split('||')) {
+    const v = part.match(/\d+(?:\.\d+){0,2}/)?.[0];
+    if (v && (!lowest || lt(v, lowest))) lowest = v;
+  }
+  return lowest;
+}
+
+/**
+ * The two lines to show when `current` is below the floor of `range`; null when this Node
+ * may run the CLI (also when the package declares no floor).
+ * @returns {[string, string] | null}
+ */
+export function nodeBelowFloor(range, current = process.versions.node) {
+  const floor = minNodeVersion(range);
+  if (!floor || !lt(current, floor)) return null;
+  return [
+    `O OpenCrew precisa do Node.js ${floor} ou mais novo. Esta máquina está com o v${current}.`,
+    'Instale a versão LTS em https://nodejs.org/ e rode o comando de novo. Nada foi alterado nesta pasta.',
+  ];
+}

package/src/lib/prompts.js

@@ -3,7 +3,30 @@
 import { IDES, allIdeIds } from './ides.js';
 import { warn } from './ui.js';
 
-export async function pickIdes({ preselected } = {}) {
+const loadCheckbox = () => import('@inquirer/checkbox');
+
+/**
+ * Load the list's library. Only the import is guarded (spec R2, rule 28): on a Node where it
+ * does not load, the user gets the way out; Ctrl+C on the open list still passes through.
+ */
+async function openIdeList(load) {
+  try {
+    return await load();
+  } catch (e) {
+    throw new Error(
+      `Não consegui abrir a lista de IDEs neste Node (v${process.versions.node}).\n`
+      + 'Atualize o Node em https://nodejs.org/ ou escolha as IDEs no próprio comando: '
+      + 'npx @aksp/opencrew init --ide=claude-code (ou --all para todas). Nada foi alterado nesta pasta.',
+      { cause: e },
+    );
+  }
+}
+
+/**
+ * @param {{ preselected?: string[] }} [opts]
+ * @param {{ load?: () => Promise<object> }} [deps]  injectable for tests
+ */
+export async function pickIdes({ preselected } = {}, { load = loadCheckbox } = {}) {
   const validIds = new Set(allIdeIds());
   const isTTY = process.stdin.isTTY && process.stdout.isTTY;
 
@@ -23,7 +46,7 @@ export async function pickIdes({ preselected } = {}) {
     warn(`Non-interactive terminal — configuring IDEs: ${chosen.join(', ')}`);
     return chosen;
   }
-  const { default: checkbox, Separator } = await import('@inquirer/checkbox');
+  const { default: checkbox, Separator } = await openIdeList(load);
   const answer = await checkbox({
     message: 'Which AI IDEs do you use? (space to toggle, enter to confirm)',
     instructions: false,