ide-agents 0.2.0 → 0.3.0

package/README.md

@@ -121,13 +121,7 @@ npm run docs:install
 npm run docs:start # http://localhost:3000
 ```
 
-Fixture repo for manual testing:
-
-```bash
-cd fixtures/sample-repo && git init && git add . && git commit -m "init"
-```
-
-Then add `file://$(pwd)` in the UI.
+For local testing, add a `file://` URL to any git repo with skills/agents (see [docs](https://ide-agents.vercel.app/docs/source-repos#local-testing)).
 
 ## Data layout
 

package/dist/git.d.ts

@@ -3,4 +3,5 @@ export declare function cloneRepo(url: string, slug: string, ref: string): Promi
 export declare function fetchRepo(slug: string): Promise<void>;
 export declare function pullRepo(slug: string): Promise<void>;
 export declare function getGitStatus(slug: string, ref: string): Promise<GitStatus>;
+export declare function commitAndPushRepo(cwd: string, ref: string): Promise<void>;
 export declare function getGitStatusWithoutFetch(slug: string, ref: string): Promise<GitStatus>;

package/dist/git.js

@@ -130,6 +130,30 @@ export async function getGitStatus(slug, ref) {
         };
     }
 }
+export async function commitAndPushRepo(cwd, ref) {
+    if (!(await isGitRepo(cwd))) {
+        throw new Error(`Not a git repository: ${cwd}`);
+    }
+    const status = await runGit(cwd, ["status", "--porcelain"]);
+    if (!status.stdout.trim()) {
+        return;
+    }
+    await runGit(cwd, ["add", "-A"]);
+    await runGit(cwd, [
+        "commit",
+        "-m",
+        "chore: bootstrap skills catalog from ide-agents template",
+    ]);
+    try {
+        await runGit(cwd, ["push", "origin", ref]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Commit succeeded but push failed: ${message}`, {
+            cause: err,
+        });
+    }
+}
 export async function getGitStatusWithoutFetch(slug, ref) {
     const cwd = getRepoPath(slug);
     if (!(await isGitRepo(cwd))) {

package/dist/server.js

@@ -3,6 +3,7 @@ import fastifyStatic from "@fastify/static";
 import { v4 as uuidv4 } from "uuid";
 import { addRecentProject, readConfig, writeConfig, } from "./config.js";
 import { cloneRepo, fetchRepo, getGitStatusWithoutFetch, pullRepo, } from "./git.js";
+import { bootstrapEmptyRepo } from "./template.js";
 import { applyInstallations } from "./apply.js";
 import { scanRepoArtifacts } from "./scan.js";
 import { getArtifactTargets } from "./targets.js";
@@ -99,14 +100,16 @@ export async function createServer(options) {
         if (config.repos.some((r) => r.id === repoId)) {
             return reply.status(409).send({ error: `Repository id already exists: ${repoId}` });
         }
+        let repoPath;
         try {
-            await cloneRepo(url.trim(), slug, ref);
+            repoPath = await cloneRepo(url.trim(), slug, ref);
         }
         catch (err) {
             return reply.status(400).send({
                 error: err instanceof Error ? err.message : String(err),
             });
         }
+        const bootstrap = await bootstrapEmptyRepo(repoPath, ref);
         const repo = { id: repoId, url: url.trim(), ref, slug };
         config.repos.push(repo);
         await writeConfig(config);
@@ -116,7 +119,10 @@ export async function createServer(options) {
                 ...repo,
                 localPath: getRepoPath(slug),
                 git,
+                skillCount: bootstrap.skillCount,
+                agentCount: bootstrap.agentCount,
             },
+            bootstrap,
         };
     });
     app.delete("/api/repos/:id", async (request, reply) => {
@@ -130,6 +136,38 @@ export async function createServer(options) {
         await writeConfig(config);
         return { ok: true };
     });
+    app.post("/api/repos/:id/bootstrap", async (request, reply) => {
+        const config = await readConfig();
+        const repo = config.repos.find((r) => r.id === request.params.id);
+        if (!repo) {
+            return reply.status(404).send({ error: "Repository not found" });
+        }
+        const repoPath = getRepoPath(repo.slug);
+        try {
+            const bootstrap = await bootstrapEmptyRepo(repoPath, repo.ref);
+            if (!bootstrap.applied) {
+                return reply.status(409).send({
+                    error: "Repository is not empty — bootstrap skipped",
+                });
+            }
+            const git = await getGitStatusWithoutFetch(repo.slug, repo.ref);
+            return {
+                repo: {
+                    ...repo,
+                    localPath: repoPath,
+                    git,
+                    skillCount: bootstrap.skillCount,
+                    agentCount: bootstrap.agentCount,
+                },
+                bootstrap,
+            };
+        }
+        catch (err) {
+            return reply.status(400).send({
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
     app.post("/api/repos/:id/fetch", async (request, reply) => {
         const config = await readConfig();
         const repo = config.repos.find((r) => r.id === request.params.id);

package/dist/template.d.ts

@@ -0,0 +1,12 @@
+export interface BootstrapResult {
+    applied: boolean;
+    pushed: boolean;
+    pushError?: string;
+    skillCount: number;
+    agentCount: number;
+}
+export declare function getTemplateDir(): string;
+/** True when the clone has no installable artifacts and no custom content. */
+export declare function isEmptySkillRepo(repoPath: string): Promise<boolean>;
+export declare function applyTemplateToRepo(repoPath: string): Promise<void>;
+export declare function bootstrapEmptyRepo(repoPath: string, ref: string): Promise<BootstrapResult>;

package/dist/template.js

@@ -0,0 +1,86 @@
+import { cp, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { commitAndPushRepo } from "./git.js";
+import { scanRepoArtifacts } from "./scan.js";
+const GITHUB_INIT_FILES = new Set([
+    "README.md",
+    "LICENSE",
+    "LICENSE.md",
+    "LICENSE.txt",
+    ".gitignore",
+]);
+export function getTemplateDir() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(moduleDir, "../template");
+}
+async function pathExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when the clone has no installable artifacts and no custom content. */
+export async function isEmptySkillRepo(repoPath) {
+    const artifacts = await scanRepoArtifacts(repoPath);
+    if (artifacts.length > 0) {
+        return false;
+    }
+    const entries = await readdir(repoPath, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name === ".git") {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            return false;
+        }
+        if (!GITHUB_INIT_FILES.has(entry.name)) {
+            return false;
+        }
+    }
+    return true;
+}
+export async function applyTemplateToRepo(repoPath) {
+    const templateDir = getTemplateDir();
+    if (!(await pathExists(templateDir))) {
+        throw new Error(`Template directory not found: ${templateDir}`);
+    }
+    const entries = await readdir(templateDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const src = path.join(templateDir, entry.name);
+        const dest = path.join(repoPath, entry.name);
+        await cp(src, dest, { recursive: true, force: true });
+    }
+}
+export async function bootstrapEmptyRepo(repoPath, ref) {
+    if (!(await isEmptySkillRepo(repoPath))) {
+        const artifacts = await scanRepoArtifacts(repoPath);
+        return {
+            applied: false,
+            pushed: false,
+            skillCount: artifacts.filter((a) => a.kind === "skill").length,
+            agentCount: artifacts.filter((a) => a.kind === "agent").length,
+        };
+    }
+    await applyTemplateToRepo(repoPath);
+    let pushed = false;
+    let pushError;
+    try {
+        await commitAndPushRepo(repoPath, ref);
+        pushed = true;
+    }
+    catch (err) {
+        pushError = err instanceof Error ? err.message : String(err);
+    }
+    const artifacts = await scanRepoArtifacts(repoPath);
+    return {
+        applied: true,
+        pushed,
+        pushError,
+        skillCount: artifacts.filter((a) => a.kind === "skill").length,
+        agentCount: artifacts.filter((a) => a.kind === "agent").length,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ide-agents",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local admin for IDE agents and skills from git repos",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "template",
     "web/dist",
     "LICENSE",
     "README.md"
@@ -23,7 +24,9 @@
     "start": "node dist/cli.js",
     "docs:install": "npm install --prefix docs",
     "docs:start": "npm --prefix docs start",
-    "docs:build": "npm --prefix docs run build"
+    "docs:build": "npm --prefix docs run build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   },
   "engines": {
     "node": ">=20"
@@ -56,6 +59,7 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@mantine/core": "^9.2.2",
     "@mantine/hooks": "^9.2.2",
     "@tabler/icons-react": "^3.44.0",
@@ -64,6 +68,9 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.2",
     "concurrently": "^9.1.2",
+    "eslint": "^10.4.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^16.5.0",
     "postcss": "^8.5.15",
     "postcss-preset-mantine": "^1.18.0",
     "postcss-simple-vars": "^7.0.1",
@@ -72,6 +79,7 @@
     "react-router-dom": "^7.3.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
+    "typescript-eslint": "^8.60.0",
     "vite": "^8.0.14"
   }
 }

package/template/.agents/AGENTS.md

@@ -0,0 +1,51 @@
+# Codex — repository guide
+
+This repository holds **Agent Skills** and **agents** consumed by ide-agents.
+
+## Expected layout
+
+```
+skills/<skill-id>/
+├── SKILL.md
+├── scripts/       # optional — *.mjs generators (stdlib, ESM)
+└── assets/        # optional — JSON config for scripts
+agents/<agent-id>.md
+```
+
+## SKILL.md
+
+Required frontmatter:
+
+```yaml
+---
+name: skill-id
+description: Short summary for the UI.
+scope: any
+---
+```
+
+Project installs symlink into `<project>/.agents/skills/<name>`.
+
+## Agents
+
+Markdown files in `agents/<agent-id>.md`. Required frontmatter:
+
+```yaml
+---
+name: agent-id          # must match filename stem
+description: When the IDE should delegate to this subagent.
+scope: any              # optional — ide-agents install toggles
+---
+```
+
+Project installs use `.agents/agents/<name>.md`.
+
+Agents define **role and workflow** only. Repeatable generators (stack detection, audits, structured reports) go in `skills/<skill-id>/scripts/` — agents invoke `node <SKILL_DIR>/scripts/….mjs` instead of improvising the same logic in chat. Pattern: [repo-audit-skills](https://github.com/sergeychernov/repo-audit-skills).
+
+## Editing rules
+
+- Do not flatten skills to repo root unless you intentionally use the flat layout (ide-agents detects nested `skills/` first).
+- Preserve skill folder names — they become installation ids.
+- Push to git after changes so remote catalogs stay in sync.
+
+See `README.md` for usage with ide-agents.

package/template/.claude/CLAUDE.md

@@ -0,0 +1,37 @@
+# Claude Code — repository guide
+
+This repo is a **skills and agents catalog** for ide-agents.
+
+## Layout
+
+- `skills/<name>/SKILL.md` — skills with YAML frontmatter (`name`, `description`, `scope`)
+- `skills/<name>/scripts/` — optional Node `.mjs` generators (stable scans, JSON reports)
+- `skills/<name>/assets/` — optional JSON/markers scripts read
+- `agents/<name>.md` — subagent orchestrators; frontmatter `name`, `description`, optional `scope`
+
+## Agents and scripts
+
+Do **not** implement multi-step repo scanners or report generators inline in agent markdown. Put them in `skills/<skill-id>/scripts/` and have agents run:
+
+```bash
+node <SKILL_DIR>/scripts/<script>.mjs
+```
+
+Then read stdout (`--json`) or documented output files. See repo-audit-skills for reference (`detect-stack.mjs`, `run-audit.mjs`).
+
+## When editing
+
+- Keep one skill per folder; the folder name is the skill id.
+- Use `scope: any` unless the skill must be global-only or project-only.
+- Write instructions in the skill body, not only in frontmatter.
+- Commit meaningful changes; ide-agents symlinks from the cloned copy under `~/.ide-agents/repos/`.
+
+## Scope values
+
+| Value | Meaning |
+|-------|---------|
+| `global` | Install only to user config (`~/.claude/`) |
+| `project` | Install only to project `.claude/` |
+| `any` | User chooses global or project in the UI |
+
+See `README.md` for the full catalog overview.

package/template/.cursor/rules/agents.mdc

@@ -0,0 +1,72 @@
+---
+description: Agent authoring — orchestration, reports, and script-backed generators
+globs: agents/**/*.md
+alwaysApply: false
+---
+
+# Agent authoring
+
+Agents in `agents/*.md` are **orchestrators**: they define role, workflow, and output format. They are not a place for ad-hoc code generation.
+
+## Generators → `scripts/`
+
+For anything that must be **stable, repeatable, and testable** (scanners, profile builders, report writers, stack detectors), put logic in bundled scripts under the **related skill folder**:
+
+```
+skills/<skill-id>/
+├── SKILL.md
+├── scripts/          # node *.mjs — run these, do not re-implement in chat
+└── assets/           # optional JSON/markers the scripts read
+```
+
+Pattern from [repo-audit-skills](https://github.com/sergeychernov/repo-audit-skills):
+
+- `skills/audit-init/scripts/detect-stack.mjs` — read-only scan, writes structured JSON
+- `skills/audit-debt/scripts/run-audit.mjs` — reads profile, runs checks, writes report
+
+### Why agents call scripts
+
+| In chat (avoid) | In `scripts/` (prefer) |
+|-----------------|------------------------|
+| Re-parsing repo layout each turn | Same repo state → same output |
+| Drifting flags and file paths | Documented CLI in script header |
+| Large inline bash one-liners | `#!/usr/bin/env node`, ESM `.mjs` |
+
+Agent body should tell the model to **resolve `<SKILL_DIR>`**, run `node <SKILL_DIR>/scripts/<name>.mjs`, then **read the artifact** (stdout JSON or a known output path). See `scripts.mdc` for script conventions.
+
+## Agent file format
+
+YAML frontmatter (filename stem must match `name`, e.g. `agents/oracle.md` → `name: oracle`):
+
+```yaml
+---
+name: my-agent          # required — lowercase id; Cursor subagent identity (/my-agent)
+description: When to delegate to this subagent. Be specific — the IDE uses this for auto-delegation.
+scope: any              # optional — ide-agents only: global | project | any (default any)
+---
+```
+
+| Field | Required | Used by |
+|-------|----------|---------|
+| `name` | yes | Cursor / Claude / Codex subagent id (defaults to filename if omitted — prefer explicit) |
+| `description` | yes | IDE delegation — when the main agent should hand off to this subagent |
+| `scope` | no | ide-agents UI — which install toggles are enabled |
+
+Subagents are **not** skills: they live in `agents/*.md`, install to `~/.cursor/agents/`, and are invoked by name in Agent mode (e.g. `/oracle …` or “use the oracle subagent”), not via the `/` skill picker.
+
+Body structure:
+
+1. **Role** — one paragraph
+2. **Inputs** — what the user or upstream skill must provide
+3. **Workflow** — numbered steps; step that runs a script must include the exact `node …mjs` command
+4. **Output contract** — fixed sections (e.g. summary, findings, gaps); use consistent severity markers if reporting issues
+
+## Do not
+
+- Embed multi-step filesystem scans or JSON schema logic in the agent markdown
+- Write into the target project except paths documented by the skill (e.g. `.audit/`)
+- Duplicate script behavior in prose — link to `SKILL.md` quick start instead
+
+## Shared helpers
+
+Cross-skill utilities may live in `skills/_shared/` (e.g. `generated-by.mjs`). Import from scripts via relative paths; agents reference the skill that owns the script.

package/template/.cursor/rules/repo-structure.mdc

@@ -0,0 +1,46 @@
+---
+description: Skills and agents repository layout for ide-agents catalogs
+alwaysApply: true
+---
+
+# Repository structure
+
+This repository is an **ide-agents skill catalog** — not an application codebase.
+
+## Directories
+
+| Path | Purpose |
+|------|---------|
+| `skills/<id>/SKILL.md` | Installable skills (required `SKILL.md` per folder) |
+| `skills/<id>/scripts/` | Optional bundled generators (`*.mjs`) — see `scripts.mdc` |
+| `skills/<id>/assets/` | Optional JSON/markers read by scripts |
+| `skills/_shared/` | Optional cross-skill helpers (imported by scripts) |
+| `agents/<id>.md` | Subagent orchestrators — call scripts, do not re-implement generators |
+| `.cursor/rules/` | Cursor project rules (this file) |
+
+## SKILL.md conventions
+
+- YAML frontmatter: `name`, `description`, `scope` (`global`, `project`, or `any`).
+- Body: instructions the IDE agent follows when the skill is invoked.
+- One skill per directory under `skills/`.
+
+## Agents
+
+- One markdown file per agent in `agents/` (e.g. `agents/oracle.md`).
+- YAML frontmatter: `name`, `description`, optional `scope` (`global`, `project`, or `any`).
+- `name` must match the filename stem; used by Cursor/Claude/Codex as the subagent id.
+- Agents **orchestrate**; deterministic generators live in `skills/<id>/scripts/` (see `agents.mdc`).
+
+## Scripts (generators)
+
+Stable scanners and report writers belong in `skills/<skill-id>/scripts/`, not inline in agent prompts. Follow `scripts.mdc` (ESM `.mjs`, stdlib only, `--json` / `--dry-run`, resolve paths via `import.meta.url`).
+
+## Do not
+
+- Put application source code here unless it supports the catalog itself.
+- Rename skill folders casually — `artifactId` in ide-agents matches the directory name.
+- Remove `SKILL.md` from a skill folder (scan ignores directories without it).
+
+## Installing
+
+Use [ide-agents](https://github.com/sergeychernov/ide-agents): add this repo, then toggle **Global** or **Project** on Skills / Agents pages.

package/template/.cursor/rules/scripts.mdc

@@ -0,0 +1,101 @@
+---
+description: Conventions for skill scripts (generators, scanners, report writers)
+globs: skills/**/scripts/**
+alwaysApply: false
+---
+
+# Skill scripts
+
+Bundled under `skills/<skill-id>/scripts/`. Invoked by skills and agents — not installed separately by ide-agents.
+
+Reference implementation: [repo-audit-skills](https://github.com/sergeychernov/repo-audit-skills) (`detect-stack.mjs`, `run-audit.mjs`, modular `checks/`).
+
+## Runtime
+
+- ESM: `*.mjs`, `#!/usr/bin/env node`
+- Node 18+, **zero npm dependencies** in scripts (stdlib only)
+- Resolve skill assets via `import.meta.url` — never assume cwd for skill paths
+
+```javascript
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const assetsDir = join(here, '..', 'assets');
+```
+
+## Target repo discovery
+
+Scripts run **from anywhere inside the user's project** (after skill symlink install). Discover the audited repo root explicitly:
+
+```javascript
+import { execSync } from 'node:child_process';
+
+const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+process.chdir(repoRoot);
+```
+
+Exit `1` with a clear message if not a git repo.
+
+## File header (required)
+
+Every entry script documents usage at the top:
+
+```javascript
+#!/usr/bin/env node
+// my-skill: one-line purpose
+//
+// Usage (from anywhere inside a git repo):
+//   node <SKILL_DIR>/scripts/my-script.mjs
+//   node <SKILL_DIR>/scripts/my-script.mjs --json
+//   node <SKILL_DIR>/scripts/my-script.mjs --dry-run
+```
+
+`<SKILL_DIR>` is the installed skill folder path (global or project symlink).
+
+## CLI flags (standard)
+
+| Flag | Effect |
+|------|--------|
+| `--json` | Machine-readable stdout |
+| `--dry-run` | Run logic without writing output files |
+| `--force` | Overwrite existing generated files (when applicable) |
+
+Add skill-specific flags (`--offline`, `--verbose`, …) only when documented in the header.
+
+## Scan and write rules
+
+- Prefer `git ls-files` over unbounded filesystem walks
+- **Read-only** toward source files in the target repo by default
+- Writable outputs only under paths the skill documents (e.g. `.audit/profile.json`, `.audit/reports/*.json`)
+- Static config and schemas stay in `skills/<id>/assets/` — edit markers here, not in the target project
+- No network calls in scan scripts unless the skill explicitly requires it
+
+## Output
+
+- Human mode: short labeled summary for the terminal
+- JSON mode: stable schema for agents to parse
+- JSON files: 2-space indent, trailing newline
+- Stamp artifacts with `generatedBy`, `version`, `generatedAt` when writing reports
+
+## Layout inside a skill
+
+```
+skills/<name>/
+├── SKILL.md
+├── scripts/
+│   ├── run-*.mjs       # entry points
+│   ├── load-*.mjs      # shared loaders
+│   └── checks/         # optional modular checks
+└── assets/             # JSON registries, markers, schemas
+```
+
+Split large generators into `scripts/checks/` modules (see `audit-debt/scripts/checks/`).
+
+## SKILL.md integration
+
+Each skill with scripts must include in `SKILL.md`:
+
+1. Folder tree showing `scripts/` and `assets/`
+2. **Quick start** — copy-pasteable `node <SKILL_DIR>/scripts/….mjs`
+3. **Agent instructions** — resolve skill dir, run script, read output

package/template/README.md

@@ -0,0 +1,60 @@
+# Skills & agents catalog
+
+A git repository of **IDE skills** and **agents** for Cursor, Claude Code, and Codex.
+
+Managed with [ide-agents](https://github.com/sergeychernov/ide-agents) — clone this repo in the UI, then install artifacts globally or per project.
+
+## Layout
+
+```
+.
+├── skills/
+│   └── <skill-id>/
+│       ├── SKILL.md          # required — frontmatter: name, description, scope
+│       ├── scripts/          # optional — *.mjs generators (see .cursor/rules/scripts.mdc)
+│       └── assets/           # optional — JSON/markers for scripts
+├── agents/
+│   └── <agent-id>.md         # orchestrators — call scripts, not inline generators
+├── .cursor/rules/            # Cursor project rules (repo structure)
+├── .claude/CLAUDE.md         # Claude Code project instructions
+└── .agents/AGENTS.md         # Codex project instructions
+```
+
+## SKILL.md frontmatter
+
+```yaml
+---
+name: my-skill
+description: What this skill does.
+scope: any   # global | project | any
+---
+```
+
+## Agents
+
+Agent files live in `agents/<agent-id>.md`. YAML frontmatter:
+
+```yaml
+---
+name: my-agent
+description: When the IDE should delegate to this subagent.
+scope: any   # global | project | any — ide-agents install toggles only
+---
+```
+
+`name` must match the filename stem (`agents/oracle.md` → `name: oracle`). Subagents install to `~/.cursor/agents/<name>.md` (or project `.cursor/agents/`); invoke in Agent mode by name, not via the `/` skill menu.
+
+## Sample artifacts
+
+This repo was bootstrapped with a demo skill and a starter agent. Extend or replace them as you build your catalog.
+
+| Kind | ID | Purpose |
+|------|-----|---------|
+| skill | `hello` | Install smoke-test + `scripts/now.mjs` (system clock) |
+| agent | `oracle` | Joke fortune-teller — always upbeat predictions |
+
+## Next steps
+
+1. Edit or add skills under `skills/` and agents under `agents/`.
+2. Commit and push to your remote.
+3. In ide-agents, open **Skills** / **Agents** and toggle **Global** or **Project** to symlink into your IDE.