aicm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# 📜 rules-manager
+
+A CLI tool for syncing AI IDE rules across projects
+
+## Why
+
+Development teams struggle with:
+
+- **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.
+
+**rules-manager** is a CLI tool that helps streamline rule management:
+
+- 🏛️ **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)
+
+## 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.
+
+Considering the following npm package:
+
+```
+@myteam/ai-tools
+├── package.json
+└── rules/
+    ├── typescript.mdc
+    ├── react.mdc
+    └── general.mdc
+```
+
+1. **Point to the path within the npm package**
+
+In your project's `rules.json`, reference the package and the specific rule:
+
+```json
+{
+  "ides": ["cursor"],
+  "rules": {
+    "typescript": "@myteam/ai-tools/rules/typescript.mdc",
+    "react": "@myteam/ai-tools/rules/react.mdc",
+    "general": "@myteam/ai-tools/rules/general.mdc"
+  }
+}
+```
+
+2. **Add a postinstall script** to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "npx -y rules-manager install"
+  }
+}
+```
+
+Now the rules will be linked to `.cursor/rules/` when you run `npm install`.
+
+### Using Presets
+
+Presets allow you to bundle multiple rules into a single configuration that can be shared across projects.
+
+1. **Create a preset file**
+
+Create a JSON file with your rule definitions:
+
+```json
+{
+  "rules": {
+    "typescript": "./rules/typescript.mdc",
+    "react": "./rules/react.mdc"
+  }
+}
+```
+
+2. **Reference the preset in your project**
+
+In your project's `rules.json`, reference the preset:
+
+```json
+{
+  "ides": ["cursor"],
+  "presets": ["@myteam/ai-tools/my-rule.json"]
+}
+```
+
+When you run `npx rules-manager install`, all rules from the preset will be installed to `.cursor/rules/`.
+
+### Demo
+
+Here is a package to demonstrate how rules manager works:
+
+```bash
+# Install a package containing a rule
+npm install --save-dev pirate-coding-rule
+
+# Install the rule via the rules-manager CLI
+npx -y rules-manager install pirate-coding pirate-coding-rule/rule.mdc
+```
+
+This command will:
+
+1. Create a `rules.json` file if it doesn't exist
+2. Add the rule to the configuration
+3. Install the rule to `.cursor/rules/`
+
+After installation, open Cursor and ask it to do something. Your AI assistant will respond with pirate-themed coding advice.
+
+## Security Note
+
+To prevent [prompt-injection](https://en.wikipedia.org/wiki/Prompt_injection), use only packages from trusted sources.
+
+## Configuration
+
+rules-manager uses a JSON configuration file (`rules.json`) in your project root directory.
+
+```json
+{
+  "ides": ["cursor"],
+  "presets": ["@my-team/ai-tools/my-rules.json"],
+  "rules": {
+    "team-standards": "@my-team/ai-tools/rules/team-standards.mdc"
+  }
+}
+```
+
+- **ides**: Array of IDE names where rules should be installed. Currently supported values:
+
+  - `"cursor"`: For the Cursor IDE
+
+- **rules**: Object containing rule configurations
+
+  - **rule-name**: A unique identifier for the rule
+  - **source-location**: Location of the rule file (path within an npm package or local path)
+
+- **presets**: Array of preset configurations to include. Each preset is a path to a JSON file (npm package or local path) that contains additional rules.
+  - Presets allow organizations to bundle a set of rules that can be easily shared across projects
+  - Preset files should contain a `rules` object with the same structure as the main configuration
+
+### Rule Source Types
+
+The type of rule is automatically detected based on the source format:
+
+#### NPM Source
+
+Rules provided by NPM packages. The package must be installed either globally or in your project's `node_modules`. Sources that start with `@` or don't contain start with path separators are detected as NPM packages.
+
+```json
+"react-best-practices": "@my-team/ai-tools/rules-manager-react"
+```
+
+#### Local Source
+
+Rules stored locally in your project or filesystem. Any path containing slashes or backslashes is detected as a local file path.
+
+```json
+"personal-rules": "./rules/custom.mdc"
+```
+
+## Supported IDEs
+
+- **Cursor**: Rules are installed as individual `.mdc` files in the Cursor rules directory (`.cursor/rules/`)
+- **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.
+
+## Commands
+
+### Global Options
+
+These options are available for all commands:
+
+- `--help`, `-h`: Show help information
+- `--version`, `-v`: Show version information
+
+### `init`
+
+Initializes a new configuration file in your current directory.
+
+```bash
+npx rules-manager init
+```
+
+### `install`
+
+Installs rules from your configuration to the appropriate IDE locations.
+
+```bash
+npx rules-manager install [rule-name] [rule-source]
+```
+
+**Options:**
+
+- `[rule-name]`: Optional - Name of a specific rule to install instead of all rules
+- `[rule-source]`: Optional - Source of the rule (npm package or local path)
+
+**Examples:**
+
+```bash
+# Install all configured rules
+npx -y rules-manager install
+
+# Install a rule from an npm package and update configuration
+npx -y rules-manager install react-best-practices @my-team/ai-tools/react-best-practices.mdc
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Development
+
+### Testing
+
+The project includes both unit tests and end-to-end (E2E) tests:
+
+```bash
+# Run all tests
+npm test
+
+# Run only unit tests
+npm run test:unit
+
+# Run only E2E tests
+npm run test:e2e
+```
+
+## License
+
+MIT

package/dist/commands/check-updates.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+export declare const checkUpdates: Command;
+export declare function checkNpmPackageUpdates(packageName: string): Promise<{
+    currentVersion: string;
+    latestVersion: string;
+}>;

package/dist/commands/check-updates.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUpdates = void 0;
+exports.checkNpmPackageUpdates = checkNpmPackageUpdates;
+const commander_1 = require("commander");
+const config_1 = require("../utils/config");
+const rule_detector_1 = require("../utils/rule-detector");
+const semver_1 = __importDefault(require("semver"));
+const chalk_1 = __importDefault(require("chalk"));
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+exports.checkUpdates = new commander_1.Command("check-updates")
+    .description("Check for updates to installed rules")
+    .option("-a, --auto-sync", "Automatically sync updates if available")
+    .action(async (options) => {
+    const config = await (0, config_1.getConfig)();
+    if (!config) {
+        console.error("No configuration file found. Run 'rules-manager init' first.");
+        process.exit(1);
+    }
+    const updates = [];
+    const errors = [];
+    // Check each rule for updates
+    for (const [ruleName, source] of Object.entries(config.rules)) {
+        try {
+            const ruleType = (0, rule_detector_1.detectRuleType)(source);
+            if (ruleType === "npm") {
+                const { currentVersion, latestVersion } = await checkNpmPackageUpdates(source.split("/")[0] // Get package name from source
+                );
+                if (latestVersion && semver_1.default.gt(latestVersion, currentVersion)) {
+                    updates.push({
+                        name: ruleName,
+                        current: currentVersion,
+                        latest: latestVersion,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            errors.push(`Error checking updates for ${ruleName}: ${errorMessage}`);
+        }
+    }
+    // Display results
+    if (updates.length > 0) {
+        console.log(chalk_1.default.yellow("\nUpdates available:"));
+        updates.forEach((update) => {
+            console.log(chalk_1.default.yellow(`  ${update.name}: ${update.current} → ${update.latest}`));
+        });
+        if (options.autoSync) {
+            console.log(chalk_1.default.blue("\nAuto-syncing updates..."));
+            // Trigger install command with updated versions
+            // This will be implemented in the install command
+            process.exit(0);
+        }
+        else {
+            console.log(chalk_1.default.blue("\nRun 'rules-manager install --update' to install updates"));
+        }
+    }
+    else {
+        console.log(chalk_1.default.green("All rules are up to date!"));
+    }
+    if (errors.length > 0) {
+        console.error(chalk_1.default.red("\nErrors:"));
+        errors.forEach((error) => console.error(chalk_1.default.red(`  ${error}`)));
+        process.exit(1);
+    }
+});
+async function checkNpmPackageUpdates(packageName) {
+    // Get current version from package.json
+    const packageJsonPath = (0, path_1.join)(process.cwd(), "node_modules", packageName, "package.json");
+    const packageJson = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, "utf-8"));
+    const currentVersion = packageJson.version;
+    // Get latest version from npm registry
+    const stdout = (0, child_process_1.execSync)(`npm view ${packageName} version`, {
+        encoding: "utf-8",
+    });
+    const latestVersion = stdout.trim();
+    return { currentVersion, latestVersion };
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(): void;

package/dist/commands/init.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCommand = initCommand;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const defaultConfig = {
+    ides: ["cursor"],
+    rules: {},
+};
+function initCommand() {
+    const configPath = path_1.default.join(process.cwd(), "rules.json");
+    if (fs_extra_1.default.existsSync(configPath)) {
+        console.log(chalk_1.default.yellow("Configuration file already exists!"));
+        return;
+    }
+    try {
+        fs_extra_1.default.writeJsonSync(configPath, defaultConfig, { spaces: 2 });
+        console.log(chalk_1.default.green("Configuration file created successfully!"));
+        console.log(`Configuration file location: ${chalk_1.default.blue(configPath)}`);
+        console.log(`\nNext steps:`);
+        console.log(`  1. Edit ${chalk_1.default.blue("rules.json")} to configure your rules`);
+        console.log(`  2. Run ${chalk_1.default.blue("npx rules-manager install")} to install rules`);
+    }
+    catch (error) {
+        console.error(chalk_1.default.red("Error creating configuration file:"), error);
+    }
+}

package/dist/commands/install.d.ts

@@ -0,0 +1 @@
+export declare function installCommand(): Promise<void>;

package/dist/commands/install.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installCommand = installCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const arg_1 = __importDefault(require("arg"));
+const config_1 = require("../utils/config");
+const rule_detector_1 = require("../utils/rule-detector");
+const rule_collector_1 = require("../utils/rule-collector");
+const rule_writer_1 = require("../utils/rule-writer");
+// Default configuration
+const defaultConfig = {
+    ides: ["cursor", "windsurf"],
+    rules: {},
+    presets: [],
+};
+async function installCommand() {
+    // Parse command-specific arguments
+    const args = (0, arg_1.default)({
+    // Removed flags as we'll infer the type from the source
+    }, {
+        permissive: true,
+        argv: process.argv.slice(3), // Skip the first two args and the command name
+    });
+    // Get rule name and source if provided
+    const ruleName = args._.length > 0 ? args._[0] : null;
+    const ruleSource = args._.length > 1 ? args._[1] : null;
+    try {
+        // Initialize rule collection
+        const ruleCollection = (0, rule_collector_1.initRuleCollection)();
+        // If a rule name and source are provided, install directly
+        if (ruleName && ruleSource) {
+            // Detect rule type from the source string
+            const ruleType = (0, rule_detector_1.detectRuleType)(ruleSource);
+            // Create config file if it doesn't exist
+            let config = (0, config_1.getConfig)();
+            if (!config) {
+                config = { ...defaultConfig };
+                console.log(chalk_1.default.blue("Configuration file not found. Creating a new one..."));
+            }
+            // Add the rule to the config
+            config.rules[ruleName] = ruleSource;
+            // Save the updated config
+            (0, config_1.saveConfig)(config);
+            console.log(chalk_1.default.green("Configuration updated successfully!"));
+            // Collect the rule based on its type
+            let ruleContent;
+            switch (ruleType) {
+                case "npm":
+                    ruleContent = (0, rule_collector_1.collectNpmRule)(ruleName, ruleSource);
+                    break;
+                case "local":
+                    ruleContent = (0, rule_collector_1.collectLocalRule)(ruleName, ruleSource);
+                    break;
+                default:
+                    console.log(chalk_1.default.yellow(`Unknown rule type: ${ruleType}`));
+                    return;
+            }
+            // Add rule to collection
+            (0, rule_collector_1.addRuleToCollection)(ruleCollection, ruleContent, config.ides);
+            // Write rules to targets
+            (0, rule_writer_1.writeRulesToTargets)(ruleCollection);
+            console.log(chalk_1.default.green("\nRules installation completed!"));
+            return;
+        }
+        // Load configuration
+        let config = (0, config_1.getConfig)();
+        // If config doesn't exist, create a new one
+        if (!config) {
+            config = { ...defaultConfig };
+            console.log(chalk_1.default.blue("Configuration file not found. Creating a new one..."));
+            (0, config_1.saveConfig)(config);
+            console.log(chalk_1.default.green("Empty configuration file created successfully!"));
+            console.log(chalk_1.default.yellow("No rules defined in configuration."));
+            console.log(`Edit your ${chalk_1.default.blue("rules.json")} file to add rules or use the direct install command: npx rules-manager install <rule-name> <rule-source>`);
+            return;
+        }
+        // Check if rules are defined (either directly or through presets)
+        if (!config.rules || Object.keys(config.rules).length === 0) {
+            // If there are no presets defined either, show a message
+            if (!config.presets || config.presets.length === 0) {
+                console.log(chalk_1.default.yellow("No rules defined in configuration."));
+                console.log(`Edit your ${chalk_1.default.blue("rules.json")} file to add rules or use the direct install command: npx rules-manager install <rule-name> <rule-source>`);
+                return;
+            }
+        }
+        if (config.presets && config.presets.length > 0) {
+            const hasValidPresets = true;
+            // If no valid presets and no direct rules, exit
+            if (!hasValidPresets &&
+                (!config.rules || Object.keys(config.rules).length === 0)) {
+                console.log(chalk_1.default.yellow("\nNo valid rules found in configuration or presets."));
+                return;
+            }
+        }
+        // Process each rule (or just the specific one if provided)
+        let hasErrors = false;
+        for (const [name, source] of Object.entries(config.rules)) {
+            // Skip if a specific rule was requested and this isn't it
+            if (ruleName && name !== ruleName) {
+                continue;
+            }
+            // Detect rule type from the source string
+            const ruleType = (0, rule_detector_1.detectRuleType)(source);
+            // Get the base path of the preset file if this rule came from a preset
+            const ruleBasePath = (0, config_1.getRuleSource)(config, name);
+            // Collect the rule based on its type
+            try {
+                let ruleContent;
+                switch (ruleType) {
+                    case "npm":
+                        ruleContent = (0, rule_collector_1.collectNpmRule)(name, source);
+                        break;
+                    case "local":
+                        ruleContent = (0, rule_collector_1.collectLocalRule)(name, source, ruleBasePath);
+                        break;
+                    default:
+                        console.log(chalk_1.default.yellow(`Unknown rule type: ${ruleType}`));
+                        continue;
+                }
+                // Add rule to collection
+                (0, rule_collector_1.addRuleToCollection)(ruleCollection, ruleContent, config.ides);
+            }
+            catch (error) {
+                hasErrors = true;
+                console.error(chalk_1.default.red(`Error processing rule ${name}: ${error instanceof Error ? error.message : String(error)}`));
+                // If a specific rule was requested and it failed, exit immediately
+                if (ruleName) {
+                    throw error;
+                }
+            }
+        }
+        // If there were errors and we're not processing a specific rule, exit with error
+        if (hasErrors && !ruleName) {
+            throw new Error("One or more rules failed to process");
+        }
+        // If a specific rule was requested but not found
+        if (ruleName && !Object.keys(config.rules).includes(ruleName)) {
+            console.log(chalk_1.default.yellow(`Rule "${ruleName}" not found in configuration.`));
+            return;
+        }
+        // Write all collected rules to their targets
+        (0, rule_writer_1.writeRulesToTargets)(ruleCollection);
+        console.log(chalk_1.default.green("\nRules installation completed!"));
+    }
+    catch (error) {
+        console.error(chalk_1.default.red(`Error during rule installation: ${error instanceof Error ? error.message : String(error)}`));
+        process.exit(1);
+    }
+}

package/dist/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function listCommand(): void;

package/dist/commands/list.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCommand = listCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../utils/config");
+const rule_status_1 = require("../utils/rule-status");
+const rule_detector_1 = require("../utils/rule-detector");
+function listCommand() {
+    const config = (0, config_1.getConfig)();
+    if (!config) {
+        console.log(chalk_1.default.red("Configuration file not found!"));
+        console.log(`Run ${chalk_1.default.blue("npx rules-manager init")} to create one.`);
+        return;
+    }
+    if (!config.rules || Object.keys(config.rules).length === 0) {
+        console.log(chalk_1.default.yellow("No rules defined in configuration."));
+        console.log(`Edit your ${chalk_1.default.blue("rules.json")} file to add rules.`);
+        return;
+    }
+    console.log(chalk_1.default.blue("Configured Rules:"));
+    console.log(chalk_1.default.dim("─".repeat(50)));
+    for (const [ruleName, source] of Object.entries(config.rules)) {
+        const ruleType = (0, rule_detector_1.detectRuleType)(source);
+        const status = (0, rule_status_1.checkRuleStatus)(ruleName, ruleType, config.ides);
+        const statusColor = status
+            ? chalk_1.default.green("Installed")
+            : chalk_1.default.yellow("Not installed");
+        console.log(`${chalk_1.default.bold(ruleName)}`);
+        console.log(`  Source: ${source}`);
+        console.log(`  Type: ${ruleType} (auto-detected)`);
+        console.log(`  Status: ${statusColor}`);
+        console.log(chalk_1.default.dim("─".repeat(50)));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const arg_1 = __importDefault(require("arg"));
+const chalk_1 = __importDefault(require("chalk"));
+const init_1 = require("./commands/init");
+const install_1 = require("./commands/install");
+const list_1 = require("./commands/list");
+// Define version from package.json
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const pkg = require("../package.json");
+// Parse arguments
+const args = (0, arg_1.default)({
+    "--help": Boolean,
+    "--version": Boolean,
+    "-h": "--help",
+    "-v": "--version",
+}, {
+    permissive: true,
+    argv: process.argv.slice(2),
+});
+// Show version
+if (args["--version"]) {
+    console.log(pkg.version);
+    process.exit(0);
+}
+// Get the command (first non-flag argument)
+const command = args._.length > 0 ? args._[0] : null;
+// Execute the appropriate command
+switch (command) {
+    case "init":
+        (0, init_1.initCommand)();
+        break;
+    case "install":
+        (0, install_1.installCommand)();
+        break;
+    case "list":
+        (0, list_1.listCommand)();
+        break;
+    default:
+        // Show help
+        showHelp();
+        break;
+}
+function showHelp() {
+    console.log(`
+${chalk_1.default.bold("rules-manager")} - A CLI tool for managing AI IDE rules
+
+${chalk_1.default.bold("USAGE")}
+  $ rules-manager [command] [options]
+
+${chalk_1.default.bold("COMMANDS")}
+  init                Initialize a new rules-manager configuration file
+  install             Install rules from configured sources
+  list                List all configured rules and their status
+
+${chalk_1.default.bold("OPTIONS")}
+  -h, --help          Show this help message
+  -v, --version       Show version number
+
+${chalk_1.default.bold("EXAMPLES")}
+  $ rules-manager init
+  $ rules-manager install
+  $ rules-manager list
+`);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,26 @@
+export type Rule = string;
+export interface Rules {
+    [ruleName: string]: Rule;
+}
+export interface Config {
+    ides: string[];
+    rules: Rules;
+    presets?: string[];
+}
+export interface RuleMetadata {
+    type?: string;
+    alwaysApply?: boolean | string;
+    globs?: string[] | string;
+    description?: string;
+    [key: string]: any;
+}
+export interface RuleContent {
+    name: string;
+    content: string;
+    metadata: RuleMetadata;
+    sourcePath: string;
+}
+export interface RuleCollection {
+    cursor: RuleContent[];
+    windsurf: RuleContent[];
+}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });