@dezkareid/ai-context-sync 0.0.1 → 1.1.0

package/README.md

@@ -1,45 +1,63 @@
 # @dezkareid/ai-context-sync
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+A CLI utility to synchronize AI agent context files across different providers, using `AGENTS.md` as the source of truth.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Features
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+- **Source of Truth**: Uses `AGENTS.md` to define project context, rules, and workflows.
+- **Multi-provider support**:
+  - **Claude**: Generates/updates `CLAUDE.md`.
+  - **Gemini**: Configures `.gemini/settings.json` to use `AGENTS.md`.
+  - **Gemini Markdown**: Generates/updates `GEMINI.md`.
+- **Plugin Architecture**: Easily extendable to support other AI agents.
 
-## Purpose
+## Installation
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@dezkareid/ai-context-sync`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+```bash
+pnpm install @dezkareid/ai-context-sync
+```
 
-## What is OIDC Trusted Publishing?
+## Usage
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+### Synchronize context
 
-## Setup Instructions
+Run the sync command in your project root (where `AGENTS.md` is located):
 
-To properly configure OIDC trusted publishing for this package:
+```bash
+npx @dezkareid/ai-context-sync sync
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+You can select the strategy using the `--strategy` (or `-s`) option:
 
-## DO NOT USE THIS PACKAGE
+```bash
+npx @dezkareid/ai-context-sync sync --strategy claude
+npx @dezkareid/ai-context-sync sync --strategy gemini
+npx @dezkareid/ai-context-sync sync --strategy all
+npx @dezkareid/ai-context-sync sync --strategy "claude, gemini"
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+If no strategy is provided, an interactive checkbox menu will appear to let you toggle which strategies to run.
 
-## More Information
+### Configuration
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+The tool can save your selected strategies in a `.ai-context-configrc` file in the project root. This avoids being prompted every time you run the command.
 
----
+To bypass reading or creating this configuration file, use the `--skip-config` flag:
 
-**Maintained for OIDC setup purposes only**
+```bash
+npx @dezkareid/ai-context-sync sync --skip-config
+```
+
+### Directory option
+
+## How it works
+
+1. The tool looks for an `AGENTS.md` file in the target directory.
+2. It reads the content of `AGENTS.md`.
+3. It applies different strategies to update provider-specific files:
+   - **Claude**: Creates a symbolic link `CLAUDE.md` pointing to `AGENTS.md`.
+   - **Gemini**: Updates `.gemini/settings.json` to include `AGENTS.md` in the `context.fileName` list.
+
+## License
+
+ISC

package/dist/constants.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_FILENAME = exports.AGENTS_FILENAME = void 0;
+exports.AGENTS_FILENAME = 'AGENTS.md';
+exports.CONFIG_FILENAME = '.ai-context-configrc';

package/dist/engine.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncEngine = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const constants_js_1 = require("./constants.js");
+const claude_js_1 = require("./strategies/claude.js");
+const gemini_js_1 = require("./strategies/gemini.js");
+const gemini_md_js_1 = require("./strategies/gemini-md.js");
+class SyncEngine {
+    allStrategies = [
+        new claude_js_1.ClaudeStrategy(),
+        new gemini_js_1.GeminiStrategy(),
+        new gemini_md_js_1.GeminiMdStrategy()
+    ];
+    async sync(projectRoot, selectedStrategies) {
+        const agentsPath = path_1.default.join(projectRoot, constants_js_1.AGENTS_FILENAME);
+        if (!(await fs_extra_1.default.pathExists(agentsPath))) {
+            throw new Error(`${constants_js_1.AGENTS_FILENAME} not found in ${projectRoot}`);
+        }
+        const context = await fs_extra_1.default.readFile(agentsPath, 'utf-8');
+        let strategiesToRun;
+        if (!selectedStrategies || (Array.isArray(selectedStrategies) && selectedStrategies.length === 0)) {
+            strategiesToRun = this.allStrategies;
+        }
+        else {
+            const selectedList = Array.isArray(selectedStrategies) ? selectedStrategies : [selectedStrategies];
+            const normalizedList = selectedList.map(s => s.toLowerCase());
+            if (normalizedList.includes('all') || normalizedList.includes('both')) {
+                strategiesToRun = this.allStrategies;
+            }
+            else {
+                strategiesToRun = this.allStrategies.filter(s => normalizedList.includes(s.name.toLowerCase()));
+            }
+        }
+        const availableNames = this.allStrategies.map(s => s.name).join(', ');
+        if (strategiesToRun.length === 0 && selectedStrategies) {
+            throw new Error(`No valid strategies found for: ${selectedStrategies}. Available strategies: ${availableNames}`);
+        }
+        for (const strategy of strategiesToRun) {
+            console.log(`Syncing for ${strategy.name}...`);
+            await strategy.sync(context, projectRoot);
+        }
+    }
+}
+exports.SyncEngine = SyncEngine;

package/dist/engine.test.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const engine_js_1 = require("./engine.js");
+const constants_js_1 = require("./constants.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+(0, vitest_1.describe)('SyncEngine', () => {
+    let tempDir;
+    (0, vitest_1.beforeEach)(async () => {
+        tempDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'sync-engine-test-'));
+    });
+    (0, vitest_1.afterEach)(async () => {
+        await fs_extra_1.default.remove(tempDir);
+    });
+    (0, vitest_1.it)('should throw error if AGENTS.md is missing', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        await (0, vitest_1.expect)(engine.sync(tempDir)).rejects.toThrow(`${constants_js_1.AGENTS_FILENAME} not found`);
+    });
+    (0, vitest_1.it)('should run all strategies when AGENTS.md exists', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        const context = '# Agent Context';
+        await fs_extra_1.default.writeFile(agentsPath, context);
+        await engine.sync(tempDir);
+        // Verify Claude
+        const claudePath = path_1.default.join(tempDir, 'CLAUDE.md');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(claudePath)).toBe(true);
+        (0, vitest_1.expect)(await fs_extra_1.default.readFile(claudePath, 'utf-8')).toBe(context);
+        // Verify Gemini
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(settingsPath)).toBe(true);
+        const settings = await fs_extra_1.default.readJson(settingsPath);
+        (0, vitest_1.expect)(settings.context.fileName).toContain(constants_js_1.AGENTS_FILENAME);
+    });
+    (0, vitest_1.it)('should run only Claude strategy when selected', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, 'claude');
+        const claudePath = path_1.default.join(tempDir, 'CLAUDE.md');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(claudePath)).toBe(true);
+        const geminiDir = path_1.default.join(tempDir, '.gemini');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(geminiDir)).toBe(false);
+    });
+    (0, vitest_1.it)('should run only Gemini strategy when selected', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, 'gemini');
+        const claudePath = path_1.default.join(tempDir, 'CLAUDE.md');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(claudePath)).toBe(false);
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(settingsPath)).toBe(true);
+    });
+    (0, vitest_1.it)('should run Gemini Markdown strategy when selected', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, 'gemini-md');
+        const geminiMdPath = path_1.default.join(tempDir, 'GEMINI.md');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(geminiMdPath)).toBe(true);
+        const stats = await fs_extra_1.default.lstat(geminiMdPath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+    });
+    (0, vitest_1.it)('should run multiple selected strategies from array', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, ['claude', 'gemini']);
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(path_1.default.join(tempDir, 'CLAUDE.md'))).toBe(true);
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(path_1.default.join(tempDir, '.gemini', 'settings.json'))).toBe(true);
+    });
+    (0, vitest_1.it)('should run all strategies when "all" is selected', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, 'all');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(path_1.default.join(tempDir, 'CLAUDE.md'))).toBe(true);
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(path_1.default.join(tempDir, '.gemini', 'settings.json'))).toBe(true);
+    });
+    (0, vitest_1.it)('should throw error for invalid strategy', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await (0, vitest_1.expect)(engine.sync(tempDir, 'invalid')).rejects.toThrow('No valid strategies found for: invalid. Available strategies: claude, gemini, gemini-md');
+    });
+});

package/dist/index.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const engine_js_1 = require("./engine.js");
+const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const constants_js_1 = require("./constants.js");
+const program = new commander_1.Command();
+program
+    .name('ai-context-sync')
+    .description('Sync AI context files across different providers')
+    .version('1.0.0');
+program
+    .command('sync')
+    .description('Synchronize context files from AGENTS.md')
+    .option('-d, --dir <path>', 'Project directory', process.cwd())
+    .option('-s, --strategy <strategy>', 'Sync strategy (claude, gemini, all, or comma-separated list)')
+    .option('--skip-config', 'Avoid reading/creating the config file', false)
+    .action(async (options) => {
+    try {
+        const projectRoot = path_1.default.resolve(options.dir);
+        const configPath = path_1.default.join(projectRoot, constants_js_1.CONFIG_FILENAME);
+        let strategy = options.strategy;
+        // 1. If no strategy provided, try to read from config
+        if (!strategy && !options.skipConfig) {
+            if (await fs_extra_1.default.pathExists(configPath)) {
+                try {
+                    const config = await fs_extra_1.default.readJson(configPath);
+                    if (config.strategies) {
+                        strategy = config.strategies;
+                    }
+                }
+                catch (e) {
+                    // Ignore corrupted config and proceed to prompt
+                }
+            }
+        }
+        // 2. If still no strategy, prompt user
+        if (!strategy) {
+            const answers = await inquirer_1.default.prompt([
+                {
+                    type: 'checkbox',
+                    name: 'strategies',
+                    message: 'Select the AI context files to sync:',
+                    choices: [
+                        { name: 'Claude (CLAUDE.md)', value: 'claude', checked: true },
+                        { name: 'Gemini (.gemini/settings.json)', value: 'gemini', checked: true },
+                        { name: 'Gemini Markdown (GEMINI.md)', value: 'gemini-md', checked: true }
+                    ],
+                    validate: (answer) => {
+                        if (answer.length < 1) {
+                            return 'You must choose at least one strategy.';
+                        }
+                        return true;
+                    }
+                }
+            ]);
+            strategy = answers.strategies;
+        }
+        else if (typeof strategy === 'string') {
+            strategy = strategy.split(',').map(s => s.trim());
+        }
+        // 3. Save strategy to config if not skipping
+        if (!options.skipConfig) {
+            await fs_extra_1.default.writeJson(configPath, { strategies: strategy }, { spaces: 2 });
+        }
+        const engine = new engine_js_1.SyncEngine();
+        await engine.sync(projectRoot, strategy);
+        const strategyMsg = Array.isArray(strategy) ? strategy.join(', ') : strategy;
+        console.log(`Successfully synchronized context files using "${strategyMsg}"!`);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/strategies/claude.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaudeStrategy = void 0;
+const symlink_js_1 = require("./symlink.js");
+class ClaudeStrategy extends symlink_js_1.SymlinkStrategy {
+    name = 'claude';
+    targetFilename = 'CLAUDE.md';
+}
+exports.ClaudeStrategy = ClaudeStrategy;

package/dist/strategies/claude.test.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const claude_js_1 = require("./claude.js");
+const constants_js_1 = require("../constants.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+(0, vitest_1.describe)('ClaudeStrategy', () => {
+    let tempDir;
+    (0, vitest_1.beforeEach)(async () => {
+        tempDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'claude-strategy-test-'));
+    });
+    (0, vitest_1.afterEach)(async () => {
+        await fs_extra_1.default.remove(tempDir);
+    });
+    (0, vitest_1.it)('should create a symbolic link CLAUDE.md pointing to AGENTS.md', async () => {
+        const strategy = new claude_js_1.ClaudeStrategy();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agents');
+        await strategy.sync('# Agents', tempDir);
+        const claudePath = path_1.default.join(tempDir, 'CLAUDE.md');
+        const stats = await fs_extra_1.default.lstat(claudePath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+        const target = await fs_extra_1.default.readlink(claudePath);
+        (0, vitest_1.expect)(target).toBe(constants_js_1.AGENTS_FILENAME);
+    });
+});

package/dist/strategies/gemini-md.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiMdStrategy = void 0;
+const symlink_js_1 = require("./symlink.js");
+class GeminiMdStrategy extends symlink_js_1.SymlinkStrategy {
+    name = 'gemini-md';
+    targetFilename = 'GEMINI.md';
+}
+exports.GeminiMdStrategy = GeminiMdStrategy;

package/dist/strategies/gemini-md.test.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const gemini_md_js_1 = require("./gemini-md.js");
+const index_js_1 = require("./index.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+(0, vitest_1.describe)('GeminiMdStrategy', () => {
+    let tempDir;
+    let strategy;
+    (0, vitest_1.beforeEach)(async () => {
+        tempDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'gemini-md-strategy-test-'));
+        await fs_extra_1.default.writeFile(path_1.default.join(tempDir, index_js_1.AGENTS_FILE), '# Agents');
+        strategy = new gemini_md_js_1.GeminiMdStrategy();
+    });
+    (0, vitest_1.afterEach)(async () => {
+        await fs_extra_1.default.remove(tempDir);
+    });
+    (0, vitest_1.it)('should create a symbolic link GEMINI.md pointing to AGENTS.md', async () => {
+        await strategy.sync('', tempDir);
+        const targetPath = path_1.default.join(tempDir, 'GEMINI.md');
+        const stats = await fs_extra_1.default.lstat(targetPath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        (0, vitest_1.expect)(target).toBe(index_js_1.AGENTS_FILE);
+    });
+});

package/dist/strategies/gemini.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiStrategy = void 0;
+const index_js_1 = require("./index.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+class GeminiStrategy {
+    name = 'gemini';
+    async sync(_context, projectRoot) {
+        const geminiDir = path_1.default.join(projectRoot, '.gemini');
+        const settingsPath = path_1.default.join(geminiDir, 'settings.json');
+        await fs_extra_1.default.ensureDir(geminiDir);
+        let settings = {};
+        let exists = false;
+        if (await fs_extra_1.default.pathExists(settingsPath)) {
+            exists = true;
+            try {
+                settings = await fs_extra_1.default.readJson(settingsPath);
+            }
+            catch (e) {
+                settings = {};
+            }
+        }
+        if (!settings.context) {
+            settings.context = {};
+        }
+        const currentFiles = settings.context.fileName;
+        let modified = false;
+        if (Array.isArray(currentFiles)) {
+            if (!currentFiles.includes(index_js_1.AGENTS_FILE)) {
+                settings.context.fileName = [...currentFiles, index_js_1.AGENTS_FILE];
+                modified = true;
+            }
+        }
+        else if (typeof currentFiles === 'string') {
+            if (currentFiles !== index_js_1.AGENTS_FILE) {
+                settings.context.fileName = [currentFiles, index_js_1.AGENTS_FILE];
+                modified = true;
+            }
+        }
+        else {
+            settings.context.fileName = [index_js_1.AGENTS_FILE];
+            modified = true;
+        }
+        if (modified || !exists) {
+            await fs_extra_1.default.writeJson(settingsPath, settings, { spaces: 2 });
+        }
+    }
+}
+exports.GeminiStrategy = GeminiStrategy;

package/dist/strategies/gemini.test.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const gemini_js_1 = require("./gemini.js");
+const constants_js_1 = require("../constants.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+(0, vitest_1.describe)('GeminiStrategy', () => {
+    let tempDir;
+    (0, vitest_1.beforeEach)(async () => {
+        tempDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'gemini-strategy-test-'));
+    });
+    (0, vitest_1.afterEach)(async () => {
+        await fs_extra_1.default.remove(tempDir);
+    });
+    (0, vitest_1.it)('should create .gemini/settings.json if it does not exist', async () => {
+        const strategy = new gemini_js_1.GeminiStrategy();
+        await strategy.sync('context', tempDir);
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(settingsPath)).toBe(true);
+        const settings = await fs_extra_1.default.readJson(settingsPath);
+        (0, vitest_1.expect)(settings.context.fileName).toContain(constants_js_1.AGENTS_FILENAME);
+    });
+    (0, vitest_1.it)('should update existing context.fileName array', async () => {
+        const strategy = new gemini_js_1.GeminiStrategy();
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(settingsPath));
+        await fs_extra_1.default.writeJson(settingsPath, {
+            context: {
+                fileName: ['OTHER.md']
+            }
+        });
+        await strategy.sync('context', tempDir);
+        const settings = await fs_extra_1.default.readJson(settingsPath);
+        (0, vitest_1.expect)(settings.context.fileName).toContain('OTHER.md');
+        (0, vitest_1.expect)(settings.context.fileName).toContain(constants_js_1.AGENTS_FILENAME);
+    });
+    (0, vitest_1.it)('should convert string fileName to array and add AGENTS.md', async () => {
+        const strategy = new gemini_js_1.GeminiStrategy();
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(settingsPath));
+        await fs_extra_1.default.writeJson(settingsPath, {
+            context: {
+                fileName: 'OTHER.md'
+            }
+        });
+        await strategy.sync('context', tempDir);
+        const settings = await fs_extra_1.default.readJson(settingsPath);
+        (0, vitest_1.expect)(Array.isArray(settings.context.fileName)).toBe(true);
+        (0, vitest_1.expect)(settings.context.fileName).toContain('OTHER.md');
+        (0, vitest_1.expect)(settings.context.fileName).toContain(constants_js_1.AGENTS_FILENAME);
+    });
+    (0, vitest_1.it)('should not add AGENTS.md twice', async () => {
+        const strategy = new gemini_js_1.GeminiStrategy();
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(settingsPath));
+        await fs_extra_1.default.writeJson(settingsPath, {
+            context: {
+                fileName: [constants_js_1.AGENTS_FILENAME]
+            }
+        });
+        await strategy.sync('context', tempDir);
+        const settings = await fs_extra_1.default.readJson(settingsPath);
+        (0, vitest_1.expect)(settings.context.fileName.filter((f) => f === constants_js_1.AGENTS_FILENAME).length).toBe(1);
+    });
+    (0, vitest_1.it)('should not write to settings.json if AGENTS.md is already present', async () => {
+        const strategy = new gemini_js_1.GeminiStrategy();
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(settingsPath));
+        await fs_extra_1.default.writeJson(settingsPath, {
+            context: {
+                fileName: [constants_js_1.AGENTS_FILENAME]
+            }
+        });
+        const mtimeBefore = (await fs_extra_1.default.stat(settingsPath)).mtimeMs;
+        // Wait a bit to ensure mtime would change if written
+        await new Promise(resolve => setTimeout(resolve, 10));
+        await strategy.sync('context', tempDir);
+        const mtimeAfter = (await fs_extra_1.default.stat(settingsPath)).mtimeMs;
+        (0, vitest_1.expect)(mtimeAfter).toBe(mtimeBefore);
+    });
+    (0, vitest_1.it)('should not write to settings.json if fileName is already AGENTS.md as a string', async () => {
+        const strategy = new gemini_js_1.GeminiStrategy();
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(settingsPath));
+        await fs_extra_1.default.writeJson(settingsPath, {
+            context: {
+                fileName: constants_js_1.AGENTS_FILENAME
+            }
+        });
+        const mtimeBefore = (await fs_extra_1.default.stat(settingsPath)).mtimeMs;
+        await new Promise(resolve => setTimeout(resolve, 10));
+        await strategy.sync('context', tempDir);
+        const mtimeAfter = (await fs_extra_1.default.stat(settingsPath)).mtimeMs;
+        (0, vitest_1.expect)(mtimeAfter).toBe(mtimeBefore);
+    });
+    (0, vitest_1.it)('should handle invalid JSON in settings.json by starting fresh', async () => {
+        const strategy = new gemini_js_1.GeminiStrategy();
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(settingsPath));
+        await fs_extra_1.default.writeFile(settingsPath, 'not a json');
+        await strategy.sync('context', tempDir);
+        const settings = await fs_extra_1.default.readJson(settingsPath);
+        (0, vitest_1.expect)(settings.context.fileName).toContain(constants_js_1.AGENTS_FILENAME);
+    });
+});

package/dist/strategies/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENTS_FILE = void 0;
+const constants_js_1 = require("../constants.js");
+exports.AGENTS_FILE = constants_js_1.AGENTS_FILENAME;

package/dist/strategies/symlink.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SymlinkStrategy = void 0;
+const index_js_1 = require("./index.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+class SymlinkStrategy {
+    async sync(_context, projectRoot) {
+        const targetPath = path_1.default.join(projectRoot, this.targetFilename);
+        // Check if it exists and what type it is
+        if (await fs_extra_1.default.pathExists(targetPath)) {
+            const stats = await fs_extra_1.default.lstat(targetPath);
+            if (stats.isSymbolicLink()) {
+                const target = await fs_extra_1.default.readlink(targetPath);
+                if (target === index_js_1.AGENTS_FILE) {
+                    // Already points to AGENTS.md, nothing to do
+                    return;
+                }
+            }
+            // If it's a file or a link to somewhere else, remove it
+            await fs_extra_1.default.remove(targetPath);
+        }
+        // Create relative symlink
+        await fs_extra_1.default.ensureSymlink(index_js_1.AGENTS_FILE, targetPath);
+    }
+}
+exports.SymlinkStrategy = SymlinkStrategy;

package/dist/strategies/symlink.test.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const symlink_js_1 = require("./symlink.js");
+const index_js_1 = require("./index.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+class TestSymlinkStrategy extends symlink_js_1.SymlinkStrategy {
+    name = 'test';
+    targetFilename = 'TEST.md';
+}
+(0, vitest_1.describe)('SymlinkStrategy', () => {
+    let tempDir;
+    let strategy;
+    (0, vitest_1.beforeEach)(async () => {
+        tempDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'symlink-strategy-test-'));
+        await fs_extra_1.default.writeFile(path_1.default.join(tempDir, index_js_1.AGENTS_FILE), '# Agents');
+        strategy = new TestSymlinkStrategy();
+    });
+    (0, vitest_1.afterEach)(async () => {
+        await fs_extra_1.default.remove(tempDir);
+    });
+    (0, vitest_1.it)('should create a symlink to AGENTS.md', async () => {
+        await strategy.sync('', tempDir);
+        const targetPath = path_1.default.join(tempDir, 'TEST.md');
+        const stats = await fs_extra_1.default.lstat(targetPath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        // It might be absolute or relative depending on environment/implementation
+        (0, vitest_1.expect)(target).toContain(index_js_1.AGENTS_FILE);
+    });
+    (0, vitest_1.it)('should not recreate symlink if it already points to AGENTS.md', async () => {
+        const targetPath = path_1.default.join(tempDir, 'TEST.md');
+        await fs_extra_1.default.ensureSymlink(index_js_1.AGENTS_FILE, targetPath);
+        // Get initial mtime
+        const initialStats = await fs_extra_1.default.lstat(targetPath);
+        await strategy.sync('', tempDir);
+        const finalStats = await fs_extra_1.default.lstat(targetPath);
+        (0, vitest_1.expect)(finalStats.mtimeMs).toBe(initialStats.mtimeMs);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        (0, vitest_1.expect)(target).toBe(index_js_1.AGENTS_FILE);
+    });
+    (0, vitest_1.it)('should recreate symlink if it points elsewhere', async () => {
+        const targetPath = path_1.default.join(tempDir, 'TEST.md');
+        const otherFile = path_1.default.join(tempDir, 'OTHER.md');
+        await fs_extra_1.default.writeFile(otherFile, 'other content');
+        await fs_extra_1.default.ensureSymlink('OTHER.md', targetPath);
+        await strategy.sync('', tempDir);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        (0, vitest_1.expect)(target).toBe(index_js_1.AGENTS_FILE);
+    });
+    (0, vitest_1.it)('should replace existing file with a symlink', async () => {
+        const targetPath = path_1.default.join(tempDir, 'TEST.md');
+        await fs_extra_1.default.writeFile(targetPath, 'existing file');
+        await strategy.sync('', tempDir);
+        const stats = await fs_extra_1.default.lstat(targetPath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        (0, vitest_1.expect)(target).toBe(index_js_1.AGENTS_FILE);
+    });
+});

package/package.json

@@ -1,10 +1,56 @@
 {
   "name": "@dezkareid/ai-context-sync",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @dezkareid/ai-context-sync",
+  "version": "1.1.0",
+  "description": "CLI utility to synchronize AI agent context files from AGENTS.md",
+  "main": "dist/index.js",
+  "bin": {
+    "ai-context-sync": "./dist/index.js"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dezkareid/dezkareid.git",
+    "directory": "packages/ai-context-sync"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "ai",
+    "context",
+    "sync",
+    "claude",
+    "gemini",
+    "agents"
+  ],
+  "author": "Joel Humberto Gomez Paredes <elmaildeldezkareid@gmail.com>",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/dezkareid/dezkareid/issues"
+  },
+  "homepage": "https://github.com/dezkareid/dezkareid/tree/main/projects/dezkareid/packages/ai-context-sync#readme",
+  "dependencies": {
+    "commander": "12.0.0",
+    "fs-extra": "11.2.0",
+    "globby": "14.0.1",
+    "inquirer": "9.2.12"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "11.0.4",
+    "@types/inquirer": "9.0.7",
+    "@types/node": "25.0.10",
+    "@vitest/coverage-v8": "4.0.18",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc -w",
+    "test": "vitest run --coverage"
+  }
+}