nexakit 0.1.0 → 0.2.0

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

package/src/setup-state.js

@@ -0,0 +1,277 @@
+// Gathers, read-only, everything the setup questions and the confirmation need: the project and what it uses, the
+// skills and their links, the agents installed, their base skills, the stable command and the project memory.
+// Nothing here writes; setup-apply.js does, after the person confirms.
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { planReviewInstructions } from './review-instructions.js';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { connectMemory } from './connect.js';
+import { ACTIONABLE_LINK_STATES } from './link-states.js';
+import {
+  findKnownMemories,
+  memoryForRepository,
+  registeredServers,
+  suggestMemoryLocation,
+} from './memory-locator.js';
+import { AGENTS, shortReason } from './setup-plan.js';
+import { loadSkillCatalog } from './skill-catalog.js';
+import {
+  inspectSkillProject,
+  planProjectSkillInstall,
+  readSetupAnswers,
+  recommendSkills,
+  uncoveredSignals,
+} from './skill-recommendations.js';
+import { planStableCommand } from './stable-command.js';
+import { inspectSuperpowers } from './superpowers.js';
+import { compareVersions, readActualVersion } from './stable-install.js';
+import {
+  TOOLKIT_ROOT,
+  executable,
+  packageVersion,
+  resolveNodeExecutable,
+  setupToolkit,
+} from './toolkit-setup.js';
+
+const CONFLICT_LINK_STATES = new Set(['conflicto', 'roto-ajeno']);
+
+// What is at a memory path: this repository's memory, a place for a new one, another project's memory ('foreign'),
+// or something else ('invalid'). Only 'memory' and 'new' are ever written; the other two are left alone.
+export async function inspectMemoryPath(target, { repositoryRoot } = {}) {
+  const info = await fs
+    .lstat(target)
+    .catch((error) => (error.code === 'ENOENT' ? null : Promise.reject(error)));
+  if (!info) return 'new';
+  if (!info.isDirectory() || info.isSymbolicLink()) return 'invalid';
+  const manifestPath = path.join(target, 'project-memory.json');
+  const manifest = await fs.lstat(manifestPath).catch(() => null);
+  if (manifest?.isFile() && !manifest.isSymbolicLink()) {
+    if (!repositoryRoot) return 'memory';
+    try {
+      const source = JSON.parse(await fs.readFile(manifestPath, 'utf8'))?.source?.repositoryPath;
+      const real =
+        typeof source === 'string' ? await fs.realpath(source).catch(() => path.resolve(source)) : null;
+      return real && real === (await fs.realpath(repositoryRoot).catch(() => repositoryRoot))
+        ? 'memory'
+        : 'foreign';
+    } catch {
+      return 'invalid';
+    }
+  }
+  return (await fs.readdir(target)).length === 0 ? 'new' : 'invalid';
+}
+
+async function readMemoryManifest(vaultPath) {
+  try {
+    return JSON.parse(await fs.readFile(path.join(vaultPath, 'project-memory.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// For an agent the memory does not reach yet: its MCP name must be free in that agent, or already serve this vault.
+async function newConnection(agent, { mcpName, vaultPath, servers, agentsFound }) {
+  if (!agentsFound[agent]) return 'unavailable';
+  if (!Object.hasOwn(servers[agent] ?? {}, mcpName)) return 'create';
+  // Taken by this same vault with the server this agent's connection uses (Antigravity: nexakit's read-only
+  // server; Claude and Codex: server-filesystem) is fine; anything else under that name is a conflict.
+  const real = await fs.realpath(vaultPath).catch(() => path.resolve(vaultPath));
+  const current = servers[agent][mcpName];
+  const expected = agent === 'antigravity' ? 'guard' : 'filesystem';
+  return current?.vault === real && current.kind === expected ? 'create' : 'conflict';
+}
+
+// How an existing memory is connected to each agent: unchanged, create, conflict or unavailable (no CLI). An agent
+// the memory does not declare yet (an older memory without Antigravity) is "create": connecting it declares it.
+export async function memoryConnections(
+  vaultPath,
+  { homeDirectory, codexHome, runCommand, nodePath, toolkitRoot, agentsFound, kind = 'memory', mcpName },
+) {
+  const servers = await registeredServers({ homeDirectory, ...(codexHome && { codexHome }) });
+  const manifest = kind === 'memory' ? await readMemoryManifest(vaultPath) : null;
+  const name = manifest?.memory?.mcpServerName ?? mcpName;
+  const declared = (manifest?.agents ?? []).filter((agent) => agent.enabled).map((agent) => agent.id);
+  const result = {};
+  for (const agent of AGENTS) {
+    if (!declared.includes(agent)) {
+      result[agent] = await newConnection(agent, { mcpName: name, vaultPath, servers, agentsFound });
+      continue;
+    }
+    try {
+      const report = await connectMemory(
+        { targetPath: vaultPath, agentId: agent },
+        { homeDirectory, nodePath, toolkitRoot, ...(runCommand && { runCommand }) },
+      );
+      const mcp = report.components.find((component) => component.id === 'mcp');
+      if (/No se encontró el comando/u.test(mcp?.message ?? '')) result[agent] = 'unavailable';
+      else if (report.components.some((component) => component.action === 'conflict'))
+        result[agent] = 'conflict';
+      else
+        result[agent] = report.components.every((component) => component.action === 'unchanged')
+          ? 'unchanged'
+          : 'create';
+    } catch {
+      result[agent] = 'conflict';
+    }
+  }
+  return result;
+}
+
+export async function gatherSetupState({
+  start = process.cwd(),
+  homeDirectory = os.homedir(),
+  environment = process.env,
+  toolkitRoot = TOOLKIT_ROOT,
+  codexHome = environment.CODEX_HOME ?? path.join(homeDirectory, '.codex'),
+  runCommand,
+  memoryPaths = [],
+} = {}) {
+  const catalog = await loadSkillCatalog(
+    toolkitRoot === TOOLKIT_ROOT
+      ? {}
+      : { catalogUrl: pathToFileURL(path.join(toolkitRoot, 'catalogs/skills.json')) },
+  );
+  const inspection = await inspectSkillProject(start, { toolkitRoot, catalog, homeDirectory });
+  const project = inspection.project;
+  const recommendation = recommendSkills({ catalog, inspection });
+  const projectPlan = await planProjectSkillInstall({
+    projectRoot: project.root,
+    skillNames: catalog.skills.map((skill) => skill.name),
+    agent: 'all',
+    mode: 'symlink',
+    catalog,
+    toolkitRoot,
+    homeDirectory,
+  });
+  const signalById = new Map(inspection.signals.map((signal) => [signal.id, signal]));
+  const linkState = (name, client) =>
+    projectPlan.links.find((link) => link.name === name && link.client === client)?.state ?? 'missing';
+  const skills = [
+    ...recommendation.recommended,
+    ...recommendation.candidates,
+    ...recommendation.optional,
+  ].map((entry) => {
+    const first = entry.matchedSignals?.[0];
+    const signal = first && signalById.get(first);
+    return {
+      name: entry.name,
+      summary: entry.summary,
+      reason: signal ? shortReason(signal.label, signal.sources[0]) : null,
+      matchCount: entry.matchedSignals?.length ?? 0,
+      suggested: (entry.matchedSignals?.length ?? 0) > 0,
+      license: entry.license,
+      tested: entry.recommendationStatus === 'validated',
+      reviewNotes: entry.reviewStatus === 'reviewed-with-observations' ? entry.reviewNotes : null,
+      links: { claude: linkState(entry.name, 'claude'), codex: linkState(entry.name, 'codex') },
+    };
+  });
+
+  const setup = await setupToolkit({
+    agent: 'all',
+    apply: false,
+    homeDirectory,
+    toolkitRoot,
+    environment,
+    codexHome,
+  });
+  const globalSkills = Object.fromEntries(
+    AGENTS.map((agent) => {
+      const items = setup.skills.filter((item) => item.client === agent);
+      return [
+        agent,
+        {
+          pending: items.filter((item) => ACTIONABLE_LINK_STATES.includes(item.state)).length,
+          conflicts:
+            items.filter((item) => CONFLICT_LINK_STATES.has(item.state)).length +
+            (setup.retiredSkills ?? []).filter((item) => item.client === agent && !item.owned).length,
+        },
+      ];
+    }),
+  );
+  const agentsFound = {
+    claude: await executable('claude', environment),
+    codex: await executable('codex', environment),
+    antigravity: setup.clients.includes('antigravity'),
+  };
+
+  const version = await packageVersion(toolkitRoot);
+  const actualVersion = setup.ephemeral ? await readActualVersion(homeDirectory) : null;
+  for (const agent of Object.keys(globalSkills))
+    globalSkills[agent].retiredCount = (setup.retiredSkills ?? []).filter(
+      (s) => s.client === agent && s.owned,
+    ).length;
+  const stableCopy = {
+    needed: Boolean(setup.ephemeral) && (!actualVersion || compareVersions(actualVersion, version) < 0),
+  };
+  const nodePath = await resolveNodeExecutable(environment);
+  const stableCommand = await planStableCommand({ homeDirectory, nodePath, toolkitRoot: setup.linkRoot });
+
+  const savedAnswers = await readSetupAnswers(project.root);
+  const known = await findKnownMemories({ homeDirectory, codexHome });
+  const existingEntry = memoryForRepository(known, project.root);
+  const suggestedPath = suggestMemoryLocation(known, { id: project.id, homeDirectory });
+  const memory = {
+    existing: existingEntry && { vaultPath: existingEntry.vaultPath },
+    suggestedPath,
+    kinds: {},
+    connections: {},
+  };
+  // The chosen path is always inspected, also one typed in "otra carpeta…" (memoryPaths).
+  const candidates = [
+    existingEntry?.vaultPath,
+    suggestedPath,
+    savedAnswers?.memory?.path,
+    ...memoryPaths,
+  ].filter(Boolean);
+  const context = {
+    homeDirectory,
+    codexHome,
+    runCommand,
+    nodePath,
+    toolkitRoot: setup.linkRoot,
+    agentsFound,
+    mcpName: `${project.id}-memory`,
+  };
+  for (const candidate of [...new Set(candidates)]) {
+    const kind = await inspectMemoryPath(candidate, { repositoryRoot: project.root });
+    memory.kinds[candidate] = kind;
+    if (kind === 'memory' || kind === 'new')
+      memory.connections[candidate] = await memoryConnections(candidate, { ...context, kind });
+  }
+
+  const reviewInstructions = await planReviewInstructions({ homeDirectory, environment, codexHome });
+  const superpowers = await inspectSuperpowers({ agentsFound, runCommand, environment });
+  return {
+    reviewInstructions,
+    superpowers,
+    homeDirectory,
+    version,
+    project,
+    signals: inspection.signals,
+    skills,
+    // Suggested but installed outside NexaKit (for example as a Claude plugin): listed, never selectable.
+    externalSkills: recommendation.externalCandidates.map(ref => ({ name: ref.name, reason: ref.reasons[0] ?? null })),
+    // Found in the project but covered by no catalog skill: reported only, never searched for automatically.
+    uncoveredTech: uncoveredSignals({ signals: inspection.signals, catalog }),
+    agentsFound,
+    globalSkills,
+    stableCopy,
+    stableCommand,
+    memory,
+    savedAnswers,
+    // For setup-apply.js and the detail screen; not part of the summary.
+    internal: {
+      catalog,
+      inspection,
+      projectPlan,
+      setup,
+      nodePath,
+      toolkitRoot,
+      linkRoot: setup.linkRoot,
+      codexHome,
+      environment,
+      runCommand,
+    },
+  };
+}