aicm 0.16.1 → 0.17.1

package/README.md

@@ -2,56 +2,76 @@
 
 > AI Configuration Manager
 
-A CLI tool for managing Agentic configurations across projects
+A CLI tool for managing Agentic configurations across projects.
 
 ![aicm](https://github.com/user-attachments/assets/ca38f2d6-ece6-43ad-a127-6f4fce8b2a5a)
 
+## Table of Contents
+
+- [Why](#why)
+- [Supported Environments](#supported-environments)
+- [Getting Started](#getting-started)
+  - [Creating a Preset](#creating-a-preset)
+  - [Using a Preset](#using-a-preset)
+- [Features](#features)
+  - [Rules](#using-rules)
+  - [Commands](#using-commands)
+  - [MCP Servers](#mcp-servers)
+  - [Auxiliary Files](#referencing-auxiliary-files)
+  - [Overrides](#overrides)
+- [Workspaces Support](#workspaces-support)
+- [Configuration](#configuration)
+- [CLI Commands](#cli-commands)
+- [Node.js API](#nodejs-api)
+
 ## Why
 
-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.
+Modern AI-powered IDEs like Cursor and Agents like Codex allow developers to add custom instructions, commands, and MCP servers. However, keeping these configurations consistent across a team or multiple projects is a challenge.
 
-**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.
+**aicm** enables **"Write Once, Use Everywhere"** for your AI configurations.
 
-## How it works
+- **Team Consistency:** Ensure every developer on your team uses the same rules and best practices.
+- **Reusable Presets:** Bundle your rules, commands & MCP configurations into npm packages (e.g., `@company/ai-preset`) to share them across your organization.
+- **Multi-Target Support:** Write rules once in the comprehensive `.mdc` format, and automatically deploy them to Cursor, Windsurf, Codex, and Claude.
 
-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:
+## Supported Environments
 
-- **Cursor**: Native `.mdc` files with full feature support
-- **Windsurf**: Generates `.windsurfrules` file
-- **Codex**: Generates `AGENTS.md` file
-- **Claude**: Generates `CLAUDE.md` file
+aicm acts as a bridge between your configuration and your AI tools. It accepts Cursor's `.mdc` format and can transform it for other environments:
 
-This approach ensures you write your rules once in the richest format available, while maintaining compatibility across different AI development environments.
+| Target       | Installation                                                                   |
+| ------------ | ------------------------------------------------------------------------------ |
+| **Cursor**   | Copies `.mdc` files to `.cursor/rules/aicm/` and configures `.cursor/mcp.json` |
+| **Windsurf** | Generates a `.windsurfrules` file that links to rules in `.aicm/`              |
+| **Codex**    | Generates an `AGENTS.md` file that references rules in `.aicm/`                |
+| **Claude**   | Generates a `CLAUDE.md` file that references rules in `.aicm/`                 |
 
 ## Getting Started
 
 The easiest way to get started with aicm is by using **presets** - npm packages containing rules and MCP configurations that you can install in any project.
 
-### Using a preset
+### Demo
 
-1. **Install a preset npm package**:
+We'll install [an npm package](https://github.com/ranyitz/pirate-coding) containing a simple "Pirate Coding" preset to demonstrate how aicm works.
+
+1. **Install the demo preset package**:
 
 ```bash
-npm install --save-dev @team/ai-preset
+npm install --save-dev pirate-coding
 ```
 
-2. **Create an `aicm.json` file** in your project root:
+2. **Create an `aicm.json` file** in your project:
 
-```json
-{ "presets": ["@team/ai-preset"] }
+```bash
+echo '{ "presets": ["pirate-coding"] }' > aicm.json
 ```
 
-3. **Add a prepare script** to your `package.json` to install all preset rules and MCPs:
+3. **Install all rules & MCPs from your configuration**:
 
-```json
-{
-  "scripts": {
-    "prepare": "npx aicm  -y install"
-  }
-}
+```bash
+npx aicm install
 ```
 
-The rules are now installed in `.cursor/rules/aicm/` and any MCP servers are configured in `.cursor/mcp.json`.
+After installation, open Cursor and ask it to do something. Your AI assistant will respond with pirate-themed coding advice.
 
 ### Creating a Preset
 
@@ -85,111 +105,130 @@ The rules are now installed in `.cursor/rules/aicm/` and any MCP servers are con
 
 > **Note:** This is syntactic sugar for `@team/ai-preset/aicm.json`.
 
-### Using Local Rules
+### Using a Preset
 
-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.
+To use a real preset in your production project:
 
-```json
-{
-  "rulesDir": "path/to/rules/dir"
-}
-```
+1. **Install a preset npm package**:
 
-### Using Commands
+```bash
+npm install --save-dev @team/ai-preset
+```
 
-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 so they install automatically into Cursor.
+2. **Create an `aicm.json` file** in your project root:
 
-#### Local Commands
+```json
+{ "presets": ["@team/ai-preset"] }
+```
 
-Add a commands directory to your project configuration:
+3. **Add a prepare script** to your `package.json` to ensure rules are always up to date:
 
 ```json
 {
-  "commandsDir": "./commands",
-  "targets": ["cursor"]
+  "scripts": {
+    "prepare": "npx aicm -y install"
+  }
 }
 ```
 
-Command files ending in `.md` are installed to `.cursor/commands/aicm/` and appear in Cursor under the `/` command menu.
+The rules are now installed in `.cursor/rules/aicm/` and any MCP servers are configured in `.cursor/mcp.json`.
+
+### 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.
+
+## Features
+
+### Using Rules
 
-#### Commands in Presets
+aicm uses Cursor's `.mdc` files for rules. Read more about the format [here](https://cursor.com/docs/context/rules).
 
-Presets can ship reusable command libraries in addition to rules:
+Add a rules directory to your project configuration:
 
 ```json
 {
-  "rulesDir": "rules",
-  "commandsDir": "commands"
+  "rulesDir": "./rules",
+  "targets": ["cursor"]
 }
 ```
 
-Preset command files install alongside local ones in `.cursor/commands/aicm/` so they appear with concise paths inside Cursor.
-If multiple presets provide a command at the same relative path, aicm will warn during installation and use the version from the
-last preset listed in your configuration. Use `overrides` to explicitly choose a different definition when needed.
+Rules are installed in `.cursor/rules/aicm/` and are loaded automatically by Cursor.
 
-#### Command Overrides
+### Using 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.
 
-Use the existing `overrides` field to customize or disable commands provided by presets:
+Add a commands directory to your project configuration:
 
 ```json
 {
-  "presets": ["@team/dev-preset"],
-  "overrides": {
-    "legacy-command": false,
-    "custom-test": "./commands/test.md"
-  }
+  "commandsDir": "./commands",
+  "targets": ["cursor"]
 }
 ```
 
-### Notes
-
-- Generated rules are always placed in a subdirectory for deterministic cleanup and easy gitignore.
-- Users may add `.cursor/rules/aicm/` and `.aicm/` (for Windsurf/Codex) to `.gitignore` if they do not want to track generated rules.
+Command files ending in `.md` are installed to `.cursor/commands/aicm/` and appear in Cursor under the `/` command menu.
 
-### Overrides
+### MCP Servers
 
-You can disable or replace specific rules 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
+  "mcpServers": {
+    "Playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp"]
+    }
   }
 }
 ```
 
-### Demo
+When installed, these servers are automatically added to your `.cursor/mcp.json`.
 
-We'll install [an npm package](https://github.com/ranyitz/pirate-coding) containing a simple preset to demonstrate how aicm works.
+### Referencing Auxiliary Files
 
-1. **Install the demo preset package**:
+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.
 
-```bash
-npm install --save-dev pirate-coding
-```
+Example `rules/my-rule.mdc`:
 
-2. **Create an `aicm.json` file** in your project:
+```markdown
+# My Rule
 
-```bash
-echo '{ "presets": ["pirate-coding"] }' > aicm.json
+See [Example](./example.ts) for details.
 ```
 
-3. **Install all rules & MCPs from your configuration**:
+#### Commands Referencing Files
 
-```bash
-npx aicm install
+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`:
+
+```markdown
+# Generate Schema
+
+Use the schema defined in [Schema Template](../rules/schema.json) to generate the response.
 ```
 
-This command installs all configured rules and MCPs to their IDE-specific locations.
+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).
 
-After installation, open Cursor and ask it to do something. Your AI assistant will respond with pirate-themed coding advice. You can also ask it about the aicm library which uses https://gitmcp.io/ to give you advice based on the latest documentation.
+> **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`.
 
-## Security Note
+### Overrides
 
-To prevent [prompt-injection](https://en.wikipedia.org/wiki/Prompt_injection), use only packages from trusted sources.
+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
+  }
+}
+```
 
 ## Workspaces Support
 
@@ -203,17 +242,14 @@ You can enable workspaces mode by setting the `workspaces` property to `true` in
 }
 ```
 
-aicm automatically detects workspaces if your `package.json` contains a `workspaces` configuration:
+aicm automatically detects workspaces if your `package.json` contains a `workspaces` configuration.
 
 ### How It Works
 
-1. **Discover packages**: Automatically find all directories containing `aicm.json` files in your repository
-2. **Install per package**: Install rules and MCPs for each package individually in their respective directories
-3. **Merge MCP servers**: Write a merged `.cursor/mcp.json` at the repository root containing all MCP servers from every package
-
-### How It Works
-
-Each directory containing an `aicm.json` file is treated as a separate package with its own configuration.
+1. **Discover packages**: Automatically find all directories containing `aicm.json` files in your repository.
+2. **Install per package**: Install rules and MCPs for each package individually in their respective directories.
+3. **Merge MCP servers**: Write a merged `.cursor/mcp.json` at the repository root containing all MCP servers from every package.
+4. **Merge commands**: Write a merged `.cursor/commands/aicm/` at the repository root containing all commands from every package.
 
 For example, in a workspace structure like:
 
@@ -274,17 +310,7 @@ Create an `aicm.json` file in your project root, or an `aicm` key in your projec
 - **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.
 
-### MCP Server Installation
-
-- **Cursor**: MCP server configs are written to `.cursor/mcp.json`.
-
-## Supported Targets
-
-- **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.
-- **Codex**: Rules are installed in the `.aicm` directory and referenced from `AGENTS.md`.
-
-## Commands
+## CLI Commands
 
 ### Global Options
 
@@ -347,27 +373,9 @@ install({
 });
 ```
 
-### API Reference
-
-#### `install(options?: InstallOptions): Promise<InstallResult>`
-
-Installs rules and MCP servers based on configuration.
-
-**Options:**
-
-- `cwd`: Base directory to use instead of `process.cwd()`
-- `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:
+## Security Note
 
-- `success`: Whether the operation was successful
-- `error`: Error object if the operation failed
-- `installedRuleCount`: Number of rules installed
+To prevent [prompt-injection](https://en.wikipedia.org/wiki/Prompt_injection), use only packages from trusted sources.
 
 ## Contributing
 

package/dist/commands/install.d.ts

@@ -41,6 +41,10 @@ export interface InstallResult {
      * Number of commands installed
      */
     installedCommandCount: number;
+    /**
+     * Number of assets installed
+     */
+    installedAssetCount: number;
     /**
      * Number of packages installed
      */

package/dist/commands/install.js

@@ -18,9 +18,7 @@ function getTargetPaths() {
     const projectDir = process.cwd();
     return {
         cursor: node_path_1.default.join(projectDir, ".cursor", "rules", "aicm"),
-        windsurf: node_path_1.default.join(projectDir, ".aicm"),
-        codex: node_path_1.default.join(projectDir, ".aicm"),
-        claude: node_path_1.default.join(projectDir, ".aicm"),
+        aicm: node_path_1.default.join(projectDir, ".aicm"),
     };
 }
 function writeCursorRules(rules, cursorRulesDir) {
@@ -43,7 +41,7 @@ function writeCursorRules(rules, cursorRulesDir) {
         fs_extra_1.default.writeFileSync(ruleFile, rule.content);
     }
 }
-function writeCursorCommands(commands, cursorCommandsDir) {
+function writeCursorCommands(commands, cursorCommandsDir, assets) {
     fs_extra_1.default.removeSync(cursorCommandsDir);
     for (const command of commands) {
         const commandNameParts = command.name
@@ -53,9 +51,25 @@ function writeCursorCommands(commands, cursorCommandsDir) {
         const commandPath = node_path_1.default.join(cursorCommandsDir, ...commandNameParts);
         const commandFile = commandPath + ".md";
         fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(commandFile));
-        fs_extra_1.default.writeFileSync(commandFile, command.content);
+        // If the command file references assets in the rules directory, we need to rewrite the links.
+        // Commands are installed in .cursor/commands/aicm/
+        // Rules/assets are installed in .cursor/rules/aicm/
+        // So a link like "../rules/asset.json" in source (from commands/ to rules/)
+        // needs to become "../../rules/aicm/asset.json" in target (from .cursor/commands/aicm/ to .cursor/rules/aicm/)
+        const content = rewriteCommandRelativeLinks(command.content, command.sourcePath, assets);
+        fs_extra_1.default.writeFileSync(commandFile, content);
     }
 }
+function rewriteCommandRelativeLinks(content, commandSourcePath, assets) {
+    const commandDir = node_path_1.default.dirname(commandSourcePath);
+    const assetMap = new Map(assets.map((a) => [node_path_1.default.normalize(a.sourcePath), a.name]));
+    return content.replace(/\.\.[/\\][\w\-/\\.]+/g, (match) => {
+        const resolved = node_path_1.default.normalize(node_path_1.default.resolve(commandDir, match));
+        return assetMap.has(resolved)
+            ? `../../rules/aicm/${assetMap.get(resolved)}`
+            : match;
+    });
+}
 function extractNamespaceFromPresetPath(presetPath) {
     // Special case: npm package names always use forward slashes, regardless of platform
     if (presetPath.startsWith("@")) {
@@ -68,7 +82,7 @@ function extractNamespaceFromPresetPath(presetPath) {
 /**
  * Write rules to a shared directory and update the given rules file
  */
-function writeRulesForFile(rules, ruleDir, rulesFile) {
+function writeRulesForFile(rules, assets, ruleDir, rulesFile) {
     fs_extra_1.default.emptyDirSync(ruleDir);
     const ruleFiles = rules.map((rule) => {
         let rulePath;
@@ -83,9 +97,10 @@ function writeRulesForFile(rules, ruleDir, rulesFile) {
             // For local rules, maintain the original flat structure
             rulePath = node_path_1.default.join(ruleDir, ...ruleNameParts);
         }
+        const content = rule.content;
         const physicalRulePath = rulePath + ".md";
         fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(physicalRulePath));
-        fs_extra_1.default.writeFileSync(physicalRulePath, rule.content);
+        fs_extra_1.default.writeFileSync(physicalRulePath, content);
         const relativeRuleDir = node_path_1.default.basename(ruleDir);
         // For the rules file, maintain the same structure
         let windsurfPath;
@@ -102,16 +117,46 @@ function writeRulesForFile(rules, ruleDir, rulesFile) {
         return {
             name: rule.name,
             path: windsurfPathPosix,
-            metadata: (0, rules_file_writer_1.parseRuleFrontmatter)(rule.content),
+            metadata: (0, rules_file_writer_1.parseRuleFrontmatter)(content),
         };
     });
     const rulesContent = (0, rules_file_writer_1.generateRulesFileContent)(ruleFiles);
     (0, rules_file_writer_1.writeRulesFile)(rulesContent, node_path_1.default.join(process.cwd(), rulesFile));
 }
+function writeAssetsToTargets(assets, targets) {
+    const targetPaths = getTargetPaths();
+    for (const target of targets) {
+        let targetDir;
+        switch (target) {
+            case "cursor":
+                targetDir = targetPaths.cursor;
+                break;
+            case "windsurf":
+            case "codex":
+            case "claude":
+                targetDir = targetPaths.aicm;
+                break;
+            default:
+                continue;
+        }
+        for (const asset of assets) {
+            let assetPath;
+            if (asset.presetName) {
+                const namespace = extractNamespaceFromPresetPath(asset.presetName);
+                assetPath = node_path_1.default.join(targetDir, ...namespace, asset.name);
+            }
+            else {
+                assetPath = node_path_1.default.join(targetDir, asset.name);
+            }
+            fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(assetPath));
+            fs_extra_1.default.writeFileSync(assetPath, asset.content);
+        }
+    }
+}
 /**
  * Write all collected rules to their respective IDE targets
  */
-function writeRulesToTargets(rules, targets) {
+function writeRulesToTargets(rules, assets, targets) {
     const targetPaths = getTargetPaths();
     for (const target of targets) {
         switch (target) {
@@ -122,29 +167,31 @@ function writeRulesToTargets(rules, targets) {
                 break;
             case "windsurf":
                 if (rules.length > 0) {
-                    writeRulesForFile(rules, targetPaths.windsurf, ".windsurfrules");
+                    writeRulesForFile(rules, assets, targetPaths.aicm, ".windsurfrules");
                 }
                 break;
             case "codex":
                 if (rules.length > 0) {
-                    writeRulesForFile(rules, targetPaths.codex, "AGENTS.md");
+                    writeRulesForFile(rules, assets, targetPaths.aicm, "AGENTS.md");
                 }
                 break;
             case "claude":
                 if (rules.length > 0) {
-                    writeRulesForFile(rules, targetPaths.claude, "CLAUDE.md");
+                    writeRulesForFile(rules, assets, targetPaths.aicm, "CLAUDE.md");
                 }
                 break;
         }
     }
+    // Write assets after rules so they don't get wiped by emptyDirSync
+    writeAssetsToTargets(assets, targets);
 }
-function writeCommandsToTargets(commands, targets) {
+function writeCommandsToTargets(commands, assets, targets) {
     const projectDir = process.cwd();
     const cursorRoot = node_path_1.default.join(projectDir, ".cursor");
     for (const target of targets) {
         if (target === "cursor") {
             const commandsDir = node_path_1.default.join(cursorRoot, "commands", "aicm");
-            writeCursorCommands(commands, commandsDir);
+            writeCursorCommands(commands, commandsDir, assets);
         }
         // Other targets do not support commands yet
     }
@@ -357,15 +404,17 @@ async function installPackage(options = {}) {
                 error: new Error("Configuration file not found"),
                 installedRuleCount: 0,
                 installedCommandCount: 0,
+                installedAssetCount: 0,
                 packagesCount: 0,
             };
         }
-        const { config, rules, commands, mcpServers } = resolvedConfig;
+        const { config, rules, commands, assets, mcpServers } = resolvedConfig;
         if (config.skipInstall === true) {
             return {
                 success: true,
                 installedRuleCount: 0,
                 installedCommandCount: 0,
+                installedAssetCount: 0,
                 packagesCount: 0,
             };
         }
@@ -373,8 +422,8 @@ async function installPackage(options = {}) {
         const commandsToInstall = dedupeCommandsForInstall(commands);
         try {
             if (!options.dryRun) {
-                writeRulesToTargets(rules, config.targets);
-                writeCommandsToTargets(commandsToInstall, config.targets);
+                writeRulesToTargets(rules, assets, config.targets);
+                writeCommandsToTargets(commandsToInstall, assets, config.targets);
                 if (mcpServers && Object.keys(mcpServers).length > 0) {
                     writeMcpServersToTargets(mcpServers, config.targets, cwd);
                 }
@@ -385,6 +434,7 @@ async function installPackage(options = {}) {
                 success: true,
                 installedRuleCount: uniqueRuleCount,
                 installedCommandCount: uniqueCommandCount,
+                installedAssetCount: assets.length,
                 packagesCount: 1,
             };
         }
@@ -394,6 +444,7 @@ async function installPackage(options = {}) {
                 error: error instanceof Error ? error : new Error(String(error)),
                 installedRuleCount: 0,
                 installedCommandCount: 0,
+                installedAssetCount: 0,
                 packagesCount: 0,
             };
         }
@@ -406,6 +457,7 @@ async function installWorkspacesPackages(packages, options = {}) {
     const results = [];
     let totalRuleCount = 0;
     let totalCommandCount = 0;
+    let totalAssetCount = 0;
     // Install packages sequentially for now (can be parallelized later)
     for (const pkg of packages) {
         const packagePath = pkg.absolutePath;
@@ -417,12 +469,14 @@ async function installWorkspacesPackages(packages, options = {}) {
             });
             totalRuleCount += result.installedRuleCount;
             totalCommandCount += result.installedCommandCount;
+            totalAssetCount += result.installedAssetCount;
             results.push({
                 path: pkg.relativePath,
                 success: result.success,
                 error: result.error,
                 installedRuleCount: result.installedRuleCount,
                 installedCommandCount: result.installedCommandCount,
+                installedAssetCount: result.installedAssetCount,
             });
         }
         catch (error) {
@@ -432,6 +486,7 @@ async function installWorkspacesPackages(packages, options = {}) {
                 error: error instanceof Error ? error : new Error(String(error)),
                 installedRuleCount: 0,
                 installedCommandCount: 0,
+                installedAssetCount: 0,
             });
         }
     }
@@ -441,6 +496,7 @@ async function installWorkspacesPackages(packages, options = {}) {
         packages: results,
         totalRuleCount,
         totalCommandCount,
+        totalAssetCount,
     };
 }
 /**
@@ -471,6 +527,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                 error: new Error("No packages with aicm configurations found"),
                 installedRuleCount: 0,
                 installedCommandCount: 0,
+                installedAssetCount: 0,
                 packagesCount: 0,
             };
         }
@@ -495,7 +552,9 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
             workspaceCommands.length > 0 &&
             workspaceCommandTargets.length > 0) {
             const dedupedWorkspaceCommands = dedupeCommandsForInstall(workspaceCommands);
-            writeCommandsToTargets(dedupedWorkspaceCommands, workspaceCommandTargets);
+            // Collect all assets from packages for command path rewriting
+            const allAssets = packages.flatMap((pkg) => { var _a; return (_a = pkg.config.assets) !== null && _a !== void 0 ? _a : []; });
+            writeCommandsToTargets(dedupedWorkspaceCommands, allAssets, workspaceCommandTargets);
         }
         const { merged: rootMcp, conflicts } = mergeWorkspaceMcpServers(packages);
         const hasCursorTarget = packages.some((p) => p.config.config.targets.includes("cursor"));
@@ -538,6 +597,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                 error: new Error(`Package installation failed for ${failedPackages.length} package(s): ${errorDetails}`),
                 installedRuleCount: result.totalRuleCount,
                 installedCommandCount: result.totalCommandCount,
+                installedAssetCount: result.totalAssetCount,
                 packagesCount: result.packages.length,
             };
         }
@@ -545,6 +605,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
             success: true,
             installedRuleCount: result.totalRuleCount,
             installedCommandCount: result.totalCommandCount,
+            installedAssetCount: result.totalAssetCount,
             packagesCount: result.packages.length,
         };
     });
@@ -562,6 +623,7 @@ async function install(options = {}) {
             success: true,
             installedRuleCount: 0,
             installedCommandCount: 0,
+            installedAssetCount: 0,
             packagesCount: 0,
         };
     }

package/dist/utils/config.d.ts

@@ -40,6 +40,13 @@ export interface ManagedFile {
     source: "local" | "preset";
     presetName?: string;
 }
+export interface AssetFile {
+    name: string;
+    content: Buffer;
+    sourcePath: string;
+    source: "local" | "preset";
+    presetName?: string;
+}
 export type RuleFile = ManagedFile;
 export type CommandFile = ManagedFile;
 export interface RuleCollection {
@@ -49,6 +56,7 @@ export interface ResolvedConfig {
     config: Config;
     rules: RuleFile[];
     commands: CommandFile[];
+    assets: AssetFile[];
     mcpServers: MCPServers;
 }
 export declare const ALLOWED_CONFIG_KEYS: readonly ["rulesDir", "commandsDir", "targets", "presets", "overrides", "mcpServers", "workspaces", "skipInstall"];
@@ -60,6 +68,7 @@ export declare function applyDefaults(config: RawConfig, workspaces: boolean): C
 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 loadCommandsFromDirectory(commandsDir: string, source: "local" | "preset", presetName?: string): Promise<CommandFile[]>;
+export declare function loadAssetsFromDirectory(rulesDir: string, source: "local" | "preset", presetName?: string): Promise<AssetFile[]>;
 export declare function resolvePresetPath(presetPath: string, cwd: string): string | null;
 export declare function loadPreset(presetPath: string, cwd: string): Promise<{
     config: Config;
@@ -69,6 +78,7 @@ export declare function loadPreset(presetPath: string, cwd: string): Promise<{
 export declare function loadAllRules(config: Config, cwd: string): Promise<{
     rules: RuleFile[];
     commands: CommandFile[];
+    assets: AssetFile[];
     mcpServers: MCPServers;
 }>;
 export declare function applyOverrides<T extends ManagedFile>(files: T[], overrides: Record<string, string | false>, cwd: string): T[];

package/dist/utils/config.js

@@ -10,6 +10,7 @@ exports.applyDefaults = applyDefaults;
 exports.validateConfig = validateConfig;
 exports.loadRulesFromDirectory = loadRulesFromDirectory;
 exports.loadCommandsFromDirectory = loadCommandsFromDirectory;
+exports.loadAssetsFromDirectory = loadAssetsFromDirectory;
 exports.resolvePresetPath = resolvePresetPath;
 exports.loadPreset = loadPreset;
 exports.loadAllRules = loadAllRules;
@@ -175,6 +176,34 @@ async function loadCommandsFromDirectory(commandsDir, source, presetName) {
     }
     return commands;
 }
+async function loadAssetsFromDirectory(rulesDir, source, presetName) {
+    const assets = [];
+    if (!fs_extra_1.default.existsSync(rulesDir)) {
+        return assets;
+    }
+    // Find all files except .mdc files and hidden files
+    const pattern = node_path_1.default.join(rulesDir, "**/*").replace(/\\/g, "/");
+    const filePaths = await (0, fast_glob_1.default)(pattern, {
+        onlyFiles: true,
+        absolute: true,
+        ignore: ["**/*.mdc", "**/.*"],
+    });
+    for (const filePath of filePaths) {
+        const content = await fs_extra_1.default.readFile(filePath);
+        // Preserve directory structure by using relative path from rulesDir
+        const relativePath = node_path_1.default.relative(rulesDir, filePath);
+        // Keep extension for assets
+        const assetName = relativePath.replace(/\\/g, "/");
+        assets.push({
+            name: assetName,
+            content,
+            sourcePath: filePath,
+            source,
+            presetName,
+        });
+    }
+    return assets;
+}
 function resolvePresetPath(presetPath, cwd) {
     // Support specifying aicm.json directory and load the config from it
     if (!presetPath.endsWith(".json")) {
@@ -230,12 +259,15 @@ async function loadPreset(presetPath, cwd) {
 async function loadAllRules(config, cwd) {
     const allRules = [];
     const allCommands = [];
+    const allAssets = [];
     let mergedMcpServers = { ...config.mcpServers };
     // Load local rules only if rulesDir is provided
     if (config.rulesDir) {
         const localRulesPath = node_path_1.default.resolve(cwd, config.rulesDir);
         const localRules = await loadRulesFromDirectory(localRulesPath, "local");
+        const localAssets = await loadAssetsFromDirectory(localRulesPath, "local");
         allRules.push(...localRules);
+        allAssets.push(...localAssets);
     }
     if (config.commandsDir) {
         const localCommandsPath = node_path_1.default.resolve(cwd, config.commandsDir);
@@ -247,7 +279,9 @@ async function loadAllRules(config, cwd) {
             const preset = await loadPreset(presetPath, cwd);
             if (preset.rulesDir) {
                 const presetRules = await loadRulesFromDirectory(preset.rulesDir, "preset", presetPath);
+                const presetAssets = await loadAssetsFromDirectory(preset.rulesDir, "preset", presetPath);
                 allRules.push(...presetRules);
+                allAssets.push(...presetAssets);
             }
             if (preset.commandsDir) {
                 const presetCommands = await loadCommandsFromDirectory(preset.commandsDir, "preset", presetPath);
@@ -262,6 +296,7 @@ async function loadAllRules(config, cwd) {
     return {
         rules: allRules,
         commands: allCommands,
+        assets: allAssets,
         mcpServers: mergedMcpServers,
     };
 }
@@ -341,9 +376,10 @@ async function loadConfig(cwd) {
     const isWorkspaces = resolveWorkspaces(config, configResult.filepath, workingDir);
     validateConfig(config, configResult.filepath, workingDir, isWorkspaces);
     const configWithDefaults = applyDefaults(config, isWorkspaces);
-    const { rules, commands, mcpServers } = await loadAllRules(configWithDefaults, workingDir);
+    const { rules, commands, assets, mcpServers } = await loadAllRules(configWithDefaults, workingDir);
     let rulesWithOverrides = rules;
     let commandsWithOverrides = commands;
+    // Note: Assets are not currently supported in overrides as they are binary/varied files
     if (configWithDefaults.overrides) {
         const overrides = configWithDefaults.overrides;
         const ruleNames = new Set(rules.map((rule) => rule.name));
@@ -366,6 +402,7 @@ async function loadConfig(cwd) {
         config: configWithDefaults,
         rules: rulesWithOverrides,
         commands: commandsWithOverrides,
+        assets,
         mcpServers,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicm",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "A TypeScript CLI tool for managing AI IDE rules across different projects and teams",
   "main": "dist/api.js",
   "types": "dist/api.d.ts",