aicm 0.17.3 → 0.19.0

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,41 +138,149 @@ 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.
 
+### Hooks
+
+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
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [{ "command": "./hooks/audit.sh" }],
+    "afterFileEdit": [{ "command": "./hooks/format.js" }]
+  }
+}
+```
+
+> **Important:** All hook scripts must be within the `hooks/` directory. References to files outside this directory will be warned about and skipped.
+
+#### Installation Behavior
+
+When you run `aicm install`, the following happens:
+
+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`
+
+#### Preset Namespacing
+
+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
+```
+
+#### Workspace Support
+
+In monorepo/workspace mode, hooks are:
+
+- 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)
+
+**Example workspace structure:**
+
+```
+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)
+```
+
+#### Content Collision Detection
+
+If the same hook file (by path) has different content across workspace packages, aicm will:
+
+1. Warn you about the collision with full source information
+2. Use the last occurrence (last-writer-wins)
+3. Continue installation
+
 ### MCP Servers
 
 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.
@@ -187,47 +298,58 @@ You can configure MCP servers directly in your `aicm.json`, which is useful for
 
 When installed, these servers are automatically added to your `.cursor/mcp.json`.
 
-### Referencing Auxiliary Files
+### Assets
 
-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.
+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.
 
-Example `rules/my-rule.mdc`:
+All files in `assets/` are copied to `.cursor/assets/aicm/` (for Cursor) or `.aicm/` (for Windsurf/Codex/Claude).
 
-```markdown
-# My Rule
+**Example structure:**
 
-See [Example](./example.ts) for details.
+```
+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
 ```
 
-#### Commands Referencing Files
-
-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.
-
-For example, if you have a schema file at `rules/schema.json` and a command at `commands/generate-schema.md`:
+**Referencing assets from rules and commands:**
 
 ```markdown
-# Generate Schema
+<!-- rules/api.mdc -->
 
-Use the schema defined in [Schema Template](../rules/schema.json) to generate the response.
+Use [this schema](../assets/schema.json) for validation.
+Check the example at `../assets/examples/response.json`.
 ```
 
-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:** 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/`.
 
-> **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`.
+**After installation:**
 
-### Overrides
-
-You can disable or replace specific rules or commands provided by presets using the `overrides` field:
-
-```json
-{
-  "presets": ["@company/ai-rules"],
-  "overrides": {
-    "rule-from-preset-a": "./rules/override-rule.mdc",
-    "rule-from-preset-b": false,
-    "legacy-command": false
-  }
-}
+```
+.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
@@ -271,6 +393,12 @@ Running `npx aicm install` will install rules for each package in their respecti
 - `packages/backend/.cursor/rules/aicm/`
 - `services/api/.cursor/rules/aicm/`
 
+**Why install in both places?**
+`aicm` installs configurations at both the package level AND the root level to support different workflows:
+
+- **Package-level context:** When a developer opens a specific package folder (e.g., `packages/frontend`) in their IDE, they get the specific rules, commands, and MCP servers for that package.
+- **Root-level context:** When a developer opens the monorepo root, `aicm` ensures they have access to all commands and MCP servers from all packages via the merged root configuration. While rules are typically read from nested directories by Cursor, commands and MCP servers must be configured at the root to be accessible.
+
 ### Preset Packages in Workspaces
 
 When you have a preset package within your workspace (a package that provides rules to be consumed by others), you can prevent aicm from installing rules into it by setting `skipInstall: true`:
@@ -278,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"]
 }
 ```
@@ -291,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
@@ -369,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

@@ -7,3 +7,4 @@ import { InstallOptions, InstallResult } from "./commands/install";
 export declare function install(options?: InstallOptions): Promise<InstallResult>;
 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/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 {

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);

package/dist/commands/install-workspaces.d.ts

@@ -0,0 +1,5 @@
+import { InstallResult } from "./install";
+/**
+ * Install rules across multiple packages in a workspace
+ */
+export declare function installWorkspaces(cwd: string, installOnCI: boolean, verbose?: boolean, dryRun?: boolean): Promise<InstallResult>;