aicm 0.18.0 → 0.19.1

package/README.md

@@ -14,11 +14,11 @@ A CLI tool for managing Agentic configurations across projects.
   - [Creating a Preset](#creating-a-preset)
   - [Using a Preset](#using-a-preset)
 - [Features](#features)
-  - [Rules](#using-rules)
-  - [Commands](#using-commands)
+  - [Rules](#rules)
+  - [Commands](#commands)
+  - [Hooks](#hooks)
   - [MCP Servers](#mcp-servers)
-  - [Auxiliary Files](#referencing-auxiliary-files)
-  - [Overrides](#overrides)
+  - [Assets](#assets)
 - [Workspaces Support](#workspaces-support)
 - [Configuration](#configuration)
 - [CLI Commands](#cli-commands)
@@ -78,19 +78,22 @@ After installation, open Cursor and ask it to do something. Your AI assistant wi
 1. **Create an npm package** with the following structure:
 
 ```
-@team/ai-preset
+@team/ai-preset/
 ├── package.json
 ├── aicm.json
-└── rules/
-    ├── typescript.mdc
-    └── react.mdc
+├── rules/           # Rule files (.mdc)
+│   ├── typescript.mdc
+│   └── react.mdc
+├── commands/        # Command files (.md) [optional]
+├── assets/          # Auxiliary files [optional]
+└── hooks.json       # Hook configuration [optional]
 ```
 
 2. **Configure the preset's `aicm.json`**:
 
 ```json
 {
-  "rulesDir": "rules",
+  "rootDir": "./",
   "mcpServers": {
     "my-mcp": { "url": "https://example.com/sse" }
   }
@@ -135,112 +138,220 @@ The rules are now installed in `.cursor/rules/aicm/` and any MCP servers are con
 
 ### Notes
 
-- Generated rules are always placed in a subdirectory for deterministic cleanup and easy gitignore.
-- Users should add `.cursor/rules/aicm/` and `.aicm/` (for Windsurf/Codex) to `.gitignore` to avoid tracking generated rules.
+- Generated files are always placed in subdirectories for deterministic cleanup and easy gitignore.
+- Users should add `.cursor/*/aicm/` to `.gitignore` to avoid tracking generated files. This single pattern covers all aicm-managed directories (rules, commands, assets, hooks).
 
 ## Features
 
-### Using Rules
+### Rules
 
 aicm uses Cursor's `.mdc` files for rules. Read more about the format [here](https://cursor.com/docs/context/rules).
 
-Add a rules directory to your project configuration:
+Create a `rules/` directory in your project (at the `rootDir` location):
+
+```
+my-project/
+├── aicm.json
+└── rules/
+    ├── typescript.mdc
+    └── react.mdc
+```
+
+Configure your `aicm.json`:
 
 ```json
 {
-  "rulesDir": "./rules",
+  "rootDir": "./",
   "targets": ["cursor"]
 }
 ```
 
 Rules are installed in `.cursor/rules/aicm/` and are loaded automatically by Cursor.
 
-### Using Commands
+### Commands
 
 Cursor supports custom commands that can be invoked directly in the chat interface. aicm can manage these command files alongside your rules and MCP configurations.
 
-Add a commands directory to your project configuration:
+Create a `commands/` directory in your project (at the `rootDir` location):
+
+```
+my-project/
+├── aicm.json
+└── commands/
+    ├── review.md
+    └── generate.md
+```
+
+Configure your `aicm.json`:
 
 ```json
 {
-  "commandsDir": "./commands",
+  "rootDir": "./",
   "targets": ["cursor"]
 }
 ```
 
 Command files ending in `.md` are installed to `.cursor/commands/aicm/` and appear in Cursor under the `/` command menu.
 
-### MCP Servers
+### Hooks
 
-You can configure MCP servers directly in your `aicm.json`, which is useful for sharing mcp configurations across your team or bundling them into presets.
+aicm provides first-class support for [Cursor Agent Hooks](https://docs.cursor.com/advanced/hooks), allowing you to intercept and extend the agent's behavior. Hooks enable you to run custom scripts before/after shell execution, file edits, MCP calls, and more.
+
+#### Basic Setup
+
+Hooks follow a convention similar to Cursor's own structure:
+
+```
+my-project/
+├── aicm.json
+├── hooks.json
+└── hooks/
+    ├── audit.sh
+    └── format.js
+```
+
+Your `hooks.json` file should reference scripts within the `hooks/` directory:
 
 ```json
 {
-  "mcpServers": {
-    "Playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp"]
-    }
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [{ "command": "./hooks/audit.sh" }],
+    "afterFileEdit": [{ "command": "./hooks/format.js" }]
   }
 }
 ```
 
-When installed, these servers are automatically added to your `.cursor/mcp.json`.
+> **Important:** All hook scripts must be within the `hooks/` directory. References to files outside this directory will be warned about and skipped.
 
-### Referencing Auxiliary Files
+#### Installation Behavior
 
-You can place any file (e.g., `example.ts`, `schema.json`, `guide.md`) in your `rulesDir` alongside your `.mdc` files. These assets are automatically copied to the target location. You can reference them in your rules using relative paths, and aicm will automatically rewrite the links to point to the correct location for each target IDE.
+When you run `aicm install`, the following happens:
 
-Example `rules/my-rule.mdc`:
+1. **Directory Copy**: All files in the `hooks/` directory (except `hooks.json`) are copied
+2. **Path Rewriting**: Command paths in `hooks.json` are rewritten to point to `.cursor/hooks/aicm/`
+3. **File Installation**: Scripts are copied to `.cursor/hooks/aicm/` (for local hooks) or `.cursor/hooks/aicm/<preset-name>/` (for preset hooks) with their directory structure preserved
+4. **Config Merging**: Your hooks configuration is merged into `.cursor/hooks.json`
 
-```markdown
-# My Rule
+#### Preset Namespacing
 
-See [Example](./example.ts) for details.
+aicm uses directory-based namespacing to prevent collisions:
+
+```
+.cursor/hooks/aicm/
+├── preset-a/
+│   └── validate.sh    # From preset-a
+└── preset-b/
+    └── validate.sh    # From preset-b
 ```
 
-#### Commands Referencing Files
+#### Workspace Support
 
-You can also use this feature to create commands that reference auxiliary files in your `rulesDir`. Since assets in `rulesDir` are copied to the target directory, your commands can link to them.
+In monorepo/workspace mode, hooks are:
 
-For example, if you have a schema file at `rules/schema.json` and a command at `commands/generate-schema.md`:
+- Installed individually for each package (in `package-x/.cursor/hooks.json`)
+- Merged and installed at the root (in `.cursor/hooks.json`)
+- Deduplicated by full path (including preset namespace)
 
-```markdown
-# Generate Schema
+**Example workspace structure:**
 
-Use the schema defined in [Schema Template](../rules/schema.json) to generate the response.
+```
+my-monorepo/
+├── aicm.json (workspaces: true)
+├── .cursor/hooks.json (merged from all packages)
+├── package-a/
+│   ├── aicm.json
+│   ├── hooks.json
+│   ├── hooks/
+│   │   └── check.sh
+│   └── .cursor/hooks.json (package-specific)
+└── package-b/
+    ├── aicm.json
+    ├── hooks.json
+    ├── hooks/
+    │   └── validate.js
+    └── .cursor/hooks.json (package-specific)
 ```
 
-When installed, `aicm` will automatically rewrite the link to point to the correct location of `schema.json` in the target environment (e.g., `../../rules/aicm/schema.json` for Cursor).
-
-> **Note:** Path rewriting works for any relative path format in your commands - markdown links, inline code references, or bare paths - as long as they point to actual files in your `rulesDir`.
-
-#### usage in workspaces mode
-
-When using workspaces, commands installed at the monorepo root need to access auxiliary files located in nested packages (e.g., `packages/frontend/rules/helper.js`).
-
-`aicm` handles this automatically by:
+#### Content Collision Detection
 
-1. Copying referenced auxiliary files from nested packages to the root `.cursor/rules/aicm/` directory
-2. Rewriting paths in the root command to point to these copied files
+If the same hook file (by path) has different content across workspace packages, aicm will:
 
-**Warning:** If your command references a `.mdc` file (Cursor rule), `aicm` will check if it's a "manual" rule or an "automatic" rule (one that is always applied or auto-attached via globs). If it's an automatic rule, `aicm` will warn you that copying it to the root might cause the rule to be included twice in the context (once from the nested package and once from the root copy). For best results, only reference manual `.mdc` files or other file types (like `.js`, `.json`, `.md`) from commands.
+1. Warn you about the collision with full source information
+2. Use the last occurrence (last-writer-wins)
+3. Continue installation
 
-### Overrides
+### MCP Servers
 
-You can disable or replace specific rules or commands provided by presets using the `overrides` field:
+You can configure MCP servers directly in your `aicm.json`, which is useful for sharing mcp configurations across your team or bundling them into presets.
 
 ```json
 {
-  "presets": ["@company/ai-rules"],
-  "overrides": {
-    "rule-from-preset-a": "./rules/override-rule.mdc",
-    "rule-from-preset-b": false,
-    "legacy-command": false
+  "mcpServers": {
+    "Playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp"]
+    }
   }
 }
 ```
 
+When installed, these servers are automatically added to your `.cursor/mcp.json`.
+
+### Assets
+
+You can include assets (examples, schemas, scripts, etc.) that can be referenced by your rules, commands, and hooks by placing them in the `assets/` directory.
+
+All files in `assets/` are copied to `.cursor/assets/aicm/` (for Cursor) or `.aicm/` (for Windsurf/Codex/Claude).
+
+**Example structure:**
+
+```
+my-project/
+├── aicm.json
+├── rules/
+│   └── api-guide.mdc        # References ../assets/schema.json
+├── commands/
+│   └── generate.md          # References ../assets/schema.json
+├── assets/
+│   ├── schema.json
+│   ├── examples/
+│   │   └── config.ts
+│   └── hooks/
+│       └── validate.sh
+└── hooks.json               # References ./hooks/validate.sh
+```
+
+**Referencing assets from rules and commands:**
+
+```markdown
+<!-- rules/api.mdc -->
+
+Use [this schema](../assets/schema.json) for validation.
+Check the example at `../assets/examples/response.json`.
+```
+
+**Note:** The `../assets/` path is automatically adjusted during installation to `../../assets/aicm/` to match the final directory structure. You don't need to worry about the installation paths - just use `../assets/`.
+
+**After installation:**
+
+```
+.cursor/
+├── assets/aicm/             # All assets copied here
+│   ├── schema.json
+│   ├── examples/
+│   │   └── config.ts
+│   └── hooks/
+│       └── validate.sh
+├── rules/aicm/
+│   └── api-guide.mdc        # References ../../assets/aicm/schema.json
+├── commands/aicm/
+│   └── generate.md          # References ../../assets/aicm/schema.json
+└── hooks/
+    ├── aicm/
+    └── hooks.json
+```
+
 ## Workspaces Support
 
 aicm supports workspaces by automatically discovering and installing configurations across multiple packages in your repository.
@@ -295,7 +406,7 @@ When you have a preset package within your workspace (a package that provides ru
 ```json
 {
   "skipInstall": true,
-  "rulesDir": "./rules",
+  "rootDir": "./",
   "targets": ["cursor"]
 }
 ```
@@ -308,25 +419,71 @@ Create an `aicm.json` file in your project root, or an `aicm` key in your projec
 
 ```json
 {
-  "rulesDir": "./rules",
-  "commandsDir": "./commands",
+  "rootDir": "./",
   "targets": ["cursor"],
   "presets": [],
-  "overrides": {},
   "mcpServers": {},
   "skipInstall": false
 }
 ```
 
-- **rulesDir**: Directory containing all rule files.
-- **commandsDir**: Directory containing Cursor command files.
-- **targets**: IDEs/Agent targets where rules should be installed. Defaults to `["cursor"]`.
+### Configuration Options
+
+- **rootDir**: Directory containing your aicm structure. Must contain one or more of: `rules/`, `commands/`, `assets/`, `hooks/`, or `hooks.json`. If not specified, aicm will only install rules from presets and will not pick up any local directories.
+- **targets**: IDEs/Agent targets where rules should be installed. Defaults to `["cursor"]`. Supported targets: `cursor`, `windsurf`, `codex`, `claude`.
 - **presets**: List of preset packages or paths to include.
-- **overrides**: Map of rule names to `false` (disable) or a replacement file path.
 - **mcpServers**: MCP server configurations.
 - **workspaces**: Set to `true` to enable workspace mode. If not specified, aicm will automatically detect workspaces from your `package.json`.
 - **skipInstall**: Set to `true` to skip rule installation for this package. Useful for preset packages that provide rules but shouldn't have rules installed into them.
 
+### Configuration Examples
+
+#### Preset-Only Configuration
+
+For projects that only consume presets and don't have their own rules, you can omit `rootDir`:
+
+```json
+{
+  "presets": ["@company/ai-preset"]
+}
+```
+
+This ensures that only rules from the preset are installed, and any local directories like `commands/` or `rules/` in your project (used for your application) won't be accidentally picked up by aicm.
+
+#### Mixed Local and Preset Configuration
+
+To combine your own rules with preset rules:
+
+```json
+{
+  "rootDir": "./ai-config",
+  "presets": ["@company/ai-preset"],
+  "targets": ["cursor", "windsurf"]
+}
+```
+
+This will load rules from both `./ai-config/rules/` and the preset, installing them to both Cursor and Windsurf.
+
+### Directory Structure
+
+aicm uses a convention-based directory structure:
+
+```
+my-project/
+├── aicm.json
+├── rules/           # Rule files (.mdc) [required for rules]
+│   ├── api.mdc
+│   └── testing.mdc
+├── commands/        # Command files (.md) [optional]
+│   └── generate.md
+├── assets/          # Auxiliary files [optional]
+│   ├── schema.json
+│   └── examples/
+├── hooks/           # Hook scripts [optional]
+│   └── validate.sh
+└── hooks.json       # Hook configuration [optional]
+```
+
 ## CLI Commands
 
 ### Global Options
@@ -386,7 +543,7 @@ install().then((result) => {
 // Install with custom options
 const customConfig = {
   targets: ["cursor"],
-  rulesDir: "rules",
+  rootDir: "./",
   presets: ["@team/ai-preset"],
 };
 

package/dist/api.d.ts

@@ -5,5 +5,12 @@ import { InstallOptions, InstallResult } from "./commands/install";
  * @returns Result of the install operation
  */
 export declare function install(options?: InstallOptions): Promise<InstallResult>;
+/**
+ * Check if workspaces mode is enabled without loading all rules/presets
+ * @param cwd Current working directory (optional, defaults to process.cwd())
+ * @returns True if workspaces mode is enabled
+ */
+export declare function checkWorkspacesEnabled(cwd?: string): Promise<boolean>;
 export type { InstallOptions, InstallResult } from "./commands/install";
 export type { ResolvedConfig, Config, RuleFile, CommandFile, MCPServers, } from "./utils/config";
+export type { HookFile, HooksJson, HookType, HookCommand } from "./utils/hooks";

package/dist/api.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.install = install;
+exports.checkWorkspacesEnabled = checkWorkspacesEnabled;
 const install_1 = require("./commands/install");
+const config_1 = require("./utils/config");
 /**
  * Install AICM rules based on configuration
  * @param options Installation options
@@ -10,3 +12,11 @@ const install_1 = require("./commands/install");
 async function install(options = {}) {
     return (0, install_1.install)(options);
 }
+/**
+ * Check if workspaces mode is enabled without loading all rules/presets
+ * @param cwd Current working directory (optional, defaults to process.cwd())
+ * @returns True if workspaces mode is enabled
+ */
+async function checkWorkspacesEnabled(cwd) {
+    return (0, config_1.checkWorkspacesEnabled)(cwd);
+}

package/dist/commands/clean.js

@@ -97,11 +97,68 @@ function cleanMcpServers(cwd, verbose) {
         return false;
     }
 }
+function cleanHooks(cwd, verbose) {
+    const hooksJsonPath = node_path_1.default.join(cwd, ".cursor", "hooks.json");
+    const hooksDir = node_path_1.default.join(cwd, ".cursor", "hooks", "aicm");
+    let hasChanges = false;
+    // Clean hooks directory
+    if (fs_extra_1.default.existsSync(hooksDir)) {
+        fs_extra_1.default.removeSync(hooksDir);
+        if (verbose)
+            console.log(chalk_1.default.gray(`  Removed ${hooksDir}`));
+        hasChanges = true;
+    }
+    // Clean hooks.json
+    if (fs_extra_1.default.existsSync(hooksJsonPath)) {
+        try {
+            const content = fs_extra_1.default.readJsonSync(hooksJsonPath);
+            // Filter out aicm-managed hooks (those pointing to hooks/aicm/)
+            const userConfig = {
+                version: content.version || 1,
+                hooks: {},
+            };
+            let removedAny = false;
+            if (content.hooks) {
+                for (const [hookType, hookCommands] of Object.entries(content.hooks)) {
+                    if (Array.isArray(hookCommands)) {
+                        const userCommands = hookCommands.filter((cmd) => !cmd.command || !cmd.command.includes("hooks/aicm/"));
+                        if (userCommands.length < hookCommands.length) {
+                            removedAny = true;
+                        }
+                        if (userCommands.length > 0) {
+                            userConfig.hooks[hookType] = userCommands;
+                        }
+                    }
+                }
+            }
+            if (removedAny) {
+                const hasUserHooks = userConfig.hooks && Object.keys(userConfig.hooks).length > 0;
+                if (!hasUserHooks) {
+                    fs_extra_1.default.removeSync(hooksJsonPath);
+                    if (verbose)
+                        console.log(chalk_1.default.gray(`  Removed empty ${hooksJsonPath}`));
+                }
+                else {
+                    fs_extra_1.default.writeJsonSync(hooksJsonPath, userConfig, { spaces: 2 });
+                    if (verbose)
+                        console.log(chalk_1.default.gray(`  Cleaned aicm hooks from ${hooksJsonPath}`));
+                }
+                hasChanges = true;
+            }
+        }
+        catch (_a) {
+            console.warn(chalk_1.default.yellow(`Warning: Failed to clean hooks.json`));
+        }
+    }
+    return hasChanges;
+}
 function cleanEmptyDirectories(cwd, verbose) {
     let cleanedCount = 0;
     const dirsToCheck = [
         node_path_1.default.join(cwd, ".cursor", "rules"),
         node_path_1.default.join(cwd, ".cursor", "commands"),
+        node_path_1.default.join(cwd, ".cursor", "assets"),
+        node_path_1.default.join(cwd, ".cursor", "hooks"),
         node_path_1.default.join(cwd, ".cursor"),
     ];
     for (const dir of dirsToCheck) {
@@ -130,6 +187,7 @@ async function cleanPackage(options = {}) {
         const filesToClean = [
             node_path_1.default.join(cwd, ".cursor", "rules", "aicm"),
             node_path_1.default.join(cwd, ".cursor", "commands", "aicm"),
+            node_path_1.default.join(cwd, ".cursor", "assets", "aicm"),
             node_path_1.default.join(cwd, ".aicm"),
         ];
         const rulesFilesToClean = [
@@ -150,6 +208,9 @@ async function cleanPackage(options = {}) {
         // Clean MCP servers
         if (cleanMcpServers(cwd, verbose))
             cleanedCount++;
+        // Clean hooks
+        if (cleanHooks(cwd, verbose))
+            cleanedCount++;
         // Clean empty directories
         cleanedCount += cleanEmptyDirectories(cwd, verbose);
         return {
@@ -190,11 +251,9 @@ async function cleanWorkspaces(cwd, verbose = false) {
     };
 }
 async function clean(options = {}) {
-    var _a;
     const cwd = options.cwd || process.cwd();
     const verbose = options.verbose || false;
-    const shouldUseWorkspaces = ((_a = (await (0, config_1.loadConfig)(cwd))) === null || _a === void 0 ? void 0 : _a.config.workspaces) ||
-        (0, config_1.detectWorkspacesFromPackageJson)(cwd);
+    const shouldUseWorkspaces = await (0, config_1.checkWorkspacesEnabled)(cwd);
     if (shouldUseWorkspaces) {
         return cleanWorkspaces(cwd, verbose);
     }

package/dist/commands/init.js

@@ -8,7 +8,8 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
 const defaultConfig = {
-    rulesDir: "rules",
+    rootDir: "./",
+    targets: ["cursor"],
 };
 function initCommand() {
     const configPath = path_1.default.join(process.cwd(), "aicm.json");
@@ -17,11 +18,30 @@ function initCommand() {
         return;
     }
     try {
+        // Create standard directory structure
+        const dirs = ["rules", "commands", "assets", "hooks"];
+        for (const dir of dirs) {
+            const dirPath = path_1.default.join(process.cwd(), dir);
+            if (!fs_extra_1.default.existsSync(dirPath)) {
+                fs_extra_1.default.mkdirSync(dirPath, { recursive: true });
+            }
+        }
+        // Create placeholder file in rules directory
+        const rulesReadmePath = path_1.default.join(process.cwd(), "rules", ".gitkeep");
+        if (!fs_extra_1.default.existsSync(rulesReadmePath)) {
+            fs_extra_1.default.writeFileSync(rulesReadmePath, "# Place your .mdc rule files here\n");
+        }
         fs_extra_1.default.writeJsonSync(configPath, defaultConfig, { spaces: 2 });
         console.log(`Configuration file location: ${chalk_1.default.blue(configPath)}`);
+        console.log(`\nCreated directory structure:`);
+        console.log(`  - ${chalk_1.default.blue("rules/")} for rule files (.mdc)`);
+        console.log(`  - ${chalk_1.default.blue("commands/")} for command files (.md)`);
+        console.log(`  - ${chalk_1.default.blue("assets/")} for auxiliary files`);
+        console.log(`  - ${chalk_1.default.blue("hooks/")} for hook scripts`);
         console.log(`\nNext steps:`);
-        console.log(`  1. Edit ${chalk_1.default.blue("aicm.json")} to configure your rules & presets`);
-        console.log(`  2. Run ${chalk_1.default.blue("npx aicm install")} to install rules & mcps`);
+        console.log(`  1. Add your rule files to ${chalk_1.default.blue("rules/")} directory`);
+        console.log(`  2. Edit ${chalk_1.default.blue("aicm.json")} to configure presets if needed`);
+        console.log(`  3. Run ${chalk_1.default.blue("npx aicm install")} to install rules & mcps`);
     }
     catch (error) {
         console.error(chalk_1.default.red("Error creating configuration file:"), error);