@googlarz/agents-sync 1.0.0

package/dist/tools/validate.d.ts

@@ -0,0 +1,22 @@
+export interface ValidateOptions {
+    projectPath: string;
+}
+export type FileStatus = "in-sync" | "drifted" | "missing";
+export interface FileValidation {
+    tool: string;
+    path: string;
+    status: FileStatus;
+    details?: string;
+}
+export interface ValidateResult {
+    canonical: {
+        path: string;
+        exists: boolean;
+    };
+    toolFiles: FileValidation[];
+    allInSync: boolean;
+    hasSnapshot: boolean;
+    report: string;
+}
+export declare function runValidate(options: ValidateOptions): Promise<ValidateResult>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/tools/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/tools/validate.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7C,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAqCD,wBAAsB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAkEnF"}

package/dist/tools/validate.js

@@ -0,0 +1,97 @@
+import path from "node:path";
+import crypto from "node:crypto";
+import { assertProjectDir, readFileSafe, fileExists } from "../lib/file-utils.js";
+import { loadSnapshot } from "../snapshot/writer.js";
+function sha256File(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+const TOOL_PATHS = {
+    "agents-md": "AGENTS.md",
+    claude: "CLAUDE.md",
+    cursor: ".cursorrules",
+    copilot: ".github/copilot-instructions.md",
+    gemini: "GEMINI.md",
+    windsurf: ".windsurfrules",
+    cline: ".clinerules",
+};
+function buildReport(canonical, toolFiles, hasSnapshot) {
+    const lines = [];
+    lines.push(`AGENTS.md (canonical)  ${canonical.exists ? "✓" : "✗ MISSING"}`);
+    lines.push("");
+    for (const f of toolFiles) {
+        const icon = f.status === "in-sync" ? "✓" : f.status === "drifted" ? "⚠" : "✗";
+        const label = f.status === "in-sync" ? "in sync" : f.status;
+        lines.push(`${icon} ${f.tool.padEnd(10)} ${label.padEnd(10)} ${f.path}`);
+        if (f.details)
+            lines.push(`              ${f.details}`);
+    }
+    if (!hasSnapshot) {
+        lines.push("");
+        lines.push("No snapshot found. Run init to establish a baseline.");
+    }
+    return lines.join("\n");
+}
+export async function runValidate(options) {
+    await assertProjectDir(options.projectPath);
+    const snapshot = await loadSnapshot(options.projectPath);
+    const agentsMdPath = path.join(options.projectPath, "AGENTS.md");
+    const canonicalExists = await fileExists(agentsMdPath);
+    if (!snapshot) {
+        // No snapshot: just check which files exist
+        const toolFiles = [];
+        for (const [tool, relPath] of Object.entries(TOOL_PATHS)) {
+            if (tool === "agents-md")
+                continue;
+            const absPath = path.join(options.projectPath, relPath);
+            const exists = await fileExists(absPath);
+            toolFiles.push({
+                tool,
+                path: absPath,
+                status: exists ? "drifted" : "missing",
+                details: exists ? "No snapshot to compare against" : undefined,
+            });
+        }
+        const result = {
+            canonical: { path: agentsMdPath, exists: canonicalExists },
+            toolFiles,
+            allInSync: false,
+            hasSnapshot: false,
+        };
+        return { ...result, report: buildReport(result.canonical, toolFiles, false) };
+    }
+    // Compare current file hashes against snapshot
+    const toolFiles = [];
+    let allInSync = true;
+    for (const managed of snapshot.filesManaged) {
+        if (managed.tool === "agents-md")
+            continue;
+        const currentContent = await readFileSafe(managed.path);
+        if (!currentContent) {
+            toolFiles.push({ tool: managed.tool, path: managed.path, status: "missing" });
+            allInSync = false;
+            continue;
+        }
+        const currentHash = sha256File(currentContent);
+        if (currentHash !== managed.sha256 && managed.sha256 !== "") {
+            toolFiles.push({
+                tool: managed.tool,
+                path: managed.path,
+                status: "drifted",
+                details: "File was modified after last sync",
+            });
+            allInSync = false;
+        }
+        else {
+            toolFiles.push({ tool: managed.tool, path: managed.path, status: "in-sync" });
+        }
+    }
+    const canonical = { path: agentsMdPath, exists: canonicalExists };
+    return {
+        canonical,
+        toolFiles,
+        allInSync,
+        hasSnapshot: true,
+        report: buildReport(canonical, toolFiles, true),
+    };
+}
+//# sourceMappingURL=validate.js.map

package/dist/tools/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/tools/validate.ts"],"names":[],"mappings":"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"}

package/docs/examples/.clinerules

@@ -0,0 +1,29 @@
+# .clinerules — managed by agents-sync v1.0.0
+# Language: TypeScript / Next.js 14
+
+## Conventions
+
+- kebab-case filenames throughout
+- Named exports only (default exports for Next.js pages/layouts only)
+- Zod for all external input validation
+- Co-locate tests (Button.test.tsx next to Button.tsx)
+- Server components by default; 'use client' only when needed
+
+## Always
+
+- Run npm test before committing
+- Validate external API responses with Zod
+- Check middleware.ts before adding /api/ routes
+- Use src/lib/db.ts for all Prisma queries
+
+## Never
+
+- Commit .env or .env.local
+- Import PrismaClient directly (use src/lib/db.ts — pool exhaustion risk)
+- Use TypeScript any (use unknown and narrow)
+- Push directly to main
+- Use console.log in production
+
+## Tests
+
+`npm test`

package/docs/examples/.cursorrules

@@ -0,0 +1,19 @@
+# .cursorrules — managed by agents-sync v1.0.0
+# Language: TypeScript / Next.js 14
+# Run tests: npm test
+
+- Always: use kebab-case filenames (user-profile.tsx not UserProfile.tsx)
+- Always: named exports only (no default exports except Next.js page/layout components)
+- Always: validate external API responses with Zod
+- Always: co-locate tests (Button.test.tsx next to Button.tsx)
+- Always: server components by default — add 'use client' only when needed
+- Always: use cn() from lib/utils.ts for conditional classNames
+- Never: import PrismaClient directly (use src/lib/db.ts — connection pool exhaustion)
+- Never: add /api/ routes without checking middleware.ts auth coverage
+- Never: use date-fns without /utc variants (multi-timezone dashboard)
+- Never: commit .env or .env.local
+- Never: use TypeScript any — use unknown and narrow
+- Never: push directly to main
+- Never: use console.log in production (use logger utility)
+- Tests: npm test
+- Build: npm run build

package/docs/examples/.windsurfrules

@@ -0,0 +1,14 @@
+# .windsurfrules — managed by agents-sync v1.0.0
+# Language: TypeScript / Next.js 14
+
+- Always: use kebab-case filenames
+- Always: named exports only (default exports for Next.js pages/layouts only)
+- Always: validate external input with Zod
+- Always: co-locate tests (*.test.ts next to source)
+- Always: server components by default; 'use client' only when required
+- Never: DB connection is singleton — use src/lib/db.ts, not new PrismaClient()
+- Never: add API routes without checking middleware.ts auth coverage
+- Never: date comparisons without UTC — use date-fns/utc variants
+- Never: commit .env or .env.local
+- Never: TypeScript any
+- Tests: npm test

package/docs/examples/AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md
+
+<!-- Generated by agents-sync v1.0.0 on 2026-05-20 -->
+
+## Project Overview
+
+Acme Dashboard is an internal analytics and reporting platform for the sales team. Built with
+Next.js 14 App Router, PostgreSQL via Prisma ORM, and NextAuth v4 for authentication. Deployed
+on Vercel with a Neon managed Postgres instance.
+
+## Tech Stack
+
+- **Language:** TypeScript
+- **Framework:** Next.js 14 (App Router)
+- **Database:** PostgreSQL via Prisma ORM
+- **Auth:** NextAuth v4
+- **UI:** shadcn/ui + Tailwind CSS
+- **Testing:** Vitest (co-located)
+- **Deployment:** Vercel + Neon
+
+## Architecture
+
+```
+src/
+  app/           Next.js App Router pages and layouts
+  features/      Domain modules: dashboard, reports, users, billing
+  lib/           Shared utilities: db singleton, auth config, api client
+  components/    Shared UI (shadcn/ui based)
+  hooks/         Client-side React hooks
+```
+
+### Key directories
+
+- `src/app/` — Next.js App Router pages and layouts (server components by default)
+- `src/features/` — Feature modules, one directory per domain
+- `src/lib/db.ts` — Prisma client singleton (do not instantiate PrismaClient elsewhere)
+- `src/lib/auth.ts` — NextAuth configuration
+- `src/components/` — Shared, reusable UI components
+
+## Conventions
+
+1. kebab-case filenames throughout (`user-profile.tsx`, not `UserProfile.tsx`)
+2. Named exports only — no default exports except Next.js page/layout components
+3. All external API responses validated with Zod before use
+4. Co-locate tests: `Button.test.tsx` lives next to `Button.tsx`
+5. Use `cn()` from `lib/utils.ts` for conditional className strings
+6. Server components by default; add `'use client'` only when hooks or browser APIs are required
+7. All database queries go through `src/lib/db.ts` — never instantiate PrismaClient directly
+
+## Gotchas
+
+1. **Never import `PrismaClient` directly** — Vercel's serverless runtime creates a new instance
+   per invocation, exhausting the Neon connection pool. Use `src/lib/db.ts` singleton only.
+2. **All API routes require auth middleware** — the `middleware.ts` matcher protects `/api/**`.
+   Any new route outside that pattern must explicitly add auth checks.
+3. **Date comparisons must use UTC** — the dashboard serves users across timezones. Use
+   `date-fns/utc` variants (`formatUTC`, `parseISO`, etc.) not the plain `date-fns` equivalents.
+4. **`src/app/` is server-first** — avoid `useState`/`useEffect` in files under `src/app/`
+   unless they are explicitly `'use client'`. Data fetching belongs in server components.
+
+## Boundaries
+
+### Always do
+
+- Run `npm test` before committing
+- Validate external API responses with Zod
+- Check `middleware.ts` before adding new `/api/` routes
+- Use `src/lib/db.ts` for all Prisma queries
+
+### Ask first
+
+- Database schema changes (Prisma migrations affect production data)
+- Adding new npm dependencies (bundle size matters)
+- Changes to the authentication flow or session handling
+- Modifying `middleware.ts`
+
+### Never
+
+- Commit `.env` or `.env.local`
+- Instantiate `PrismaClient` outside of `src/lib/db.ts`
+- Use TypeScript `any` — use `unknown` and narrow instead
+- Push directly to `main` branch
+- Use `console.log` in production code (use the `logger` utility instead)
+
+## Testing
+
+- **Framework:** Vitest
+- **Run:** `npm test`
+- **Coverage:** `npm run test:coverage`
+- **Location:** Co-located with source (`*.test.ts` / `*.test.tsx`)
+
+## Deployment
+
+- **Target:** Vercel (automatic on push to `main`)
+- **Database:** Neon PostgreSQL (`DATABASE_URL` in environment)
+- **Migrations:** Run `npx prisma migrate deploy` after schema changes
+- **Env:** `.env.local` for local dev; Vercel dashboard for production secrets

package/docs/examples/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+<!-- Derived from AGENTS.md by agents-sync v1.0.0 on 2026-05-20 -->
+<!-- Source: AGENTS.md — edit that file, then run /agents-sync sync -->
+
+## Project Overview
+
+Acme Dashboard is an internal analytics and reporting platform for the sales team. Built with
+Next.js 14 App Router, PostgreSQL via Prisma ORM, and NextAuth v4 for authentication. Deployed
+on Vercel with a Neon managed Postgres instance.
+
+## Tech Stack
+
+- **Language:** TypeScript
+- **Framework:** Next.js 14 (App Router)
+- **Database:** PostgreSQL via Prisma ORM
+- **Auth:** NextAuth v4
+- **UI:** shadcn/ui + Tailwind CSS
+- **Testing:** Vitest (co-located)
+- **Deployment:** Vercel + Neon
+
+## Architecture
+
+- `src/app/` — Next.js App Router pages and layouts (server components by default)
+- `src/features/` — Feature modules, one directory per domain
+- `src/lib/db.ts` — Prisma client singleton (do not instantiate PrismaClient elsewhere)
+- `src/lib/auth.ts` — NextAuth configuration
+- `src/components/` — Shared, reusable UI components
+
+## Conventions
+
+1. kebab-case filenames throughout (`user-profile.tsx`, not `UserProfile.tsx`)
+2. Named exports only — no default exports except Next.js page/layout components
+3. All external API responses validated with Zod before use
+4. Co-locate tests: `Button.test.tsx` lives next to `Button.tsx`
+5. Use `cn()` from `lib/utils.ts` for conditional className strings
+6. Server components by default; add `'use client'` only when hooks or browser APIs are required
+7. All database queries go through `src/lib/db.ts`
+
+## Gotchas
+
+1. **Never import `PrismaClient` directly** — connection pool exhaustion. Use `src/lib/db.ts`.
+2. **All API routes require auth middleware** — `middleware.ts` matcher covers `/api/**`.
+3. **Date comparisons must use UTC** — use `date-fns/utc` variants throughout.
+4. **`src/app/` is server-first** — no hooks/browser APIs unless `'use client'` is declared.
+
+## Boundaries
+
+### Always do
+
+- Run `npm test` before committing
+- Validate external API responses with Zod
+- Check `middleware.ts` before adding new `/api/` routes
+- Use `src/lib/db.ts` for all Prisma queries
+
+### Ask first
+
+- Database schema changes
+- Adding new npm dependencies
+- Changes to authentication flow
+- Modifying `middleware.ts`
+
+### Never
+
+- Commit `.env` or `.env.local`
+- Instantiate `PrismaClient` outside of `src/lib/db.ts`
+- Use TypeScript `any`
+- Push directly to `main`
+- Use `console.log` in production
+
+## Commands
+
+```bash
+npm run dev          # local dev server
+npm test             # run tests
+npm run test:watch   # watch mode
+npm run build        # production build
+npm run lint         # lint
+npx prisma studio    # database GUI
+npx prisma migrate dev  # run migrations locally
+```
+
+## Claude Code notes
+
+- When adding API routes, check `middleware.ts` first to understand auth coverage
+- For UI work, use existing shadcn/ui components from `src/components/ui/`
+- Feature work lives in `src/features/<name>/` — match the existing module structure
+- The Prisma schema is in `prisma/schema.prisma`

package/docs/examples/GEMINI.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+<!-- Derived for Gemini CLI by agents-sync v1.0.0 on 2026-05-20 -->
+
+## Project Overview
+
+Acme Dashboard is an internal analytics and reporting platform for the sales team. Built with
+Next.js 14 App Router, PostgreSQL via Prisma ORM, and NextAuth v4 for authentication.
+
+## Tech Stack
+
+- TypeScript / Next.js 14 (App Router)
+- PostgreSQL via Prisma ORM
+- Auth: NextAuth v4
+- UI: shadcn/ui + Tailwind CSS
+- Testing: Vitest (co-located)
+- Deployment: Vercel + Neon
+
+## Architecture
+
+- `src/app/` — App Router pages and layouts
+- `src/features/` — Domain modules
+- `src/lib/db.ts` — Prisma client singleton
+- `src/components/` — Shared UI
+
+## Conventions
+
+1. kebab-case filenames throughout
+2. Named exports only
+3. Zod for all external input validation
+4. Co-locate tests
+5. Server components by default
+
+## Gotchas
+
+1. Never import PrismaClient directly — use src/lib/db.ts
+2. All API routes protected by middleware.ts
+3. Date comparisons must use UTC (date-fns/utc)
+
+## Boundaries
+
+### Never
+- Commit .env or .env.local
+- Instantiate PrismaClient outside src/lib/db.ts
+- Use TypeScript any
+- Push directly to main
+
+### Always do
+- Run npm test before committing
+- Validate external responses with Zod
+
+## Testing
+
+`npm test`
+
+---
+
+## Gemini CLI Notes
+
+This file is managed by [agents-sync](https://github.com/googlarz/agents-sync). Edit `AGENTS.md`
+then run `agents-sync sync` to regenerate all tool context files.

package/docs/examples/copilot-instructions.md

@@ -0,0 +1,24 @@
+<!-- Managed by agents-sync v1.0.0. Source: AGENTS.md -->
+# GitHub Copilot Instructions — Acme Dashboard
+
+**Stack:** TypeScript · Next.js 14 App Router · Prisma + Neon PostgreSQL · NextAuth v4 · shadcn/ui
+
+## Code rules
+
+- kebab-case filenames; named exports only (default exports for Next.js pages/layouts only)
+- Validate external data with Zod before use
+- Tests co-located: `Foo.test.tsx` next to `Foo.tsx`
+- Server components by default; `'use client'` only for hooks/browser APIs
+
+## Critical constraints
+
+- Database: always use `src/lib/db.ts` singleton — never `new PrismaClient()`
+- Auth: all `/api/` routes are protected by `middleware.ts`; check before adding routes
+- Dates: use `date-fns/utc` variants — dashboard is multi-timezone
+- No `console.log` in production; no TypeScript `any`; no `.env` commits
+
+## Tests
+
+```
+npm test
+```

package/docs/github-action.yml

@@ -0,0 +1,89 @@
+# agents-sync GitHub Action
+#
+# Checks for codebase drift weekly and when package.json/manifest changes.
+# Opens a PR when drift is detected so the team can review and re-sync.
+#
+# Setup:
+#   1. Copy this file to .github/workflows/agents-sync.yml in your repo
+#   2. Add ANTHROPIC_API_KEY to your repository secrets
+#      (Settings → Secrets and variables → Actions → New repository secret)
+#   3. Commit and push
+
+name: agents-sync drift check
+
+on:
+  schedule:
+    # Run every Monday at 9am UTC
+    - cron: "0 9 * * 1"
+  push:
+    paths:
+      # Re-check whenever a manifest or major structure file changes
+      - "package.json"
+      - "pyproject.toml"
+      - "Cargo.toml"
+      - "go.mod"
+      - "composer.json"
+  workflow_dispatch:
+    inputs:
+      force_sync:
+        description: "Force a full re-sync even if drift is low"
+        type: boolean
+        default: false
+
+jobs:
+  drift-check:
+    name: Check AI context drift
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Check drift
+        id: drift
+        run: npx @googlarz/agents-sync drift . --ci
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          NO_COLOR: "1"
+        # --ci exits with code 1 when drift is HIGH; the step fails,
+        # which triggers the sync step below.
+        continue-on-error: true
+
+      - name: Re-sync context files
+        if: steps.drift.outcome == 'failure' || inputs.force_sync == true
+        run: npx @googlarz/agents-sync sync .
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          NO_COLOR: "1"
+
+      - name: Open PR with updated files
+        if: steps.drift.outcome == 'failure' || inputs.force_sync == true
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore: re-sync AI context files"
+          title: "chore: re-sync AI context files (agents-sync)"
+          body: |
+            Codebase drift detected. agents-sync has re-generated the AI context files.
+
+            **Files updated:**
+            - `AGENTS.md` — canonical source
+            - `CLAUDE.md` — Claude Code
+            - `.cursorrules` — Cursor
+            - `.github/copilot-instructions.md` — GitHub Copilot
+            - `GEMINI.md` — Gemini CLI
+            - `.windsurfrules` — Windsurf
+            - `.clinerules` — Cline
+
+            Review the diff and merge to keep your AI tools in sync.
+
+            > Generated by [agents-sync](https://github.com/googlarz/agents-sync)
+          branch: "agents-sync/update"
+          delete-branch: true
+          labels: "ai-context,automated"

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@googlarz/agents-sync",
+  "version": "1.0.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"
+  }
+}