@thesmurph/agentlink 0.1.0

package/src/convention.ts

@@ -0,0 +1,232 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync } from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "./link.js";
+import type { ScopePaths, Scope } from "./scope.js";
+
+export const BEGIN_MARKER = "<!-- agentlink:begin v1 -->";
+export const END_MARKER = "<!-- agentlink:end -->";
+
+/** Whole-line markers only: prose mentioning the marker is not the marker. */
+const BEGIN_LINE = /^<!-- agentlink:begin v1 -->[ \t]*$/m;
+const END_LINE = /^<!-- agentlink:end -->[ \t]*$/m;
+
+const PROJECT_CLAUSE = `${BEGIN_MARKER}
+## Agent docs and skills: one source of truth
+
+This repository keeps exactly one copy of every agent instruction file and skill.
+Paths such as \`CLAUDE.md\`, \`GEMINI.md\`, \`.claude/skills/\` and \`.cursor/skills/\`
+are symlinks maintained by \`agentlink\`. Never edit a symlink, and never create a
+file next to one — edit or create the source it points to.
+
+- **Instructions** live in \`AGENTS.md\` at the repository root.
+- **Skills** live in \`.agents/skills/<skill-name>/SKILL.md\`, one directory per skill.
+- **Extra documentation** goes under \`.agents/\` (for example \`.agents/testing.md\`),
+  or in an \`AGENTS.md\` in the subdirectory it applies to.
+- **Naming**: the skill directory and its frontmatter \`name\` are the same
+  lowercase-hyphenated string, 1-64 characters (\`pdf-forms\`, not \`PDF_Forms\`).
+  \`SKILL.md\` needs frontmatter with \`name\` and a \`description\` that states what
+  the skill does *and* when to use it. Keep scripts and references inside the
+  skill directory and link them with relative paths.
+- **After adding, renaming, or moving a skill or doc**, run \`agentlink sync\`
+  so every harness picks up the change.
+${END_MARKER}`;
+
+const GLOBAL_CLAUSE = `${BEGIN_MARKER}
+## Personal agent setup
+
+This is your user-level instructions file, loaded by every session regardless of
+project. Personal skills live once, in \`~/.agents/skills/<skill-name>/SKILL.md\`.
+Paths such as \`~/.claude/CLAUDE.md\` and \`~/.claude/skills/\` are symlinks
+maintained by \`agentlink\`; never edit a symlink, and never create a file or
+skill directory next to one.
+
+A project that carries its own \`AGENTS.md\` and \`.agents/skills/\` takes
+precedence over anything here, so keep this file to preferences that apply
+everywhere: how you like work done, what to ask before doing, personal tooling.
+
+- **Naming**: skill directory and frontmatter \`name\` are the same
+  lowercase-hyphenated string, 1-64 characters.
+- **After adding, renaming, or moving a personal skill**, run
+  \`agentlink sync --global\`.
+${END_MARKER}`;
+
+/**
+ * The clause agentlink appends to AGENTS.md.
+ *
+ * Its job is to tell a *future agent* — one that has never heard of agentlink —
+ * where documentation and skills belong and how to name them, so the convention
+ * survives without a human enforcing it. The text differs by scope because a
+ * global file is loaded in every project, including ones that do not use this
+ * convention, so it must not claim anything about "this repository".
+ */
+export function clauseFor(scope: Scope): string {
+  return scope === "global" ? GLOBAL_CLAUSE : PROJECT_CLAUSE;
+}
+
+/** The repository-scope clause, kept as a named export for documentation. */
+export const CLAUSE = PROJECT_CLAUSE;
+
+export type ClauseAction = "inserted" | "updated" | "unchanged" | "malformed";
+
+export interface ClauseResult {
+  changed: boolean;
+  action: ClauseAction;
+  file: string;
+}
+
+export function hasClause(text: string): boolean {
+  return BEGIN_LINE.test(text);
+}
+
+/**
+ * Insert the clause, or replace the existing one in place.
+ *
+ * A lone marker is left untouched: the text after an unterminated block might be
+ * the user's own prose, and guessing would delete it.
+ */
+export function upsertClause(
+  text: string,
+  scope: Scope = "project",
+): { text: string; changed: boolean; action: ClauseAction } {
+  const clause = clauseFor(scope);
+  const begin = BEGIN_LINE.exec(text);
+  const end = END_LINE.exec(text);
+  if (begin && !end) return { text, changed: false, action: "malformed" };
+  if (!begin && end) return { text, changed: false, action: "malformed" };
+
+  if (begin && end) {
+    const endIndex = end.index;
+    const existing = text.slice(begin.index, endIndex + end[0].length);
+    if (existing === clause) return { text, changed: false, action: "unchanged" };
+    const next = `${text.slice(0, begin.index)}${clause}${text.slice(endIndex + end[0].length)}`;
+    return { text: next, changed: true, action: "updated" };
+  }
+
+  const trimmed = text.replace(/\s+$/, "");
+  const separator = trimmed.length === 0 ? "" : "\n\n";
+  return { text: `${trimmed}${separator}${clause}\n`, changed: true, action: "inserted" };
+}
+
+export function ensureClause(
+  paths: ScopePaths,
+  options: { dryRun?: boolean } = {},
+): ClauseResult {
+  const file = paths.instructions;
+  if (!existsSync(file)) return { changed: false, action: "unchanged", file };
+
+  const before = readFileSync(file, "utf8");
+  const { text, changed, action } = upsertClause(before, paths.scope);
+  if (changed && !options.dryRun) writeFileAtomic(file, text);
+  return { changed, action, file };
+}
+
+/** Create AGENTS.md and .agents/skills/ when they do not exist yet. */
+export function initConvention(
+  paths: ScopePaths,
+  options: { dryRun?: boolean } = {},
+): { createdFile: boolean; createdSkillsDir: boolean; file: string; skills: string } {
+  const createdFile = !existsSync(paths.instructions);
+  if (createdFile && !options.dryRun) {
+    const title = path.basename(paths.root) || "project";
+    const heading = paths.scope === "global" ? "Global agent instructions" : title;
+    const body =
+      paths.scope === "global"
+        ? "<!-- Preferences that apply in every project. Project AGENTS.md files take precedence. -->"
+        : "<!-- One or two sentences: what this is, who it is for. -->";
+    writeFileAtomic(
+      paths.instructions,
+      `# ${heading}\n\n${body}\n\n${clauseFor(paths.scope)}\n`,
+    );
+  } else if (!options.dryRun) {
+    ensureClause(paths, options);
+  }
+
+  const createdSkillsDir = !existsSync(paths.skills);
+  if (createdSkillsDir && !options.dryRun) mkdirSync(paths.skills, { recursive: true });
+
+  return {
+    createdFile,
+    createdSkillsDir,
+    file: paths.instructions,
+    skills: paths.skills,
+  };
+}
+
+export interface AdoptResult {
+  performed: boolean;
+  reason?: string;
+  from?: string;
+  to?: string;
+  /** Set when the only blocker is a symlinked AGENTS.md. */
+  needsInvert?: boolean;
+}
+
+/**
+ * Migrate a harness instructions file into the canonical AGENTS.md.
+ *
+ * Only the unambiguous case is handled: AGENTS.md is absent and exactly one real
+ * (non-symlink) harness file exists. A rename keeps `git log --follow` intact and
+ * leaves the old path as a symlink afterwards. When both files exist as real
+ * content, merging is a judgement call and we refuse.
+ */
+export function adoptInstructions(
+  paths: ScopePaths,
+  options: { dryRun?: boolean } = {},
+): AdoptResult {
+  const candidates = ["CLAUDE.md", "GEMINI.md", "QWEN.md", "CRUSH.md", "WARP.md", "CONTEXT.md"];
+  const present = candidates
+    .map((name) => path.join(paths.root, name))
+    .filter((file) => existsSync(file) && !isSymlink(file));
+
+  if (existsSync(paths.instructions)) {
+    if (isSymlink(paths.instructions)) {
+      // AGENTS.md is itself an alias, so something else holds the real content.
+      const link = isSymlink(paths.instructions) ? targetsOf(paths.instructions) : undefined;
+      return {
+        performed: false,
+        needsInvert: true,
+        reason: `AGENTS.md is a symlink${link ? ` to ${link}` : ""} — make AGENTS.md the real file and link the other name to it`,
+      };
+    }
+    if (present.length > 0) {
+      return {
+        performed: false,
+        reason: `AGENTS.md and ${present.map((p) => path.basename(p)).join(", ")} both contain real content — merge them by hand, then re-run`,
+      };
+    }
+    return { performed: false, reason: "AGENTS.md already exists" };
+  }
+
+  if (present.length === 0) return { performed: false, reason: "no harness instructions file to adopt" };
+  if (present.length > 1) {
+    const names = present.map((p) => path.basename(p));
+    return {
+      performed: false,
+      reason: `several candidates (${names.join(", ")}) — keep one, delete or merge the others, then re-run`,
+    };
+  }
+
+  const from = present[0] as string;
+  if (options.dryRun) {
+    return { performed: false, reason: "dry run", from, to: paths.instructions };
+  }
+  // A rename keeps the original bytes and shows up as a rename in git.
+  renameSync(from, paths.instructions);
+  return { performed: true, from, to: paths.instructions };
+}
+
+function isSymlink(file: string): boolean {
+  try {
+    return lstatSync(file).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function targetsOf(file: string): string | undefined {
+  try {
+    return readlinkSync(file);
+  } catch {
+    return undefined;
+  }
+}

package/src/detect.ts

@@ -0,0 +1,43 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { HARNESSES, type Harness } from "./harnesses.js";
+
+export interface Detection {
+  harness: Harness;
+  installed: boolean;
+  reasons: string[];
+}
+
+/** Look the binary up in PATH without shelling out. */
+export function isOnPath(bins: string[]): string | undefined {
+  const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE").split(";") : [""];
+  for (const bin of bins) {
+    for (const dir of dirs) {
+      for (const ext of exts) {
+        const candidate = path.join(dir, bin + ext);
+        if (existsSync(candidate)) return candidate;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * A harness counts as present when its binary is on PATH or its config
+ * directory exists. Config roots come from `herdr integration status`, which
+ * knows where each harness actually keeps its state.
+ */
+export function detect(harness: Harness, home = homedir()): Detection {
+  const reasons: string[] = [];
+  const bin = isOnPath(harness.bins);
+  if (bin) reasons.push(`binary ${path.basename(bin)}`);
+  const configPath = path.join(home, harness.configRoot);
+  if (existsSync(configPath)) reasons.push(`config ${harness.configRoot.startsWith(".") ? "~/" : ""}${harness.configRoot}`);
+  return { harness, installed: reasons.length > 0, reasons };
+}
+
+export function detectAll(home = homedir()): Detection[] {
+  return HARNESSES.map((harness) => detect(harness, home));
+}

package/src/doctor.ts

@@ -0,0 +1,289 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { clauseFor, hasClause, BEGIN_MARKER } from "./convention.js";
+import { endpointVerified, unverifiedEndpoints, type Harness } from "./harnesses.js";
+import { ignoreEntries, isIgnoreMode, readIgnoreBlock } from "./ignore.js";
+import { inspect, plan, readState } from "./link.js";
+import { listHiddenSubdirectories, listSubdirectories, type ScopePaths } from "./scope.js";
+
+export type Severity = "error" | "warn" | "info";
+
+export interface Finding {
+  severity: Severity;
+  message: string;
+  fix?: string;
+}
+
+export interface SkillRecord {
+  name: string;
+  dir: string;
+  frontmatter: { name?: string; description?: string };
+  hasDirectSkillFile: boolean;
+  hasNestedSkillFile: boolean;
+}
+
+export function readSkills(paths: ScopePaths): SkillRecord[] {
+  return listSubdirectories(paths.skills).map((name) => {
+    const dir = path.join(paths.skills, name);
+    const direct = path.join(dir, "SKILL.md");
+    const hasDirectSkillFile = existsSync(direct);
+    return {
+      name,
+      dir,
+      hasDirectSkillFile,
+      hasNestedSkillFile: !hasDirectSkillFile && findNestedSkillFile(dir, 1) !== undefined,
+      frontmatter: hasDirectSkillFile ? parseFrontmatter(readFileSync(direct, "utf8")) : {},
+    };
+  });
+}
+
+/** A SKILL.md in a subdirectory, which only some harnesses read. */
+export function findNestedSkillFile(dir: string, depth = 0): string | undefined {
+  const direct = path.join(dir, "SKILL.md");
+  if (existsSync(direct)) return direct;
+  if (depth >= 2) return undefined;
+  for (const child of listSubdirectories(dir)) {
+    const found = findNestedSkillFile(path.join(dir, child), depth + 1);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+export function parseFrontmatter(text: string): { name?: string; description?: string } {
+  if (!text.startsWith("---")) return {};
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return {};
+  const block = text.slice(3, end);
+  const read = (key: string): string | undefined => {
+    const match = block.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+    if (!match?.[1]) return undefined;
+    return match[1].trim().replace(/^["']|["']$/g, "");
+  };
+  return { name: read("name"), description: read("description") };
+}
+
+export interface DoctorInput {
+  paths: ScopePaths;
+  harnesses: Harness[];
+}
+
+/**
+ * Report the problems a user can act on.
+ *
+ * Missing or misdirected links for a selected harness are errors, not warnings:
+ * the whole promise of the tool is that the harness reads what you wrote, and a
+ * repository that fails that should not pass a CI check.
+ */
+export function diagnose({ paths, harnesses }: DoctorInput): Finding[] {
+  const findings: Finding[] = [];
+
+  // With nothing selected there are no links to check. Say so, rather than
+  // reporting a clean bill of health that was never actually earned: a CI
+  // runner has no harnesses installed, so this is reachable on every run.
+  if (harnesses.length === 0) {
+    findings.push({
+      severity: "warn",
+      message: "no harnesses are selected or installed, so only the convention was checked",
+      fix: "agentlink init, or pass --harnesses to check a specific set",
+    });
+  }
+
+  // --- the convention itself ------------------------------------------------
+  const instructionsExist = existsSync(paths.instructions);
+  if (!instructionsExist) {
+    findings.push({
+      severity: "error",
+      message: `${label(paths, paths.instructions)} is missing`,
+      fix: "agentlink init",
+    });
+  } else {
+    const text = readFileSync(paths.instructions, "utf8");
+    if (!hasClause(text)) {
+      findings.push({
+        severity: "warn",
+        message: `${path.basename(paths.instructions)} does not explain the convention to agents`,
+        fix: "agentlink sync  (appends the agentlink clause)",
+      });
+    } else if (!text.includes(clauseFor(paths.scope))) {
+      findings.push({
+        severity: "info",
+        message: `${path.basename(paths.instructions)} has an outdated agentlink clause, or an unterminated one`,
+        fix: "agentlink sync, then check the section by hand",
+      });
+    }
+  }
+
+  if (!existsSync(paths.skills)) {
+    findings.push({
+      severity: "warn",
+      message: `${short(paths, paths.skills)} does not exist`,
+      fix: "agentlink init",
+    });
+  }
+
+  // --- skills ---------------------------------------------------------------
+  for (const file of safeReadDir(paths.skills).filter((name) => name.endsWith(".md"))) {
+    findings.push({
+      severity: "warn",
+      message: `${short(paths, path.join(paths.skills, file))} sits at the root of .agents/skills`,
+      fix: "move it into .agents/skills/<skill-name>/SKILL.md — root Markdown is not a skill",
+    });
+  }
+
+  for (const hidden of listHiddenSubdirectories(paths.skills)) {
+    findings.push({
+      severity: "info",
+      message: `.agents/skills/${hidden} starts with a dot, so it is skipped`,
+      fix: "rename it without the dot to publish it as a skill",
+    });
+  }
+
+  for (const name of safeReadDir(paths.skills)) {
+    const entry = path.join(paths.skills, name);
+    if (name.startsWith(".") || name.endsWith(".md")) continue;
+    const kind = inspect(entry).kind;
+    if (kind === "symlink") {
+      const target = (inspect(entry) as { resolved?: string }).resolved;
+      if (!target || !existsSync(target)) {
+        findings.push({
+          severity: "error",
+          message: `.agents/skills/${name} is a broken symlink`,
+          fix: "remove it or point it at a directory that exists",
+        });
+      }
+      continue;
+    }
+    if (kind === "error") {
+      findings.push({
+        severity: "error",
+        message: `.agents/skills/${name} cannot be read`,
+        fix: "check permissions on the path",
+      });
+    }
+  }
+
+  for (const skill of readSkills(paths)) {
+    if (!skill.hasDirectSkillFile) {
+      findings.push({
+        severity: "error",
+        message: skill.hasNestedSkillFile
+          ? `.agents/skills/${skill.name} has no SKILL.md directly inside, only nested ones — most harnesses will not find it`
+          : `.agents/skills/${skill.name} has no SKILL.md`,
+        fix: "put SKILL.md at .agents/skills/<skill-name>/SKILL.md",
+      });
+      continue;
+    }
+    const name = skill.frontmatter.name;
+    if (!name) {
+      findings.push({
+        severity: "error",
+        message: `.agents/skills/${skill.name}/SKILL.md has no \`name\` frontmatter`,
+        fix: "add `name:` matching the directory name",
+      });
+      continue;
+    }
+    if (name !== skill.name) {
+      findings.push({
+        severity: "warn",
+        message: `.agents/skills/${skill.name} declares name \`${name}\``,
+        fix: "keep the directory name and frontmatter name identical so every harness resolves it",
+      });
+    }
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name) || name.length > 64) {
+      findings.push({
+        severity: "error",
+        message: `skill name \`${name}\` is not lowercase-hyphenated, 1-64 chars`,
+      });
+    }
+    if (!skill.frontmatter.description) {
+      findings.push({
+        severity: "error",
+        message: `.agents/skills/${skill.name}/SKILL.md has no \`description\``,
+        fix: "describe what the skill does and when to use it",
+      });
+    }
+  }
+
+  // --- links ----------------------------------------------------------------
+  const desired = plan(paths, harnesses);
+  for (const op of desired.ops) {
+    const existing = inspect(op.target);
+    if (existing.kind === "missing") {
+      findings.push({
+        severity: "error",
+        message: `${short(paths, op.target)} is not linked (${op.harnessIds.join(", ")})`,
+        fix: "agentlink sync",
+      });
+    } else if (existing.kind === "symlink" && existing.resolved !== op.source) {
+      findings.push({
+        severity: "error",
+        message: `${short(paths, op.target)} points at ${short(paths, existing.resolved ?? "")}`,
+        fix: "agentlink sync",
+      });
+    } else if (existing.kind === "file" || existing.kind === "dir") {
+      if (op.kind === "instructions") {
+        findings.push({
+          severity: "error",
+          message: `${short(paths, op.target)} is a real ${existing.kind}, not a symlink — two copies of your instructions`,
+          fix: "agentlink adopt  (moves it to AGENTS.md and links back)",
+        });
+      } else {
+        // Reported even when empty: an empty directory still blocks the link.
+        findings.push({
+          severity: "error",
+          message: `${short(paths, op.target)} is a real ${existing.kind} instead of a link to skill \`${op.skill}\``,
+          fix: `agentlink fix  (the canonical copy is .agents/skills/${op.skill})`,
+        });
+      }
+    }
+  }
+
+  // --- honesty about the table ---------------------------------------------
+  for (const harness of harnesses) {
+    for (const { kind, endpoint } of unverifiedEndpoints(harness, paths.scope)) {
+      const where = endpoint.native ? "native path" : endpoint.alias;
+      findings.push({
+        severity: "info",
+        message: `${harness.label}: ${kind} ${where} is not confirmed by ${harness.source}`,
+      });
+    }
+  }
+
+  // --- gitignore ------------------------------------------------------------
+  const state = readState(paths);
+  const mode = isIgnoreMode(state.ignore) ? state.ignore : "skills";  if (paths.scope === "project" && existsSync(path.join(paths.root, ".git")) && mode !== "none") {
+    const expected = ignoreEntries(mode, {
+      skillDirs: [...new Set(desired.ops.filter((op) => op.kind === "skill").map((op) => path.posix.dirname(op.rel)))],
+      instructionFiles: [...new Set(desired.ops.filter((op) => op.kind === "instructions").map((op) => op.rel))],
+    });
+    const actual = readIgnoreBlock(paths);
+    const missing = expected.filter((entry) => !actual.includes(entry));
+    if (missing.length > 0) {
+      findings.push({
+        severity: "warn",
+        message: `${missing.length} linked path${missing.length === 1 ? "" : "s"} would show up as untracked: ${missing.slice(0, 3).join(", ")}${missing.length > 3 ? ", …" : ""}`,
+        fix: "agentlink sync",
+      });
+    }
+  }
+
+  return findings;
+}
+
+function safeReadDir(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+function short(paths: ScopePaths, absolute: string): string {
+  return path.relative(paths.root, absolute) || ".";
+}
+
+function label(paths: ScopePaths, absolute: string): string {
+  return path.join(paths.scope === "global" ? "~" : ".", short(paths, absolute));
+}
+
+export { statSync, BEGIN_MARKER };