@googlarz/agents-sync 1.4.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@googlarz/agents-sync",
+  "version": "1.4.0",
+  "description": "Write your AI context once. One canonical AGENTS.md auto-derived into CLAUDE.md, .cursorrules, copilot-instructions.md, GEMINI.md, .windsurfrules, and .clinerules.",
+  "keywords": ["claude", "cursor", "mcp", "agents", "ai", "codegen", "context", "agentsmd", "cursorrules", "windsurf", "cline", "gemini", "agents-sync"],
+  "homepage": "https://github.com/googlarz/agents-sync#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/googlarz/agents-sync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/googlarz/agents-sync/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "googlarz",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "agents-sync": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "skill/",
+    "docs/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test": "vitest run --reporter verbose",
+    "test:watch": "vitest",
+    "test:integration": "INTEGRATION=1 vitest run tests/integration --reporter verbose",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "fast-glob": "^3.3.3",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "@typescript-eslint/eslint-plugin": "^8.32.1",
+    "@typescript-eslint/parser": "^8.32.1",
+    "@vitest/coverage-v8": "^3.1.4",
+    "eslint": "^9.27.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
+  }
+}

package/scripts/demo.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# agents-sync demo script
+#
+# Shows the full agents-sync workflow using a temporary Next.js fixture.
+# Records cleanly with: asciinema rec demo.cast --command ./scripts/demo.sh
+#
+# Prerequisites:
+#   export ANTHROPIC_API_KEY=sk-ant-...
+#   npm run build  (or: npx @googlarz/agents-sync)
+
+set -euo pipefail
+
+AGENTS_SYNC="${AGENTS_SYNC_BIN:-node dist/cli.js}"
+DEMO_DIR="$(mktemp -d)"
+trap 'rm -rf "$DEMO_DIR"' EXIT
+
+# ─── helpers ─────────────────────────────────────────────────────────────────
+
+say()  { printf '\n\033[1;36m%s\033[0m\n' "$*"; }
+run()  { printf '\033[0;33m$ %s\033[0m\n' "$*"; sleep 0.4; eval "$*"; }
+pause(){ sleep "${1:-1.2}"; }
+
+# ─── scaffold a minimal Next.js project ──────────────────────────────────────
+
+say "Setting up a minimal Next.js project..."
+
+mkdir -p "$DEMO_DIR/src/app" "$DEMO_DIR/src/lib" "$DEMO_DIR/src/components"
+
+cat > "$DEMO_DIR/package.json" <<'EOF'
+{
+  "name": "acme-dashboard",
+  "version": "0.1.0",
+  "description": "Internal analytics dashboard for the sales team",
+  "scripts": { "dev": "next dev", "build": "next build", "test": "vitest" },
+  "dependencies": {
+    "next": "14.2.3",
+    "react": "^18.3.1",
+    "@prisma/client": "^5.15.0",
+    "next-auth": "^4.24.7",
+    "zod": "^3.23.8",
+    "tailwindcss": "^3.4.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "prisma": "^5.15.0",
+    "vitest": "^1.6.0"
+  }
+}
+EOF
+
+cat > "$DEMO_DIR/src/lib/db.ts" <<'EOF'
+// IMPORTANT: Never import PrismaClient directly — use this singleton.
+// Direct imports exhaust the connection pool in Vercel's serverless runtime.
+import { PrismaClient } from "@prisma/client";
+
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
+export const db = globalForPrisma.prisma ?? new PrismaClient();
+if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = db;
+EOF
+
+cat > "$DEMO_DIR/src/app/page.tsx" <<'EOF'
+import { db } from "../lib/db";
+
+export default async function DashboardPage() {
+  const stats = await db.report.count();
+  return <main><h1>Dashboard</h1><p>Total reports: {stats}</p></main>;
+}
+EOF
+
+cat > "$DEMO_DIR/README.md" <<'EOF'
+# Acme Dashboard
+
+Internal analytics and reporting platform for the sales team.
+
+Built with Next.js 14, Prisma, and NextAuth.
+EOF
+
+pause
+
+# ─── 1. agents-sync init ─────────────────────────────────────────────────────
+
+say "Step 1: Initialize agents-sync (scans codebase → Claude API → generates all files)"
+run "$AGENTS_SYNC init $DEMO_DIR"
+
+pause 2
+
+# ─── 2. show generated files ─────────────────────────────────────────────────
+
+say "Step 2: View the generated files"
+run "ls -1 $DEMO_DIR/*.md $DEMO_DIR/.cursor* $DEMO_DIR/.github/copilot-instructions.md $DEMO_DIR/GEMINI.md $DEMO_DIR/.windsurfrules $DEMO_DIR/.clinerules 2>/dev/null || ls $DEMO_DIR"
+
+pause 1.5
+
+say "The canonical AGENTS.md:"
+run "head -40 $DEMO_DIR/AGENTS.md"
+
+pause 1.5
+
+say "The derived .cursorrules (directive-style, <400 words):"
+run "cat $DEMO_DIR/.cursorrules"
+
+pause
+
+# ─── 3. simulate a codebase change ───────────────────────────────────────────
+
+say "Step 3: Simulate a dependency change (add drizzle-orm)"
+run "node -e \"const p=require('$DEMO_DIR/package.json'); p.dependencies['drizzle-orm']='^0.31.0'; require('fs').writeFileSync('$DEMO_DIR/package.json', JSON.stringify(p, null, 2));\""
+
+# also add a new directory
+run "mkdir -p $DEMO_DIR/src/workers && touch $DEMO_DIR/src/workers/report-worker.ts"
+
+pause
+
+# ─── 4. drift check ──────────────────────────────────────────────────────────
+
+say "Step 4: Check what drifted"
+run "$AGENTS_SYNC drift $DEMO_DIR"
+
+pause 1.5
+
+# ─── 5. re-sync ──────────────────────────────────────────────────────────────
+
+say "Step 5: Re-sync to update all files"
+run "$AGENTS_SYNC sync $DEMO_DIR"
+
+pause
+
+# ─── 6. validate ─────────────────────────────────────────────────────────────
+
+say "Step 6: Validate all files are in sync"
+run "$AGENTS_SYNC validate $DEMO_DIR"
+
+pause
+
+# ─── done ────────────────────────────────────────────────────────────────────
+
+say "Done! One AGENTS.md, six tool files, always in sync."
+printf '\n\033[0;32m%s\033[0m\n\n' "npx @googlarz/agents-sync — try it on your project"

package/skill/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: agents-sync
+description: Generate and sync AI context files (AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions.md, GEMINI.md, .windsurfrules, .clinerules) from your codebase. One canonical source, every tool stays current.
+version: 1.0.0
+---
+
+# agents-sync
+
+Generate and sync AI context files across every coding tool you use.
+
+## Prerequisites
+
+Add to your Claude Code MCP config (`.claude/settings.json` or `~/.claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agents-sync": {
+      "command": "npx",
+      "args": ["@googlarz/agents-sync"],
+      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
+    }
+  }
+}
+```
+
+Then restart Claude Code to connect.
+
+## Commands
+
+### `/agents-sync init`
+
+First-time setup. Reads your codebase and generates all context files.
+
+**When to use:** New project, or starting from scratch.
+
+**What it does:**
+1. Scans your codebase (manifests, structure, source samples, docs, TODO/FIXME comments)
+2. Extracts project metadata via Claude API
+3. Generates canonical `AGENTS.md`
+4. Derives `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, `GEMINI.md`, `.windsurfrules`, `.clinerules`
+5. Saves a snapshot for drift detection
+
+**Usage:**
+> Run `/agents-sync init` on this project
+
+Claude will call `agents_sync_init` with the current project path.
+
+---
+
+### `/agents-sync sync`
+
+Re-sync after your codebase has changed. Preserves any manual customizations.
+
+**When to use:** After major refactors, new dependencies, architecture changes.
+
+**Options:**
+- Add `--fast` to skip Claude API call when drift is minor (re-derives from existing AGENTS.md)
+- Add `--dry-run` to preview changes without writing
+
+**Usage:**
+> Sync my AI context files
+> `/agents-sync sync --fast`
+
+---
+
+### `/agents-sync drift`
+
+Check what changed in your codebase since the last sync. Read-only.
+
+**Usage:**
+> What's drifted in my AI context files?
+> `/agents-sync drift`
+
+---
+
+### `/agents-sync export [tool]`
+
+Re-derive a single tool file without re-running analysis.
+
+**Tools:** `claude`, `cursor`, `copilot`, `gemini`, `windsurf`, `cline`
+
+**Usage:**
+> `/agents-sync export cursor`
+> Regenerate just my .cursorrules
+
+---
+
+### `/agents-sync validate`
+
+Check whether all managed files are in sync with AGENTS.md.
+
+**Usage:**
+> `/agents-sync validate`
+> Are my AI context files in sync?
+
+---
+
+### `/agents-sync status`
+
+Show sync status: last sync time, managed files, drift score.
+
+**Usage:**
+> `/agents-sync status`
+
+---
+
+## How Claude Should Handle These Commands
+
+When the user types `/agents-sync <command>`, call the corresponding MCP tool:
+
+| Command | MCP Tool | Required params |
+|---|---|---|
+| `init` | `agents_sync_init` | `projectPath` = cwd |
+| `sync` | `agents_sync_sync` | `projectPath` = cwd |
+| `drift` | `agents_sync_drift` | `projectPath` = cwd |
+| `export <tool>` | `agents_sync_export` | `projectPath` = cwd, `tool` = argument |
+| `validate` | `agents_sync_validate` | `projectPath` = cwd |
+| `status` | `agents_sync_status` | `projectPath` = cwd |
+
+**Determine `projectPath`:** Use the current working directory. If ambiguous, ask the user which project to target.
+
+**If MCP not connected:** Respond with:
+> agents-sync MCP server is not connected. Add this to your Claude Code settings and restart:
+> ```json
+> {
+>   "mcpServers": {
+>     "agents-sync": {
+>       "command": "npx",
+>       "args": ["@googlarz/agents-sync"],
+>       "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
+>     }
+>   }
+> }
+> ```
+
+**After init:** Remind the user to:
+1. Add `AGENTS.md` to git
+2. Add `.agents-sync/` to `.gitignore`
+
+**After sync:** Show the list of files updated.
+
+**Flags parsing:**
+- `--fast` → set `fast: true` in `agents_sync_sync`
+- `--dry-run` → set `dryRun: true`
+
+## Custom Sections
+
+Users can add permanent customizations to any managed file that survive re-syncs:
+
+```markdown
+<!-- AGENTS-SYNC:CUSTOM:START -->
+When working on the payments module, always check with @alice first.
+Use staging Stripe keys (in .env.staging) for all local testing.
+<!-- AGENTS-SYNC:CUSTOM:END -->
+```
+
+Add this anywhere in `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`, or `.clinerules`. Re-sync preserves it.