Skip to content

Write HTML. Render video. Built for agents.

12.5 KB
Raw Blame
// Fan the canonical global skills store out to every OTHER installed agent.
//
// `skills add --global --agent claude-code universal --copy` writes REAL files
// to two global stores: the Claude store (~/.claude/skills — what Claude Code
// reads, at global priority) and the shared universal store (~/.agents/skills,
// which Cursor/… read in PROJECT scope and Codex, Pi and the .agents-family
// agents read globally). But every other agent reads its OWN global dir (~/.cursor/skills,
// goose → ~/.config/goose/skills, …), which upstream's --global does NOT
// populate.
//
// So we mirror the canonical Claude store into each of those per-agent dirs, but
// only for agents the machine actually has (their marker dir exists). Agents
// that already consume the universal ~/.agents/skills store globally (Pi, Codex) are
// skipped: their universal copy is authoritative and a per-agent copy would
// collide with it (#3294). On Unix
// each skill is a relative symlink back into the store (one source of truth,
// near-zero size, auto-fresh on update); on Windows it's a copy, because
// symlinks there need admin / Developer Mode and otherwise silently dangle —
// the same fallback the upstream `skills` CLI and gstack both make.
//
// Agent dirs are resolved through the same env-overridable base dirs upstream
// uses (XDG_CONFIG_HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, …), so a machine with
// those set mirrors into the exact dir the agent reads.

import {
  existsSync,
  lstatSync,
  mkdirSync,
  readdirSync,
  realpathSync,
  rmSync,
  statSync,
  symlinkSync,
  unlinkSync,
} from "node:fs";
import { copyDirSync } from "./copyDir.js";
import { homedir } from "node:os";
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { AGENT_GLOBAL_DIRS, type AgentDirBase } from "./agentDirs.generated.js";

/**
 * Agents that natively discover the universal `~/.agents/skills` store globally
 * in ADDITION to their own agent-specific directory. Mirroring into their own
 * dir makes every skill discoverable twice.
 *
 * Pi and Codex are known cases. Pi (earendil-works/pi) reads both `~/.pi/agent/skills/`
 * and `~/.agents/skills/` as global locations (pi's packages/coding-agent/docs/
 * skills.md#locations), so a mirrored entry collides with the universal copy
 * and Pi skips the universal one on name conflict (#3294). Codex likewise
 * discovers the user-level `~/.agents/skills/` store.
 *
 * The generated table cannot carry this capability — it is a plain
 * (agent, base, sub) list synced from vercel-labs/skills — so the set lives
 * here next to the mirror logic that needs it.
 */
const UNIVERSAL_STORE_READERS = new Set(["pi", "codex"]);

export interface MirrorResult {
  /** The store mirrored from, or null when no global Claude store was found. */
  source: string | null;
  /** Agents whose global dir was (re)populated. */
  mirrored: { agent: string; dir: string }[];
  /** Agent targets skipped because their filesystem identity was unsafe. */
  skipped: {
    agent: string;
    dir: string;
    reason: "aliases_install_owned_store" | "unresolvable_target";
  }[];
}

type MirrorSkipReason = MirrorResult["skipped"][number]["reason"];

/** Resolve a path through existing ancestors without creating its missing tail. */
function canonicalCandidate(input: string): string | null {
  let current = resolve(input);
  const missing: string[] = [];
  while (true) {
    try {
      lstatSync(current);
      break;
    } catch (error) {
      const code = (error as NodeJS.ErrnoException).code;
      if (code !== "ENOENT" && code !== "ENOTDIR") return null;
      const parent = dirname(current);
      if (parent === current) return null;
      missing.unshift(basename(current));
      current = parent;
    }
  }
  try {
    return resolve(realpathSync(current), ...missing);
  } catch {
    return null;
  }
}

function pathsOverlap(left: string, right: string): boolean {
  const fromLeft = relative(left, right);
  const leftContainsRight =
    fromLeft === "" ||
    (fromLeft !== ".." && !fromLeft.startsWith(`..${sep}`) && !isAbsolute(fromLeft));
  if (leftContainsRight) return true;
  const fromRight = relative(right, left);
  return fromRight !== ".." && !fromRight.startsWith(`..${sep}`) && !isAbsolute(fromRight);
}

function sameExistingNode(left: string, right: string): boolean {
  try {
    const leftStat = statSync(left, { bigint: true });
    const rightStat = statSync(right, { bigint: true });
    return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
  } catch {
    return false;
  }
}

function targetSafety(
  target: string,
  protectedPaths: ReadonlyArray<{ lexical: string; canonical: string }>,
): MirrorSkipReason | null {
  const canonical = canonicalCandidate(target);
  if (!canonical) return "unresolvable_target";
  for (const protectedPath of protectedPaths) {
    if (
      pathsOverlap(canonical, protectedPath.canonical) ||
      sameExistingNode(target, protectedPath.lexical)
    ) {
      return "aliases_install_owned_store";
    }
  }
  return null;
}

function skillTargetSafety(
  sourceSkill: string,
  targetSkill: string,
  targetDirSafety: () => MirrorSkipReason | null,
): MirrorSkipReason | null {
  const directoryReason = targetDirSafety();
  if (directoryReason) return directoryReason;
  try {
    // A final symlink is the normal Unix mirror shape. rmSync unlinks it
    // without traversing its target, so canonical equality is safe here.
    if (lstatSync(targetSkill).isSymbolicLink()) return null;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== "ENOENT") return "unresolvable_target";
  }
  const sourceCanonical = canonicalCandidate(sourceSkill);
  const targetCanonical = canonicalCandidate(targetSkill);
  if (!sourceCanonical || !targetCanonical) return "unresolvable_target";
  if (
    pathsOverlap(sourceCanonical, targetCanonical) ||
    sameExistingNode(sourceSkill, targetSkill)
  ) {
    return "aliases_install_owned_store";
  }
  return null;
}

/** Resolve each env-overridable base dir exactly as upstream agents.ts does. */
function resolveBases(home: string, env: NodeJS.ProcessEnv): Record<AgentDirBase, string> {
  const xdg = env["XDG_CONFIG_HOME"]?.trim();
  return {
    home,
    configHome: xdg && isAbsolute(xdg) ? xdg : join(home, ".config"),
    codexHome: env["CODEX_HOME"]?.trim() || join(home, ".codex"),
    claudeHome: env["CLAUDE_CONFIG_DIR"]?.trim() || join(home, ".claude"),
    vibeHome: env["VIBE_HOME"]?.trim() || join(home, ".vibe"),
    hermesHome: env["HERMES_HOME"]?.trim() || join(home, ".hermes"),
    autohandHome: env["AUTOHAND_HOME"]?.trim() || join(home, ".autohand"),
  };
}

/** Skill bundle names directly under a store (a dir/symlink with a SKILL.md). */
function listSkillDirs(store: string): string[] {
  return readdirSync(store, { withFileTypes: true })
    .filter(
      (e) => (e.isDirectory() || e.isSymbolicLink()) && existsSync(join(store, e.name, "SKILL.md")),
    )
    .map((e) => e.name);
}

/**
 * Point `targetSkill` at `sourceSkill`. Any prior entry (our symlink, a stale
 * copy, or a previous install) is removed first so the mirror always reflects
 * the canonical store — that's the whole point of "update".
 */
function linkOrCopy(
  sourceSkill: string,
  targetSkill: string,
  platform: NodeJS.Platform,
  safety: () => MirrorSkipReason | null,
): MirrorSkipReason | null {
  const unsafe = safety();
  if (unsafe) return unsafe;
  rmSync(targetSkill, { recursive: true, force: true });
  if (platform === "win32") {
    copyDirSync(sourceSkill, targetSkill);
  } else {
    symlinkSync(relative(dirname(targetSkill), sourceSkill), targetSkill);
  }
  return null;
}

/**
 * Populate one agent's global dir from the store. Best-effort and idempotent;
 * per-skill failures don't abort the others. Unsafe target identity stops the
 * agent before the next destructive operation and returns a reportable reason.
 */
function mirrorInto(
  targetDir: string,
  source: string,
  skills: string[],
  platform: NodeJS.Platform,
  safety: () => MirrorSkipReason | null,
): { mirrored: boolean; skipReason?: MirrorSkipReason } {
  const beforeCreate = safety();
  if (beforeCreate) return { mirrored: false, skipReason: beforeCreate };
  try {
    mkdirSync(targetDir, { recursive: true });
  } catch {
    return { mirrored: false };
  }
  const afterCreate = safety();
  if (afterCreate) return { mirrored: false, skipReason: afterCreate };
  for (const skill of skills) {
    try {
      const sourceSkill = join(source, skill);
      const targetSkill = join(targetDir, skill);
      const skipReason = linkOrCopy(sourceSkill, targetSkill, platform, () =>
        skillTargetSafety(sourceSkill, targetSkill, safety),
      );
      if (skipReason) return { mirrored: false, skipReason };
    } catch {
      // best-effort per skill
    }
  }
  return { mirrored: true };
}

/**
 * Unlink symlinks an earlier mirror left in `targetDir` (they resolve to the same source skill),
 * only where the universal store holds that skill. Real dirs and Windows copies stay.
 */
function removeMirrorLinks(
  targetDir: string,
  source: string,
  universalStore: string,
  skills: string[],
  safety: () => MirrorSkipReason | null,
): MirrorSkipReason | null {
  const unsafe = safety();
  if (unsafe) return unsafe;
  for (const skill of skills) {
    const targetSkill = join(targetDir, skill);
    try {
      if (!existsSync(join(universalStore, skill, "SKILL.md"))) continue;
      if (!lstatSync(targetSkill).isSymbolicLink()) continue;
      if (realpathSync(targetSkill) !== realpathSync(join(source, skill))) continue;
      unlinkSync(targetSkill);
    } catch {
      // absent or dangling: nothing of ours to remove
    }
  }
  return null;
}

/**
 * Mirror the global Claude store into every installed agent's global skills
 * dir. Best-effort and idempotent: a no-op when the store is absent, and per
 * skill failures (permissions, races) don't abort the rest.
 */
export function mirrorGlobalSkills(opts: {
  skills: readonly string[];
  home?: string;
  platform?: NodeJS.Platform;
  env?: NodeJS.ProcessEnv;
}): MirrorResult {
  const home = opts.home ?? homedir();
  const platform = opts.platform ?? process.platform;
  const bases = resolveBases(home, opts.env ?? process.env);

  // The two stores the global --copy install writes as real files. The mirror
  // reads from the Claude store and must never link/copy onto either of them.
  const source = join(bases.claudeHome, "skills");
  const universalStore = join(home, ".agents", "skills");
  if (!existsSync(source)) return { source: null, mirrored: [], skipped: [] };

  // Mirror ONLY HyperFrames' own skills (by name), NEVER everything in the
  // store: ~/.claude/skills is shared, so a user's gstack / personal / company
  // skills live there too and must not be fanned out to (or overwrite) other
  // agents. `opts.skills` is the lock-attributed HyperFrames set (see
  // hyperframesSkillNames).
  const allowed = new Set(opts.skills);
  const skills = listSkillDirs(source).filter((name) => allowed.has(name));
  if (skills.length === 0) return { source, mirrored: [], skipped: [] };

  const protectedPaths = [source, universalStore].map((lexical) => ({
    lexical,
    canonical: canonicalCandidate(lexical),
  }));
  const resolvedProtectedPaths = protectedPaths.filter(
    (entry): entry is { lexical: string; canonical: string } => entry.canonical !== null,
  );
  if (resolvedProtectedPaths.length !== protectedPaths.length) {
    return { source, mirrored: [], skipped: [] };
  }

  const mirrored: { agent: string; dir: string }[] = [];
  const skipped: MirrorResult["skipped"] = [];
  for (const { agent, base, sub } of AGENT_GLOBAL_DIRS) {
    const targetDir = join(bases[base], ...sub.split("/").filter(Boolean));
    if (targetDir === source || targetDir === universalStore) continue; // install-owned
    if (UNIVERSAL_STORE_READERS.has(agent)) {
      // Already reads the universal store (#3294); drop links an older version mirrored here.
      const skipReason = removeMirrorLinks(targetDir, source, universalStore, skills, () =>
        targetSafety(targetDir, resolvedProtectedPaths),
      );
      if (skipReason) skipped.push({ agent, dir: targetDir, reason: skipReason });
      continue;
    }
    if (!existsSync(dirname(targetDir))) continue; // agent not installed (no marker)
    const attempt = mirrorInto(targetDir, source, skills, platform, () =>
      targetSafety(targetDir, resolvedProtectedPaths),
    );
    if (attempt.mirrored) mirrored.push({ agent, dir: targetDir });
    else if (attempt.skipReason)
      skipped.push({ agent, dir: targetDir, reason: attempt.skipReason });
  }
  return { source, mirrored, skipped };
}