link-agents 0.9.0

package/AGENTS.md

@@ -0,0 +1,127 @@
+# AGENTS.md — link-agents
+
+Guidance for autonomous coding agents contributing to the `link-agents` package.
+
+## TL;DR
+
+- Prefer TypeScript (NodeNext modules).
+- Run `npm install` then `npm run build` before shipping changes.
+- Run `npm test` to verify all tests pass.
+- Default CLI mode is interactive; keep UX non-destructive.
+
+> Note: the public CLI now centers on `sync`, `doctor`, and `restore` subcommands. Older mode/flag descriptions below are legacy until the rest of this document is refreshed.
+
+## Project Overview
+
+- **Purpose:** synchronize agent artifacts (AGENTS, commands, prompts, rules, skills, MCP configs) across Codex, Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Roo Code, Gemini CLI, OpenCode, VS Code, Antigravity, Goose, and the current project.
+- **Entry point:** `src/index.ts` (CLI executable exported via `bin.link-agents`).
+
+## Key Modules
+
+### CLI Layer
+
+- `src/cli/options.ts` — argument parsing (commander)
+- `src/cli/interactive-v2.ts` — interactive TUI flow using @clack/prompts
+
+### Core Utils
+
+- `src/utils/discovery.ts` — asset discovery via globbing
+- `src/utils/plan.ts` — merge/source planning logic
+- `src/utils/apply.ts` — file writes with backup, verification, skip-unchanged
+- `src/utils/fs.ts` — filesystem utilities (read, write, symlink, backup, hash)
+- `src/utils/mcp.ts` — MCP config parsing, merging, validation, secret obfuscation
+- `src/utils/similarity.ts` — content similarity calculation for conflict resolution
+- `src/utils/paths.ts` — path normalization and canonical path resolution
+- `src/utils/validation.ts` — asset validation utilities
+- `src/utils/cursorHistory.ts` — Cursor UI "Rules & Config" export helper
+
+### Client Definitions
+
+- `src/clients/definitions.ts` — client root paths and asset type mappings
+
+### Types
+
+- `src/types/index.ts` — shared TypeScript types
+
+## Interactive Flow
+
+The interactive mode (`npm run dev`) follows this sequence:
+
+1. Select scope (global/project)
+2. Select direction (push/pull/sync)
+3. Scan all clients for assets
+4. Detect & resolve conflicts (shows similarity %, modification time)
+5. Select target clients (shows diff counts: +new, ~update)
+6. Build sync plan
+7. Review MCP servers (shows env vars with secrets obfuscated, diffs between clients)
+8. Validate MCP configs (check commands exist, warn about removals)
+9. Show planned changes
+10. Confirm apply
+11. Ask about symlinks vs copying
+12. Apply with backup, skip-unchanged, and post-verification
+
+## Workflow
+
+1. Install deps with `npm install`.
+2. Use `npm run dev` for iterative runs (`tsx`).
+3. Run `npm run build` before publishing; output lives in `dist/`.
+4. Run `npm test` to run vitest tests.
+5. Keep new dependencies minimal and ESM-friendly.
+
+## Style & Testing
+
+- Strict TypeScript; avoid `any`.
+- Prefer pure utilities over side effects.
+- Add unit tests with `vitest` when adding planners or new merge behaviors.
+- Tests live alongside source files as `*.spec.ts`.
+
+## Safety Features
+
+### File Operations
+
+- Never touch directories outside defined client roots without explicit confirmation.
+- Interactive mode is the safest default; `--dry-run` should work in every mode.
+- `writeFileSafe` ensures directories exist before writing.
+- Backup files (`.bak`) are created before overwriting existing files.
+- Post-write verification ensures file was written correctly.
+- Unchanged files are skipped (hash comparison).
+
+### MCP Handling
+
+- Secrets in env vars are auto-detected and obfuscated in display.
+- Detected patterns: API keys, tokens, passwords, long alphanumeric strings.
+- MCP configs are validated before apply (check for missing commands).
+- Warnings shown when servers would be removed from target.
+- Users can pick which version when same server has different configs across clients.
+
+### Sync Direction
+
+- `push`: Project -> Global clients
+- `pull`: Global clients -> Project
+- `sync`: Merge all and sync everywhere
+
+### Symlinks
+
+- `--link` flag or interactive prompt to use symlinks instead of copying.
+- Symlinks keep files in sync automatically.
+
+## Client Notes
+
+- Claude commands are treated as Codex `prompts/*.md` during sync—Codex users must restart the CLI/IDE after syncing so slash commands reload.
+- Writing to Codex's home (e.g., `~/.codex/agents` or `~/.codex/prompts`) may require elevated permissions.
+- Codex uses `prompts/` for commands (not `commands/`).
+- Claude Desktop only supports MCP configs (`claude_desktop_config.json`), no agents/commands/rules/skills.
+
+## CLI Flags
+
+| Flag                | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `--dry-run`         | Show what would be done without making changes |
+| `--link`            | Use symlinks instead of copying files          |
+| `--separate-claude-md` | Leave Claude's `CLAUDE.md` unmanaged during sync |
+| `--verbose`         | Show detailed output                           |
+| `--scope <scope>`   | `global`, `project`, or `all`                  |
+| `--direction <dir>` | `push`, `pull`, or `sync`                      |
+| `--source <client>` | Source client name                             |
+| `--clients <names>` | Comma-separated client names                   |
+| `--types <types>`   | Comma-separated asset types                    |

package/README.md

@@ -0,0 +1,93 @@
+# link-agents
+
+Synchronize canonical `.agents` assets across AI coding assistants.
+
+## Quick Start
+
+```bash
+npx link-agents sync
+```
+
+This command:
+
+1. Reads canonical assets from `.agents/`
+2. Bootstraps missing canonical assets from legacy client files when possible
+3. Warns about unsupported legacy inputs like `~/.cursor/rules/*`
+4. Fans out canonical assets to client-specific locations
+5. Creates a restore point before mutating targets
+
+## Canonical Layout
+
+```text
+.agents/
+  AGENTS.md
+  commands/
+  skills/
+  mcp.json
+```
+
+`link-agents` treats `.agents/*` as the source of truth once those files exist.
+
+## Commands
+
+### `sync`
+
+Bootstrap canonical assets if needed, then sync them to supported clients.
+
+```bash
+npx link-agents sync
+npx link-agents sync --dry-run
+npx link-agents sync --link
+npx link-agents sync --copy
+npx link-agents sync --separate-claude-md
+npx link-agents sync --bootstrap-source claude
+npx link-agents sync --clients claude,cursor
+npx link-agents sync --types agents,mcp
+```
+
+Notes:
+
+- `--link` prefers symlinks when target bytes can exactly reuse canonical bytes.
+- `--copy` always writes independent copies.
+- If neither flag is provided and the terminal is interactive, `sync` asks which write mode to use.
+- `--separate-claude-md` leaves `CLAUDE.md` unmanaged for that run.
+- If bootstrap is ambiguous, interactive sync asks which client to use; non-interactive sync requires `--bootstrap-source`.
+
+### `doctor`
+
+Inspect canonical sync health, ignored legacy inputs, broken generated targets, and canonical assets eligible for bootstrap.
+
+```bash
+npx link-agents doctor
+npx link-agents doctor --verbose
+```
+
+### `restore`
+
+Restore sync-managed targets from a snapshot.
+
+```bash
+npx link-agents restore --latest
+npx link-agents restore --list
+npx link-agents restore --id <snapshot-id>
+npx link-agents restore --latest --dry-run
+```
+
+## Supported Clients
+
+Public sync targets only home-directory clients. The repo-local `.agents/*` tree is canonical storage, not a public client target.
+
+| Client    | Root                 | Agents      | Commands                         | Skills                                | MCP            |
+| --------- | -------------------- | ----------- | -------------------------------- | ------------------------------------- | -------------- |
+| `codex`   | `~/.codex`           | `AGENTS.md` | `skills/commands/**/SKILL.md`    | `skills/**/SKILL.md`                  | `config.toml` |
+| `claude`  | `~/.claude`          | `CLAUDE.md` | `commands/**/*.md`               | —                                     | — |
+| `cursor`  | `~/.cursor`          | `AGENTS.md` | `commands/**/*.md`               | —                                     | `mcp.json` |
+| `opencode`| `~/.config/opencode` | `AGENTS.md` | `command/**/*.md`                | `skill/**/SKILL.md`                   | `opencode.json` |
+
+## Behavior Notes
+
+- `~/.cursor/rules/*` is treated as an unsupported legacy input. It is reported by `sync`/`doctor`, but never imported into canonical storage.
+- `CLAUDE.md` can be left unmanaged with `--separate-claude-md`.
+- Restore points are created before `sync` mutates targets.
+- Generated symlinks always point back to canonical `.agents/*` sources, not to legacy client files.
+- Public sync does not read from or write to legacy project-level command locations.

package/cursor-rules-notes.md

@@ -0,0 +1,23 @@
+# Cursor User Rules Storage Notes
+
+## Global rule files
+- The Cursor desktop app stores each global "Rules and Config" entry as Markdown files under `~/Library/Application Support/Cursor/User/History/<hash>/`.
+- Every rule folder contains multiple `.md` copies (for example `OVGe.md`, `BDkg.md`, etc.) that all mirror the text shown in the UI. These are the files to back up/edit when exporting rules.
+- The same folder also includes an `entries.json` with metadata (timestamps, IDs) that Cursor uses internally; it is not required when copying text.
+
+## Example (rule reminding agent to ask clarifying questions)
+- Files located at `~/Library/Application Support/Cursor/User/History/5dbb075c/`:
+  - `OVGe.md`, `BDkg.md`, `N4sE.md`, `NSdP.md`, `7oPW.md`: contain the full rule content ("Expert AI Programming Assistant" instructions).
+  - `entries.json`: metadata that can be ignored unless you need Cursor’s IDs.
+
+## How to extract your current rules
+1. `cd ~/Library/Application\ Support/Cursor/User/History`.
+2. Inspect the folders (each is a short hash) and open the `.md` file(s) inside to read or copy the rule text.
+3. To find a specific line (e.g. "yarn install fails"), use ripgrep: `rg -n "yarn install fails" "~/Library/Application Support/Cursor/User/History"`.
+4. The matches show the exact hash + file name, so you can open and archive that Markdown.
+
+## Key takeaways
+- Cursor does **not** save those rules in `settings.json`; the History tree is the source of truth.
+- The `.md` files are plain text and safe to version-control or back up.
+- Searching within `~/Library/Application Support/Cursor/User/History` is the quickest way to locate any current rule snippet.
+- `link-agents --export-cursor-history --cursor-history-dest "~/.cursor/AGENTS.md"` can aggregate every history rule into a single file (adjust the destination if you prefer a different path).

package/dist/cli/interactive.d.ts

@@ -0,0 +1,9 @@
+import type { ClientDefinition, SyncDirection, SyncOptions, SyncPlanEntry, SyncScope } from "../types/index.js";
+export interface InteractiveResult {
+    proceed: boolean;
+    entries: SyncPlanEntry[];
+    scope: SyncScope;
+    direction: SyncDirection;
+}
+export declare function runInteractiveFlow(defs: ClientDefinition[], options: SyncOptions): Promise<InteractiveResult>;
+//# sourceMappingURL=interactive.d.ts.map

package/dist/cli/interactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.d.ts","sourceRoot":"","sources":["../../src/cli/interactive.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAKV,gBAAgB,EAEhB,aAAa,EACb,WAAW,EACX,aAAa,EACb,SAAS,EACV,MAAM,mBAAmB,CAAC;AAyE3B,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,gBAAgB,EAAE,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAiL5B"}