nexakit 0.1.0 → 0.2.0

package/src/skill-scan-report.js

@@ -0,0 +1,14 @@
+// Never calls a skill "safe": the scan only reports what its rules saw.
+export function formatScanReport(report, label) {
+  const count = severity => report.findings.filter(f => f.severity === severity).length;
+  const blocks = count('bloqueo');
+  const warnings = count('aviso');
+  const lines = [blocks
+    ? `Escaneo de ${label}: BLOQUEADA (${blocks} bloqueos, ${warnings} avisos)`
+    : `Escaneo de ${label}: sin bloqueos; ${warnings} avisos`];
+  for (const f of report.findings) lines.push(`  [${f.severity}] ${f.rule} · ${f.file}:${f.line} · ${f.excerpt}`);
+  const caps = Object.entries(report.capabilities).filter(([, on]) => on).map(([name]) => name);
+  lines.push(`Capacidades detectadas: ${caps.length ? caps.join(', ') : 'ninguna'}`);
+  lines.push('El escaneo no ejecuta la skill ni garantiza que sea útil o segura.');
+  return lines.join('\n') + '\n';
+}

package/src/skill-scan.js

@@ -0,0 +1,178 @@
+import path from 'node:path';
+import { readSkillFiles } from './skill-files.js';
+import { SECRET_PATTERNS } from './sensitive-data.js';
+
+// Offline content review of a skill. Reads bytes only: nothing here executes, imports or fetches the skill.
+
+const SCRIPT_EXTENSIONS = new Set(['.sh', '.bash', '.zsh', '.js', '.mjs', '.cjs', '.ts', '.py', '.rb', '.ps1']);
+const SEVERITY = {
+  'unicode-oculto': 'bloqueo', credencial: 'bloqueo', 'descarga-y-ejecuta': 'bloqueo', exfiltracion: 'bloqueo',
+  'instruccion-oculta': 'aviso', inyeccion: 'aviso', 'comando-peligroso': 'aviso', ofuscacion: 'aviso',
+  red: 'info'
+};
+// Lines longer than this skip the rules with open-ended wildcards: a crafted 512 KiB line must not hang the scan.
+const MAX_RULE_LINE = 4096;
+
+// Zero width, bidirectional controls, tag characters, Arabic letter mark, Mongolian vowel separator,
+// Hangul fillers and variation selectors supplement. U+200D and U+FEFF have their own rules below.
+const HIDDEN_CLASS = String.raw`​‌‎‏⁠-⁤‪-‮⁦-⁩؜᠎ᅟᅠㅤﾠ\u{E0000}-\u{E007F}\u{E0100}-\u{E01EF}`;
+const HIDDEN = new RegExp(`[${HIDDEN_CLASS}]`, 'u');
+const SHOWN_AS_CODEPOINT = new RegExp(`[${HIDDEN_CLASS}\\u200D\\uFEFF]`, 'gu');
+const PICTO = /\p{Extended_Pictographic}/u;
+const EMOJI_TAIL = /[️\u{1F3FB}-\u{1F3FF}]/u;
+
+// Only concrete secret formats: the generic "password: ..." assignment fires on every code example in a skill.
+const CREDENTIAL_PATTERNS = SECRET_PATTERNS.filter(({ name }) => name !== 'asignación sensible').map(({ pattern }) => pattern);
+const URL_WITH_PASSWORD = /https?:\/\/[^\s/:@]{1,200}:[^\s/@]{1,200}@/i;
+
+const FETCHER = String.raw`(?:curl|wget|iwr|irm|Invoke-WebRequest)`;
+const INTERPRETER = String.raw`(?:(?:sudo(?:\s+-\S+){0,5}\s+)?(?:env\s+)?(?:(?:ba|z|da)?sh|python3?|node|perl|ruby|iex|Invoke-Expression)\b)`;
+const DOWNLOAD_EXEC = [
+  new RegExp(String.raw`\b${FETCHER}\b[^\n]{0,400}\|\s*${INTERPRETER}`, 'i'),
+  new RegExp(String.raw`\bbase64\s+(?:-d|--decode|-D)\b[^\n]{0,400}\|\s*${INTERPRETER}`, 'i'),
+  new RegExp(String.raw`\b(?:(?:ba|z|da)?sh|python3?|node|perl|ruby|eval|source|iex)\b[^\n]{0,200}(?:\$\(|<\(|\x60)\s*${FETCHER}\b`, 'i')
+];
+// Linear fallback for long lines: a fetcher plus a pipe into a shell or a fetch inside a substitution.
+const LONG_FETCHER = new RegExp(String.raw`\b${FETCHER}\b`, 'i');
+const LONG_EXEC = new RegExp(String.raw`\|\s*(?:sudo\s+)?(?:ba|z|da)?sh\b|(?:\$\(|<\()\s*${FETCHER}\b`, 'i');
+
+const SENSITIVE_READ = /~\/\.ssh\b|\$HOME\/\.ssh\b|\bid_rsa\b|\bid_ed25519\b|~\/\.aws\b|\.aws\/credentials|(?:^|[\s"'/])\.env(?!\.(?:example|sample|template|dist)\b)\b|\bKeychain\b|security\s+find-generic-password|process\.env\b|os\.environ\b|\bprintenv\b/i;
+const NETWORK_SEND = /\bcurl\b[^\n]{0,400}(?:\s-d\b|\s--data|\s-F\b|\s--form|\s-T\b|\s--upload-file)|\bwget\b[^\n]{0,400}--post-(?:data|file)|\bfetch\s*\([^\n]{0,400}method\s*:\s*['"]POST|\brequests\.(?:post|put)\s*\(|\b(?:nc|ncat|netcat)\s+[\w.-]{1,200}\s+\d+|\baxios\.post\s*\(/i;
+const NETWORK = /\bcurl\b|\bwget\b|\bfetch\s*\(|\brequests\.\w+\s*\(|\burllib\b|\bhttps?\.request\s*\(|\baxios\b|\bInvoke-WebRequest\b|\b(?:nc|ncat|netcat)\s+\S{1,200}\s+\d+/i;
+const INJECTION = /\bignore\s+(?:all\s+)?(?:the\s+)?(?:previous|prior|above)\s+instructions\b|\bdisregard\s+(?:all\s+)?(?:previous|prior|above)\b|\bdo\s+not\s+(?:tell|inform|mention\s+(?:this\s+)?to)\s+the\s+user\b|\bsystem\s+prompt\b|\bignora\s+(?:todas\s+)?las\s+instrucciones\s+(?:anteriores|previas)\b|\bno\s+se\s+lo\s+(?:digas|cuentes|menciones)\s+al\s+usuario\b|\bsin\s+que\s+el\s+usuario\s+lo\s+sepa\b/i;
+const DANGEROUS = /\brm\s+-[a-z]*r[a-z]*f[a-z]*\s+(?:\/(?:\s|$|\*)|~(?:\/?\s|\/?$)|"?\$HOME"?\/?(?:\s|$))|\brm\s+-[a-z]*f[a-z]*r[a-z]*\s+(?:\/(?:\s|$|\*)|~(?:\/?\s|\/?$)|"?\$HOME"?\/?(?:\s|$))|\bsudo\s+\S|\bchmod\s+(?:-R\s+)?777\b|>>?\s*~\/\.(?:bashrc|zshrc|bash_profile|profile|zprofile)\b|~\/\.ssh\/authorized_keys|\bcrontab\s+(?:-\s|-e|\S+\.(?:txt|cron))|\blaunchctl\s+(?:load|bootstrap|submit)\b/i;
+const BASE64_BLOB = /[A-Za-z0-9+/]{200,}={0,2}/;
+const EVAL_DECODED = /\b(?:eval|exec|Function)\s*\(\s*(?:atob|Buffer\.from|base64\.b64decode|bytes\.fromhex|unescape|decodeURIComponent)\b/;
+const PROCESS = /\bchild_process\b|\bexecSync\s*\(|\bspawn\s*\(|\bsubprocess\b|\bos\.system\s*\(/;
+const FILE_WRITE = /\bwriteFile(?:Sync)?\s*\(|\bfs\.(?:rm|unlink|rename|mkdir)\w*\s*\(|\bopen\s*\([^)\n]{0,200}['"][wa]\+?['"]|\brm\s+-|>\s*[~/\w.]/;
+const FENCE = /^\s{0,3}(?:```|~~~)/;
+// Files a skill copies for the user (templates, examples) are material, not code the skill runs.
+const MATERIAL_DIR = /^(?:assets|templates|examples?)\//;
+const runsCode = filePath => SCRIPT_EXTENSIONS.has(path.extname(filePath).toLowerCase()) && !MATERIAL_DIR.test(filePath);
+
+const codepoint = ch => `<U+${ch.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}>`;
+const excerptOf = line => {
+  const trimmed = line.trim();
+  const shown = (trimmed.length > 2000 ? trimmed.slice(0, 2000) : trimmed).replace(SHOWN_AS_CODEPOINT, codepoint);
+  return shown.length > 120 ? `${shown.slice(0, 117)}...` : shown;
+};
+
+function hiddenUnicodeIn(line, isFirstLine) {
+  if (HIDDEN.test(line)) return true;
+  if (!line.includes('‍') && !line.includes('')) return false;
+  const chars = [...line];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === '' && !(isFirstLine && i === 0)) return true;
+    if (chars[i] === '‍') {
+      // A ZWJ joins two emoji; skin tones and the emoji presentation selector may sit before it.
+      let before = i - 1;
+      while (before >= 0 && EMOJI_TAIL.test(chars[before])) before--;
+      if (!(PICTO.test(chars[before] ?? '') && PICTO.test(chars[i + 1] ?? ''))) return true;
+    }
+  }
+  return false;
+}
+
+// Joins shell continuation lines ("\" at the end) so a pipe on the next line is seen with its command.
+function logicalLines(lines) {
+  const result = [];
+  let current = null;
+  lines.forEach((line, index) => {
+    const text = current ? `${current.text} ${line.trim()}` : line;
+    const start = current ? current.start : index + 1;
+    if (/\\\s*$/.test(line) && text.length < MAX_RULE_LINE) current = { start, text: text.replace(/\\\s*$/, '') };
+    else { result.push({ start, text }); current = null; }
+  });
+  if (current) result.push(current);
+  return result;
+}
+
+function scanText(filePath, text, push, capabilities) {
+  const isScript = SCRIPT_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+  const runs = runsCode(filePath);
+  const isMarkdown = /\.(?:md|markdown|mdx)$/i.test(filePath);
+  const lines = text.split(/\r?\n/);
+  // Exfiltration needs a sensitive read and a network send in the same unit: the file for scripts,
+  // a fenced code block for Markdown, and a single line for prose and data rows (CSV, JSON), so
+  // unrelated documentation does not block.
+  const sensitiveUnits = new Set();
+  const sendUnits = new Map();
+  let fence = 0;
+  let inFence = false;
+  let networkSeen = false;
+  let commentStart = 0;
+  let commentText = '';
+  lines.forEach((line, index) => {
+    const n = index + 1;
+    const hit = rule => push(rule, filePath, n, line);
+    const long = line.length > MAX_RULE_LINE;
+    const fenceLine = isMarkdown && FENCE.test(line);
+    if (fenceLine) { inFence = !inFence; if (inFence) fence++; }
+    const unit = isScript ? 'file' : isMarkdown && inFence ? `fence-${fence}` : `line-${n}`;
+    if (hiddenUnicodeIn(line, index === 0)) hit('unicode-oculto');
+    if (CREDENTIAL_PATTERNS.some(re => re.test(line)) || (!long && URL_WITH_PASSWORD.test(line))) hit('credencial');
+    if (long && LONG_FETCHER.test(line) && LONG_EXEC.test(line)) hit('descarga-y-ejecuta');
+    if (INJECTION.test(line)) hit('inyeccion');
+    if (DANGEROUS.test(line)) hit('comando-peligroso');
+    if (long || BASE64_BLOB.test(line) || EVAL_DECODED.test(line) || (isScript && line.length > 1000)) hit('ofuscacion');
+    if (SENSITIVE_READ.test(line)) sensitiveUnits.add(unit);
+    if (!long && NETWORK_SEND.test(line) && !sendUnits.has(unit)) sendUnits.set(unit, n);
+    // Capabilities come only from code the skill runs; examples in documentation are reported as `red` info.
+    if (NETWORK.test(line)) {
+      if (runs) capabilities.network = true;
+      if (!networkSeen) { networkSeen = true; hit('red'); }
+    }
+    if (runs && PROCESS.test(line)) capabilities.processes = true;
+    if (runs && !long && FILE_WRITE.test(line)) capabilities.filesystem = true;
+    // An HTML comment inside a fenced code block is shown to the reader, so it is not hidden.
+    if (isMarkdown && (!inFence || commentStart) && !fenceLine) {
+      let rest = line;
+      while (rest.length) {
+        if (!commentStart) {
+          const open = rest.indexOf('<!--');
+          if (open < 0) break;
+          commentStart = n;
+          commentText = '';
+          rest = rest.slice(open + 4);
+        }
+        const close = rest.indexOf('-->');
+        if (close < 0) { commentText += rest; break; }
+        commentText += rest.slice(0, close);
+        if (commentText.trim()) push('instruccion-oculta', filePath, commentStart, lines[commentStart - 1]);
+        commentStart = 0;
+        rest = rest.slice(close + 3);
+      }
+      if (commentStart && n !== commentStart) commentText += ' ';
+    }
+  });
+  for (const { start, text: logical } of logicalLines(lines)) {
+    if (logical.length <= MAX_RULE_LINE && DOWNLOAD_EXEC.some(re => re.test(logical))) push('descarga-y-ejecuta', filePath, start, lines[start - 1]);
+  }
+  if (commentStart && commentText.trim()) push('instruccion-oculta', filePath, commentStart, lines[commentStart - 1]);
+  const exfil = [...sendUnits].find(([unit]) => sensitiveUnits.has(unit));
+  if (exfil) push('exfiltracion', filePath, exfil[1], lines[exfil[1] - 1]);
+}
+
+export function scanSkillFiles(files) {
+  const findings = [];
+  const capabilities = { filesystem: false, processes: false, network: false };
+  const push = (rule, file, line, text) => findings.push({ rule, severity: SEVERITY[rule], file, line, excerpt: excerptOf(text) });
+  // ignoreBOM keeps a leading U+FEFF in the text, so a second one right after it is still caught.
+  const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+    let text;
+    try {
+      text = decoder.decode(file.bytes);
+    } catch {
+      findings.push({ rule: 'ofuscacion', severity: 'aviso', file: file.path, line: 1, excerpt: 'archivo binario o no UTF-8' });
+      continue;
+    }
+    if (runsCode(file.path)) capabilities.processes = true;
+    scanText(file.path, text, push, capabilities);
+  }
+  return { blocked: findings.some(f => f.severity === 'bloqueo'), findings, capabilities };
+}
+
+export async function scanSkillDirectory(dir) {
+  return scanSkillFiles(await readSkillFiles(path.resolve(dir), dir));
+}

package/src/stable-command.js

@@ -0,0 +1,53 @@
+// ~/.nexakit/nexakit: a small launcher that runs nexakit from its active root with a fixed node, so skills and the
+// person can call nexakit without npx and without nexakit on the PATH. It is rewritten only when its content
+// changes, and a link or a folder in its place is never replaced.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { IS_WINDOWS } from './platform.js';
+import { nexakitDir } from './stable-install.js';
+
+const shellQuote = value => `'${value.replaceAll("'", "'\\''")}'`;
+// The second line marks the file as nexakit's: a file without it is the person's and is never replaced.
+const MARK = 'nexakit: orden estable (se reescribe sola)';
+// In a batch file % expands variables even inside quotes; %% is a literal %.
+const batchPath = value => value.replaceAll('%', '%%');
+
+export function stableCommandContent({ nodePath, toolkitRoot, windows = IS_WINDOWS }) {
+  return windows
+    ? `@rem ${MARK}\r\n@"${batchPath(nodePath)}" "${batchPath(toolkitRoot)}\\bin\\nexakit.js" %*\r\n`
+    : `#!/bin/sh\n# ${MARK}\nexec ${shellQuote(nodePath)} ${shellQuote(path.join(toolkitRoot, 'bin', 'nexakit.js'))} "$@"\n`;
+}
+
+export async function planStableCommand({ homeDirectory, nodePath, toolkitRoot, windows = IS_WINDOWS }) {
+  const target = path.join(nexakitDir(homeDirectory), windows ? 'nexakit.cmd' : 'nexakit');
+  const content = stableCommandContent({ nodePath, toolkitRoot, windows });
+  let state;
+  try {
+    const info = await fs.lstat(target);
+    const current = info.isFile() ? await fs.readFile(target, 'utf8') : null;
+    state = current === null || !current.includes(MARK) ? 'conflicto' : current === content ? 'igual' : 'distinto';
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    state = 'falta';
+  }
+  return { path: target, content, state, windows };
+}
+
+export async function writeStableCommand(plan, lock) {
+  if (plan.state === 'igual' || plan.state === 'conflicto') return false;
+  await lock.assertHeld();
+  await fs.mkdir(path.dirname(plan.path), { recursive: true, mode: 0o700 });
+  const temporary = `${plan.path}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, plan.content, { mode: 0o755, flag: 'wx' });
+  try {
+    await fs.chmod(temporary, 0o755);
+    await lock.assertHeld();
+    // Read again right before replacing: something that became a link or a folder meanwhile is left alone.
+    const current = await fs.lstat(plan.path).catch(error => (error.code === 'ENOENT' ? null : Promise.reject(error)));
+    if (current && (!current.isFile() || !(await fs.readFile(plan.path, 'utf8')).includes(MARK))) return false;
+    await fs.rename(temporary, plan.path);
+    return true;
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+}

package/src/stable-install.js

@@ -0,0 +1,222 @@
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { LockError } from './install-lock.js';
+import { IS_WINDOWS } from './platform.js';
+
+const PACKAGE_NAME = 'nexakit';
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/u;
+const COMPLETE_MARKER = '.completa';
+const PROBED_IMPORTS = ['ajv', 'zod', '@modelcontextprotocol/sdk/client/index.js'];
+const NPM_TIMEOUT_MS = 10 * 60 * 1000;
+const PROBE_TIMEOUT_MS = 30 * 1000;
+
+export class StableInstallError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'StableInstallError';
+  }
+}
+
+export const nexakitDir = homeDirectory => path.join(homeDirectory, '.nexakit');
+export const actualRoot = homeDirectory => path.join(nexakitDir(homeDirectory), 'actual');
+
+const lstatOrNull = file => fs.lstat(file).catch(error => {
+  if (error.code === 'ENOENT') return null;
+  throw error;
+});
+const realpathOrNull = file => fs.realpath(file).catch(error => {
+  if (['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code)) return null;
+  throw error;
+});
+const samePath = (a, b) => (IS_WINDOWS ? a.toLowerCase() === b.toLowerCase() : a === b);
+const firstLine = text => (String(text ?? '').split('\n').map(line => line.trim()).find(Boolean) ?? 'sin detalle').slice(0, 300);
+
+export function compareVersions(a, b) {
+  const left = VERSION_RE.exec(a), right = VERSION_RE.exec(b);
+  if (!left || !right) return 0;
+  for (let index = 1; index <= 3; index++) {
+    const difference = Number(left[index]) - Number(right[index]);
+    if (difference !== 0) return difference > 0 ? 1 : -1;
+  }
+  // A release is newer than its own prerelease.
+  if (left[4] === right[4]) return 0;
+  if (left[4] === undefined) return 1;
+  if (right[4] === undefined) return -1;
+  return left[4] > right[4] ? 1 : -1;
+}
+
+export async function readActualVersion(homeDirectory) {
+  try {
+    const manifest = JSON.parse(await fs.readFile(path.join(actualRoot(homeDirectory), 'package.json'), 'utf8'));
+    return manifest?.name === PACKAGE_NAME && typeof manifest.version === 'string' && VERSION_RE.test(manifest.version)
+      ? manifest.version : null;
+  } catch { return null; }
+}
+
+// The npm that launched us (`npx` sets npm_execpath) runs as `node npm-cli.js`, so no .cmd shim is involved.
+// Without it POSIX falls back to `npm` on the PATH; Windows has no safe fallback and reports unavailable (null).
+export function npmInvocation(args, { environment = process.env, platform = process.platform } = {}) {
+  const script = environment.npm_execpath;
+  if (typeof script === 'string' && path.isAbsolute(script) && /\.[cm]?js$/iu.test(script)) {
+    return { command: environment.npm_node_execpath || process.execPath, args: [script, ...args] };
+  }
+  return platform === 'win32' ? null : { command: 'npm', args };
+}
+
+export function defaultRunNpm(args) {
+  const invocation = npmInvocation(args);
+  if (!invocation) return { status: 1, stderr: 'No se encontró npm. Ejecuta nexakit con `npx nexakit`.' };
+  const result = spawnSync(invocation.command, invocation.args, {
+    encoding: 'utf8', shell: false, timeout: NPM_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024, windowsHide: true
+  });
+  return { status: result.status ?? 1, stderr: result.stderr || result.error?.message || '' };
+}
+
+export async function validatePackageRoot(root, version) {
+  const fail = reason => { throw new StableInstallError(`La copia de nexakit ${version} no es válida (${reason}): ${root}`); };
+  let manifest;
+  try { manifest = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8')); } catch { fail('falta package.json'); }
+  if (manifest?.name !== PACKAGE_NAME) fail('el paquete no es nexakit');
+  if (manifest.version !== version) fail(`trae la versión ${manifest.version}`);
+
+  const mcp = await lstatOrNull(path.join(root, 'bin/agent-toolkit-mcp.js'));
+  if (!mcp?.isFile()) fail('falta bin/agent-toolkit-mcp.js');
+
+  for (const folder of ['skills', 'catalogs/skills']) {
+    let entries;
+    try { entries = await fs.readdir(path.join(root, folder), { withFileTypes: true }); } catch { fail(`falta ${folder}/`); }
+    for (const entry of entries.filter(item => item.isDirectory())) {
+      const file = await lstatOrNull(path.join(root, folder, entry.name, 'SKILL.md'));
+      if (!file?.isFile()) fail(`la skill ${entry.name} no tiene SKILL.md`);
+    }
+  }
+
+  // Importing (not just resolving) catches a dependency that is present but cannot load.
+  const probe = spawnSync(process.execPath, ['--input-type=module', '-e', `for (const name of ${JSON.stringify(PROBED_IMPORTS)}) await import(name);`], {
+    cwd: root, encoding: 'utf8', timeout: PROBE_TIMEOUT_MS, windowsHide: true
+  });
+  if (probe.status !== 0) {
+    fail(`no se cargan sus dependencias: ${firstLine((probe.stderr ?? '').split('\n').find(line => /Error/u.test(line)))}`);
+  }
+}
+
+async function ensureRealDirectory(directory) {
+  const info = await lstatOrNull(directory);
+  if (!info) {
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    return;
+  }
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new StableInstallError(`${directory} no es una carpeta normal; muévela o bórrala para continuar.`);
+  }
+}
+
+async function ensurePointerSlot(actual) {
+  const info = await lstatOrNull(actual);
+  if (info && !info.isSymbolicLink()) {
+    throw new StableInstallError(`${actual} no es un enlace de nexakit; muévelo para continuar.`);
+  }
+  return info;
+}
+
+async function publishVersion({ stagingDir, versionDir, version, packageSpec, runNpm, lock }) {
+  // We hold the lock, so anything left in the staging folder is from a run that died.
+  for (const entry of await fs.readdir(stagingDir)) await fs.rm(path.join(stagingDir, entry), { recursive: true, force: true });
+  const staging = path.join(stagingDir, `${version}-${crypto.randomUUID()}`);
+  try {
+    const result = await runNpm(['install', '--prefix', staging, '--no-audit', '--no-fund', packageSpec]);
+    if (result?.status !== 0) throw new StableInstallError(`npm no pudo instalar ${packageSpec}: ${firstLine(result?.stderr)}`);
+    await validatePackageRoot(path.join(staging, 'node_modules', PACKAGE_NAME), version);
+    await fs.writeFile(path.join(staging, COMPLETE_MARKER), `${new Date().toISOString()}\n`, { flag: 'wx', mode: 0o600 });
+    await lock.assertHeld();
+    await fs.rename(staging, versionDir);
+  } catch (error) {
+    await fs.rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+// Puts the link `temporary` where `actual` is. Renaming over the old link is atomic; Windows refuses that for a
+// junction, so there the old pointer is moved aside first and put back if the second rename fails: the pointer
+// can be missing for an instant there, but it is never lost.
+export async function replacePointer(temporary, actual, { windows = IS_WINDOWS, rename = fs.rename } = {}) {
+  try {
+    await rename(temporary, actual);
+    return;
+  } catch (error) {
+    if (!windows || !['EPERM', 'EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error;
+  }
+  const aside = `${actual}.anterior.${crypto.randomUUID()}`;
+  await rename(actual, aside);
+  try {
+    await rename(temporary, actual);
+  } catch (error) {
+    await rename(aside, actual).catch(() => {});
+    throw error;
+  }
+  await fs.unlink(aside).catch(() => {});
+}
+
+async function movePointer({ base, actual, packageRoot, lock }) {
+  const current = await ensurePointerSlot(actual);
+  if (current) {
+    const [real, wanted] = await Promise.all([realpathOrNull(actual), fs.realpath(packageRoot)]);
+    if (real && samePath(real, wanted)) return 'igual';
+  }
+  // Build the new link beside the old one and rename over it: the pointer never goes missing.
+  const temporary = path.join(base, `actual.${crypto.randomUUID()}`);
+  await fs.symlink(packageRoot, temporary, IS_WINDOWS ? 'junction' : 'dir');
+  try {
+    await lock.assertHeld();
+    await replacePointer(temporary, actual);
+  } catch (error) {
+    await fs.unlink(temporary).catch(() => {});
+    throw error;
+  }
+  return 'movido';
+}
+
+// Leaves `~/.nexakit/actual` pointing at a complete, validated copy of this version (or keeps a newer one).
+// Must run under the install lock; `runNpm(args)` returns `{ status, stderr }` and may be async.
+export async function ensureStableInstall({
+  homeDirectory, version, lock, runNpm = defaultRunNpm,
+  packageSpec = process.env.NEXAKIT_PAQUETE || `nexakit@${version}`
+}) {
+  if (typeof version !== 'string' || !VERSION_RE.test(version)) {
+    throw new StableInstallError(`Versión de nexakit no válida: ${String(version)}`);
+  }
+  const base = nexakitDir(homeDirectory);
+  const versionsDir = path.join(base, 'versiones');
+  const stagingDir = path.join(base, 'preparacion');
+  const actual = actualRoot(homeDirectory);
+  try {
+    await lock.assertHeld();
+    for (const directory of [base, versionsDir, stagingDir]) await ensureRealDirectory(directory);
+    await ensurePointerSlot(actual);
+
+    const activeVersion = await readActualVersion(homeDirectory);
+    if (activeVersion && compareVersions(activeVersion, version) > 0) {
+      return { root: actual, version: activeVersion, reused: true, pointer: 'mayor-conservado' };
+    }
+
+    const versionDir = path.join(versionsDir, version);
+    const packageRoot = path.join(versionDir, 'node_modules', PACKAGE_NAME);
+    let reused = false;
+    if (await lstatOrNull(path.join(versionDir, COMPLETE_MARKER))) {
+      await validatePackageRoot(packageRoot, version);
+      reused = true;
+    } else {
+      if (await lstatOrNull(versionDir)) {
+        throw new StableInstallError(`La carpeta ${versionDir} existe pero está incompleta; bórrala para reinstalar.`);
+      }
+      await publishVersion({ stagingDir, versionDir, version, packageSpec, runNpm, lock });
+    }
+    const pointer = await movePointer({ base, actual, packageRoot, lock });
+    return { root: actual, version, reused, pointer };
+  } catch (error) {
+    if (error instanceof StableInstallError || error instanceof LockError || error?.code === 'perdido') throw error;
+    throw new StableInstallError(`No se pudo preparar la copia estable de nexakit: ${error.message}`);
+  }
+}

package/src/superpowers.js

@@ -0,0 +1,133 @@
+// Superpowers (obra/superpowers, MIT) is required: it carries the work process (brainstorming, plans, debugging,
+// TDD, verification). Each agent installs it from the marketplace reviewed for it; nexakit only lists, installs or
+// enables it through the agent's own CLI and never edits plugin folders by hand.
+import { spawnSync } from 'node:child_process';
+import { constants } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveCliInvocation } from './cli-executable.js';
+import { IS_WINDOWS } from './platform.js';
+
+export const SUPERPOWERS = Object.freeze({
+  claude: Object.freeze({
+    command: 'claude',
+    id: 'superpowers@claude-plugins-official',
+    list: ['plugin', 'list', '--json'],
+    install: ['plugin', 'install', 'superpowers@claude-plugins-official'],
+    enable: ['plugin', 'enable', 'superpowers@claude-plugins-official'],
+  }),
+  codex: Object.freeze({
+    command: 'codex',
+    id: 'superpowers@openai-curated-remote',
+    list: ['plugin', 'list'],
+    install: ['plugin', 'add', 'superpowers@openai-curated-remote'],
+    // `codex plugin` has no enable: a disabled plugin is turned on from Codex itself (/plugins).
+    enable: null,
+  }),
+  antigravity: Object.freeze({
+    command: 'agy',
+    id: 'superpowers@antigravity-plugins-partners',
+    list: ['plugin', 'list', '--json'],
+    install: ['plugin', 'install', 'superpowers@antigravity-plugins-partners'],
+    enable: ['plugin', 'enable', 'superpowers'],
+  }),
+});
+
+const TIMEOUT_MS = 120_000;
+const AGENT_NAMES = { claude: 'Claude Code', codex: 'Codex', antigravity: 'Antigravity' };
+
+// 'activo' | 'desactivado' | 'falta' | 'desconocido'. Anything that cannot be read is unknown, never missing,
+// so nexakit does not try to install over a list it did not understand.
+export function parseSuperpowersState(agent, result) {
+  if (!result || result.status !== 0) return 'desconocido';
+  const text = String(result.stdout ?? '');
+  if (agent === 'codex') {
+    const row = text.split(/\r?\n/u).find((line) => /^superpowers@\S+\s/u.test(line.trim()));
+    if (!row) return 'desconocido';
+    if (/\bnot installed\b/u.test(row)) return 'falta';
+    if (/\bdisabled\b/u.test(row)) return 'desactivado';
+    return /\benabled\b/u.test(row) ? 'activo' : 'desconocido';
+  }
+  if (agent === 'antigravity' && /^\s*No plugins installed\.?\s*$/iu.test(text)) return 'falta';
+  let list;
+  try {
+    list = JSON.parse(text);
+  } catch {
+    return 'desconocido';
+  }
+  if (!Array.isArray(list)) list = list?.plugins;
+  if (!Array.isArray(list)) return 'desconocido';
+  const entry = list.find((item) =>
+    agent === 'claude' ? item?.id === SUPERPOWERS.claude.id : item?.name === 'superpowers',
+  );
+  if (!entry) return 'falta';
+  return entry.enabled === false ? 'desactivado' : 'activo';
+}
+
+function spawnCommand(command, args) {
+  // `codex plugin list` prints every remote marketplace (about 2 MB), above the 1 MB default buffer.
+  const result = spawnSync(command, args, { encoding: 'utf8', shell: false, timeout: TIMEOUT_MS, maxBuffer: 32 * 1024 * 1024 });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '', errorCode: result.error?.code };
+}
+
+const notFound = () => ({ status: null, stdout: '', stderr: '', errorCode: 'ENOENT' });
+
+// The CLI is looked up in the given environment's PATH, not this process's, so a test HOME never reaches the
+// person's real agents.
+async function defaultRunner(command, environment = process.env) {
+  if (!IS_WINDOWS) {
+    for (const folder of (environment.PATH ?? '').split(path.delimiter).filter(Boolean)) {
+      const file = path.join(folder, command);
+      try {
+        await fs.access(file, constants.X_OK);
+        if ((await fs.stat(file)).isFile()) return (_command, args) => spawnCommand(file, args);
+      } catch {}
+    }
+    return notFound;
+  }
+  try {
+    const invocation = await resolveCliInvocation({ name: command, environment });
+    return (_command, args) => spawnCommand(invocation.executable, [...invocation.argsPrefix, ...args]);
+  } catch {
+    return notFound;
+  }
+}
+
+export async function inspectSuperpowers({ agentsFound, runCommand, environment } = {}) {
+  const states = {};
+  for (const agent of Object.keys(SUPERPOWERS)) {
+    if (!agentsFound?.[agent]) continue;
+    const { command, list } = SUPERPOWERS[agent];
+    const run = runCommand ?? (await defaultRunner(command, environment));
+    let result;
+    try {
+      result = await run(command, list);
+    } catch {
+      result = null;
+    }
+    states[agent] = parseSuperpowersState(agent, result);
+  }
+  return states;
+}
+
+// The command a person can run by hand, for messages.
+export function superpowersCommand(agent, state) {
+  const entry = SUPERPOWERS[agent];
+  const args = state === 'desactivado' ? entry.enable : entry.install;
+  return args ? `${entry.command} ${args.join(' ')}` : null;
+}
+
+export async function applySuperpowers(agent, state, { runCommand, environment } = {}) {
+  const entry = SUPERPOWERS[agent];
+  if (!entry) throw new Error(`Agente desconocido: ${agent}`);
+  if (state !== 'falta' && state !== 'desactivado') return false;
+  const args = state === 'falta' ? entry.install : entry.enable;
+  if (!args) throw new Error(`Superpowers está desactivado en ${AGENT_NAMES[agent]}; actívalo desde ${AGENT_NAMES[agent]} (/plugins).`);
+  const run = runCommand ?? (await defaultRunner(entry.command, environment));
+  const result = await run(entry.command, args);
+  if (result?.status !== 0) {
+    const detail = String(result?.stderr || result?.stdout || result?.errorCode || '').trim();
+    throw new Error(`No se pudo ${state === 'falta' ? 'instalar' : 'activar'} Superpowers en ${AGENT_NAMES[agent]}.${detail ? ` ${detail}` : ''}`);
+  }
+  return true;
+}

package/src/sync-apply.js

@@ -161,7 +161,7 @@ function writeNotes({ vault, notes, before, capture, report }, context) {
   try {
     check();
     const fd = io.openSync(lockPath, "wx", 0o600);
-    try { lock = fs.fstatSync(fd); } finally { fs.closeSync(fd); }
+    try { lock = fs.fstatSync(fd, { bigint: true }); } finally { fs.closeSync(fd); }
     artifacts.push({ path: lockPath, stat: lock }); ignored.push(relativeGitPath(vault, lockPath));
     check();
     const pending = notes.filter((n) => !n.satisfied), temps = new Map();
@@ -171,7 +171,7 @@ function writeNotes({ vault, notes, before, capture, report }, context) {
       const temp = path.join(path.dirname(note.file.path), `.project-memory-sync-apply-${randomUUID()}.tmp`);
       const fd = io.openSync(temp, "wx", 0o600); let stat;
       try {
-        stat = fs.fstatSync(fd); artifacts.push({ path: temp, stat }); ignored.push(relativeGitPath(vault, temp));
+        stat = fs.fstatSync(fd, { bigint: true }); artifacts.push({ path: temp, stat }); ignored.push(relativeGitPath(vault, temp));
         io.writeFileSync(fd, note.bytes); io.fchmodSync(fd, note.file.mode); io.fsyncSync(fd);
       } finally { fs.closeSync(fd); }
       assertOwnedArtifact(temp, stat);
@@ -186,9 +186,12 @@ function writeNotes({ vault, notes, before, capture, report }, context) {
       if (prepared.hash !== note.afterHash || prepared.mode !== note.file.mode) rejectFile("temporary-content", "Un temporal cambió antes de reemplazar.");
       let renameError;
       try { io.renameSync(temp.path, note.file.path); } catch (error) { renameError = error; }
-      let result;
-      try { result = readSyncFile(note.file.path, APPLY_LIMITS.note); } catch { /* An unconfirmable outcome is conservative, never rolled back. */ }
-      const installed = result && result.identity[0] === temp.stat.dev && result.identity[1] === temp.stat.ino && result.hash === note.afterHash && result.mode === note.file.mode;
+      let result, installedIdentity;
+      try {
+        installedIdentity = fs.lstatSync(note.file.path, { bigint: true });
+        result = readSyncFile(note.file.path, APPLY_LIMITS.note);
+      } catch { /* An unconfirmable outcome is conservative, never rolled back. */ }
+      const installed = result && installedIdentity.dev === temp.stat.dev && installedIdentity.ino === temp.stat.ino && result.hash === note.afterHash && result.mode === note.file.mode;
       if (installed) {
         applied.push(note.path);
         expected.files[expected.files.findIndex((f) => f.path === note.file.path)] = fileState(result);

package/src/sync-files.js

@@ -102,7 +102,8 @@ export function assertSameState(before, after) {
 }
 export function assertOwnedArtifact(file, expected) {
   assertPhysicalPath(file);
-  const stat = fs.lstatSync(file);
+  // Inodes on Windows may exceed Number.MAX_SAFE_INTEGER. Never round ownership.
+  const stat = fs.lstatSync(file, { bigint: true });
   if (!stat.isFile() || stat.isSymbolicLink() || stat.dev !== expected.dev || stat.ino !== expected.ino) rejectFile("artifact-conflict", "Un artefacto fue sustituido; no se tocará.");
 }
 function identity(stat) { return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs]; }