nexakit 0.1.0 → 0.2.0

package/src/init.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 const SOURCE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATE_ROOT = path.resolve(SOURCE_DIRECTORY, "../templates/project-memory");
 const PROJECT_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const KNOWN_AGENTS = ["codex", "claude", "antigravity"];
 const BRANCH_PATTERN = /^(?!.*(?:\.\.|\/\/|@\{|\\))[A-Za-z0-9][A-Za-z0-9._/-]*[A-Za-z0-9]$|^[A-Za-z0-9]$/;
 const SYNC_MODES = new Set(["none", "git-manual", "git-automated"]);
 
@@ -73,6 +74,7 @@ function normalizeOptions(options, context) {
     memoryBranch: "main",
     mcpName: options.mcpName?.trim() || `${options.projectId?.trim()}-memory`,
     syncMode,
+    agents: options.agents ?? ["codex", "claude"],
     date: formatDate(now),
     templateRoot: path.resolve(context.templateRoot ?? TEMPLATE_ROOT)
   };
@@ -89,6 +91,12 @@ function validateConfig(config) {
     errors.push("--project-id debe usar minúsculas, números y guiones.");
   }
 
+  if (!Array.isArray(config.agents) || config.agents.length === 0 ||
+    config.agents.some((agent) => !KNOWN_AGENTS.includes(agent)) ||
+    new Set(config.agents).size !== config.agents.length) {
+    errors.push("Los agentes deben ser codex, claude o antigravity, sin repetir.");
+  }
+
   if (!config.projectName || config.projectName.length > 100) {
     errors.push("--project-name es obligatorio y admite máximo 100 caracteres.");
   }
@@ -261,7 +269,7 @@ function createManifest(config) {
     },
     source,
     memory,
-    agents: ["codex", "claude"].map((id) => ({
+    agents: config.agents.map((id) => ({
       id,
       enabled: true,
       skillName: config.projectId

package/src/install-lock.js

@@ -0,0 +1,127 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const LOCK_FILE = 'bloqueo';
+const MAX_RECOVERIES = 10;
+
+export class LockError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'LockError';
+    this.code = code;
+  }
+}
+
+export function defaultIsAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const ignoreMissing = error => { if (error.code !== 'ENOENT') throw error; };
+
+// The state is `missing`, `unreadable` (not valid JSON, wrong shape or not a regular file) or `ok`.
+async function readOwner(file) {
+  let text;
+  try { text = await fs.readFile(file, 'utf8'); } catch (error) {
+    return error.code === 'ENOENT' ? { state: 'missing' } : { state: 'unreadable' };
+  }
+  try {
+    const data = JSON.parse(text);
+    if (Number.isInteger(data?.pid) && data.pid > 0 && typeof data.equipo === 'string' && typeof data.marca === 'string') {
+      return { state: 'ok', owner: data };
+    }
+  } catch { /* falls through */ }
+  return { state: 'unreadable' };
+}
+
+// Writes the record to a private file and hard-links it into place: the lock never exists half written.
+async function createExclusive(file, record) {
+  const temporary = `${file}.nuevo-${crypto.randomUUID()}`;
+  await fs.writeFile(temporary, JSON.stringify(record), { mode: 0o600, flag: 'wx' });
+  try {
+    await fs.link(temporary, file);
+    return true;
+  } catch (error) {
+    if (error.code === 'EEXIST') return false;
+    throw error;
+  } finally {
+    await fs.unlink(temporary).catch(() => {});
+  }
+}
+
+// Called only for an owner judged dead. The removal happens under a second guard, so two recoverers can never
+// act at once. Under the guard only the dead lock can be at `file`: acquirers create it only when it is absent,
+// and its dead owner will not release it. The guard itself is never removed by anyone but its holder: a guard
+// left by a process that died in the middle of a recovery (a few milliseconds) must be removed by hand, because
+// removing it by reading and deleting would reopen the same race. Returns 'recuperado' or 'ocupado'.
+async function recover(file, judgedMark, { record }) {
+  const guard = `${file}.recuperando`;
+  if (!(await createExclusive(guard, record))) return 'ocupado';
+  try {
+    const again = await readOwner(file);
+    if (again.state === 'ok' && again.owner.marca === judgedMark) await fs.unlink(file).catch(ignoreMissing);
+    return 'recuperado';
+  } finally {
+    const current = await readOwner(guard);
+    if (current.state === 'ok' && current.owner.marca === record.marca) await fs.unlink(guard).catch(ignoreMissing);
+  }
+}
+
+const busy = (file, unreadable) => new LockError('ocupado', unreadable
+  ? `No se puede leer el bloqueo de nexakit. Si no hay ninguna instalación en curso, bórralo a mano: ${file}`
+  : 'Otra instalación de nexakit está en curso; vuelve a intentarlo cuando termine.');
+
+export async function acquireLock(nexakitDir, {
+  waitMs = 30_000, pollMs = 250, hostname = os.hostname(), pid = process.pid, isAlive = defaultIsAlive
+} = {}) {
+  await fs.mkdir(nexakitDir, { recursive: true, mode: 0o700 });
+  const file = path.join(nexakitDir, LOCK_FILE);
+  const token = crypto.randomUUID();
+  const record = { pid, equipo: hostname, hora: new Date().toISOString(), marca: token };
+  const deadline = Date.now() + waitMs;
+  let recoveries = 0;
+
+  while (true) {
+    if (await createExclusive(file, record)) return heldLock(file, token);
+
+    const current = await readOwner(file);
+    if (current.state === 'missing') continue;
+    if (current.state === 'ok') {
+      const { owner } = current;
+      if (owner.equipo !== hostname) {
+        throw new LockError('otro-equipo', `El bloqueo de nexakit lo creó otro equipo (${owner.equipo}). Si no hay ninguna instalación en curso, bórralo a mano: ${file}`);
+      }
+      // Age never decides: a live owner keeps the lock however long it takes.
+      if (!isAlive(owner.pid) && await recover(file, owner.marca, { record }) === 'recuperado') {
+        if (++recoveries > MAX_RECOVERIES) throw busy(file, false);
+        continue;
+      }
+    }
+    if (Date.now() >= deadline) {
+      const guard = await readOwner(`${file}.recuperando`);
+      if (guard.state === 'ok' && guard.owner.equipo === hostname && !isAlive(guard.owner.pid)) {
+        throw new LockError('ocupado', `Se interrumpió una recuperación anterior del bloqueo de nexakit. Si no hay ninguna instalación en curso, borra a mano: ${file}.recuperando`);
+      }
+      throw busy(file, current.state === 'unreadable');
+    }
+    await sleep(Math.max(1, Math.min(pollMs, deadline - Date.now())));
+  }
+}
+
+function heldLock(file, token) {
+  return {
+    token,
+    async assertHeld() {
+      const current = await readOwner(file);
+      if (!(current.state === 'ok' && current.owner.marca === token)) {
+        throw new LockError('perdido', 'Se perdió el bloqueo de nexakit; no se escribió nada más.');
+      }
+    },
+    async release() {
+      const current = await readOwner(file);
+      if (current.state === 'ok' && current.owner.marca === token) await fs.unlink(file).catch(ignoreMissing);
+    }
+  };
+}

package/src/install-registry.js

@@ -0,0 +1,61 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const REGISTRY_FILE = 'instalaciones.json';
+const MAX_REGISTRY_BYTES = 4 * 1024 * 1024;
+const FIELDS = ['destino', 'apunta', 'raiz', 'fecha'];
+
+const damaged = file => new Error(`El registro de instalaciones de nexakit está dañado: ${file}`);
+const isText = value => typeof value === 'string' && value.length > 0;
+const empty = () => ({ version: 1, entradas: [] });
+
+// The registry is the only proof that a broken link belongs to nexakit. `apunta` must be what `readlink`
+// returns for the link, since that is the value compared later.
+export async function readRegistry(nexakitDir) {
+  const file = path.join(nexakitDir, REGISTRY_FILE);
+  let info;
+  try { info = await fs.lstat(file); } catch (error) {
+    if (error.code === 'ENOENT') return empty();
+    throw error;
+  }
+  if (!info.isFile() || info.size > MAX_REGISTRY_BYTES) throw damaged(file);
+  let data;
+  try { data = JSON.parse(await fs.readFile(file, 'utf8')); } catch { throw damaged(file); }
+  const valid = data?.version === 1 && Array.isArray(data.entradas) &&
+    data.entradas.every(entry => entry && typeof entry === 'object' && FIELDS.every(field => isText(entry[field])));
+  if (!valid) throw damaged(file);
+  return {
+    version: 1,
+    entradas: data.entradas.map(({ destino, apunta, raiz, fecha }) => ({ destino, apunta, raiz, fecha }))
+  };
+}
+
+export const isRegistered = (registry, target, literal) =>
+  registry.entradas.some(entry => entry.destino === target && entry.apunta === literal);
+
+// Must run under the install lock: the lock is checked on entry and again right before the file is replaced.
+export async function recordEntries(nexakitDir, entries, lock) {
+  if (!Array.isArray(entries) || !entries.every(entry => isText(entry?.destino) && isText(entry?.apunta) && isText(entry?.raiz))) {
+    throw new Error('Entrada del registro de instalaciones no válida.');
+  }
+  if (entries.length === 0) return;
+  await lock.assertHeld();
+
+  const registry = await readRegistry(nexakitDir);
+  const fecha = new Date().toISOString();
+  // A Map keeps the position of an entry that is replaced.
+  const byTarget = new Map(registry.entradas.map(entry => [entry.destino, entry]));
+  for (const { destino, apunta, raiz } of entries) byTarget.set(destino, { destino, apunta, raiz, fecha });
+
+  const file = path.join(nexakitDir, REGISTRY_FILE);
+  const temporary = `${file}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify({ version: 1, entradas: [...byTarget.values()] }, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    await lock.assertHeld();
+    await fs.rename(temporary, file);
+  } catch (error) {
+    await fs.unlink(temporary).catch(() => {});
+    throw error;
+  }
+}

package/src/legacy-repair.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { acquireLock } from './install-lock.js';
+import { recordEntries } from './install-registry.js';
+import { relinkIfUnchanged } from './link-states.js';
+import { actualRoot, ensureStableInstall, nexakitDir } from './stable-install.js';
+import { TOOLKIT_ROOT, packageVersion, registrationCommand, resolveNodeExecutable, setupToolkit } from './toolkit-setup.js';
+
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+const exists = file => fs.access(file).then(() => true, () => false);
+
+// Finds the global links that point into a root that no longer exists, `from`, and that nexakit cannot prove
+// are its own (no entry in the install registry). Only skill names this version ships are considered.
+// Nothing is written here: the person has to confirm what this lists.
+export async function planLegacyRepair({
+  from, agent = 'all', homeDirectory = os.homedir(), toolkitRoot = TOOLKIT_ROOT, environment = process.env, codexHome
+} = {}) {
+  const dead = path.resolve(from);
+  const setup = await setupToolkit({ agent, homeDirectory, toolkitRoot, environment, ...(codexHome && { codexHome }) });
+  const links = setup.skills
+    .filter(skill => skill.state === 'roto-ajeno' && skill.root && samePath(skill.root, dead))
+    .map(({ client, name, target, literal }) => ({ client, name, target, literal }))
+    .sort((a, b) => a.client.localeCompare(b.client) || a.name.localeCompare(b.name));
+  const mcp = {};
+  for (const [client, state] of Object.entries(setup.mcp.states)) {
+    if (state.state === 'roto-ajeno' && state.root && samePath(state.root, dead)) mcp[client] = { name: state.name, literal: state.literal };
+  }
+  return { from: dead, agent, activeRoot: setup.activeRoot, ephemeral: setup.ephemeral && !setup.otherCopy, links, mcp };
+}
+
+// Repoints the links of the plan to the copy of nexakit in use and records them as nexakit's own.
+// Each link is read again right before writing: one that changed since the plan is left alone.
+export async function applyLegacyRepair(plan, {
+  homeDirectory = os.homedir(), toolkitRoot = TOOLKIT_ROOT, environment = process.env, runNpm, packageSpec, lockOptions,
+  acquire = acquireLock
+} = {}) {
+  const home = await fs.realpath(homeDirectory);
+  const lock = await acquire(nexakitDir(home), lockOptions);
+  try {
+    if (plan.ephemeral && plan.links.length) {
+      await ensureStableInstall({
+        homeDirectory: home, version: await packageVersion(await fs.realpath(toolkitRoot)), lock,
+        ...(runNpm && { runNpm }), ...(packageSpec && { packageSpec })
+      });
+    }
+    const entries = [], skipped = [];
+    let changed = 0;
+    for (const link of plan.links) {
+      const source = path.join(plan.activeRoot, 'skills', link.name);
+      if (!(await exists(path.join(source, 'SKILL.md')))) { skipped.push(link.name); continue; }
+      await lock.assertHeld();
+      if (await relinkIfUnchanged({ target: link.target, expectedLiteral: link.literal, source }) === 'cambio') { changed++; continue; }
+      entries.push({ destino: link.target, apunta: await fs.readlink(link.target), raiz: plan.activeRoot });
+    }
+    await recordEntries(nexakitDir(home), entries, lock);
+
+    // The MCP entry is not rewritten here: its client owns that file, so only the exact commands are given.
+    const mcpCommands = [];
+    const script = path.join(plan.activeRoot, 'bin/agent-toolkit-mcp.js');
+    if (Object.keys(plan.mcp ?? {}).length && await exists(script)) {
+      const nodePath = await resolveNodeExecutable(environment);
+      for (const [client, current] of Object.entries(plan.mcp)) {
+        mcpCommands.push(registrationCommand(client, { state: 'roto-ajeno', name: current.name }, nodePath, script));
+      }
+    }
+    return { repaired: entries.length, changed, skipped, mcpCommands, stableRoot: actualRoot(home) };
+  } finally {
+    await lock.release();
+  }
+}

package/src/link-states.js

@@ -0,0 +1,172 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { IS_WINDOWS } from './platform.js';
+
+// Evaluated in this order; the first one that holds wins.
+export const LINK_STATES = Object.freeze(['falta', 'conflicto', 'efimero', 'instalado', 'otra-copia', 'roto-propio', 'roto-ajeno', 'quitada']);
+// What an apply acts on, and what counts as ready.
+export const ACTIONABLE_LINK_STATES = Object.freeze(['falta', 'efimero', 'roto-propio']);
+export const READY_LINK_STATES = Object.freeze(['instalado', 'otra-copia']);
+// `quitada`: nexakit instaló el enlace y el usuario lo quitó. No es pendiente: se respeta hasta que pida `--reponer`.
+export const REMOVED_BY_USER_STATE = 'quitada';
+export const SETTLED_LINK_STATES = Object.freeze([...READY_LINK_STATES, REMOVED_BY_USER_STATE]);
+
+const PACKAGE_NAMES = new Set(['nexakit', 'agent-toolkit']);
+const MAX_PACKAGE_BYTES = 1_048_576;
+const BROKEN_CODES = new Set(['ENOENT', 'ENOTDIR', 'ELOOP']);
+
+const normalized = value => (IS_WINDOWS ? value.toLowerCase() : value);
+const samePath = (a, b) => normalized(a) === normalized(b);
+const lstatOrNull = file => fs.lstat(file).catch(error => {
+  if (error.code === 'ENOENT') return null;
+  throw error;
+});
+
+export const isEphemeralPath = value => path.resolve(value).split(path.sep).includes('_npx');
+
+// A copy of nexakit inside an npx cache: `…/_npx/<hash>/node_modules/nexakit` (or the old name, agent-toolkit).
+// Anything else under `_npx` belongs to another package and is never treated as nexakit's.
+export function isEphemeralNexakitRoot(root) {
+  const parts = path.resolve(root).split(path.sep);
+  const n = parts.length;
+  return n >= 4 && parts[n - 4] === '_npx' && parts[n - 2] === 'node_modules' && PACKAGE_NAMES.has(parts[n - 1]);
+}
+
+export async function readLink(target) {
+  const info = await lstatOrNull(target);
+  if (!info) return { exists: false, isLink: false };
+  if (!info.isSymbolicLink()) return { exists: true, isLink: false };
+  const literal = await fs.readlink(target);
+  return { exists: true, isLink: true, literal, absolute: path.resolve(path.dirname(target), literal) };
+}
+
+// Strips `suffix` from the end of `value`; null when it does not end with it.
+function rootFrom(value, suffix) {
+  const tail = path.normalize(suffix);
+  const resolved = path.resolve(value);
+  if (!normalized(resolved).endsWith(normalized(path.sep + tail))) return null;
+  return resolved.slice(0, resolved.length - tail.length - 1) || null;
+}
+
+export async function recognizedRoot(resolvedPath, suffix) {
+  const root = rootFrom(resolvedPath, suffix);
+  if (!root) return null;
+  const file = path.join(root, 'package.json');
+  const info = await lstatOrNull(file);
+  if (!info?.isFile() || info.isSymbolicLink() || info.size > MAX_PACKAGE_BYTES) return null;
+  try {
+    const pkg = JSON.parse(await fs.readFile(file, 'utf8'));
+    return PACKAGE_NAMES.has(pkg?.name) ? root : null;
+  } catch { return null; }
+}
+
+async function realpathOrNull(file) {
+  try { return await fs.realpath(file); } catch (error) {
+    if (BROKEN_CODES.has(error.code)) return null;
+    throw error;
+  }
+}
+
+export async function classifyLink({ target, suffix, activeRoots = [], isOwned = () => false }) {
+  const link = await readLink(target);
+  if (!link.exists) return { target, suffix, state: 'falta' };
+  if (!link.isLink) return { target, suffix, state: 'conflicto' };
+  return classifyReference({ target, literal: link.literal, absolute: link.absolute, suffix, activeRoots, isOwned });
+}
+
+// Classifies a path that points into a copy of nexakit without being a link itself, such as the script
+// an MCP entry runs. `target` identifies the reference for `isOwned`; `absolute` defaults to the literal.
+export async function classifyReference({ target, literal, absolute = path.resolve(literal), suffix, activeRoots = [], isOwned = () => false }) {
+  const base = { target, suffix };
+  const resolved = await realpathOrNull(absolute);
+
+  // Before `instalado`, so a link into the cache this run came from is never taken as good. It must point at
+  // exactly `<copy of nexakit in an npx cache>/<suffix>`; another package there is not nexakit's to move.
+  const ephemeralRoot = [absolute, resolved].filter(Boolean)
+    .map(candidate => rootFrom(candidate, suffix)).find(root => root && isEphemeralNexakitRoot(root));
+  if (ephemeralRoot) return { ...base, state: 'efimero', literal, root: ephemeralRoot };
+
+  if (resolved) {
+    const tail = path.normalize(suffix);
+    for (const candidate of activeRoots) {
+      if (isEphemeralPath(candidate)) continue;
+      const real = await realpathOrNull(candidate);
+      if (real && samePath(resolved, path.join(real, tail))) return { ...base, state: 'instalado', literal, root: real };
+    }
+    const other = await recognizedRoot(resolved, suffix);
+    if (other) return { ...base, state: 'otra-copia', literal, root: other };
+    return { ...base, state: 'conflicto', literal };
+  }
+
+  const owned = await isOwned(target, literal);
+  return { ...base, state: owned ? 'roto-propio' : 'roto-ajeno', literal, root: rootFrom(absolute, suffix) ?? undefined };
+}
+
+export function chooseActiveRoot(items, fallbackRoot) {
+  const counts = new Map();
+  for (const item of items) {
+    if (item.state !== 'otra-copia' || !item.root || isEphemeralPath(item.root)) continue;
+    counts.set(item.root, (counts.get(item.root) ?? 0) + 1);
+  }
+  let best = null;
+  for (const [root, count] of counts) {
+    if (count * 2 > items.length && (!best || count > best.count)) best = { root, count };
+  }
+  return best?.root ?? fallbackRoot;
+}
+
+export function legacyGroups(items, { skillNames, mcpDeadRoot } = {}) {
+  const groups = new Map();
+  for (const item of items) {
+    if (item.state !== 'roto-ajeno' || !item.root || !skillNames?.has(path.basename(item.target))) continue;
+    groups.set(item.root, [...(groups.get(item.root) ?? []), item.target]);
+  }
+  return [...groups]
+    .filter(([root, targets]) => targets.length >= 3 || (mcpDeadRoot !== undefined && root === mcpDeadRoot))
+    .map(([root, targets]) => ({ root, targets }));
+}
+
+// `expectedLiteral` is the readlink value the plan saw; null means the path must not exist yet.
+// Re-reads right before writing and touches nothing when the link is no longer what the plan saw.
+// `relative` writes the link relative to its own folder (Windows junctions are always absolute).
+export async function relinkIfUnchanged({ target, expectedLiteral, source, relative = false }) {
+  const type = IS_WINDOWS ? 'junction' : 'dir';
+  const absoluteSource = path.resolve(source);
+  const linkValue = relative && !IS_WINDOWS ? path.relative(path.dirname(target), absoluteSource) : absoluteSource;
+  const info = await lstatOrNull(target);
+
+  if (expectedLiteral === null) {
+    if (info) return 'cambio';
+    try { await fs.symlink(linkValue, target, type); } catch (error) {
+      if (error.code === 'EEXIST') return 'cambio';
+      throw error;
+    }
+    return 'hecho';
+  }
+
+  if (!info?.isSymbolicLink() || await fs.readlink(target) !== expectedLiteral) return 'cambio';
+
+  if (IS_WINDOWS) {
+    // A junction cannot be renamed over; this window is not atomic there.
+    await fs.unlink(target);
+    await fs.symlink(linkValue, target, type);
+    return 'hecho';
+  }
+
+  // Build the new link beside the old one and rename over it, so the name is never missing.
+  const temporary = `${target}.nx-${crypto.randomUUID()}`;
+  await fs.symlink(linkValue, temporary, type);
+  try {
+    if (await fs.readlink(target) !== expectedLiteral) {
+      await fs.unlink(temporary);
+      return 'cambio';
+    }
+    await fs.rename(temporary, target);
+  } catch (error) {
+    await fs.unlink(temporary).catch(() => {});
+    if (error.code === 'ENOENT' || error.code === 'EINVAL') return 'cambio';
+    throw error;
+  }
+  return 'hecho';
+}

package/src/memory-locator.js

@@ -0,0 +1,118 @@
+// Finds the project memories this person already has, from the memory MCP servers registered in Claude Code, Codex
+// and Antigravity, so a repository reuses its memory and a new one goes next to the others. Read-only. No new
+// registry: the clients' own configuration is the source of truth.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getStaticTOMLValue, parseTOML } from 'toml-eslint-parser';
+
+const MAX_CONFIG_BYTES = 2 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = 512 * 1024;
+const CLIENT_ORDER = ['claude', 'codex', 'antigravity'];
+const FILESYSTEM_PACKAGE = /^@modelcontextprotocol\/server-filesystem(?:@[^/]+)?$/u;
+const MEMORY_SCRIPT = 'project-memory-mcp.js';
+
+async function readBounded(file, maxBytes) {
+  try {
+    const info = await fs.lstat(file);
+    if (!info.isFile() || info.size > maxBytes) return null;
+    return await fs.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function serversOf(client, { homeDirectory, codexHome }) {
+  try {
+    if (client === 'claude') {
+      const config = JSON.parse(await readBounded(path.join(homeDirectory, '.claude.json'), MAX_CONFIG_BYTES) ?? 'null');
+      const projects = Object.values(config?.projects ?? {}).map(project => project?.mcpServers ?? {});
+      return [config?.mcpServers ?? {}, ...projects].flatMap(Object.entries);
+    }
+    if (client === 'codex') {
+      const text = await readBounded(path.join(codexHome, 'config.toml'), MAX_CONFIG_BYTES);
+      return text ? Object.entries(getStaticTOMLValue(parseTOML(text, { tomlVersion: '1.0.0' }))?.mcp_servers ?? {}) : [];
+    }
+    const config = JSON.parse(await readBounded(path.join(homeDirectory, '.gemini', 'config', 'mcp_config.json'), MAX_CONFIG_BYTES) ?? 'null');
+    return Object.entries(config?.mcpServers ?? {});
+  } catch {
+    return []; // An unreadable configuration means no known memories from that client, never an error.
+  }
+}
+
+// The manifest a server points at: the last argument of server-filesystem, or the --manifest of project-memory-mcp.
+function manifestCandidate(server) {
+  const args = Array.isArray(server?.args) ? server.args.filter(arg => typeof arg === 'string') : [];
+  const script = args.findIndex(arg => arg.replaceAll('\\', '/').endsWith(`/${MEMORY_SCRIPT}`));
+  if (script >= 0 && args[script + 1] === '--manifest' && path.isAbsolute(args[script + 2] ?? '')) return args[script + 2];
+  if (args.some(arg => FILESYSTEM_PACKAGE.test(arg))) {
+    const last = args.at(-1);
+    if (last && path.isAbsolute(last)) return path.join(last, 'project-memory.json');
+  }
+  return null;
+}
+
+async function readManifest(manifestPath) {
+  const text = await readBounded(manifestPath, MAX_MANIFEST_BYTES); // lstat: a linked manifest is not accepted.
+  if (text === null) return null;
+  try {
+    const manifest = JSON.parse(text);
+    const id = manifest?.project?.id;
+    const repositoryPath = manifest?.source?.repositoryPath;
+    if (typeof id !== 'string' || typeof repositoryPath !== 'string') return null;
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+// Every MCP server name registered in each agent, with the vault it serves when it is a memory (else null).
+export async function registeredServers({ homeDirectory, codexHome = path.join(homeDirectory, '.codex') } = {}) {
+  const result = {};
+  for (const client of CLIENT_ORDER) {
+    result[client] = {};
+    for (const [name, server] of await serversOf(client, { homeDirectory, codexHome })) {
+      const candidate = manifestCandidate(server);
+      const vault = candidate ? await fs.realpath(path.dirname(candidate)).catch(() => null) : null;
+      const kind = !candidate ? null : (server.args ?? []).some(arg => typeof arg === 'string' && arg.replaceAll('\\', '/').endsWith(`/${MEMORY_SCRIPT}`)) ? 'guard' : 'filesystem';
+      result[client][name] = vault && { vault, kind };
+    }
+  }
+  return result;
+}
+
+export async function findKnownMemories({ homeDirectory, codexHome = path.join(homeDirectory, '.codex') } = {}) {
+  const byVault = new Map();
+  for (const client of CLIENT_ORDER) {
+    for (const [name, server] of await serversOf(client, { homeDirectory, codexHome })) {
+      const candidate = manifestCandidate(server);
+      if (!candidate) continue;
+      const manifest = await readManifest(candidate);
+      if (!manifest) continue;
+      const vaultPath = await fs.realpath(path.dirname(candidate)).catch(() => null);
+      if (!vaultPath) continue;
+      const entry = byVault.get(vaultPath) ?? {
+        vaultPath,
+        manifestPath: path.join(vaultPath, 'project-memory.json'),
+        projectId: manifest.project.id,
+        repositoryPath: manifest.source.repositoryPath,
+        mcpName: typeof manifest.memory?.mcpServerName === 'string' ? manifest.memory.mcpServerName : name,
+        clients: []
+      };
+      if (!entry.clients.includes(client)) entry.clients.push(client);
+      byVault.set(vaultPath, entry);
+    }
+  }
+  return [...byVault.values()].sort((a, b) => (a.vaultPath < b.vaultPath ? -1 : a.vaultPath > b.vaultPath ? 1 : 0));
+}
+
+export function memoryForRepository(known, root) {
+  return known.find(entry => path.resolve(entry.repositoryPath) === path.resolve(root)) ?? null;
+}
+
+// Next to the memories already known when they share one parent folder; otherwise a folder of its own.
+export function suggestMemoryLocation(known, { id, homeDirectory }) {
+  const parents = [...new Set(known.map(entry => path.dirname(entry.vaultPath)))];
+  return parents.length === 1
+    ? path.join(parents[0], `${id.toUpperCase()}-MEMORY`)
+    : path.join(homeDirectory, 'nexakit-memorias', id);
+}

package/src/missing-dependencies.js

@@ -0,0 +1,21 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isEphemeralPath } from './link-states.js';
+
+// This file must stay free of third-party imports: it has to run exactly when they are missing.
+const copyRoot = () => path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+
+// Loads a module of nexakit. If a third-party package is missing in a checkout, says how to install it instead
+// of showing a stack trace. Any other failure is raised untouched, and so is a missing package under npx,
+// where `npm ci` would be the wrong advice.
+export async function loadWithDependencyCheck(load, { root = copyRoot(), write = text => process.stderr.write(text) } = {}) {
+  try {
+    return await load();
+  } catch (error) {
+    const missingPackage = error?.code === 'ERR_MODULE_NOT_FOUND' && /^Cannot find package '/u.test(error.message ?? '');
+    if (!missingPackage || isEphemeralPath(root)) throw error;
+    write(`Faltan las dependencias de esta copia. Ejecuta \`npm ci\` en ${root}.\n`);
+    process.exitCode = 1;
+    return null;
+  }
+}