nexakit 0.0.0-stage → 0.2.0

package/src/setup-apply.js

@@ -0,0 +1,231 @@
+import { planReviewInstructions, applyReviewInstructions } from './review-instructions.js';
+// Applies the confirmation, block by block, in the fixed order of setup-plan.js. The state is gathered again right
+// before applying, so what changed meanwhile is respected. The first block that fails stops the run: what was
+// applied stays, nothing is undone, and running `npx nexakit` again resumes from the real state.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { connectMemory } from './connect.js';
+import { diagnoseMemory } from './doctor.js';
+import { initializeMemory } from './init.js';
+import { acquireLock } from './install-lock.js';
+import { AGENT_NAMES, buildConfirmation } from './setup-plan.js';
+import { gatherSetupState } from './setup-state.js';
+import {
+  applyProjectSkillInstall,
+  applyToolkitDetach,
+  planProjectSkillInstall,
+  planToolkitDetach,
+  writeSetupAnswers,
+} from './skill-recommendations.js';
+import { planStableCommand, writeStableCommand } from './stable-command.js';
+import { ensureStableInstall, nexakitDir } from './stable-install.js';
+import { packageVersion, setupToolkit } from './toolkit-setup.js';
+import { applySuperpowers } from './superpowers.js';
+
+const RETRY = 'Vuelve a ejecutar `npx nexakit` para reintentar.';
+
+// Project skill folders: Claude reads .claude/skills; Codex and Antigravity share .agents/skills.
+function projectAgent(agents) {
+  const claude = agents.includes('claude');
+  const shared = agents.includes('codex') || agents.includes('antigravity');
+  if (claude && shared) return 'all';
+  if (claude) return 'claude';
+  return agents.includes('codex') ? 'codex' : 'antigravity';
+}
+
+// An older memory may not declare an agent (Antigravity came later): declare it, enabled, with the same skill.
+// Only this repository's memory is touched, and the read-modify-replace runs under the install lock.
+async function ensureMemoryAgent(vaultPath, agent, repositoryRoot, lock) {
+  const file = path.join(vaultPath, 'project-memory.json');
+  await lock.assertHeld();
+  const manifest = JSON.parse(await fs.readFile(file, 'utf8'));
+  const source = await fs.realpath(manifest.source?.repositoryPath ?? '').catch(() => null);
+  if (source !== (await fs.realpath(repositoryRoot)))
+    throw new Error('La memoria es de otro proyecto; no se modifica.');
+  const current = manifest.agents.find((entry) => entry.id === agent);
+  if (current?.enabled) return;
+  if (current) current.enabled = true;
+  else
+    manifest.agents.push({
+      id: agent,
+      enabled: true,
+      skillName: manifest.agents[0]?.skillName ?? manifest.project.id,
+    });
+  const temporary = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+  try {
+    await lock.assertHeld();
+    await fs.rename(temporary, file);
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+}
+
+async function withLock(homeDirectory, acquire, fn) {
+  const lock = await acquire(nexakitDir(homeDirectory));
+  try {
+    return await fn(lock);
+  } finally {
+    await lock.release();
+  }
+}
+
+export async function applySetup(
+  options,
+  answers,
+  { onProgress = () => {}, runNpm, packageSpec, acquire = acquireLock, gather = gatherSetupState } = {},
+) {
+  const memoryPath = answers.memory.decision === 'path' ? answers.memory.path : null;
+  // The chosen memory path is always inspected again, also one typed in "otra carpeta…".
+  const stateOptions = { ...options, memoryPaths: memoryPath ? [memoryPath] : [] };
+  const state = await gather(stateOptions);
+  const confirmation = buildConfirmation(state, answers);
+  const { homeDirectory } = state;
+  const { catalog, toolkitRoot, environment, codexHome, nodePath, runCommand } = state.internal;
+  let linkRoot = state.internal.linkRoot;
+  const done = [];
+  let finalCheck = null;
+
+  const blocks = {
+    'stable-copy': () =>
+      withLock(homeDirectory, acquire, async (lock) => {
+        const result = await ensureStableInstall({
+          homeDirectory,
+          version: await packageVersion(toolkitRoot),
+          lock,
+          ...(runNpm && { runNpm }),
+          ...(packageSpec && { packageSpec }),
+        });
+        linkRoot = path.join(nexakitDir(homeDirectory), 'actual');
+        return result;
+      }),
+    'stable-command': () =>
+      withLock(homeDirectory, acquire, async (lock) =>
+        writeStableCommand(await planStableCommand({ homeDirectory, nodePath, toolkitRoot: linkRoot }), lock),
+      ),
+    'project-skills': async () => {
+      const chosen = answers.skills.chosen;
+      if (chosen.length) {
+        const plan = await planProjectSkillInstall({
+          projectRoot: state.project.root,
+          skillNames: chosen,
+          agent: projectAgent(answers.agents),
+          mode: 'symlink',
+          catalog,
+          toolkitRoot,
+          homeDirectory,
+        });
+        await applyProjectSkillInstall(plan, {
+          ...(runNpm && { runNpm }),
+          ...(packageSpec && { packageSpec }),
+          acquire,
+        });
+      }
+      if (confirmation.removeSkills.length) {
+        const detach = await planToolkitDetach({
+          projectRoot: state.project.root,
+          skillNames: confirmation.removeSkills,
+          catalog,
+          toolkitRoot,
+          homeDirectory,
+        });
+        await applyToolkitDetach(detach);
+      }
+    },
+    'review-instructions': () =>
+      withLock(homeDirectory, acquire, async (lock) => {
+        const plan = await planReviewInstructions({
+          homeDirectory,
+          environment,
+          codexHome,
+          agents: answers.agents,
+        });
+        await applyReviewInstructions(plan, lock);
+      }),
+    'memory-init': async () => {
+      const report = initializeMemory({
+        destination: memoryPath,
+        projectId: state.project.id,
+        projectName: state.project.displayName,
+        sourcePath: state.project.root,
+        syncMode: 'none',
+        agents: answers.agents,
+        apply: true,
+      });
+      if (report.status === 'conflict')
+        throw new Error('La carpeta de la memoria ya tiene archivos que no son de nexakit.');
+      const diagnosis = await diagnoseMemory(memoryPath);
+      if (diagnosis.summary.errors > 0)
+        throw new Error('La memoria se creó, pero su comprobación encontró errores.');
+    },
+    answers: () =>
+      withLock(homeDirectory, acquire, (lock) => writeSetupAnswers(state.project.root, answers, lock)),
+    'final-check': async () => {
+      const after = buildConfirmation(await gather(stateOptions), answers).lines;
+      const pending = after.filter((line) => ['+', '−', '↻'].includes(line.mark)).map((line) => line.text);
+      const warnings = after.filter((line) => line.mark === '!').map((line) => line.text);
+      const memoryErrors = memoryPath ? (await diagnoseMemory(memoryPath)).summary.errors : 0;
+      if (memoryErrors) pending.push('la memoria tiene errores');
+      finalCheck = pending.length
+        ? { ok: false, message: `quedó pendiente: ${pending.join('; ')}.`, warnings }
+        : {
+            ok: true,
+            message: warnings.length ? `responde, con avisos: ${warnings.join('; ')}.` : 'todo responde',
+            warnings,
+          };
+    },
+  };
+  const runBlock = async (id) => {
+    if (blocks[id]) return blocks[id]();
+    const [kind, agent] = id.split(':');
+    if (kind === 'global-skills') {
+      return setupToolkit({
+        agent,
+        apply: true,
+        homeDirectory,
+        toolkitRoot,
+        environment,
+        codexHome,
+        ...(runNpm && { runNpm }),
+        ...(packageSpec && { packageSpec }),
+        acquire,
+      });
+    }
+    if (kind === 'superpowers') {
+      return applySuperpowers(agent, state.superpowers?.[agent], { environment, ...(runCommand && { runCommand }) });
+    }
+    if (kind === 'memory-connect') {
+      await withLock(homeDirectory, acquire, (lock) =>
+        ensureMemoryAgent(memoryPath, agent, state.project.root, lock),
+      );
+      const report = await connectMemory(
+        { targetPath: memoryPath, agentId: agent, apply: true },
+        { homeDirectory, nodePath, toolkitRoot: linkRoot, ...(runCommand && { runCommand }) },
+      );
+      if (report.status === 'conflict') {
+        const reason = report.components.find((component) => component.action === 'conflict')?.message ?? '';
+        throw new Error(`No se pudo conectar la memoria a ${AGENT_NAMES[agent]}: ${reason}`);
+      }
+      return report;
+    }
+    throw new Error(`Bloque desconocido: ${id}`);
+  };
+
+  for (const { id } of confirmation.blocks) {
+    onProgress(id, 'start');
+    try {
+      await runBlock(id);
+    } catch (error) {
+      const detail = error instanceof Error ? error.details?.join(' ') || error.message : String(error);
+      const message = id.startsWith('memory-connect:')
+        ? `${detail.startsWith('No se pudo') ? detail : `No se pudo conectar la memoria a ${AGENT_NAMES[id.split(':')[1]]}: ${detail}`} ${RETRY}`
+        : `Falló «${confirmation.blocks.find((block) => block.id === id).label}»: ${detail} ${RETRY}`;
+      onProgress(id, 'failed', message);
+      return { ok: false, done, failed: { id, message }, finalCheck };
+    }
+    done.push(id);
+    onProgress(id, 'done');
+  }
+  // A final check that finds something still pending is a failure: the person must not read «Listo».
+  return { ok: finalCheck?.ok ?? true, done, finalCheck };
+}

package/src/setup-plan.js

@@ -0,0 +1,231 @@
+// Pure: turns what nexakit found (setup-state.js) and the person's answers into the confirmation summary, in short
+// sentences, and the ordered blocks that apply it. No I/O, so every screen and every decision is testable.
+
+export const AGENTS = Object.freeze(['claude', 'codex', 'antigravity']);
+export const AGENT_NAMES = Object.freeze({
+  claude: 'Claude Code',
+  codex: 'Codex',
+  antigravity: 'Antigravity',
+});
+// Claude reads project skills from .claude/skills; Codex and Antigravity share .agents/skills.
+const folderOf = (agent) => (agent === 'claude' ? 'claude' : 'codex');
+const FOLDER_PATHS = Object.freeze({ claude: '.claude/skills', codex: '.agents/skills' });
+const PENDING_LINKS = new Set(['missing', 'replace']);
+
+export function joinNames(names) {
+  return names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} y ${names.at(-1)}`;
+}
+// ~/… for paths under the home folder, with either separator (Windows uses \\).
+export const shortPath = (target, homeDirectory) =>
+  homeDirectory &&
+  (target === homeDirectory ||
+    target.startsWith(`${homeDirectory}/`) ||
+    target.startsWith(`${homeDirectory}\\`))
+    ? `~${target.slice(homeDirectory.length)}`
+    : target;
+const plural = (count, one, many) => (count === 1 ? one : many);
+
+// "frontend usa React", "el README menciona Tauri": the reason for a suggestion, from where the signal was found.
+export function shortReason(label, source) {
+  const file = source.replace(/\s*\(.*\)$/u, '');
+  const parts = file.split('/');
+  const folder = parts.length > 1 ? parts.slice(0, -1).join('/') : null;
+  if (/^readme\.md$/iu.test(parts.at(-1)))
+    return folder ? `${folder}/README menciona ${label}` : `el README menciona ${label}`;
+  return folder ? `${folder} usa ${label}` : `el proyecto usa ${label}`;
+}
+
+const linkStates = (skill, agents) =>
+  [...new Set(agents.map(folderOf))].map((folder) => [folder, skill.links?.[folder] ?? 'missing']);
+
+export function suggestedAnswers(state) {
+  const names = new Set(state.skills.map((skill) => skill.name));
+  const saved = state.savedAnswers;
+  if (saved) {
+    const answered = new Set([...saved.skills.chosen, ...saved.skills.discarded]);
+    const chosen = state.skills
+      .filter(
+        (skill) => saved.skills.chosen.includes(skill.name) || (skill.suggested && !answered.has(skill.name)),
+      )
+      .map((skill) => skill.name);
+    return {
+      version: 1,
+      skills: { chosen, discarded: saved.skills.discarded.filter((name) => names.has(name)) },
+      agents: [...saved.agents],
+      memory: { ...saved.memory },
+    };
+  }
+  const installed = (skill) => Object.values(skill.links ?? {}).includes('installed');
+  const found = AGENTS.filter((agent) => state.agentsFound[agent]);
+  const memory = state.memory.existing
+    ? { decision: 'path', path: state.memory.existing.vaultPath }
+    : state.project.git
+      ? { decision: 'path', path: state.memory.suggestedPath }
+      : { decision: 'later' };
+  return {
+    version: 1,
+    skills: {
+      chosen: state.skills.filter((skill) => skill.suggested || installed(skill)).map((skill) => skill.name),
+      discarded: [],
+    },
+    agents: found.length ? found : [...AGENTS],
+    memory,
+  };
+}
+
+const sameAnswers = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+export function buildConfirmation(state, answers) {
+  const lines = [];
+  const blocks = [];
+  const add = (mark, text) => lines.push({ mark, text });
+  const block = (id, label) => blocks.push({ id, label });
+  const answersChanged = !state.savedAnswers || !sameAnswers(state.savedAnswers, answers);
+  const agents = AGENTS.filter((agent) => answers.agents.includes(agent));
+  const home = state.homeDirectory;
+
+  if (state.stableCopy.needed) {
+    add('+', 'Copia estable de nexakit en ~/.nexakit');
+    block('stable-copy', 'Copia estable de nexakit');
+  }
+  if (['falta', 'distinto'].includes(state.stableCommand.state)) {
+    add('+', 'Orden nexakit para tus IA');
+    block('stable-command', 'Orden nexakit');
+  } else if (state.stableCommand.state === 'conflicto') {
+    add('!', '~/.nexakit/nexakit existe y no es de nexakit; no lo toco');
+  }
+
+  // Project skills, in the folders of the chosen agents.
+  const chosen = state.skills.filter((skill) => answers.skills.chosen.includes(skill.name));
+  const toInstall = [],
+    conflicts = [],
+    readySkills = [];
+  for (const skill of chosen) {
+    // Per folder: a user folder is left alone, and the skill is still installed where it is missing.
+    const states = linkStates(skill, agents);
+    for (const [folder, value] of states) if (value === 'conflict') conflicts.push([skill, folder]);
+    if (states.some(([, value]) => PENDING_LINKS.has(value))) toInstall.push(skill);
+    else if (states.every(([, value]) => value === 'installed')) readySkills.push(skill);
+  }
+  const removeSkills = state.skills
+    .filter(
+      (skill) =>
+        !answers.skills.chosen.includes(skill.name) && Object.values(skill.links ?? {}).includes('installed'),
+    )
+    .map((skill) => skill.name);
+  if (toInstall.length) {
+    add(
+      '+',
+      `${toInstall.length} ${plural(toInstall.length, 'skill en el proyecto (ignorada en Git)', 'skills en el proyecto (ignoradas en Git)')}`,
+    );
+  }
+  if (removeSkills.length)
+    add('−', `Quitar ${removeSkills.length} ${plural(removeSkills.length, 'skill', 'skills')} del proyecto`);
+  for (const [skill, folder] of conflicts) {
+    add('!', `${skill.name}: ya hay una carpeta tuya con ese nombre en ${FOLDER_PATHS[folder]}; no la toco`);
+  }
+  if (!toInstall.length && readySkills.length) add('✓', 'Skills del proyecto ya estaban listas');
+  if (toInstall.length || removeSkills.length) block('project-skills', 'Skills del proyecto');
+
+  // Base skills of each chosen agent: only what is missing or repairable; conflicts are reported.
+  const globalBlocks = [];
+  for (const agent of agents) {
+    const global = state.globalSkills[agent] ?? { pending: 0, conflicts: 0 };
+    if (global.retiredCount)
+      add('−', `Quitar ${global.retiredCount} comandos antiguos de ${AGENT_NAMES[agent]}`);
+    if (global.retiredCount && !global.pending) globalBlocks.push(agent);
+    if (global.pending) {
+      add(
+        '+',
+        `${global.pending} ${plural(global.pending, 'skill base', 'skills base')} en ${AGENT_NAMES[agent]}`,
+      );
+      globalBlocks.push(agent);
+    }
+    if (global.conflicts) {
+      add(
+        '!',
+        `${global.conflicts} ${plural(global.conflicts, 'skill base', 'skills base')} de ${AGENT_NAMES[agent]} ${plural(global.conflicts, 'choca con una carpeta tuya; no la toco', 'chocan con carpetas tuyas; no las toco')}`,
+      );
+    }
+  }
+  for (const agent of globalBlocks) block(`global-skills:${agent}`, `Skills base en ${AGENT_NAMES[agent]}`);
+
+  // Superpowers is required: the work process (brainstorming, plans, debugging, TDD, verification) comes from it.
+  const superpowers = state.superpowers ?? {};
+  const activeIn = [];
+  for (const agent of agents.filter((item) => Object.hasOwn(superpowers, item))) {
+    const status = superpowers[agent];
+    if (status === 'activo') activeIn.push(AGENT_NAMES[agent]);
+    else if (status === 'falta') {
+      add('+', `Superpowers en ${AGENT_NAMES[agent]}`);
+      block(`superpowers:${agent}`, `Superpowers en ${AGENT_NAMES[agent]}`);
+    } else if (status === 'desactivado' && agent !== 'codex') {
+      add('↻', `Activar Superpowers en ${AGENT_NAMES[agent]}`);
+      block(`superpowers:${agent}`, `Superpowers activo en ${AGENT_NAMES[agent]}`);
+    } else if (status === 'desactivado') {
+      add('!', `Superpowers está desactivado en ${AGENT_NAMES[agent]}; actívalo desde /plugins`);
+    } else {
+      add('!', `No pude comprobar Superpowers en ${AGENT_NAMES[agent]}; revisa ${agent === 'claude' ? '/plugin' : '/plugins'}`);
+    }
+  }
+  if (activeIn.length) add('✓', `Superpowers activo en ${joinNames(activeIn)}`);
+
+  // Memory: create it if needed, then connect it to each chosen agent.
+  if (answers.memory.decision === 'path') {
+    const target = answers.memory.path;
+    const kind = state.memory.kinds?.[target] ?? 'new';
+    if (kind === 'invalid') {
+      add('!', `${shortPath(target, home)} no está vacía y no es una memoria; elige otra carpeta`);
+    } else if (kind === 'foreign') {
+      add('!', `${shortPath(target, home)} es la memoria de otro proyecto; elige otra carpeta`);
+    } else {
+      if (kind === 'new') {
+        add('+', `Memoria nueva en ${shortPath(target, home)}`);
+        block('memory-init', 'Memoria creada');
+      } else {
+        add('✓', `Memoria del proyecto en ${shortPath(target, home)}`);
+      }
+      const connections = state.memory.connections?.[target] ?? {};
+      const statusOf = (agent) => connections[agent] ?? (state.agentsFound[agent] ? 'create' : 'unavailable');
+      const need = agents.filter((agent) => statusOf(agent) === 'create');
+      const connected = agents.filter((agent) => statusOf(agent) === 'unchanged');
+      if (need.length)
+        add('+', `Conectar la memoria a ${joinNames(need.map((agent) => AGENT_NAMES[agent]))}`);
+      else if (connected.length)
+        add('✓', `Memoria conectada a ${joinNames(connected.map((agent) => AGENT_NAMES[agent]))}`);
+      for (const agent of agents) {
+        if (statusOf(agent) === 'conflict')
+          add('!', `${AGENT_NAMES[agent]} ya tiene otra memoria con el mismo nombre; no la toco`);
+        if (statusOf(agent) === 'unavailable')
+          add('!', `No encontré ${AGENT_NAMES[agent]}; no puedo conectarle la memoria`);
+      }
+      for (const agent of need) block(`memory-connect:${agent}`, `Memoria conectada a ${AGENT_NAMES[agent]}`);
+    }
+  }
+
+  const instructionNames = new Set(
+    agents.map((agent) => ({ claude: 'CLAUDE.md', codex: 'AGENTS.md', antigravity: 'GEMINI.md' })[agent]),
+  );
+  const instructionItems = (state.reviewInstructions?.items ?? []).filter((item) =>
+    instructionNames.has(item.name),
+  );
+  for (const item of instructionItems.filter((item) => item.state === 'conflict'))
+    add('!', `${item.name}: las instrucciones existentes no se pueden actualizar; no las toco`);
+  const pendingInstructions = instructionItems.filter((item) => item.state === 'pending');
+  if (pendingInstructions.length) {
+    add(
+      '+',
+      `Reglas de trabajo en tus instrucciones de ${joinNames(pendingInstructions.map((item) => AGENT_NAMES[item.client]))}`,
+    );
+    block('review-instructions', 'Reglas de trabajo de tus IA');
+  }
+  if (answersChanged && (blocks.length || state.savedAnswers)) {
+    // Saved first, before any block that can fail, so a retry starts from what the person decided.
+    blocks.unshift({ id: 'answers', label: 'Respuestas guardadas' });
+    if (!blocks.some((item) => item.id === 'project-skills'))
+      add('+', 'Guardar tus respuestas en .agent-toolkit (ignorado en Git)');
+  }
+  if (blocks.length) block('final-check', 'Comprobación final');
+  const allReady = !lines.some((line) => ['+', '−', '↻'].includes(line.mark));
+  return { lines, blocks, allReady, removeSkills };
+}