aicm 0.14.1 → 0.14.3

package/README.md

@@ -1,16 +1,25 @@
 # 🗂️ aicm
 
-> Agentic IDE Configuration Manager
+> AI Configuration Manager
 
-A CLI tool for managing Agentic IDE configurations across projects
+A CLI tool for managing Agentic configurations across projects
 
 ![aicm](https://github.com/user-attachments/assets/ca38f2d6-ece6-43ad-a127-6f4fce8b2a5a)
 
 ## Why
 
-Agentic IDEs like Cursor enable AI-driven development through custom rules and configurations. However, sharing these configurations across projects and teams is challenging.
+Modern AI-powered IDEs like Cursor and Agents like Codex enable developers to write custom instructions to maintain context across coding sessions. They also support MCPs for enhanced functionality. However, sharing these configurations across multiple projects is a challenge.
 
-**aicm** solves this by distributing AI rules and MCP servers through npm packages, automatically installing them to the correct IDE locations.
+**aicm** solves this by enabling you to create reusable presets that bundle rules and MCP configurations together. With multi-target support, you can write your rules once and deploy them consistently across different AI tools and IDEs.
+
+## How it works
+
+aicm accepts Cursor's `.mdc` format as it provides the most comprehensive feature set. For other AI tools and IDEs, aicm automatically generates compatible formats:
+
+- **Cursor**: Native `.mdc` files with full feature support
+- **Windsurf/Codex**: Generates `.windsurfrules`/`AGENTS.md` files with natural language adaptations
+
+This approach ensures you write your rules once in the richest format available, while maintaining compatibility across different AI development environments.
 
 ## Getting Started
 
@@ -21,27 +30,21 @@ The easiest way to get started with aicm is by using **presets** - npm packages
 1. **Install a preset npm package**:
 
 ```bash
-npm install --save-dev @yourteam/ai-preset
+npm install --save-dev @team/ai-preset
 ```
 
-2. **Create an `aicm.json` file** in your project:
+2. **Create an `aicm.json` file** in your project root:
 
 ```json
-{ "presets": ["@yourteam/ai-preset"] }
+{ "presets": ["@team/ai-preset"] }
 ```
 
-3. **Install the rules and MCPs**:
-
-```bash
-npx -y aicm install
-```
-
-4. **Add a prepare script** to your `package.json` for automatic installation:
+3. **Add a prepare script** to your `package.json` to install all preset rules and MCPs:
 
 ```json
 {
   "scripts": {
-    "prepare": "npx aicm install"
+    "prepare": "npx aicm  -y install"
   }
 }
 ```
@@ -50,12 +53,10 @@ The rules are now installed in `.cursor/rules/aicm/` and any MCP servers are con
 
 ### Creating a Preset
 
-To create a reusable preset for your team:
-
 1. **Create an npm package** with the following structure:
 
 ```
-@myteam/ai-tools
+@team/ai-preset
 ├── package.json
 ├── aicm.json
 └── rules/
@@ -67,28 +68,28 @@ To create a reusable preset for your team:
 
 ```json
 {
-  "rulesDir": "./rules",
+  "rulesDir": "rules",
   "mcpServers": {
     "my-mcp": { "url": "https://example.com/sse" }
   }
 }
 ```
 
-3. **Publish the package** and reference it in your projects:
+3. **Publish the package** and use it in your project's `aicm.json`:
 
 ```json
-{ "presets": ["@myteam/ai-tools"] }
+{ "presets": ["@team/ai-preset"] }
 ```
 
-> **Note:** This is syntactic sugar for `@myteam/ai-tools/aicm.json`. Both forms are equivalent.
+> **Note:** This is syntactic sugar for `@team/ai-preset/aicm.json`.
 
 ### Using Local Rules
 
-For project-specific rules, you can specify `rulesDir` in your `aicm.json` config. This approach allows you to write rules once and automatically generate them for all configured targets:
+For project-specific rules, you can specify `rulesDir` in your `aicm.json` config. This approach allows you to write rules once and automatically generate them for all configured targets.
 
 ```json
 {
-  "rulesDir": "./rules"
+  "rulesDir": "path/to/rules/dir"
 }
 ```
 
@@ -246,6 +247,7 @@ Options:
 
 - `--ci`: run in CI environments (default: `false`)
 - `--verbose`: show detailed output and stack traces for debugging
+- `--dry-run`: simulate installation without writing files, useful for validating presets in CI
 
 ## Node.js API
 
@@ -264,11 +266,9 @@ install().then((result) => {
 
 // Install with custom options
 const customConfig = {
-  ides: ["cursor"],
-  rules: {
-    typescript: "./rules/typescript.mdc",
-    react: "./rules/react.mdc",
-  },
+  targets: ["cursor"],
+  rulesDir: "rules",
+  presets: ["@team/ai-preset"],
 };
 
 install({
@@ -291,32 +291,26 @@ Installs rules and MCP servers based on configuration.
 - `config`: Custom config object to use instead of loading from file
 - `installOnCI`: Run installation on CI environments (default: `false`)
 - `verbose`: Show verbose output and stack traces for debugging (default: `false`)
+- `dryRun`: Simulate installation without writing files, useful for preset validation in CI (default: `false`)
 
 **Returns:**
 
 A Promise that resolves to an object with:
 
 - `success`: Whether the operation was successful
-- `error`: Error message if the operation failed
+- `error`: Error object if the operation failed
 - `installedRuleCount`: Number of rules installed
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please feel free to open an issue or submit a Pull Request.
 
 ## Development
 
 ### Testing
 
 ```bash
-# Run all tests
-npm test
-
-# Run only unit tests
-npm run test:unit
-
-# Run only E2E tests
-npm run test:e2e
+pnpm test
 ```
 
 ### Publishing

package/dist/commands/init.js

@@ -8,7 +8,7 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
 const defaultConfig = {
-    rules: {},
+    rulesDir: "rules",
 };
 function initCommand() {
     const configPath = path_1.default.join(process.cwd(), "aicm.json");

package/dist/utils/config.d.ts

@@ -44,10 +44,12 @@ export interface ResolvedConfig {
     rules: RuleFile[];
     mcpServers: MCPServers;
 }
+export declare const ALLOWED_CONFIG_KEYS: readonly ["rulesDir", "targets", "presets", "overrides", "mcpServers", "workspaces"];
 export declare const SUPPORTED_TARGETS: readonly ["cursor", "windsurf", "codex"];
 export type SupportedTarget = (typeof SUPPORTED_TARGETS)[number];
 export declare function detectWorkspacesFromPackageJson(cwd: string): boolean;
-export declare function applyDefaults(config: RawConfig, cwd?: string): Config;
+export declare function resolveWorkspaces(config: unknown, configFilePath: string, cwd: string): boolean;
+export declare function applyDefaults(config: RawConfig, workspaces: boolean): Config;
 export declare function validateConfig(config: unknown, configFilePath: string, cwd: string, isWorkspaceMode?: boolean): asserts config is Config;
 export declare function loadRulesFromDirectory(rulesDir: string, source: "local" | "preset", presetName?: string): Promise<RuleFile[]>;
 export declare function resolvePresetPath(presetPath: string, cwd: string): string | null;

package/dist/utils/config.js

@@ -3,8 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_TARGETS = void 0;
+exports.SUPPORTED_TARGETS = exports.ALLOWED_CONFIG_KEYS = void 0;
 exports.detectWorkspacesFromPackageJson = detectWorkspacesFromPackageJson;
+exports.resolveWorkspaces = resolveWorkspaces;
 exports.applyDefaults = applyDefaults;
 exports.validateConfig = validateConfig;
 exports.loadRulesFromDirectory = loadRulesFromDirectory;
@@ -19,6 +20,14 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const node_path_1 = __importDefault(require("node:path"));
 const cosmiconfig_1 = require("cosmiconfig");
 const fast_glob_1 = __importDefault(require("fast-glob"));
+exports.ALLOWED_CONFIG_KEYS = [
+    "rulesDir",
+    "targets",
+    "presets",
+    "overrides",
+    "mcpServers",
+    "workspaces",
+];
 exports.SUPPORTED_TARGETS = ["cursor", "windsurf", "codex"];
 function detectWorkspacesFromPackageJson(cwd) {
     try {
@@ -33,12 +42,17 @@ function detectWorkspacesFromPackageJson(cwd) {
         return false;
     }
 }
-function applyDefaults(config, cwd) {
-    const workingDir = cwd || process.cwd();
-    // Auto-detect workspaces if not explicitly set
-    const workspaces = config.workspaces !== undefined
-        ? config.workspaces
-        : detectWorkspacesFromPackageJson(workingDir);
+function resolveWorkspaces(config, configFilePath, cwd) {
+    const hasConfigWorkspaces = typeof config === "object" && config !== null && "workspaces" in config;
+    if (hasConfigWorkspaces) {
+        if (typeof config.workspaces === "boolean") {
+            return config.workspaces;
+        }
+        throw new Error(`workspaces must be a boolean in config at ${configFilePath}`);
+    }
+    return detectWorkspacesFromPackageJson(cwd);
+}
+function applyDefaults(config, workspaces) {
     return {
         rulesDir: config.rulesDir,
         targets: config.targets || ["cursor"],
@@ -52,6 +66,10 @@ function validateConfig(config, configFilePath, cwd, isWorkspaceMode = false) {
     if (typeof config !== "object" || config === null) {
         throw new Error(`Config is not an object at ${configFilePath}`);
     }
+    const unknownKeys = Object.keys(config).filter((key) => !exports.ALLOWED_CONFIG_KEYS.includes(key));
+    if (unknownKeys.length > 0) {
+        throw new Error(`Invalid configuration at ${configFilePath}: unknown keys: ${unknownKeys.join(", ")}`);
+    }
     // Validate that either rulesDir or presets is provided
     const hasRulesDir = "rulesDir" in config && typeof config.rulesDir === "string";
     const hasPresets = "presets" in config &&
@@ -256,9 +274,10 @@ async function loadConfig(cwd) {
     if (!(configResult === null || configResult === void 0 ? void 0 : configResult.config)) {
         return null;
     }
-    const configWithDefaults = applyDefaults(configResult.config, workingDir);
-    const isWorkspaceMode = configWithDefaults.workspaces;
-    validateConfig(configResult.config, configResult.filepath, workingDir, isWorkspaceMode);
+    const config = configResult.config;
+    const isWorkspaces = resolveWorkspaces(config, configResult.filepath, workingDir);
+    validateConfig(config, configResult.filepath, workingDir, isWorkspaces);
+    const configWithDefaults = applyDefaults(config, isWorkspaces);
     const { rules, mcpServers } = await loadAllRules(configWithDefaults, workingDir);
     let rulesWithOverrides = rules;
     if (configWithDefaults.overrides) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicm",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "A TypeScript CLI tool for managing AI IDE rules across different projects and teams",
   "main": "dist/api.js",
   "types": "dist/api.d.ts",
@@ -12,9 +12,6 @@
     "README.md",
     "LICENSE"
   ],
-  "np": {
-    "tests": false
-  },
   "keywords": [
     "ai",
     "ide",
@@ -27,7 +24,6 @@
   "license": "MIT",
   "dependencies": {
     "arg": "^5.0.2",
-    "args": "^5.0.3",
     "chalk": "^4.1.2",
     "cosmiconfig": "^9.0.0",
     "fast-glob": "^3.3.3",
@@ -43,8 +39,6 @@
     "husky": "^8.0.3",
     "jest": "^29.7.0",
     "lint-staged": "^15.2.0",
-    "mock-fs": "^5.2.0",
-    "nock": "^13.3.8",
     "np": "^10.2.0",
     "prettier": "^3.1.0",
     "rimraf": "^5.0.5",
@@ -65,12 +59,10 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:all": "npm run build && npm run test",
-    "test:unit": "jest --config jest.unit.config.js",
-    "test:e2e": "pnpm run build && jest tests/e2e",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint",
     "version": "auto-changelog -p && git add CHANGELOG.md",
-    "release": "np"
+    "release": "np --no-tests"
   }
 }