aicm 0.5.0 → 0.6.0

package/README.md

@@ -6,23 +6,13 @@ A CLI tool for syncing and managing Agentic IDE rules across projects
 
 ## Why
 
-Development teams struggle with:
+With the rise of Agentic IDEs like cursor and windsurf, we have an opportunity to enforce best practices through rules. However, these rules are typically isolated within individual developers or projects.
 
-- **Inconsistent Practices**: Developers apply varying standards across projects
-- **Knowledge Silos**: Best practices remain trapped in individual projects
-- **Change Management**: No efficient way to update and distribute new standards
-
-As developers increasingly adopt AI-powered IDEs like Cursor and Windsurf, we have an opportunity to enforce best practices through rules. However, these rules are typically isolated within individual developers or projects.
-
-**aicm** is a CLI tool that helps with distribution of agentic IDE configurations, rules and mcps:
-
-- 🏛️ **Single Source of Truth**: Define, maintain and version-control all AI IDE rules in one central repository
-- 📦 **Seamless Distribution**: Automatically synchronize the latest rules to developers' local projects using npm packages
-- 🌐 **Cross-IDE Support**: Supports multiple AI-powered IDEs (Cursor, Windsurf)
+**aicm** is a CLI tool for distributing Agentic IDE configurations, rules, and MCPs across projects. It leverages package managers to copy configurations from node_modules to the correct locations in your file system.
 
 ## Getting Started
 
-To get automatic rule updates from NPM Packages, you can create, publish, and use dedicated npm packages to distribute AI rules across multiple projects.
+Since aicm is not a package manager, begin by creating an npm package that contains your rules and MCP configurations.
 
 Consider the following npm package structure:
 
@@ -31,8 +21,7 @@ Consider the following npm package structure:
 ├── package.json
 └── rules/
     ├── typescript.mdc
-    ├── react.mdc
-    └── general.mdc
+    └── react.mdc
 ```
 
 1. **Point to the path within the npm package**
@@ -44,8 +33,7 @@ In your project's `aicm.json`, reference the package and the specific rule:
   "ides": ["cursor"],
   "rules": {
     "typescript": "@myteam/ai-tools/rules/typescript.mdc",
-    "react": "@myteam/ai-tools/rules/react.mdc",
-    "general": "@myteam/ai-tools/rules/general.mdc"
+    "react": "@myteam/ai-tools/rules/react.mdc"
   }
 }
 ```
@@ -60,21 +48,28 @@ In your project's `aicm.json`, reference the package and the specific rule:
 }
 ```
 
-Now the rules will be linked to `.cursor/rules/` when you run `npm install`.
+Now the rules will be linked to `.cursor/rules/aicm/` when you run `npm install`.
 
 ### Using Presets
 
-Presets allow you to bundle multiple rules into a single configuration that can be shared across projects.
+Presets allow you to bundle multiple rules & mcps into a single configuration that can be shared across projects.
 
 1. **Create a preset package or directory**
 
 Create an npm package with your rule definitions in an `aicm.json` file:
 
+> `@myteam/ai-tools/aicm.json`
+
 ```json
 {
   "rules": {
     "typescript": "./rules/typescript.mdc",
     "react": "./rules/react.mdc"
+  },
+  "mcpServers": {
+    "my-mcp": {
+      "url": "https://example.com/sse"
+    }
   }
 }
 ```
@@ -90,14 +85,19 @@ In your project's `aicm.json`, reference the preset by its npm package or direct
 }
 ```
 
-When you run `npx aicm install`, all rules from the preset will be installed to `.cursor/rules/`.
+When you run `npx aicm install`, all rules from the preset will be installed to `.cursor/rules/aicm/` and all mcps from the preset will be installed to `.cursor/mcp.json`.
+
+### Notes
 
-### Overriding and Canceling Rules and MCP Servers from Presets
+- Generated rules are always placed in a subdirectory for deterministic cleanup and easy gitignore.
+- Users may add `.cursor/rules/aicm/` and `.aicm/` (for Windsurf) to their `.gitignore` if they do not want to track generated rules.
 
-When you use a preset, you can override or cancel any rule or mcpServer from the preset in your own `aicm.json` configuration:
+### Overriding and Disabling Rules and MCP Servers from Presets
+
+When you use a preset, you can override or disable any rule or mcpServer from the preset in your own `aicm.json` configuration:
 
 - **Override**: To override a rule or mcpServer, specify the same key in your config with a new value. The value in your config will take precedence over the preset.
-- **Cancel**: To cancel (remove) a rule or mcpServer from a preset, set its value to `false` in your config.
+- **Disable**: To disable a rule or mcpServer from a preset, set its value to `false` in your config.
 
 **Example:**
 
@@ -119,16 +119,11 @@ When you use a preset, you can override or cancel any rule or mcpServer from the
 }
 ```
 
-- In this example, `npm-rule` is overridden with a local rule, and `preset-rule` is canceled.
-- The `preset-mcp` server is overridden, and `another-mcp` is canceled.
-
-This allows you to fully customize or selectively disable rules and servers from any preset you use.
-
 ### Demo
 
-Here is a package to demonstrate how aicm works:
+We'll install an npm package containing a simple rule to demonstrate how aicm works.
 
-1. Install a package containing a rule
+1. Install an npm package containing a rule
 
 ```bash
 npm install --save-dev pirate-coding-rule
@@ -179,11 +174,11 @@ Example `aicm.json`:
   "ides": ["cursor"],
   "presets": ["@my-team/ai-tools/my-aicm.json"],
   "rules": {
-    "team-standards": "@my-team/ai-tools/rules/team-standards.mdc"
+    "team-rules/team-standards": "@my-team/ai-tools/rules/team-standards.mdc"
   },
   "mcpServers": {
     "remote-mcp": {
-      "url": "https://example.com/mcp-config.json"
+      "url": "https://example.com/sse"
     }
   }
 }
@@ -195,7 +190,7 @@ Example `aicm.json`:
 
 - **rules**: Object containing rule configurations
 
-  - **rule-name**: A unique identifier for the rule
+  - **rule-name**: A unique identifier for the rule. Can include a directory path to install the rule to a specific directory.
   - **source-location**: Location of the rule file (path within an npm package or local path)
 
 - **mcpServers**: Object containing MCP server configurations. Each key is a unique server name, and the value is an object with either:
@@ -234,8 +229,8 @@ Rules stored locally in your project or filesystem. Any path containing slashes
 
 ## Supported IDEs
 
-- **Cursor**: Rules are installed as individual `.mdc` files in the Cursor rules directory (`.cursor/rules/`), mcp servers are installed to `.cursor/mcp.json`
-- **Windsurf**: Rules are installed in the `.rules` directory which should be added to your `.gitignore` file. Our approach for Windsurf is to create links from the `.windsurfrules` file to the respective rules in the `.rules` directory. There is no support for local mcp servers at the moment.
+- **Cursor**: Rules are installed as individual `.mdc` files in the Cursor rules directory (`.cursor/rules/aicm/`), mcp servers are installed to `.cursor/mcp.json`
+- **Windsurf**: Rules are installed in the `.aicm` directory which should be added to your `.gitignore` file. Our approach for Windsurf is to create links from the `.windsurfrules` file to the respective rules in the `.aicm` directory. There is no support for local mcp servers at the moment.
 
 ## Commands
 
@@ -262,17 +257,6 @@ Installs rules from your configuration to the appropriate IDE locations.
 npx aicm install
 ```
 
-**Options:**
-
-- No arguments are supported. All rules are installed from your configuration and any referenced presets.
-
-**Examples:**
-
-```bash
-# Install all configured rules
-npx -y aicm install
-```
-
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
@@ -281,8 +265,6 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ### Testing
 
-The project includes both unit tests and end-to-end (E2E) tests:
-
 ```bash
 # Run all tests
 npm test

package/dist/utils/rule-status.js

@@ -13,8 +13,8 @@ const node_path_1 = __importDefault(require("node:path"));
 function getIdePaths() {
     const projectDir = process.cwd(); // Get current working directory (project root)
     return {
-        cursor: node_path_1.default.join(projectDir, ".cursor", "rules"),
-        windsurf: node_path_1.default.join(projectDir, ".rules"),
+        cursor: node_path_1.default.join(projectDir, ".cursor", "rules", "aicm"),
+        windsurf: node_path_1.default.join(projectDir, ".aicm"),
     };
 }
 /**
@@ -22,7 +22,6 @@ function getIdePaths() {
  */
 function checkRuleStatus(ruleName, ruleType, ides) {
     const idePaths = getIdePaths();
-    // Check if rule is installed in all specified IDEs
     return ides.every((ide) => {
         if (!idePaths[ide]) {
             return false;
@@ -31,14 +30,11 @@ function checkRuleStatus(ruleName, ruleType, ides) {
             return fs_extra_1.default.existsSync(node_path_1.default.join(idePaths[ide], `${ruleName}.mdc`));
         }
         if (ide === "windsurf") {
-            // For Windsurf, check if the rule exists in .rules directory
-            // and if it's referenced in .windsurfrules
             const ruleExists = fs_extra_1.default.existsSync(node_path_1.default.join(idePaths[ide], `${ruleName}.md`));
-            // Check if .windsurfrules exists and contains a reference to this rule
             const windsurfRulesPath = node_path_1.default.join(process.cwd(), ".windsurfrules");
             if (fs_extra_1.default.existsSync(windsurfRulesPath)) {
                 const windsurfRulesContent = fs_extra_1.default.readFileSync(windsurfRulesPath, "utf8");
-                return (ruleExists && windsurfRulesContent.includes(`.rules/${ruleName}.md`));
+                return (ruleExists && windsurfRulesContent.includes(`.aicm/${ruleName}.md`));
             }
             return false;
         }

package/dist/utils/rule-writer.js

@@ -20,7 +20,7 @@ function writeRulesToTargets(collection) {
     }
     // Write Windsurf rules
     if (collection.windsurf.length > 0) {
-        writeWindsurfRulesFromCollection(collection.windsurf);
+        writeWindsurfRulesFromCollection(collection.windsurf, idePaths.windsurf);
     }
 }
 /**
@@ -29,16 +29,14 @@ function writeRulesToTargets(collection) {
  * @param cursorRulesDir The path to Cursor's rules directory
  */
 function writeCursorRules(rules, cursorRulesDir) {
-    fs_extra_1.default.ensureDirSync(cursorRulesDir);
+    fs_extra_1.default.emptyDirSync(cursorRulesDir);
     for (const rule of rules) {
-        const ruleFile = node_path_1.default.join(cursorRulesDir, `${rule.name}.mdc`);
-        // For Cursor, we either copy the file or create a symlink to the original
+        const ruleFile = node_path_1.default.join(cursorRulesDir, ...rule.name.split("/")) + ".mdc";
+        fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(ruleFile));
         if (fs_extra_1.default.existsSync(rule.sourcePath)) {
-            // Copy the file (safer than symlink)
             fs_extra_1.default.copyFileSync(rule.sourcePath, ruleFile);
         }
         else {
-            // If source path doesn't exist (shouldn't happen), write content directly
             const mdcContent = `---\n${JSON.stringify(rule.metadata, null, 2)}\n---\n\n${rule.content}`;
             fs_extra_1.default.writeFileSync(ruleFile, mdcContent);
         }
@@ -48,21 +46,22 @@ function writeCursorRules(rules, cursorRulesDir) {
  * Write rules to Windsurf's rules directory and update .windsurfrules file
  * @param rules The rules to write
  */
-function writeWindsurfRulesFromCollection(rules) {
-    const idePaths = (0, rule_status_1.getIdePaths)();
-    const ruleDir = idePaths.windsurf;
-    fs_extra_1.default.ensureDirSync(ruleDir);
-    // First write individual rule files
+function writeWindsurfRulesFromCollection(rules, ruleDir) {
+    fs_extra_1.default.emptyDirSync(ruleDir);
     const ruleFiles = rules.map((rule) => {
-        const ruleFile = node_path_1.default.join(ruleDir, `${rule.name}.md`);
-        fs_extra_1.default.writeFileSync(ruleFile, rule.content);
+        const physicalRulePath = node_path_1.default.join(ruleDir, ...rule.name.split("/")) + ".md";
+        fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(physicalRulePath));
+        fs_extra_1.default.writeFileSync(physicalRulePath, rule.content);
+        const relativeRuleDir = node_path_1.default.basename(ruleDir); // Gets '.rules'
+        const windsurfPath = node_path_1.default.join(relativeRuleDir, ...rule.name.split("/")) + ".md";
+        // Normalize to POSIX style for cross-platform compatibility in .windsurfrules
+        const windsurfPathPosix = windsurfPath.replace(/\\/g, "/");
         return {
             name: rule.name,
-            path: `.rules/${rule.name}.md`,
+            path: windsurfPathPosix,
             metadata: rule.metadata,
         };
     });
-    // Then generate and write the .windsurfrules file
     const windsurfRulesContent = (0, windsurf_writer_1.generateWindsurfRulesContent)(ruleFiles);
     (0, windsurf_writer_1.writeWindsurfRules)(windsurfRulesContent);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicm",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A TypeScript CLI tool for managing AI IDE rules across different projects and teams",
   "main": "dist/index.js",
   "bin": {
@@ -24,7 +24,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint",
-    "prepare": "husky && npx ts-node src/index.ts install",
+    "prepare": "husky install && npx ts-node src/index.ts install",
     "version": "auto-changelog -p && git add CHANGELOG.md"
   },
   "keywords": [