@borasta/agentlink 1.0.0

package/README.md

@@ -0,0 +1,250 @@
+# agentlink
+
+Manage symlinks from a single `.ai` folder to multiple agentic IDE configurations. Write your AI instructions once, link them everywhere.
+
+## Why
+
+Every agentic IDE (Claude Code, Cursor, Codex, OpenCode, Windsurf, ...) expects its configuration in a different location. `agentlink` lets you keep a **single source of truth** in `.ai/` and automatically creates granular symlinks to each IDE's expected paths.
+
+- **Granular linking** -- each file (skill, agent, command, root doc) is linked individually, not as a bulk folder copy.
+- **Incremental sync** -- file hashes are tracked so re-running the command is a no-op when nothing changed. Safe for git hooks (e.g. husky).
+- **Stale link cleanup** -- renamed or deleted sources automatically remove their old symlinks on the next sync.
+- **Extensible** -- built-in adapters for the major IDEs, plus support for custom targets via the programmatic API.
+
+## Install
+
+```bash
+# Global install (recommended)
+npm install -g agentlink
+
+# Or run without installing
+npx agentlink <command>
+```
+
+After installing globally, both `agentlink` and `ag` are available as CLI commands.
+
+## Quick Start
+
+```bash
+# 1. Initialize the .ai directory
+ag init
+
+# 2. Add your content to .ai/
+#    (see "Recommended .ai structure" below)
+
+# 3. Sync to your IDE
+ag claude          # creates symlinks for Claude Code
+ag cursor          # creates symlinks for Cursor
+ag codex           # creates symlinks for Codex
+
+# 4. Check health
+ag doctor
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ag init` | Create the `.ai` source directory with the recommended structure |
+| `ag <target>` | Full sync: detect changes, clean stale links, create new ones |
+| `ag sync <target>` | Same as `ag <target>` (explicit form) |
+| `ag unlink <target>` | Remove all managed symlinks for a target |
+| `ag doctor` | Validate all managed symlinks (healthy, broken, missing) |
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-s, --source <path>` | Use a custom source folder instead of `.ai` |
+| `-f, --force` | Force sync even if no changes detected (sync only) |
+
+### Available Targets
+
+Each adapter only links the categories that the IDE actually supports, based on official documentation.
+
+| Target | IDE | Root doc | Skills | Agents | Commands |
+|--------|-----|----------|--------|--------|----------|
+| `claude` | Claude Code | `CLAUDE.md` | `.claude/skills/` | `.claude/agents/` | `.claude/commands/` |
+| `cursor` | Cursor | `.cursor/rules/AGENTS.md` | `.cursor/skills/` | -- | -- |
+| `codex` | Codex CLI | `AGENTS.md` | -- | -- | -- |
+| `opencode` | OpenCode | `AGENTS.md` | `.opencode/skills/` | `.opencode/agents/` | `.opencode/commands/` |
+| `windsurf` | Windsurf | `.windsurf/rules/AGENTS.md` | -- | -- | -- |
+
+Sources: [Claude Code docs](https://docs.claude.com/en/docs/claude-code/plugins), [Cursor docs](https://cursor.com/docs/context/rules), [Codex docs](https://developers.openai.com/codex/guides/agents-md/), [OpenCode docs](https://open-code.ai/docs/en/config), [Windsurf docs](https://windsurf.com/editor/directory).
+
+## Recommended `.ai` Structure
+
+```
+.ai/
+├── AGENTS.md                      # Main agent instructions (root doc)
+├── skills/                        # Reusable skill definitions
+│   ├── coding-standards/          # Each skill is a directory
+│   │   ├── SKILL.md               #   with SKILL.md as entrypoint
+│   │   └── examples/              #   and optional supporting files
+│   │       └── sample.md
+│   ├── testing/
+│   │   └── SKILL.md
+│   └── frontend-react/
+│       ├── SKILL.md
+│       └── reference.md
+├── agents/                        # Custom agent definitions
+│   ├── code-reviewer.md
+│   └── researcher.md
+├── commands/                      # Custom slash commands
+│   ├── deploy.md
+│   └── test-suite.md
+└── .agentlink-state.json          # Auto-generated sync state (do not edit)
+```
+
+### What goes where
+
+| Folder | Purpose | Example content |
+|--------|---------|-----------------|
+| `AGENTS.md` | Main instructions for all AI agents | Project description, coding standards, architecture overview |
+| `skills/` | Reusable knowledge/skills that agents can reference | Each skill is a directory with a `SKILL.md` entrypoint and optional supporting files |
+| `agents/` | Definitions for specialized agents | Code reviewer instructions, research agent prompts (YAML frontmatter + markdown) |
+| `commands/` | Custom slash commands the agent can execute | Deployment scripts, test runners, migration helpers |
+
+Nested folders within any category are fully supported. For example, `.ai/skills/coding-standards/SKILL.md` will be linked to `.claude/skills/coding-standards/SKILL.md` (for the Claude target).
+
+> **Note:** Not every IDE supports every category. For example, Codex and Windsurf only use the root doc (`AGENTS.md`). When you sync to a target that doesn't support a category, those files are simply not linked -- no error, no noise.
+
+## How Linking Works
+
+When you run `ag claude`, `agentlink`:
+
+1. **Scans** `.ai/` to discover all files (root docs, skills, agents, commands).
+2. **Computes** the expected symlink mapping using the Claude adapter.
+3. **Checks** if anything changed since the last sync (via SHA-256 hashes stored in `.agentlink-state.json`).
+4. **Removes** stale symlinks from previous syncs that no longer have a source file.
+5. **Creates** new symlinks using relative paths.
+
+### Example: Claude Code mapping
+
+```
+.ai/AGENTS.md                            →  CLAUDE.md
+.ai/skills/coding-standards/SKILL.md     →  .claude/skills/coding-standards/SKILL.md
+.ai/skills/coding-standards/examples/    →  .claude/skills/coding-standards/examples/
+.ai/agents/reviewer.md                   →  .claude/agents/reviewer.md
+.ai/commands/deploy.md                   →  .claude/commands/deploy.md
+```
+
+### Example: Cursor mapping
+
+```
+.ai/AGENTS.md                            →  .cursor/rules/AGENTS.md
+.ai/skills/coding-standards/SKILL.md     →  .cursor/skills/coding-standards/SKILL.md
+```
+
+(Cursor does not support agents or commands, so those are skipped.)
+
+### Example: Codex mapping
+
+```
+.ai/AGENTS.md                →  AGENTS.md
+```
+
+(Codex reads `AGENTS.md` at the project root. Skills, agents, and commands are not supported.)
+
+## Custom Source Folder
+
+If you prefer a different folder name instead of `.ai`:
+
+```bash
+ag init --source .my-ai
+ag claude --source .my-ai
+ag doctor --source .my-ai
+```
+
+## Using with Git Hooks
+
+Since `agentlink` is incremental (no-op when nothing changed), it is safe to run on every commit:
+
+```json
+{
+  "husky": {
+    "hooks": {
+      "pre-commit": "ag claude && ag cursor"
+    }
+  }
+}
+```
+
+## Programmatic API
+
+`agentlink` is also usable as a library:
+
+```typescript
+import {
+  AdapterRegistry,
+  syncCommand,
+  nodeFs,
+} from 'agentlink';
+
+const registry = new AdapterRegistry();
+
+// Register a custom adapter
+registry.register({
+  id: 'my-ide',
+  name: 'My IDE',
+  description: 'Custom IDE adapter',
+  rootDocs: [{ source: 'AGENTS.md', target: '.myide/instructions.md' }],
+  skills: { dir: '.myide/skills' },
+});
+
+const result = await syncCommand(
+  'my-ide',
+  { source: '.ai' },
+  process.cwd(),
+  nodeFs,
+  registry,
+);
+
+console.log(result);
+// { skipped: false, created: 3, removed: 0, unchanged: 0, errors: [] }
+```
+
+## Troubleshooting
+
+### Symlink permission errors on Windows
+
+Windows requires developer mode or elevated permissions to create symlinks. Enable developer mode in Settings > Update & Security > For developers.
+
+### Target exists and is not a symlink
+
+If a target file already exists as a regular file (not a symlink), `agentlink` will skip it and report an error. Remove or rename the file manually, then re-run.
+
+### Stale symlinks after renaming
+
+`agentlink` automatically cleans up stale symlinks when you rename or delete source files. Just run `ag <target>` again -- the old symlink will be removed and the new one created.
+
+### Category not linked for my IDE
+
+Each adapter only links the categories that the IDE officially supports. If you run `ag codex` and your `.ai/skills/` folder isn't linked, that's expected -- Codex only reads `AGENTS.md`. Check the [target table](#available-targets) to see what each IDE supports.
+
+## Development
+
+```bash
+git clone <repo-url>
+cd agentlink
+npm install
+
+# Run unit tests
+npm test
+
+# Run e2e tests
+npm run test:e2e
+
+# Run all tests
+npm run test:all
+
+# Build
+npm run build
+
+# Type check
+npm run lint
+```
+
+## License
+
+MIT

package/bin/ag.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/chunk-IYLBLNXA.js

@@ -0,0 +1,533 @@
+// src/core/fs.ts
+import * as fs from "fs/promises";
+import * as nodePath from "path";
+var nodeFs = {
+  readFile: (p) => fs.readFile(p, "utf-8"),
+  writeFile: async (p, c) => {
+    await fs.mkdir(nodePath.dirname(p), { recursive: true });
+    await fs.writeFile(p, c, "utf-8");
+  },
+  readdir: (p) => fs.readdir(p),
+  lstat: (p) => fs.lstat(p),
+  symlink: (t, p) => fs.symlink(t, p),
+  readlink: (p) => fs.readlink(p),
+  unlink: (p) => fs.unlink(p),
+  mkdir: (p) => fs.mkdir(p, { recursive: true }).then(() => {
+  }),
+  exists: async (p) => {
+    try {
+      await fs.lstat(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/adapters/builtins/claude.ts
+var claudeAdapter = {
+  id: "claude",
+  name: "Claude Code",
+  description: "Anthropic Claude Code CLI",
+  rootDocs: [{ source: "AGENTS.md", target: "CLAUDE.md" }],
+  skills: { dir: ".claude/skills" },
+  agents: { dir: ".claude/agents" },
+  commands: { dir: ".claude/commands" }
+};
+
+// src/adapters/builtins/cursor.ts
+var cursorAdapter = {
+  id: "cursor",
+  name: "Cursor",
+  description: "Cursor AI IDE",
+  rootDocs: [{ source: "AGENTS.md", target: ".cursor/rules/AGENTS.md" }],
+  skills: { dir: ".cursor/skills" }
+};
+
+// src/adapters/builtins/codex.ts
+var codexAdapter = {
+  id: "codex",
+  name: "Codex",
+  description: "OpenAI Codex CLI",
+  rootDocs: [{ source: "AGENTS.md", target: "AGENTS.md" }]
+};
+
+// src/adapters/builtins/opencode.ts
+var opencodeAdapter = {
+  id: "opencode",
+  name: "OpenCode",
+  description: "OpenCode AI editor",
+  rootDocs: [{ source: "AGENTS.md", target: "AGENTS.md" }],
+  skills: { dir: ".opencode/skills" },
+  agents: { dir: ".opencode/agents" },
+  commands: { dir: ".opencode/commands" }
+};
+
+// src/adapters/builtins/windsurf.ts
+var windsurfAdapter = {
+  id: "windsurf",
+  name: "Windsurf",
+  description: "Codeium Windsurf IDE",
+  rootDocs: [{ source: "AGENTS.md", target: ".windsurf/rules/AGENTS.md" }]
+};
+
+// src/adapters/builtins/index.ts
+var builtinAdapters = [
+  claudeAdapter,
+  cursorAdapter,
+  codexAdapter,
+  opencodeAdapter,
+  windsurfAdapter
+];
+
+// src/adapters/registry.ts
+var AdapterRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  constructor() {
+    for (const adapter of builtinAdapters) {
+      this.register(adapter);
+    }
+  }
+  register(adapter) {
+    this.adapters.set(adapter.id, adapter);
+  }
+  get(id) {
+    return this.adapters.get(id);
+  }
+  has(id) {
+    return this.adapters.has(id);
+  }
+  list() {
+    return Array.from(this.adapters.values());
+  }
+  ids() {
+    return Array.from(this.adapters.keys());
+  }
+};
+
+// src/core/scaffold.ts
+import * as path from "path";
+var DEFAULT_AGENTS_MD = `# Project Agents
+
+Define your AI agent instructions here.
+`;
+var CATEGORIES = ["skills", "agents", "commands"];
+async function scaffoldSourceDir(fs2, sourceDir) {
+  const created = [];
+  if (!await fs2.exists(sourceDir)) {
+    await fs2.mkdir(sourceDir);
+    created.push(sourceDir);
+  }
+  const agentsPath = path.join(sourceDir, "AGENTS.md");
+  if (!await fs2.exists(agentsPath)) {
+    await fs2.writeFile(agentsPath, DEFAULT_AGENTS_MD);
+    created.push(agentsPath);
+  }
+  for (const cat of CATEGORIES) {
+    const catDir = path.join(sourceDir, cat);
+    if (!await fs2.exists(catDir)) {
+      await fs2.mkdir(catDir);
+      created.push(catDir);
+    }
+  }
+  return { created };
+}
+
+// src/commands/init.ts
+import * as path2 from "path";
+async function initCommand(options, projectRoot, fs2) {
+  const sourceDir = path2.resolve(projectRoot, options.source);
+  const result = await scaffoldSourceDir(fs2, sourceDir);
+  if (result.created.length === 0) {
+    console.log(`Source directory already initialized: ${options.source}`);
+  } else {
+    console.log(`Initialized ${options.source} with:`);
+    for (const item of result.created) {
+      console.log(`  + ${path2.relative(projectRoot, item)}`);
+    }
+  }
+  return result;
+}
+
+// src/core/scanner.ts
+import * as path3 from "path";
+async function listFilesRecursive(fs2, dirPath, prefix = "") {
+  if (!await fs2.exists(dirPath)) return [];
+  const entries = await fs2.readdir(dirPath);
+  const files = [];
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue;
+    const fullPath = path3.join(dirPath, entry);
+    const relativePath = prefix ? path3.join(prefix, entry) : entry;
+    const stat = await fs2.lstat(fullPath);
+    if (stat.isFile()) {
+      files.push(relativePath);
+    } else if (stat.isDirectory()) {
+      const nested = await listFilesRecursive(fs2, fullPath, relativePath);
+      files.push(...nested);
+    }
+  }
+  return files.sort();
+}
+async function scanSourceDir(fs2, sourceDir) {
+  if (!await fs2.exists(sourceDir)) {
+    throw new Error(`Source directory not found: ${sourceDir}`);
+  }
+  const rootEntries = await fs2.readdir(sourceDir);
+  const rootDocs = [];
+  for (const entry of rootEntries) {
+    if (entry.startsWith(".")) continue;
+    const fullPath = path3.join(sourceDir, entry);
+    const stat = await fs2.lstat(fullPath);
+    if (stat.isFile()) {
+      rootDocs.push(entry);
+    }
+  }
+  return {
+    rootDocs: rootDocs.sort(),
+    skills: await listFilesRecursive(fs2, path3.join(sourceDir, "skills")),
+    agents: await listFilesRecursive(fs2, path3.join(sourceDir, "agents")),
+    commands: await listFilesRecursive(fs2, path3.join(sourceDir, "commands"))
+  };
+}
+
+// src/core/mapper.ts
+import * as path4 from "path";
+var CATEGORY_KEYS = ["skills", "agents", "commands"];
+function computeMappings(projectRoot, sourceDir, items, adapter) {
+  const mappings = [];
+  for (const docMap of adapter.rootDocs) {
+    if (items.rootDocs.includes(docMap.source)) {
+      mappings.push({
+        source: path4.resolve(sourceDir, docMap.source),
+        target: path4.resolve(projectRoot, docMap.target),
+        category: "rootDocs"
+      });
+    }
+  }
+  for (const key of CATEGORY_KEYS) {
+    const catTarget = adapter[key];
+    if (!catTarget) continue;
+    const files = items[key];
+    for (const file of files) {
+      const targetName = catTarget.transform?.(file) ?? file;
+      mappings.push({
+        source: path4.resolve(sourceDir, key, file),
+        target: path4.resolve(projectRoot, catTarget.dir, targetName),
+        category: key
+      });
+    }
+  }
+  return mappings;
+}
+
+// src/core/linker.ts
+import * as path5 from "path";
+async function createSymlinks(fs2, mappings) {
+  const created = [];
+  const errors = [];
+  for (const mapping of mappings) {
+    try {
+      const targetDir = path5.dirname(mapping.target);
+      await fs2.mkdir(targetDir);
+      if (await fs2.exists(mapping.target)) {
+        const stat = await fs2.lstat(mapping.target);
+        if (stat.isSymbolicLink()) {
+          const existingTarget = await fs2.readlink(mapping.target);
+          const resolved = path5.resolve(
+            path5.dirname(mapping.target),
+            existingTarget
+          );
+          if (resolved === mapping.source) {
+            continue;
+          }
+          await fs2.unlink(mapping.target);
+        } else {
+          errors.push({
+            path: mapping.target,
+            message: "Target exists and is not a symlink, skipping"
+          });
+          continue;
+        }
+      }
+      const relSource = path5.relative(targetDir, mapping.source);
+      await fs2.symlink(relSource, mapping.target);
+      created.push(mapping.target);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push({ path: mapping.target, message });
+    }
+  }
+  return { created, errors };
+}
+async function removeSymlinks(fs2, targets) {
+  const removed = [];
+  const errors = [];
+  for (const target of targets) {
+    try {
+      if (!await fs2.exists(target)) continue;
+      const stat = await fs2.lstat(target);
+      if (stat.isSymbolicLink()) {
+        await fs2.unlink(target);
+        removed.push(target);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push({ path: target, message });
+    }
+  }
+  return { removed, errors };
+}
+
+// src/core/reconciler.ts
+import * as path6 from "path";
+async function reconcileStaleLinks(fs2, projectRoot, previousMappings, currentMappings) {
+  const currentTargets = new Set(
+    currentMappings.map((m) => path6.relative(projectRoot, m.target))
+  );
+  const removed = [];
+  for (const prev of previousMappings) {
+    if (!currentTargets.has(prev.target)) {
+      const absTarget = path6.resolve(projectRoot, prev.target);
+      try {
+        if (await fs2.exists(absTarget)) {
+          const stat = await fs2.lstat(absTarget);
+          if (stat.isSymbolicLink()) {
+            await fs2.unlink(absTarget);
+            removed.push(prev.target);
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  return { removed };
+}
+
+// src/core/state.ts
+import * as crypto from "crypto";
+import * as path7 from "path";
+var STATE_VERSION = 1;
+async function loadState(fs2, statePath) {
+  if (!await fs2.exists(statePath)) {
+    return { version: STATE_VERSION, targets: {} };
+  }
+  try {
+    const content = await fs2.readFile(statePath);
+    return JSON.parse(content);
+  } catch {
+    return { version: STATE_VERSION, targets: {} };
+  }
+}
+async function saveState(fs2, statePath, state) {
+  await fs2.writeFile(statePath, JSON.stringify(state, null, 2));
+}
+async function hashFile(fs2, filePath) {
+  const content = await fs2.readFile(filePath);
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+async function computeStoredMappings(fs2, projectRoot, mappings) {
+  const stored = [];
+  for (const m of mappings) {
+    const hash = await hashFile(fs2, m.source);
+    stored.push({
+      source: path7.relative(projectRoot, m.source),
+      target: path7.relative(projectRoot, m.target),
+      sourceHash: hash
+    });
+  }
+  return stored;
+}
+function hasChanges(previous, current) {
+  if (previous.length !== current.length) return true;
+  const prevMap = /* @__PURE__ */ new Map();
+  for (const m of previous) {
+    prevMap.set(`${m.source}::${m.target}`, m.sourceHash);
+  }
+  for (const m of current) {
+    const key = `${m.source}::${m.target}`;
+    if (prevMap.get(key) !== m.sourceHash) return true;
+  }
+  return false;
+}
+
+// src/commands/sync.ts
+import * as path8 from "path";
+async function syncCommand(target, options, projectRoot, fs2, registry) {
+  const adapter = registry.get(target);
+  if (!adapter) {
+    const available = registry.ids().join(", ");
+    throw new Error(`Unknown target "${target}". Available: ${available}`);
+  }
+  const sourceDir = path8.resolve(projectRoot, options.source);
+  const statePath = path8.join(sourceDir, ".agentlink-state.json");
+  const items = await scanSourceDir(fs2, sourceDir);
+  const mappings = computeMappings(projectRoot, sourceDir, items, adapter);
+  const state = await loadState(fs2, statePath);
+  const prevTarget = state.targets[target];
+  const currentStored = await computeStoredMappings(
+    fs2,
+    projectRoot,
+    mappings
+  );
+  if (!options.force && prevTarget && !hasChanges(prevTarget.mappings, currentStored)) {
+    return {
+      skipped: true,
+      created: 0,
+      removed: 0,
+      unchanged: mappings.length,
+      errors: []
+    };
+  }
+  const { removed } = await reconcileStaleLinks(
+    fs2,
+    projectRoot,
+    prevTarget?.mappings ?? [],
+    mappings
+  );
+  const linkResult = await createSymlinks(fs2, mappings);
+  state.targets[target] = {
+    lastSync: (/* @__PURE__ */ new Date()).toISOString(),
+    mappings: currentStored
+  };
+  await saveState(fs2, statePath, state);
+  return {
+    skipped: false,
+    created: linkResult.created.length,
+    removed: removed.length,
+    unchanged: mappings.length - linkResult.created.length,
+    errors: linkResult.errors
+  };
+}
+
+// src/commands/unlink.ts
+import * as path9 from "path";
+async function unlinkCommand(target, options, projectRoot, fs2, registry) {
+  if (!registry.has(target)) {
+    const available = registry.ids().join(", ");
+    throw new Error(`Unknown target "${target}". Available: ${available}`);
+  }
+  const sourceDir = path9.resolve(projectRoot, options.source);
+  const statePath = path9.join(sourceDir, ".agentlink-state.json");
+  const state = await loadState(fs2, statePath);
+  const targetState = state.targets[target];
+  if (!targetState || targetState.mappings.length === 0) {
+    console.log(`No managed symlinks found for "${target}".`);
+    return { removed: 0, errors: 0 };
+  }
+  const absPaths = targetState.mappings.map(
+    (m) => path9.resolve(projectRoot, m.target)
+  );
+  const { removed, errors } = await removeSymlinks(fs2, absPaths);
+  delete state.targets[target];
+  await saveState(fs2, statePath, state);
+  console.log(`Removed ${removed.length} symlink(s) for "${target}".`);
+  if (errors.length > 0) {
+    for (const e of errors) {
+      console.error(`  Error: ${e.path} - ${e.message}`);
+    }
+  }
+  return { removed: removed.length, errors: errors.length };
+}
+
+// src/commands/doctor.ts
+import * as path10 from "path";
+async function doctorCommand(options, projectRoot, fs2, _registry) {
+  const sourceDir = path10.resolve(projectRoot, options.source);
+  const statePath = path10.join(sourceDir, ".agentlink-state.json");
+  const report = {
+    sourceExists: await fs2.exists(sourceDir),
+    stateExists: await fs2.exists(statePath),
+    targets: {}
+  };
+  if (!report.sourceExists) {
+    console.log(`Source directory not found: ${options.source}`);
+    console.log('Run "ag init" to create it.');
+    return report;
+  }
+  if (!report.stateExists) {
+    console.log('No sync state found. Run "ag <target>" to create symlinks.');
+    return report;
+  }
+  const state = await loadState(fs2, statePath);
+  for (const [targetId, targetState] of Object.entries(state.targets)) {
+    const targetReport = {
+      total: targetState.mappings.length,
+      healthy: 0,
+      broken: 0,
+      missing: 0,
+      issues: []
+    };
+    for (const mapping of targetState.mappings) {
+      const absTarget = path10.resolve(projectRoot, mapping.target);
+      const absSource = path10.resolve(projectRoot, mapping.source);
+      if (!await fs2.exists(absTarget)) {
+        targetReport.missing++;
+        targetReport.issues.push(`Missing symlink: ${mapping.target}`);
+        continue;
+      }
+      try {
+        const stat = await fs2.lstat(absTarget);
+        if (!stat.isSymbolicLink()) {
+          targetReport.broken++;
+          targetReport.issues.push(`Not a symlink: ${mapping.target}`);
+          continue;
+        }
+        const linkTarget = await fs2.readlink(absTarget);
+        const resolved = path10.resolve(
+          path10.dirname(absTarget),
+          linkTarget
+        );
+        if (resolved !== absSource) {
+          targetReport.broken++;
+          targetReport.issues.push(
+            `Wrong target: ${mapping.target} -> ${linkTarget} (expected source: ${mapping.source})`
+          );
+          continue;
+        }
+        if (!await fs2.exists(absSource)) {
+          targetReport.broken++;
+          targetReport.issues.push(
+            `Dangling symlink: ${mapping.target} (source missing: ${mapping.source})`
+          );
+          continue;
+        }
+        targetReport.healthy++;
+      } catch {
+        targetReport.broken++;
+        targetReport.issues.push(`Error checking: ${mapping.target}`);
+      }
+    }
+    report.targets[targetId] = targetReport;
+  }
+  for (const [targetId, tr] of Object.entries(report.targets)) {
+    console.log(`
+[${targetId}] ${tr.healthy}/${tr.total} healthy`);
+    if (tr.missing > 0) console.log(`  ${tr.missing} missing`);
+    if (tr.broken > 0) console.log(`  ${tr.broken} broken`);
+    for (const issue of tr.issues) {
+      console.log(`  - ${issue}`);
+    }
+  }
+  return report;
+}
+
+export {
+  nodeFs,
+  builtinAdapters,
+  AdapterRegistry,
+  scaffoldSourceDir,
+  initCommand,
+  scanSourceDir,
+  computeMappings,
+  createSymlinks,
+  removeSymlinks,
+  reconcileStaleLinks,
+  loadState,
+  saveState,
+  computeStoredMappings,
+  hasChanges,
+  syncCommand,
+  unlinkCommand,
+  doctorCommand
+};

package/dist/cli.js

@@ -0,0 +1,78 @@
+import {
+  AdapterRegistry,
+  doctorCommand,
+  initCommand,
+  nodeFs,
+  syncCommand,
+  unlinkCommand
+} from "./chunk-IYLBLNXA.js";
+
+// src/cli.ts
+import { Command } from "commander";
+var KNOWN_COMMANDS = ["init", "sync", "unlink", "doctor", "help"];
+var firstArg = process.argv[2];
+if (firstArg && !firstArg.startsWith("-") && !KNOWN_COMMANDS.includes(firstArg)) {
+  process.argv.splice(2, 0, "sync");
+}
+var registry = new AdapterRegistry();
+var projectRoot = process.cwd();
+var program = new Command();
+program.name("ag").description(
+  `Manage symlinks from .ai to agentic IDE configurations.
+
+Available targets: ${registry.ids().join(", ")}`
+).version("0.1.0");
+program.command("init").description("Initialize the source directory structure").option("-s, --source <path>", "Source directory name", ".ai").action(async (opts) => {
+  try {
+    await initCommand(opts, projectRoot, nodeFs);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+program.command("sync <target>").description(
+  "Sync symlinks for a target IDE (detect changes, clean stale, relink)"
+).option("-s, --source <path>", "Source directory name", ".ai").option("-f, --force", "Force sync even if no changes detected").action(async (target, opts) => {
+  try {
+    const result = await syncCommand(
+      target,
+      opts,
+      projectRoot,
+      nodeFs,
+      registry
+    );
+    if (result.skipped) {
+      console.log("Already up to date.");
+    } else {
+      console.log(
+        `Sync complete: ${result.created} created, ${result.removed} removed, ${result.unchanged} unchanged.`
+      );
+      if (result.errors.length > 0) {
+        for (const e of result.errors) {
+          console.error(`  Error: ${e.path} - ${e.message}`);
+        }
+        process.exitCode = 1;
+      }
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+program.command("unlink <target>").description("Remove all managed symlinks for a target IDE").option("-s, --source <path>", "Source directory name", ".ai").action(async (target, opts) => {
+  try {
+    await unlinkCommand(target, opts, projectRoot, nodeFs, registry);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+program.command("doctor").description("Check health of managed symlinks").option("-s, --source <path>", "Source directory name", ".ai").action(async (opts) => {
+  try {
+    await doctorCommand(opts, projectRoot, nodeFs, registry);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+interface RootDocMapping {
+    source: string;
+    target: string;
+}
+interface CategoryTarget {
+    dir: string;
+    transform?: (filename: string) => string;
+}
+interface IdeAdapter {
+    id: string;
+    name: string;
+    description: string;
+    rootDocs: RootDocMapping[];
+    skills?: CategoryTarget;
+    agents?: CategoryTarget;
+    commands?: CategoryTarget;
+}
+
+interface LinkMapping {
+    source: string;
+    target: string;
+    category: string;
+}
+interface SourceItems {
+    rootDocs: string[];
+    skills: string[];
+    agents: string[];
+    commands: string[];
+}
+interface StoredMapping {
+    source: string;
+    target: string;
+    sourceHash: string;
+}
+interface TargetState {
+    lastSync: string;
+    mappings: StoredMapping[];
+}
+interface SyncState {
+    version: number;
+    targets: Record<string, TargetState>;
+}
+interface SyncResult {
+    skipped: boolean;
+    created: number;
+    removed: number;
+    unchanged: number;
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+
+interface FsStats {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+interface FileSystem {
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    readdir(dirPath: string): Promise<string[]>;
+    lstat(filePath: string): Promise<FsStats>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    readlink(linkPath: string): Promise<string>;
+    unlink(filePath: string): Promise<void>;
+    mkdir(dirPath: string): Promise<void>;
+    exists(filePath: string): Promise<boolean>;
+}
+declare const nodeFs: FileSystem;
+
+declare class AdapterRegistry {
+    private adapters;
+    constructor();
+    register(adapter: IdeAdapter): void;
+    get(id: string): IdeAdapter | undefined;
+    has(id: string): boolean;
+    list(): IdeAdapter[];
+    ids(): string[];
+}
+
+declare const builtinAdapters: IdeAdapter[];
+
+declare function scanSourceDir(fs: FileSystem, sourceDir: string): Promise<SourceItems>;
+
+declare function computeMappings(projectRoot: string, sourceDir: string, items: SourceItems, adapter: IdeAdapter): LinkMapping[];
+
+interface LinkResult {
+    created: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+declare function createSymlinks(fs: FileSystem, mappings: LinkMapping[]): Promise<LinkResult>;
+declare function removeSymlinks(fs: FileSystem, targets: string[]): Promise<{
+    removed: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+}>;
+
+declare function reconcileStaleLinks(fs: FileSystem, projectRoot: string, previousMappings: StoredMapping[], currentMappings: LinkMapping[]): Promise<{
+    removed: string[];
+}>;
+
+declare function loadState(fs: FileSystem, statePath: string): Promise<SyncState>;
+declare function saveState(fs: FileSystem, statePath: string, state: SyncState): Promise<void>;
+declare function computeStoredMappings(fs: FileSystem, projectRoot: string, mappings: LinkMapping[]): Promise<StoredMapping[]>;
+declare function hasChanges(previous: StoredMapping[], current: StoredMapping[]): boolean;
+
+declare function scaffoldSourceDir(fs: FileSystem, sourceDir: string): Promise<{
+    created: string[];
+}>;
+
+interface SyncOptions {
+    source: string;
+    force?: boolean;
+}
+declare function syncCommand(target: string, options: SyncOptions, projectRoot: string, fs: FileSystem, registry: AdapterRegistry): Promise<SyncResult>;
+
+interface InitOptions {
+    source: string;
+}
+declare function initCommand(options: InitOptions, projectRoot: string, fs: FileSystem): Promise<{
+    created: string[];
+}>;
+
+interface UnlinkOptions {
+    source: string;
+}
+declare function unlinkCommand(target: string, options: UnlinkOptions, projectRoot: string, fs: FileSystem, registry: AdapterRegistry): Promise<{
+    removed: number;
+    errors: number;
+}>;
+
+interface DoctorOptions {
+    source: string;
+}
+interface TargetReport {
+    total: number;
+    healthy: number;
+    broken: number;
+    missing: number;
+    issues: string[];
+}
+interface DoctorReport {
+    sourceExists: boolean;
+    stateExists: boolean;
+    targets: Record<string, TargetReport>;
+}
+declare function doctorCommand(options: DoctorOptions, projectRoot: string, fs: FileSystem, _registry: AdapterRegistry): Promise<DoctorReport>;
+
+export { AdapterRegistry, type CategoryTarget, type FileSystem, type FsStats, type IdeAdapter, type LinkMapping, type RootDocMapping, type SourceItems, type StoredMapping, type SyncResult, type SyncState, type TargetState, builtinAdapters, computeMappings, computeStoredMappings, createSymlinks, doctorCommand, hasChanges, initCommand, loadState, nodeFs, reconcileStaleLinks, removeSymlinks, saveState, scaffoldSourceDir, scanSourceDir, syncCommand, unlinkCommand };

package/dist/index.js

@@ -0,0 +1,38 @@
+import {
+  AdapterRegistry,
+  builtinAdapters,
+  computeMappings,
+  computeStoredMappings,
+  createSymlinks,
+  doctorCommand,
+  hasChanges,
+  initCommand,
+  loadState,
+  nodeFs,
+  reconcileStaleLinks,
+  removeSymlinks,
+  saveState,
+  scaffoldSourceDir,
+  scanSourceDir,
+  syncCommand,
+  unlinkCommand
+} from "./chunk-IYLBLNXA.js";
+export {
+  AdapterRegistry,
+  builtinAdapters,
+  computeMappings,
+  computeStoredMappings,
+  createSymlinks,
+  doctorCommand,
+  hasChanges,
+  initCommand,
+  loadState,
+  nodeFs,
+  reconcileStaleLinks,
+  removeSymlinks,
+  saveState,
+  scaffoldSourceDir,
+  scanSourceDir,
+  syncCommand,
+  unlinkCommand
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@borasta/agentlink",
+  "version": "1.0.0",
+  "description": "Manage symlinks from a canonical .ai folder to multiple agentic IDE configurations",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "agentlink": "./bin/ag.js",
+    "ag": "./bin/ag.js"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "NODE_OPTIONS='--experimental-vm-modules --no-warnings' jest --config jest.config.ts",
+    "test:watch": "NODE_OPTIONS='--experimental-vm-modules --no-warnings' jest --config jest.config.ts --watch",
+    "test:e2e": "NODE_OPTIONS='--experimental-vm-modules --no-warnings' jest --config jest.e2e.config.ts",
+    "test:all": "npm run test && npm run test:e2e",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "symlink",
+    "ide",
+    "cursor",
+    "claude",
+    "codex",
+    "windsurf",
+    "opencode",
+    "agentlink"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  }
+}