@thesmurph/agentlink 0.1.0

package/src/fix.ts

@@ -0,0 +1,209 @@
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+} from "node:fs";
+import path from "node:path";
+import type { Harness } from "./harnesses.js";
+import { inspect, isOwned, isInside, pruneEmptyParents } from "./link.js";
+import { listSubdirectories, relativeTo, type ScopePaths } from "./scope.js";
+
+export type FixKind = "move" | "remove-identical" | "conflict";
+
+export interface FixAction {
+  /** Path relative to the scope root, inside a harness directory. */
+  target: string;
+  /** Path relative to the scope root, in the canonical tree. */
+  canonical: string;
+  kind: FixKind;
+  skill?: string;
+  detail?: string;
+}
+
+/**
+ * Find real copies sitting where a symlink belongs.
+ *
+ * A copy is cheap to resolve when the canonical tree has nothing at that name
+ * (move it in) or has an identical directory (delete the copy). When the two
+ * differ, nothing is guessed: the caller reports both paths and stops, unless
+ * the user explicitly asks for the canonical copy to win.
+ */
+export function planFixes(paths: ScopePaths, harnesses: Harness[]): FixAction[] {
+  const actions: FixAction[] = [];
+  const seen = new Set<string>();
+
+  for (const harness of harnesses) {
+    const skills = harness.skills[paths.scope];
+    if (!skills.native && skills.alias) {
+      const dir = path.join(paths.root, skills.alias);
+      // A harness directory that is itself a symlink into the canonical tree
+      // would make every entry look like an identical duplicate of itself.
+      // Acting on that would delete the canonical skills.
+      if (isInsideCanonical(paths, dir)) continue;
+
+      for (const name of listSubdirectories(dir)) {
+        const target = path.join(dir, name);
+        const rel = relativeTo(paths.root, target);
+        if (seen.has(rel)) continue;
+        seen.add(rel);
+
+        // Only real directories are copies. Symlinks are already correct, and
+        // a symlinked directory is resolved through, never replaced.
+        if (inspect(target).kind !== "dir") continue;
+        if (isInsideCanonical(paths, target)) continue;
+
+        const source = path.join(paths.skills, name);
+        const canonical = relativeTo(paths.root, source);
+        if (!existsSync(source)) {
+          actions.push({ target: rel, canonical, kind: "move", skill: name });
+        } else if (hashTree(target) === hashTree(source)) {
+          actions.push({ target: rel, canonical, kind: "remove-identical", skill: name });
+        } else {
+          actions.push({ target: rel, canonical, kind: "conflict", skill: name, detail: "both copies differ" });
+        }
+      }
+    }
+
+    // Instructions: a real file or directory where a symlink belongs needs a human.
+    const instructions = harness.instructions[paths.scope];
+    if (!instructions.native && instructions.alias && existsSync(paths.instructions)) {
+      const target = path.join(paths.root, instructions.alias);
+      const rel = relativeTo(paths.root, target);
+      const kind = inspect(target).kind;
+      if (!seen.has(rel) && (kind === "file" || kind === "dir")) {
+        seen.add(rel);
+        actions.push({
+          target: rel,
+          canonical: relativeTo(paths.root, paths.instructions),
+          kind: "conflict",
+          detail: "two copies of your instructions",
+        });
+      }
+    }
+  }
+
+  return actions;
+}
+
+/** True when `candidate` is the canonical skills tree, or inside it. */
+function isInsideCanonical(paths: ScopePaths, candidate: string): boolean {
+  if (!existsSync(candidate)) return false;
+  let real: string;
+  try {
+    real = realpathSync(candidate);
+  } catch {
+    return false;
+  }
+  let skillsReal: string;
+  try {
+    skillsReal = realpathSync(paths.skills);
+  } catch {
+    return false;
+  }
+  if (isInside(skillsReal, real)) return true;
+  try {
+    // Resolving the parent catches a canonical entry that is itself a symlink
+    // into .agents, which realpath already collapsed above.
+    return isInside(realpathSync(paths.agentsDir), real);
+  } catch {
+    return false;
+  }
+}
+
+export interface FixResult extends FixAction {
+  performed: boolean;
+}
+
+export function applyFixes(
+  paths: ScopePaths,
+  actions: FixAction[],
+  options: { dryRun?: boolean; force?: boolean } = {},
+): FixResult[] {
+  return actions.map((action) => {
+    if (action.kind === "conflict" && !options.force) return { ...action, performed: false };
+
+    const target = path.join(paths.root, action.target);
+    const canonical = path.join(paths.root, action.canonical);
+
+    // Never touch anything that is not inside the scope root, and never touch
+    // the canonical tree itself.
+    if (!isInside(paths.root, target) || isOwned(paths, target)) {
+      return { ...action, performed: false, detail: "refused: outside the scope root" };
+    }
+    if (options.dryRun) return { ...action, performed: false };
+
+    try {
+      if (action.kind === "move") {
+        mkdirSync(path.dirname(canonical), { recursive: true });
+        renameSync(target, canonical);
+      } else {
+        rmSync(target, { recursive: true, force: true });
+      }
+      pruneEmptyParents(path.dirname(target), paths.root);
+      return { ...action, performed: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { ...action, performed: false, detail: `failed: ${message}` };
+    }
+  });
+}
+
+/** Stable hash of a directory tree, tolerant of line-ending differences. */
+export function hashTree(dir: string): string {
+  const hash = createHash("sha256");
+  walk(dir, "", hash);
+  return hash.digest("hex");
+}
+
+function walk(current: string, prefix: string, hash: ReturnType<typeof createHash>): void {
+  let entries;
+  try {
+    entries = readdirSync(current, { withFileTypes: true });
+  } catch (error) {
+    // An unreadable directory must not look like an empty one.
+    hash.update(`unreadable ${prefix} ${(error as NodeJS.ErrnoException)?.code ?? "?"}\n`);
+    return;
+  }
+  for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const full = path.join(current, entry.name);
+    if (entry.isSymbolicLink()) {
+      hash.update(`link ${rel} ${safeReadlink(full)}\n`);
+    } else if (entry.isDirectory()) {
+      hash.update(`dir ${rel}\n`);
+      walk(full, rel, hash);
+    } else {
+      hash.update(`file ${rel} ${hashFile(full)}\n`);
+    }
+  }
+}
+
+function hashFile(file: string): string {
+  try {
+    const buffer = readFileSync(file);
+    // Treat CRLF and LF files as equal so a Windows-authored copy is not
+    // reported as a conflict.
+    const isBinary = buffer.includes(0);
+    const content = isBinary ? buffer : Buffer.from(buffer.toString("utf8").replace(/\r\n/g, "\n"));
+    return createHash("sha256").update(content).digest("hex");
+  } catch (error) {
+    // A constant sentinel would make two different unreadable files compare
+    // equal, which would pick "identical" and delete one of them.
+    const code = (error as NodeJS.ErrnoException)?.code ?? "?";
+    return `unreadable:${code}:${Buffer.from(file).toString("base64")}`;
+  }
+}
+
+function safeReadlink(file: string): string {
+  try {
+    return readlinkSync(file);
+  } catch {
+    return "?";
+  }
+}

package/src/harnesses.ts

@@ -0,0 +1,353 @@
+/**
+ * The harness table.
+ *
+ * Every row states, for one coding-agent harness, two things per scope
+ * (project / global):
+ *
+ *   1. the *instructions* file it loads (AGENTS.md, CLAUDE.md, …), and
+ *   2. the *skills* directory it scans.
+ *
+ * An endpoint is either `native` — the harness reads the canonical path
+ * (`AGENTS.md`, `.agents/skills/`) on its own, so agentlink creates nothing —
+ * or it has an `alias`, a path we symlink to the canonical source.
+ *
+ * An endpoint with neither `native: true` nor `alias` is *unknown*: we do not
+ * invent a path for it. `agentlink list` prints it as unavailable rather than
+ * writing a symlink somewhere the harness never looks.
+ *
+ * `source` is the documentation each row was read from, so a wrong row is a
+ * one-line fix rather than archaeology. `verified: false` marks rows whose
+ * documentation could not be confirmed.
+ */
+import type { Scope } from "./scope.js";
+
+export interface Endpoint {
+  /** The harness reads AGENTS.md / .agents/skills directly. */
+  native: boolean;
+  /** Path relative to the scope root; symlinked to the canonical source. */
+  alias?: string;
+  note?: string;
+  /** False when no vendor documentation confirms this path. Defaults to true. */
+  verified?: boolean;
+}
+
+export interface Harness {
+  id: string;
+  label: string;
+  /** Executables checked on PATH for detection. */
+  bins: string[];
+  /** Config directory relative to $HOME (from `herdr integration status`). */
+  configRoot: string;
+  instructions: Record<Scope, Endpoint>;
+  skills: Record<Scope, Endpoint>;
+  /** Primary documentation these paths were read from. */
+  source: string;
+}
+
+export function endpointVerified(endpoint: Endpoint): boolean {
+  return endpoint.verified !== false;
+}
+
+/** Endpoints in a scope that no vendor documentation confirms. */
+export function unverifiedEndpoints(
+  harness: Harness,
+  scope: Scope,
+): { kind: "instructions" | "skills"; endpoint: Endpoint }[] {
+  const found: { kind: "instructions" | "skills"; endpoint: Endpoint }[] = [];
+  for (const kind of ["instructions", "skills"] as const) {
+    const endpoint = harness[kind][scope];
+    if (!endpointVerified(endpoint)) found.push({ kind, endpoint });
+  }
+  return found;
+}
+
+const PI_SKILLS_DOC =
+  "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md";
+const CODEX_SKILLS_DOC = "https://developers.openai.com/codex/skills";
+const CLAUDE_SKILLS_DOC = "https://code.claude.com/docs/en/skills";
+const COPILOT_SKILLS_DOC =
+  "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills";
+const COPILOT_INSTRUCTIONS_DOC =
+  "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions";
+
+/** Build a endpoints pair: project + global in one call. */
+function scopes(project: Endpoint, global: Endpoint): Record<Scope, Endpoint> {
+  return { project, global };
+}
+
+const NATIVE: Endpoint = { native: true };
+
+export const HARNESSES: Harness[] = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    bins: ["claude"],
+    configRoot: ".claude",
+    // Claude Code reads CLAUDE.md, not AGENTS.md, and never scans .agents/skills.
+    instructions: scopes(
+      { native: false, alias: "CLAUDE.md", note: "Claude Code has no AGENTS.md fallback" },
+      { native: false, alias: ".claude/CLAUDE.md" },
+    ),
+    skills: scopes(
+      { native: false, alias: ".claude/skills" },
+      { native: false, alias: ".claude/skills" },
+    ),
+    source: CLAUDE_SKILLS_DOC,
+  },
+  {
+    id: "codex",
+    label: "OpenAI Codex CLI",
+    bins: ["codex"],
+    configRoot: ".codex",
+    // Codex reads AGENTS.md in the repo and ~/.codex/AGENTS.md globally.
+    instructions: scopes(
+      { native: true },
+      { native: false, alias: ".codex/AGENTS.md" },
+    ),
+    // Codex's user-level skills directory is $HOME/.agents/skills: native both ways.
+    skills: scopes(NATIVE, NATIVE),
+    source: CODEX_SKILLS_DOC,
+  },
+  {
+    id: "pi",
+    label: "Pi",
+    bins: ["pi"],
+    configRoot: ".pi",
+    instructions: scopes(
+      { native: true },
+      { native: false, alias: ".pi/agent/AGENTS.md" },
+    ),
+    // Pi reads ~/.agents/skills and .agents/skills directly.
+    skills: scopes(NATIVE, NATIVE),
+    source: PI_SKILLS_DOC,
+  },
+  {
+    id: "omp",
+    label: "Oh My Pi (omp)",
+    bins: ["omp"],
+    configRoot: ".omp",
+    instructions: scopes(
+      { native: true, note: "standalone AGENTS.md via the agents-md provider" },
+      { native: false, alias: ".omp/agent/AGENTS.md" },
+    ),
+    // omp scans its own .omp/skills trees; it does not read .agents/skills.
+    skills: scopes(
+      { native: false, alias: ".omp/skills" },
+      { native: false, alias: ".omp/agent/skills" },
+    ),
+    source: "https://github.com/can1357/oh-my-pi/blob/main/docs/config-usage.md",
+  },
+  {
+    id: "copilot",
+    label: "GitHub Copilot CLI",
+    bins: ["copilot"],
+    configRoot: ".copilot",
+    // Copilot CLI reads AGENTS.md everywhere, but its *user* instructions live
+    // in a differently named file.
+    instructions: scopes(
+      { native: true },
+      { native: false, alias: ".copilot/copilot-instructions.md" },
+    ),
+    skills: scopes(NATIVE, NATIVE),
+    source: `${COPILOT_SKILLS_DOC} · ${COPILOT_INSTRUCTIONS_DOC}`,
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    bins: ["cursor-agent", "cursor"],
+    configRoot: ".cursor",
+    instructions: scopes(
+      { native: true, note: "Cursor reads AGENTS.md" },
+      { native: false, alias: ".cursor/AGENTS.md", note: "not documented by Cursor", verified: false },
+    ),
+    skills: scopes(
+      { native: false, alias: ".cursor/skills", verified: false },
+      { native: false, alias: ".cursor/skills", verified: false },
+    ),
+    source: "https://cursor.com/docs/agent/context",
+  },
+  {
+    id: "opencode",
+    label: "opencode",
+    bins: ["opencode"],
+    configRoot: ".config/opencode",
+    instructions: scopes(
+      { native: true },
+      { native: false, alias: ".config/opencode/AGENTS.md" },
+    ),
+    skills: scopes(
+      { native: false, alias: ".opencode/skills", verified: false },
+      { native: false, alias: ".config/opencode/skills", verified: false },
+    ),
+    source: "https://opencode.ai/docs/rules/",
+  },
+  {
+    id: "qwen",
+    label: "Qwen Code",
+    bins: ["qwen"],
+    configRoot: ".qwen",
+    instructions: scopes(
+      { native: true, note: "QWEN.md is the legacy name" },
+      { native: false, alias: ".qwen/AGENTS.md", note: "not documented by Qwen", verified: false },
+    ),
+    skills: scopes(
+      { native: false, alias: ".qwen/skills" },
+      { native: false, alias: ".qwen/skills" },
+    ),
+    source: "https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/",
+  },
+  {
+    id: "kimi",
+    label: "Kimi Code CLI",
+    bins: ["kimi"],
+    configRoot: ".kimi-code",
+    instructions: scopes(
+      { native: true },
+      { native: false, alias: ".kimi-code/AGENTS.md", note: "not documented by Kimi", verified: false },
+    ),
+    skills: scopes(
+      { native: false, alias: ".kimi-code/skills" },
+      NATIVE, // Kimi scans ~/.agents/skills as its "generic group"
+    ),
+    source: "https://www.kimi.com/code/docs/en/kimi-code-cli/customization/skills.html",
+  },
+  {
+    id: "kilo",
+    label: "Kilo Code",
+    bins: ["kilo"],
+    configRoot: ".config/kilo",
+    instructions: scopes(
+      { native: true },
+      { native: false, alias: ".config/kilo/AGENTS.md", note: "not documented by Kilo" },
+    ),
+    // Kilo Code reads Claude Code's skills directory for compatibility.
+    skills: scopes(
+      { native: false, alias: ".claude/skills", note: "shares Claude Code's directory", verified: false },
+      { native: false, alias: ".config/kilo/skills", note: "unconfirmed", verified: false },
+    ),
+    source: "https://github.com/intellectronica/ruler#skills-support-experimental",
+  },
+  {
+    id: "droid",
+    label: "Factory Droid",
+    bins: ["droid"],
+    configRoot: ".factory",
+    instructions: scopes(
+      { native: true, note: "AGENTS.md may also live in the home directory" },
+      { native: false, alias: ".factory/AGENTS.md" },
+    ),
+    skills: scopes(
+      { native: false, alias: ".factory/skills" },
+      { native: false, alias: ".factory/skills" },
+    ),
+    source: "https://docs.factory.ai/harness/skills",
+  },
+  {
+    id: "devin",
+    label: "Devin CLI",
+    bins: ["devin"],
+    configRoot: ".config/devin",
+    instructions: scopes(
+      { native: true },
+      { native: false, alias: ".config/devin/AGENTS.md" },
+    ),
+    skills: scopes(
+      { native: false, alias: ".devin/skills" },
+      { native: false, alias: ".config/devin/skills" },
+    ),
+    source: "https://docs.devin.ai/cli/extensibility/rules",
+  },
+  {
+    id: "mastracode",
+    label: "Mastra Code",
+    bins: ["mastracode"],
+    configRoot: ".mastracode",
+    instructions: scopes(
+      { native: true },
+      { native: false, alias: ".mastracode/AGENTS.md", note: "not documented by Mastra", verified: false },
+    ),
+    // Mastra Code lists .agents/skills as a project source and Agent Skills
+    // spec compatibility, so both scopes are native.
+    skills: scopes(NATIVE, NATIVE),
+    source: "https://code.mastra.ai/configuration",
+  },
+  {
+    id: "grok",
+    label: "Grok CLI",
+    bins: ["grok"],
+    configRoot: ".grok",
+    instructions: scopes(
+      { native: true, note: "reads AGENTS.md, CLAUDE.md, AGENT.md" },
+      { native: false, alias: ".grok/AGENTS.md", note: "not documented by Grok", verified: false },
+    ),
+    skills: scopes(
+      { native: false, alias: ".grok/skills" },
+      { native: false, alias: ".grok/skills" },
+    ),
+    source: "https://docs.x.ai/docs/grok-cli/skills",
+  },
+  {
+    id: "qoder",
+    label: "Qoder CLI",
+    bins: ["qodercli", "qoder"],
+    configRoot: ".qoder",
+    instructions: scopes(
+      { native: true, note: "configurable via context.fileName" },
+      { native: false, alias: ".qoder/AGENTS.md", note: "not documented by Qoder", verified: false },
+    ),
+    skills: scopes(
+      { native: false, alias: ".qoder/skills" },
+      { native: false, alias: ".qoder/skills" },
+    ),
+    source: "https://docs.qoder.com/cli/Skills",
+  },
+  {
+    id: "antigravity",
+    label: "Antigravity CLI",
+    bins: ["agy", "antigravity"],
+    configRoot: ".gemini/config",
+    instructions: scopes(
+      { native: true, note: "Gemini-lineage discovery: AGENTS.md, CONTEXT.md, GEMINI.md", verified: false },
+      { native: false, alias: ".gemini/config/AGENTS.md", note: "unconfirmed", verified: false },
+    ),
+    skills: scopes(
+      { native: false, alias: ".agent/skills", note: "unconfirmed", verified: false },
+      { native: false, alias: ".gemini/config/skills", note: "unconfirmed", verified: false },
+    ),
+    source: "https://github.com/intellectronica/ruler#skills-support-experimental",
+  },
+  {
+    id: "hermes",
+    label: "Hermes",
+    bins: ["hermes"],
+    configRoot: ".hermes",
+    instructions: scopes(
+      { native: true, note: "unconfirmed", verified: false },
+      { native: false, alias: ".hermes/AGENTS.md", note: "unconfirmed" },
+    ),
+    skills: scopes(
+      { native: false, alias: ".hermes/skills", note: "unconfirmed", verified: false },
+      { native: false, alias: ".hermes/skills", note: "unconfirmed", verified: false },
+    ),
+    source: "https://herdr.dev/llms.txt",
+  },
+];
+
+export const HARNESS_IDS = HARNESSES.map((h) => h.id);
+
+export function findHarness(id: string): Harness | undefined {
+  const needle = id.trim().toLowerCase();
+  return HARNESSES.find((h) => h.id === needle || h.label.toLowerCase() === needle);
+}
+
+/** Resolve a comma/space separated harness list; unknown ids are returned to the caller. */
+export function resolveHarnessList(input: string): { found: Harness[]; unknown: string[] } {
+  const found: Harness[] = [];
+  const unknown: string[] = [];
+  for (const raw of input.split(/[,\s]+/).filter(Boolean)) {
+    const harness = findHarness(raw);
+    if (harness) found.push(harness);
+    else unknown.push(raw);
+  }
+  return { found, unknown };
+}