ide-agents 0.1.0 → 0.2.0

package/README.md

@@ -1,15 +1,18 @@
 # ide-agents
 
-Local admin for **IDE agents and skills** (Cursor and similar) from any git repository.
+Local admin for **IDE agents and skills** from any git repository — **Cursor**, **Claude Code**, and **Codex** (enable in Settings).
 
 Install skills and subagents into your IDE via symlinks — no copy-paste, no manual path juggling.
 
+[![GitHub](https://img.shields.io/badge/GitHub-sergeychernov%2Fide--agents-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/sergeychernov/ide-agents)
+[![npm](https://img.shields.io/npm/v/ide-agents?style=for-the-badge&logo=npm&logoColor=white&label=npm)](https://www.npmjs.com/package/ide-agents)
+
 ## What it does
 
 - Clones git repositories into `~/.ide-agents/repos/`
 - Scans `skills/*/SKILL.md` and optional `agents/*.md`
-- Creates symlinks in `~/.cursor/` (global) or `<project>/.cursor/` (per-project)
-- Provides a browser UI for repos, skills, and agents
+- Creates symlinks in each enabled tool’s config directory and per-project folders
+- Provides a browser UI: Settings, Repositories, Skills, Agents
 
 **Not affiliated with Cursor.**
 
@@ -28,8 +31,8 @@ npm i -g ide-agents
 Or from source:
 
 ```bash
-git clone https://github.com/sergeychernov/agentdesk.git
-cd agentdesk
+git clone https://github.com/sergeychernov/ide-agents.git
+cd ide-agents
 npm install
 npm run build
 npm i -g .
@@ -56,10 +59,16 @@ ide-agents --port 3922    # custom port
 ide-agents --no-open      # do not open browser
 ```
 
+## Settings
+
+Open **Settings** (`/settings`) and enable the tools you use (Codex, Claude, Cursor). Set each **config path** (defaults: `~/.codex`, `~/.claude`, `~/.cursor`).
+
+On first run, a tool is enabled only if its default folder already exists in your home directory. You can change paths and toggles anytime; installs apply to all enabled tools.
+
 ## Add a repository
 
-1. Open **Settings** in the UI
-2. Enter a git URL and branch (default `main`)
+1. Open **Repositories** in the UI
+2. Pick a suggested catalog or enter a git URL and branch (default `main`)
 3. Click **Add / Clone**
 
 Your repo should contain:
@@ -86,10 +95,13 @@ Private repos: configure SSH or `gh` auth yourself — ide-agents does not store
 2. Select a repository
 3. Click **Global** (🌐) or **Project** (📁) on a card — symlinks apply immediately
 
-| Kind  | Global                         | Project                              |
-|-------|--------------------------------|--------------------------------------|
-| Skill | `~/.cursor/skills/<name>`      | `<project>/.cursor/skills/<name>`    |
-| Agent | `~/.cursor/agents/<name>.md`   | `<project>/.cursor/agents/<name>.md` |
+| Tool   | Global (default config path) | Project subfolder |
+|--------|------------------------------|-------------------|
+| Cursor | `~/.cursor/`                 | `.cursor`         |
+| Claude | `~/.claude/`                 | `.claude`         |
+| Codex  | `~/.codex/`                  | `.agents`         |
+
+Global paths use your configured **config path** per tool. Project path is the directory where you started `ide-agents`.
 
 Click the active icon again to remove the symlink (only if target is already a symlink).
 
@@ -121,11 +133,13 @@ Then add `file://$(pwd)` in the UI.
 
 ```
 ~/.ide-agents/
-├── config.json
+├── config.json     # repos, installations, ides (per-tool enable + paths)
 └── repos/
     └── <slug>/     # git clone
 ```
 
+Docs: [Settings & IDEs](https://ide-agents.vercel.app/docs/settings) on the project site.
+
 ## License
 
 MIT

package/dist/adapters/create.d.ts

@@ -0,0 +1,9 @@
+import type { IdeId } from "../types.js";
+import type { Adapter } from "./types.js";
+interface IdeLayout {
+    id: IdeId;
+    /** Subfolder under a project root for project-scoped installs. */
+    projectDir: string;
+}
+export declare function createAdapter(layout: IdeLayout, configPath: string): Adapter;
+export {};

package/dist/adapters/create.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { expandUserPath, resolveProjectPath } from "../paths.js";
+function skillsDir(base) {
+    return path.join(base, "skills");
+}
+function agentsDir(base) {
+    return path.join(base, "agents");
+}
+function targetPath(base, kind, targetName) {
+    if (kind === "skill") {
+        return path.join(skillsDir(base), targetName);
+    }
+    return path.join(agentsDir(base), `${targetName}.md`);
+}
+export function createAdapter(layout, configPath) {
+    const globalBase = expandUserPath(configPath);
+    return {
+        id: layout.id,
+        getGlobalTargetPath(installation) {
+            return targetPath(globalBase, installation.kind, installation.targetName);
+        },
+        getProjectTargetPath(installation) {
+            if (!installation.projectPath) {
+                throw new Error("projectPath is required for project target");
+            }
+            const projectBase = path.join(resolveProjectPath(installation.projectPath), layout.projectDir);
+            return targetPath(projectBase, installation.kind, installation.targetName);
+        },
+        getSourcePath(repoRoot, installation) {
+            return path.join(repoRoot, installation.sourcePath);
+        },
+    };
+}

package/dist/adapters/index.d.ts

@@ -0,0 +1,6 @@
+import type { IdeAgentsConfig, IdeId } from "../types.js";
+import type { Adapter } from "./types.js";
+export declare function getAdapter(ideId: IdeId, configPath: string): Adapter;
+export declare function getEnabledAdapters(config: IdeAgentsConfig): Adapter[];
+export declare function isSymlinkType(kind: "skill" | "agent"): "dir" | "file";
+export type { Adapter } from "./types.js";

package/dist/adapters/index.js

@@ -0,0 +1,16 @@
+import { getEnabledIdeIds } from "../ides.js";
+import { createAdapter } from "./create.js";
+const LAYOUTS = {
+    cursor: { id: "cursor", projectDir: ".cursor" },
+    claude: { id: "claude", projectDir: ".claude" },
+    codex: { id: "codex", projectDir: ".agents" },
+};
+export function getAdapter(ideId, configPath) {
+    return createAdapter(LAYOUTS[ideId], configPath);
+}
+export function getEnabledAdapters(config) {
+    return getEnabledIdeIds(config).map((id) => getAdapter(id, config.ides[id].configPath));
+}
+export function isSymlinkType(kind) {
+    return kind === "skill" ? "dir" : "file";
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,7 @@
+import type { IdeId, Installation } from "../types.js";
+export interface Adapter {
+    id: IdeId;
+    getGlobalTargetPath(installation: Pick<Installation, "kind" | "targetName">): string;
+    getProjectTargetPath(installation: Pick<Installation, "kind" | "targetName" | "projectPath">): string;
+    getSourcePath(repoRoot: string, installation: Pick<Installation, "sourcePath">): string;
+}

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/apply.js

@@ -1,7 +1,8 @@
 import { lstat, mkdir, readlink, symlink, unlink } from "node:fs/promises";
 import path from "node:path";
-import { getAdapter } from "./adapters/cursor.js";
-import { getRepoPath } from "./paths.js";
+import { getEnabledAdapters } from "./adapters/index.js";
+import { addManagedGitignoreEntry, removeManagedGitignoreEntry, toGitignorePath, } from "./gitignore.js";
+import { getRepoPath, resolveProjectPath } from "./paths.js";
 async function pathExists(filePath) {
     try {
         await lstat(filePath);
@@ -52,11 +53,29 @@ async function createSymlink(targetPath, sourcePath, type) {
     await symlink(resolvedSource, targetPath, type);
     return { path: targetPath, action: "created" };
 }
-async function applyScope(installation, sourcePath, type, enabled, targetPath) {
+async function syncProjectGitignore(projectRoot, targetPath, mode) {
+    if (!projectRoot) {
+        return;
+    }
+    const entry = toGitignorePath(projectRoot, targetPath);
+    if (!entry) {
+        return;
+    }
+    if (mode === "add") {
+        await addManagedGitignoreEntry(projectRoot, entry);
+        return;
+    }
+    await removeManagedGitignoreEntry(projectRoot, entry);
+}
+async function applyScope(sourcePath, type, enabled, targetPath, projectRoot) {
     const results = [];
     if (enabled) {
         try {
-            results.push(await createSymlink(targetPath, sourcePath, type));
+            const result = await createSymlink(targetPath, sourcePath, type);
+            results.push(result);
+            if (!result.error) {
+                await syncProjectGitignore(projectRoot, targetPath, "add");
+            }
         }
         catch (err) {
             results.push({
@@ -70,12 +89,16 @@ async function applyScope(installation, sourcePath, type, enabled, targetPath) {
     const removed = await removeSymlinkIfExists(targetPath);
     if (removed.action === "removed") {
         results.push(removed);
+        await syncProjectGitignore(projectRoot, targetPath, "remove");
     }
     return results;
 }
 export async function applyInstallations(config) {
-    const adapter = getAdapter(config.adapter);
+    const adapters = getEnabledAdapters(config);
     const results = [];
+    if (adapters.length === 0) {
+        return { results };
+    }
     for (const installation of config.installations) {
         const repo = config.repos.find((r) => r.id === installation.repoId);
         if (!repo) {
@@ -87,13 +110,17 @@ export async function applyInstallations(config) {
             continue;
         }
         const repoRoot = getRepoPath(repo.slug);
-        const sourcePath = adapter.getSourcePath(repoRoot, installation);
         const type = installation.kind === "skill" ? "dir" : "file";
-        const globalTarget = adapter.getGlobalTargetPath(installation);
-        results.push(...(await applyScope(installation, sourcePath, type, installation.global, globalTarget)));
-        if (installation.projectPath) {
-            const projectTarget = adapter.getProjectTargetPath(installation);
-            results.push(...(await applyScope(installation, sourcePath, type, installation.project, projectTarget)));
+        for (const adapter of adapters) {
+            const sourcePath = adapter.getSourcePath(repoRoot, installation);
+            const globalTarget = adapter.getGlobalTargetPath(installation);
+            results.push(...(await applyScope(sourcePath, type, installation.global, globalTarget, null)));
+            // projectPath is kept in config while project is off so removal can run.
+            if (installation.projectPath) {
+                const projectRoot = resolveProjectPath(installation.projectPath);
+                const projectTarget = adapter.getProjectTargetPath(installation);
+                results.push(...(await applyScope(sourcePath, type, installation.project, projectTarget, projectRoot)));
+            }
         }
     }
     return { results };

package/dist/config.js

@@ -2,14 +2,19 @@ import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { homedir } from "node:os";
 import { getConfigPath, getIdeAgentsHome } from "./paths.js";
-const DEFAULT_CONFIG = {
-    version: 1,
-    adapter: "cursor",
-    server: { port: 3921 },
-    repos: [],
-    installations: [],
-    recentProjects: [],
-};
+import { defaultAdapterFromIdes, getDefaultIdes, migrateIdesConfig, } from "./ides.js";
+function buildDefaultConfig() {
+    const ides = getDefaultIdes();
+    return {
+        version: 1,
+        adapter: defaultAdapterFromIdes(ides),
+        ides,
+        server: { port: 3921 },
+        repos: [],
+        installations: [],
+        recentProjects: [],
+    };
+}
 const LEGACY_HOME = path.join(homedir(), ".agentdesk");
 async function fileExists(filePath) {
     try {
@@ -38,6 +43,26 @@ function migrateInstallation(raw) {
         projectPath: item.projectPath ?? null,
     };
 }
+function isLegacySampleRepo(repo) {
+    if (repo.id === "sample") {
+        return true;
+    }
+    const normalized = repo.url.toLowerCase();
+    return (normalized.includes("fixtures/sample-repo") ||
+        normalized.includes("fixtures%2fsample-repo"));
+}
+function stripLegacySampleRepo(config) {
+    const repos = config.repos.filter((r) => !isLegacySampleRepo(r));
+    if (repos.length === config.repos.length) {
+        return config;
+    }
+    const removedIds = new Set(config.repos.filter(isLegacySampleRepo).map((r) => r.id));
+    return {
+        ...config,
+        repos,
+        installations: config.installations.filter((i) => !removedIds.has(i.repoId)),
+    };
+}
 async function migrateLegacyHome() {
     const home = getIdeAgentsHome();
     if (home === LEGACY_HOME) {
@@ -57,20 +82,30 @@ export async function ensureIdeAgentsHome() {
 export async function readConfig() {
     await ensureIdeAgentsHome();
     const configPath = getConfigPath();
+    const defaults = buildDefaultConfig();
     if (!(await fileExists(configPath))) {
-        await writeConfig(DEFAULT_CONFIG);
-        return structuredClone(DEFAULT_CONFIG);
+        await writeConfig(defaults);
+        return structuredClone(defaults);
     }
     const raw = await readFile(configPath, "utf8");
     const parsed = JSON.parse(raw);
-    return {
-        ...DEFAULT_CONFIG,
+    const ides = migrateIdesConfig(parsed);
+    let config = {
+        ...defaults,
         ...parsed,
-        server: { ...DEFAULT_CONFIG.server, ...parsed.server },
+        adapter: parsed.adapter ?? defaultAdapterFromIdes(ides),
+        ides,
+        server: { ...defaults.server, ...parsed.server },
         repos: parsed.repos ?? [],
         installations: (parsed.installations ?? []).map(migrateInstallation),
         recentProjects: parsed.recentProjects ?? [],
     };
+    const withoutSample = stripLegacySampleRepo(config);
+    if (withoutSample.repos.length !== config.repos.length) {
+        await writeConfig(withoutSample);
+        config = withoutSample;
+    }
+    return config;
 }
 export async function writeConfig(config) {
     await ensureIdeAgentsHome();

package/dist/git.js

@@ -20,10 +20,26 @@ async function runGit(cwd, args) {
     });
     return { stdout: result.stdout.trim(), stderr: result.stderr.trim() };
 }
+async function syncExistingRepo(target, ref) {
+    try {
+        await runGit(target, ["fetch", "--all", "--prune"]);
+        try {
+            await runGit(target, ["checkout", ref]);
+        }
+        catch {
+            // ref may be a tag or detached state — pull current branch below
+        }
+        await runGit(target, ["pull", "--ff-only"]);
+    }
+    catch {
+        // Best effort: re-attaching a previously removed repo still succeeds
+    }
+}
 export async function cloneRepo(url, slug, ref) {
     const target = getRepoPath(slug);
     if (await isGitRepo(target)) {
-        throw new Error(`Repository already cloned at ${target}`);
+        await syncExistingRepo(target, ref);
+        return target;
     }
     await execFileAsync("git", ["clone", "--branch", ref, url, target], {
         maxBuffer: 10 * 1024 * 1024,

package/dist/gitignore.d.ts

@@ -0,0 +1,5 @@
+export declare const IDE_AGENTS_GITIGNORE_HEADER = "# ide-agents (managed \u2014 do not edit manually)";
+export declare function toGitignorePath(projectRoot: string, targetPath: string): string | null;
+export declare function isGitRepository(projectRoot: string): Promise<boolean>;
+export declare function addManagedGitignoreEntry(projectRoot: string, entry: string): Promise<void>;
+export declare function removeManagedGitignoreEntry(projectRoot: string, entry: string): Promise<void>;

package/dist/gitignore.js

@@ -0,0 +1,105 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const IDE_AGENTS_GITIGNORE_HEADER = "# ide-agents (managed — do not edit manually)";
+export function toGitignorePath(projectRoot, targetPath) {
+    const relative = path.relative(path.resolve(projectRoot), path.resolve(targetPath));
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        return null;
+    }
+    return relative.split(path.sep).join("/");
+}
+export async function isGitRepository(projectRoot) {
+    try {
+        await access(path.join(projectRoot, ".git"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseGitignore(content) {
+    const lines = content.split("\n");
+    const headerIndex = lines.findIndex((line) => line.trim() === IDE_AGENTS_GITIGNORE_HEADER);
+    if (headerIndex === -1) {
+        return { before: content.replace(/\n?$/, ""), entries: [], after: "" };
+    }
+    const before = lines.slice(0, headerIndex).join("\n").replace(/\n?$/, "");
+    const entries = [];
+    let index = headerIndex + 1;
+    while (index < lines.length) {
+        const line = lines[index];
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            index += 1;
+            break;
+        }
+        if (trimmed.startsWith("#")) {
+            break;
+        }
+        entries.push(line);
+        index += 1;
+    }
+    const after = lines.slice(index).join("\n").replace(/^\n?/, "");
+    return { before, entries, after };
+}
+function formatGitignore(parsed) {
+    const parts = [];
+    if (parsed.before.length > 0) {
+        parts.push(parsed.before);
+    }
+    if (parsed.entries.length > 0) {
+        parts.push(IDE_AGENTS_GITIGNORE_HEADER);
+        parts.push(...parsed.entries);
+        parts.push("");
+    }
+    if (parsed.after.length > 0) {
+        parts.push(parsed.after.replace(/\n?$/, ""));
+    }
+    if (parts.length === 0) {
+        return "";
+    }
+    return `${parts.join("\n")}\n`;
+}
+async function readGitignore(gitignorePath) {
+    try {
+        return await readFile(gitignorePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return "";
+        }
+        throw err;
+    }
+}
+async function writeGitignoreIfChanged(gitignorePath, nextContent) {
+    const current = await readGitignore(gitignorePath);
+    if (current === nextContent) {
+        return;
+    }
+    await writeFile(gitignorePath, nextContent, "utf8");
+}
+export async function addManagedGitignoreEntry(projectRoot, entry) {
+    if (!(await isGitRepository(projectRoot))) {
+        return;
+    }
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    const parsed = parseGitignore(await readGitignore(gitignorePath));
+    if (parsed.entries.includes(entry)) {
+        return;
+    }
+    parsed.entries.push(entry);
+    parsed.entries.sort((a, b) => a.localeCompare(b));
+    await writeGitignoreIfChanged(gitignorePath, formatGitignore(parsed));
+}
+export async function removeManagedGitignoreEntry(projectRoot, entry) {
+    if (!(await isGitRepository(projectRoot))) {
+        return;
+    }
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    const parsed = parseGitignore(await readGitignore(gitignorePath));
+    if (!parsed.entries.includes(entry)) {
+        return;
+    }
+    parsed.entries = parsed.entries.filter((line) => line !== entry);
+    await writeGitignoreIfChanged(gitignorePath, formatGitignore(parsed));
+}

package/dist/ides.d.ts

@@ -0,0 +1,5 @@
+import type { AdapterId, IdeAgentsConfig, IdeId, IdesConfig } from "./types.js";
+export declare function getDefaultIdes(): IdesConfig;
+export declare function defaultAdapterFromIdes(ides: IdesConfig): AdapterId;
+export declare function migrateIdesConfig(parsed: Partial<IdeAgentsConfig>): IdesConfig;
+export declare function getEnabledIdeIds(config: IdeAgentsConfig): IdeId[];

package/dist/ides.js

@@ -0,0 +1,52 @@
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+function homeDirExists(dirPath) {
+    try {
+        return existsSync(dirPath) && statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function getDefaultIdes() {
+    const home = homedir();
+    const cursorPath = path.join(home, ".cursor");
+    const claudePath = path.join(home, ".claude");
+    const codexPath = path.join(home, ".codex");
+    return {
+        cursor: { enabled: homeDirExists(cursorPath), configPath: cursorPath },
+        claude: { enabled: homeDirExists(claudePath), configPath: claudePath },
+        codex: { enabled: homeDirExists(codexPath), configPath: codexPath },
+    };
+}
+export function defaultAdapterFromIdes(ides) {
+    if (ides.cursor.enabled)
+        return "cursor";
+    if (ides.claude.enabled)
+        return "claude";
+    if (ides.codex.enabled)
+        return "codex";
+    return "cursor";
+}
+export function migrateIdesConfig(parsed) {
+    const defaults = getDefaultIdes();
+    if (!parsed.ides) {
+        return defaults;
+    }
+    return {
+        cursor: { ...defaults.cursor, ...parsed.ides.cursor },
+        claude: { ...defaults.claude, ...parsed.ides.claude },
+        codex: { ...defaults.codex, ...parsed.ides.codex },
+    };
+}
+export function getEnabledIdeIds(config) {
+    const ids = [];
+    if (config.ides.cursor.enabled)
+        ids.push("cursor");
+    if (config.ides.claude.enabled)
+        ids.push("claude");
+    if (config.ides.codex.enabled)
+        ids.push("codex");
+    return ids;
+}

package/dist/paths.d.ts

@@ -6,3 +6,4 @@ export declare function getRepoPath(slug: string): string;
 export declare function slugFromUrl(url: string): string;
 export declare function getWebDistDir(): string;
 export declare function resolveProjectPath(projectPath: string): string;
+export declare function expandUserPath(inputPath: string): string;

package/dist/paths.js

@@ -55,3 +55,13 @@ export function getWebDistDir() {
 export function resolveProjectPath(projectPath) {
     return path.resolve(projectPath);
 }
+export function expandUserPath(inputPath) {
+    const trimmed = inputPath.trim();
+    if (trimmed === "~") {
+        return homedir();
+    }
+    if (trimmed.startsWith("~/")) {
+        return path.join(homedir(), trimmed.slice(2));
+    }
+    return path.resolve(trimmed);
+}