@thesmurph/agentlink 0.1.0

package/src/ignore.ts

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "./link.js";
+import type { ScopePaths } from "./scope.js";
+
+export type IgnoreMode = "skills" | "all" | "none";
+
+/** Matched as whole lines: a user comment like "# agentlink:beginning" is not our marker. */
+const BEGIN_LINE = /^# agentlink:begin\s*$/m;
+const END_LINE = /^# agentlink:end\s*$/m;
+const BLOCK = "# agentlink:begin";
+
+export const IGNORE_MODES: IgnoreMode[] = ["skills", "all", "none"];
+
+export function isIgnoreMode(value: string): value is IgnoreMode {
+  return (IGNORE_MODES as string[]).includes(value);
+}
+
+/**
+ * Which created links belong in .gitignore.
+ *
+ * Instructions aliases are one small file per harness and are the thing that
+ * makes a fresh clone work for a teammate on a different harness, so they are
+ * committed. Skill links are derived, multiply with every skill and harness,
+ * and their parent directories also hold machine-local harness state, so they
+ * are ignored and regenerated by `agentlink sync`.
+ */
+export function ignoreEntries(
+  mode: IgnoreMode,
+  input: { skillDirs: string[]; instructionFiles: string[] },
+): string[] {
+  const entries: string[] = [];
+  if (mode === "none") return entries;
+  for (const dir of input.skillDirs) entries.push(`${dir}/`);
+  if (mode === "all") entries.push(...input.instructionFiles);
+  return [...new Set(entries)].sort();
+}
+
+export type BlockStatus = "updated" | "unchanged" | "malformed";
+
+export interface IgnoreResult {
+  status: BlockStatus;
+  file: string;
+  entries: string[];
+  skipped?: string;
+}
+
+export function updateGitignore(
+  paths: ScopePaths,
+  mode: IgnoreMode,
+  input: { skillDirs: string[]; instructionFiles: string[] },
+  options: { dryRun?: boolean } = {},
+): IgnoreResult {
+  const file = path.join(paths.root, ".gitignore");
+  const entries = ignoreEntries(mode, input);
+
+  // Only touch a repository that actually tracks files here.
+  if (paths.scope !== "project" || !existsSync(path.join(paths.root, ".git"))) {
+    return { status: "unchanged", file, entries, skipped: "not a git repository" };
+  }
+
+  const before = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const spliced = applyIgnoreBlock(before, entries);
+  if (spliced.status === "malformed") return { status: spliced.status, file, entries };
+
+  const changed = spliced.status === "updated";
+  if (changed && !options.dryRun) writeFileAtomic(file, spliced.text);
+  return { status: spliced.status, file, entries };
+}
+
+/** Remove the managed block, leaving the rest of .gitignore alone. */
+export function removeIgnoreBlock(paths: ScopePaths, options: { dryRun?: boolean } = {}): boolean {
+  const file = path.join(paths.root, ".gitignore");
+  if (!existsSync(file)) return false;
+  const before = readFileSync(file, "utf8");
+  const spliced = applyIgnoreBlock(before, []);
+  if (spliced.status !== "updated" || spliced.text === before) return false;
+  if (!options.dryRun) writeFileAtomic(file, spliced.text);
+  return true;
+}
+
+/** Read the entries currently inside the managed block. */
+export function readIgnoreBlock(paths: ScopePaths): string[] {
+  const text = existsSync(path.join(paths.root, ".gitignore"))
+    ? readFileSync(path.join(paths.root, ".gitignore"), "utf8")
+    : "";
+  return blockSpan(text)?.entries ?? [];
+}
+
+interface Span {
+  start: number;
+  end: number;
+  entries: string[];
+}
+
+/** Locate the managed block by whole-line markers. Returns null when absent. */
+function blockSpan(text: string): Span | null {
+  const begin = BEGIN_LINE.exec(text);
+  if (!begin) return null;
+  const afterBegin = begin.index + begin[0].length;
+  const end = END_LINE.exec(text.slice(afterBegin));
+  if (!end) return null;
+  const endIndex = afterBegin + end.index;
+  const body = text.slice(afterBegin, endIndex);
+  return {
+    start: begin.index,
+    end: endIndex + end[0].length,
+    entries: body
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith("#")),
+  };
+}
+
+export interface SpliceResult {
+  text: string;
+  status: BlockStatus;
+}
+
+/**
+ * Insert, replace or remove the managed block.
+ *
+ * Text outside the block is never rewritten: no whitespace normalisation runs
+ * over the user's file. A lone marker is refused rather than guessed at, since
+ * anything after an unterminated block might be the user's own rules.
+ */
+export function applyIgnoreBlock(text: string, entries: string[]): SpliceResult {
+  const beginMatch = BEGIN_LINE.exec(text);
+  const endMatch = END_LINE.exec(text);
+  if (beginMatch && !endMatch) {
+    return { text, status: "malformed" };
+  }
+  if (!beginMatch && endMatch) {
+    return { text, status: "malformed" };
+  }
+
+  const span = beginMatch && endMatch ? blockSpan(text) : null;
+  const without = span ? `${text.slice(0, span.start)}${text.slice(span.end)}` : text;
+
+  if (entries.length === 0) {
+    if (!span) return { text, status: "unchanged" };
+    // Remove the blank line the block was separated by, but nothing else.
+    const trimmed = without.replace(/\n[ \t]*\n$/, "\n").replace(/\n$/, text.endsWith("\n") ? "\n" : "");
+    return { text: trimmed, status: "updated" };
+  }
+
+  const block = [BLOCK, ...entries, "# agentlink:end"].join("\n");
+  if (span) {
+    const next = `${without.slice(0, span.start)}${block}\n${without.slice(span.start).replace(/^\n/, "")}`;
+    return { text: next, status: next === text ? "unchanged" : "updated" };
+  }
+
+  const base = text.replace(/\s+$/, "");
+  const next = base === "" ? `${block}\n` : `${base}\n\n${block}\n`;
+  return { text: next, status: next === text ? "unchanged" : "updated" };
+}

package/src/link.ts

@@ -0,0 +1,429 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  rmdirSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import type { Harness } from "./harnesses.js";
+import { listSubdirectories, relativeTo, type ScopePaths } from "./scope.js";
+
+export type LinkKind = "instructions" | "skill";
+
+export interface LinkOp {
+  /** Absolute path of the symlink to create. */
+  target: string;
+  /** Absolute path of the canonical source it points at. */
+  source: string;
+  /** `target` relative to the scope root, for state and display. */
+  rel: string;
+  kind: LinkKind;
+  skill?: string;
+  harnessIds: string[];
+}
+
+export interface SkipOp {
+  target: string;
+  rel: string;
+  kind: LinkKind;
+  harnessIds: string[];
+  reason: string;
+}
+
+export interface Plan {
+  ops: LinkOp[];
+  skips: SkipOp[];
+  /** Harnesses that already read the canonical path; nothing to create. */
+  native: { harnessId: string; kind: LinkKind }[];
+  /** Harnesses whose path for this scope has no documented answer. */
+  unknown: { harnessId: string; kind: LinkKind }[];
+  /**
+   * Harness directories that are themselves symlinks to the canonical tree.
+   * Already correct, so no links are planned, but still derived paths that
+   * belong in .gitignore.
+   */
+  aliases: { rel: string; harnessId: string }[];
+  skillsFound: string[];
+}
+
+/** True when `dir` resolves to the same place as the canonical skills tree. */
+function resolvesToCanonicalSkills(paths: ScopePaths, dir: string): boolean {
+  try {
+    return realpathSync(dir) === realpathSync(paths.skills);
+  } catch {
+    return false;
+  }
+}
+
+/** Build the full set of links for a scope without touching the filesystem. */
+export function plan(paths: ScopePaths, harnesses: Harness[]): Plan {
+  const ops = new Map<string, LinkOp>();
+  const skips: SkipOp[] = [];
+  const native: Plan["native"] = [];
+  const unknown: Plan["unknown"] = [];
+  const aliases: Plan["aliases"] = [];
+
+  const add = (op: Omit<LinkOp, "harnessIds">, harnessId: string) => {
+    const existing = ops.get(op.target);
+    if (existing) {
+      if (!existing.harnessIds.includes(harnessId)) existing.harnessIds.push(harnessId);
+      return;
+    }
+    ops.set(op.target, { ...op, harnessIds: [harnessId] });
+  };
+
+  const skip = (op: Omit<SkipOp, "harnessIds">, harnessId: string) => {
+    const existing = skips.find((s) => s.target === op.target && s.reason === op.reason);
+    if (existing) {
+      if (!existing.harnessIds.includes(harnessId)) existing.harnessIds.push(harnessId);
+      return;
+    }
+    skips.push({ ...op, harnessIds: [harnessId] });
+  };
+
+  const instructionsExist = existsSync(paths.instructions);
+  const skills = listSubdirectories(paths.skills);
+
+  for (const harness of harnesses) {
+    const instr = harness.instructions[paths.scope];
+    const alias = instr.native ? undefined : instr.alias;
+    if (instr.native) {
+      native.push({ harnessId: harness.id, kind: "instructions" });
+    } else if (!alias) {
+      unknown.push({ harnessId: harness.id, kind: "instructions" });
+    } else if (!instructionsExist) {
+      skip(
+        {
+          target: path.join(paths.root, alias),
+          rel: alias,
+          kind: "instructions",
+          reason: "AGENTS.md does not exist yet — run `agentlink init` first",
+        },
+        harness.id,
+      );
+    } else {
+      add(
+        {
+          target: path.join(paths.root, alias),
+          source: paths.instructions,
+          rel: alias,
+          kind: "instructions",
+        },
+        harness.id,
+      );
+    }
+
+    const sk = harness.skills[paths.scope];
+    const skillsAlias = sk.native ? undefined : sk.alias;
+    if (sk.native) {
+      native.push({ harnessId: harness.id, kind: "skill" });
+    } else if (!skillsAlias) {
+      unknown.push({ harnessId: harness.id, kind: "skill" });
+    } else if (resolvesToCanonicalSkills(paths, path.join(paths.root, skillsAlias))) {
+      // The harness directory is a symlink to .agents/skills, which is already
+      // the arrangement this tool exists to create.
+      aliases.push({ rel: skillsAlias, harnessId: harness.id });
+    } else if (skills.length === 0) {
+      skip(
+        {
+          target: path.join(paths.root, skillsAlias),
+          rel: skillsAlias,
+          kind: "skill",
+          reason: "no skills in .agents/skills yet",
+        },
+        harness.id,
+      );
+    } else {
+      for (const skill of skills) {
+        add(
+          {
+            target: path.join(paths.root, skillsAlias, skill),
+            source: path.join(paths.skills, skill),
+            rel: path.posix.join(skillsAlias, skill),
+            kind: "skill",
+            skill,
+          },
+          harness.id,
+        );
+      }
+    }
+  }
+
+  return { ops: [...ops.values()], skips, native, unknown, aliases, skillsFound: skills };
+}
+
+export type LinkState = "linked" | "relinked" | "unchanged" | "skipped";
+
+export interface ApplyResult {
+  op: LinkOp;
+  state: LinkState;
+  detail?: string;
+}
+
+/**
+ * Apply a plan. Each op is isolated: one failure is reported as skipped rather
+ * than aborting the batch, so links created earlier stay recorded in state and
+ * remain removable by `unlink`.
+ */
+export function apply(paths: ScopePaths, plan: Plan, options: { dryRun?: boolean } = {}): ApplyResult[] {
+  return plan.ops.map((op) => {
+    try {
+      return createLink(paths, op, options);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { op, state: "skipped" as const, detail: `could not link: ${message}` };
+    }
+  });
+}
+
+function createLink(paths: ScopePaths, op: LinkOp, options: { dryRun?: boolean }): ApplyResult {
+  const existing = inspect(op.target);
+
+  if (existing.kind === "error") {
+    return { op, state: "skipped", detail: `cannot inspect: ${existing.detail}` };
+  }
+
+  if (existing.kind === "missing") {
+    if (!options.dryRun) {
+      mkdirSync(path.dirname(op.target), { recursive: true });
+      symlinkSync(relativeTo(path.dirname(op.target), op.source), op.target);
+    }
+    return { op, state: "linked" };
+  }
+
+  if (existing.kind === "symlink") {
+    if (existing.resolved === op.source) return { op, state: "unchanged" };
+    if (isOwned(paths, existing.resolved)) {
+      if (!options.dryRun) {
+        unlinkSync(op.target);
+        symlinkSync(relativeTo(path.dirname(op.target), op.source), op.target);
+      }
+      return { op, state: "relinked" };
+    }
+    return { op, state: "skipped", detail: `already a symlink to ${existing.resolved}` };
+  }
+
+  return { op, state: "skipped", detail: blockerMessage(op, existing.kind) };
+}
+
+function blockerMessage(op: LinkOp, kind: "file" | "dir"): string {
+  if (op.kind === "instructions") {
+    return kind === "dir"
+      ? `a directory sits at ${op.rel} — remove it, or point it at AGENTS.md yourself`
+      : `a real instructions file sits here — merge it into AGENTS.md and re-run`;
+  }
+  return kind === "dir"
+    ? "a real directory sits here — run `agentlink fix` to fold it into .agents/skills"
+    : "a real file sits here — remove it and re-run";
+}
+
+/**
+ * True when agentlink created a path: the canonical AGENTS.md it links aliases
+ * to, or anything inside <root>/.agents. Only these are safe to replace/delete.
+ */
+function isOwned(paths: ScopePaths, target: string | undefined): boolean {
+  if (!target) return false;
+  if (target === paths.instructions) return true;
+  const owned = `${paths.agentsDir}${path.sep}`;
+  return target === paths.agentsDir || target.startsWith(owned);
+}
+
+/** True when `target` is inside `root` after normalisation. */
+export function isInside(root: string, target: string): boolean {
+  const resolved = path.resolve(root, target);
+  return resolved === root || resolved.startsWith(`${root}${path.sep}`);
+}
+
+interface Inspection {
+  kind: "missing" | "symlink" | "file" | "dir" | "error";
+  resolved?: string;
+  detail?: string;
+}
+
+export function inspect(target: string): Inspection {
+  let stat;
+  try {
+    stat = lstatSync(target);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException)?.code;
+    // Anything other than "does not exist" (ENOTDIR, EACCES, ELOOP, …) is a
+    // real problem the caller must report rather than paper over by writing.
+    if (code === "ENOENT") return { kind: "missing" };
+    return { kind: "error", detail: `${code ?? "unknown error"}` };
+  }
+  if (stat.isSymbolicLink()) {
+    return { kind: "symlink", resolved: path.resolve(path.dirname(target), readlinkSync(target)) };
+  }
+  return { kind: stat.isDirectory() ? "dir" : "file" };
+}
+
+// --- state ------------------------------------------------------------------
+
+export interface State {
+  version: 1;
+  scope: string;
+  harnesses: string[];
+  /** Which created links are listed in .gitignore. */
+  ignore: string;
+  links: { path: string; source: string }[];
+}
+
+export function readState(paths: ScopePaths): State {
+  try {
+    const parsed = JSON.parse(readFileSync(paths.stateFile, "utf8")) as Partial<State>;
+    if (parsed?.version === 1) {
+      return {
+        version: 1,
+        scope: parsed.scope ?? paths.scope,
+        harnesses: parsed.harnesses ?? [],
+        ignore: parsed.ignore ?? "skills",
+        // A hand-edited or hostile state file must not let a later unlink reach
+        // outside the scope root.
+        links: (parsed.links ?? []).filter(
+          (link) => typeof link?.path === "string" && isInside(paths.root, link.path),
+        ),
+      };
+    }
+  } catch {
+    /* first run */
+  }
+  return { version: 1, scope: paths.scope, harnesses: [], ignore: "skills", links: [] };
+}
+
+export function writeState(paths: ScopePaths, state: State): void {
+  mkdirSync(paths.agentsDir, { recursive: true });
+  writeFileAtomic(paths.stateFile, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+/** Write via a temp file and rename, so an interrupted run cannot truncate. */
+export function writeFileAtomic(file: string, contents: string): void {
+  const temporary = `${file}.agentlink-tmp`;
+  writeFileSync(temporary, contents, "utf8");
+  renameSync(temporary, file);
+}
+
+/**
+ * Remove links agentlink owns that the current plan no longer wants: a
+ * deselected harness, or a skill that was renamed or deleted. Without this the
+ * old symlinks stay behind and dangle.
+ */
+export function pruneStale(
+  paths: ScopePaths,
+  plan: Plan,
+  previous: State,
+  options: { dryRun?: boolean } = {},
+): string[] {
+  const wanted = new Set(plan.ops.map((op) => op.rel));
+  const removed: string[] = [];
+
+  for (const link of previous.links) {
+    if (wanted.has(link.path) || !isInside(paths.root, link.path)) continue;
+    const target = path.join(paths.root, link.path);
+    const existing = inspect(target);
+    if (existing.kind !== "symlink" || !isOwned(paths, existing.resolved)) continue;
+    if (!options.dryRun) {
+      unlinkSync(target);
+      pruneEmptyParents(path.dirname(target), paths.root);
+    }
+    removed.push(link.path);
+  }
+  return removed;
+}
+
+export interface MergeOptions {
+  ignore?: string;
+  /** Kept links shrink to this set; pair with pruneStale to delete them. */
+  plannedRels?: string[];
+}
+
+/** Fold this run's results into the previous state. */
+export function mergeState(
+  paths: ScopePaths,
+  previous: State,
+  results: ApplyResult[],
+  harnessIds: string[],
+  options: MergeOptions = {},
+): State {
+  const planned = options.plannedRels ? new Set(options.plannedRels) : undefined;
+  const links = new Map(
+    previous.links.filter((link) => !planned || planned.has(link.path)).map((link) => [link.path, link]),
+  );
+
+  for (const result of results) {
+    if (result.state === "skipped") continue;
+    links.set(result.op.rel, {
+      path: result.op.rel,
+      source: relativeTo(paths.root, result.op.source),
+    });
+  }
+
+  return {
+    version: 1,
+    scope: paths.scope,
+    harnesses: harnessIds,
+    ignore: options.ignore ?? previous.ignore ?? "skills",
+    links: [...links.values()].sort((a, b) => a.path.localeCompare(b.path)),
+  };
+}
+
+export interface UnlinkResult {
+  removed: string[];
+  kept: { path: string; reason: string }[];
+}
+
+/**
+ * Remove the symlinks agentlink created. Anything that is no longer a symlink
+ * pointing into .agents is left alone and reported instead.
+ */
+export function unlink(paths: ScopePaths, options: { dryRun?: boolean } = {}): UnlinkResult {
+  const state = readState(paths);
+  const removed: string[] = [];
+  const kept: { path: string; reason: string }[] = [];
+
+  for (const link of state.links) {
+    if (!isInside(paths.root, link.path)) {
+      kept.push({ path: link.path, reason: "outside this scope" });
+      continue;
+    }
+    const target = path.join(paths.root, link.path);
+    const existing = inspect(target);
+    if (existing.kind === "missing") continue;
+    if (existing.kind !== "symlink") {
+      kept.push({ path: link.path, reason: `no longer a symlink (real ${existing.kind})` });
+      continue;
+    }
+    if (!isOwned(paths, existing.resolved)) {
+      kept.push({ path: link.path, reason: "points outside .agents now" });
+      continue;
+    }
+    if (!options.dryRun) {
+      unlinkSync(target);
+      pruneEmptyParents(path.dirname(target), paths.root);
+    }
+    removed.push(link.path);
+  }
+
+  if (!options.dryRun) writeState(paths, { ...state, links: [] });
+  return { removed, kept };
+}
+
+export function pruneEmptyParents(dir: string, root: string): void {
+  let current = dir;
+  while (current !== root && current.startsWith(`${root}${path.sep}`)) {
+    try {
+      rmdirSync(current);
+    } catch {
+      return;
+    }
+    current = path.dirname(current);
+  }
+}
+
+export { isOwned };

package/src/scope.ts

@@ -0,0 +1,117 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export type Scope = "project" | "global";
+
+/**
+ * Everything agentlink needs to know about *where* it is working.
+ *
+ * The convention has exactly two roots: a repository root (project scope) and
+ * $HOME (global scope). Both hold the same three things:
+ *
+ *   <root>/AGENTS.md              instructions, source of truth
+ *   <root>/.agents/skills/<name>  skills, source of truth
+ *   <root>/.agents/agentlink.json what agentlink has linked
+ */
+export interface ScopePaths {
+  scope: Scope;
+  root: string;
+  agentsDir: string;
+  instructions: string;
+  skills: string;
+  stateFile: string;
+}
+
+export function resolveScope(scope: Scope, cwd: string): ScopePaths {
+  const root = scope === "global" ? homedir() : (findRepoRoot(cwd) ?? cwd);
+  const agentsDir = path.join(root, ".agents");
+  return {
+    scope,
+    root,
+    agentsDir,
+    instructions: path.join(root, "AGENTS.md"),
+    skills: path.join(agentsDir, "skills"),
+    stateFile: path.join(agentsDir, "agentlink.json"),
+  };
+}
+
+/**
+ * Walk up for a `.git` entry (directory, or a file for linked worktrees).
+ * Returns null when no repository root exists above cwd.
+ */
+export function findRepoRoot(cwd: string): string | null {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    if (existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function expandHome(input: string): string {
+  if (input === "~") return homedir();
+  if (input.startsWith("~/")) return path.join(homedir(), input.slice(2));
+  return input;
+}
+
+export function exists(target: string): boolean {
+  try {
+    statSync(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isDirectory(target: string): boolean {
+  try {
+    return statSync(target).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Names of the immediate subdirectories of `dir`, sorted; `[]` when missing. */
+export function listSubdirectories(dir: string): string[] {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const names: string[] = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (entry.isDirectory()) {
+      names.push(entry.name);
+    } else if (entry.isSymbolicLink()) {
+      // A symlink is only a skill if it resolves to a directory. A dangling or
+      // file-valued link would otherwise become a broken link in every harness.
+      try {
+        if (statSync(path.join(dir, entry.name)).isDirectory()) names.push(entry.name);
+      } catch {
+        /* broken symlink: reported by doctor, never linked */
+      }
+    }
+  }
+  return names.sort();
+}
+
+/** Names of dot-directories, which the convention reserves and skips. */
+export function listHiddenSubdirectories(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.name.startsWith(".") && (entry.isDirectory() || entry.isSymbolicLink()))
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+export function relativeTo(fromDir: string, target: string): string {
+  const rel = path.relative(fromDir, target);
+  return rel === "" ? "." : rel;
+}