@malamute/ai-rules 1.2.0 → 1.3.0

package/README.md

@@ -313,11 +313,13 @@ mkdir configs/your-tech
 ### Adding a Technology
 
 1. Create `configs/[tech]/CLAUDE.md` — start with `@../_shared/CLAUDE.md`
-2. Add rules in `configs/[tech]/.claude/rules/`
-3. Add `configs/[tech]/.claude/settings.json` for permissions
+2. Add rules in `configs/[tech]/rules/`
+3. Add `configs/[tech]/settings.json` for permissions
 4. Add tests
 5. Submit a PR
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on skills structure.
+
 ## License
 
 MIT © Mehdi Chaabi

package/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { run } = require('../src/cli.js');
+import { run } from '../src/cli.js';
 
 run(process.argv.slice(2)).catch((err) => {
   console.error(err);

package/configs/_shared/rules/conventions/npm.md

@@ -0,0 +1,80 @@
+---
+paths:
+  - "**/package.json"
+---
+
+# npm Conventions
+
+## Version Pinning
+
+**Always use exact versions** - no `^` or `~` prefixes.
+
+```json
+// GOOD
+{
+  "dependencies": {
+    "express": "4.18.2",
+    "lodash": "4.17.21"
+  }
+}
+
+// BAD
+{
+  "dependencies": {
+    "express": "^4.18.2",
+    "lodash": "~4.17.21"
+  }
+}
+```
+
+### Why?
+
+- **Reproducible builds** across environments
+- **No surprise breaking changes** from minor/patch updates
+- **Lock file is source of truth** but pinning adds defense in depth
+- **Explicit upgrades** via `npm update` or renovate/dependabot
+
+### Commands
+
+```bash
+# Install with exact version
+npm install express --save-exact
+
+# Configure npm to always save exact
+npm config set save-exact true
+
+# Or in .npmrc
+save-exact=true
+```
+
+## Scripts
+
+Use consistent script names:
+
+```json
+{
+  "scripts": {
+    "dev": "...",
+    "build": "...",
+    "start": "...",
+    "test": "...",
+    "test:watch": "...",
+    "test:cov": "...",
+    "lint": "...",
+    "lint:fix": "...",
+    "format": "..."
+  }
+}
+```
+
+## Engine Requirements
+
+Specify Node.js version:
+
+```json
+{
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}
+```

package/configs/angular/{.claude/settings.json → settings.json}

@@ -18,6 +18,8 @@
       "Write"
     ],
     "deny": [
+      "Bash(git push *)",
+      "Bash(git push)",
       "Bash(rm -rf *)",
       "Bash(nx reset)",
       "Read(.env)",

package/configs/dotnet/{.claude/settings.json → settings.json}

@@ -14,6 +14,8 @@
       "Write"
     ],
     "deny": [
+      "Bash(git push *)",
+      "Bash(git push)",
       "Bash(rm -rf *)",
       "Read(appsettings.*.json)",
       "Read(**/secrets.json)",

package/configs/fastapi/{.claude/settings.json → settings.json}

@@ -19,6 +19,8 @@
       "Write"
     ],
     "deny": [
+      "Bash(git push *)",
+      "Bash(git push)",
       "Bash(rm -rf *)",
       "Read(.env)",
       "Read(.env.*)",

package/configs/flask/{.claude/settings.json → settings.json}

@@ -18,6 +18,8 @@
       "Write"
     ],
     "deny": [
+      "Bash(git push *)",
+      "Bash(git push)",
       "Bash(rm -rf *)",
       "Read(.env)",
       "Read(.env.*)",

package/configs/nestjs/{.claude/settings.json → settings.json}

@@ -17,6 +17,8 @@
       "Write"
     ],
     "deny": [
+      "Bash(git push *)",
+      "Bash(git push)",
       "Bash(rm -rf *)",
       "Read(.env)",
       "Read(.env.*)",

package/configs/nextjs/{.claude/settings.json → settings.json}

@@ -20,6 +20,8 @@
       "Write"
     ],
     "deny": [
+      "Bash(git push *)",
+      "Bash(git push)",
       "Bash(rm -rf *)",
       "Bash(nx reset)",
       "Read(.env)",

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@malamute/ai-rules",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Claude Code configuration boilerplates for Angular, Next.js, NestJS, .NET, Python and more",
+  "type": "module",
   "main": "src/index.js",
   "bin": "./bin/cli.js",
   "scripts": {

package/src/cli.js

@@ -1,7 +1,7 @@
-const readline = require('readline');
-const { colors, log } = require('./utils');
-const { VERSION, AVAILABLE_TECHS } = require('./config');
-const { init, update, status, listTechnologies } = require('./installer');
+import readline from 'readline';
+import { colors, log } from './utils.js';
+import { VERSION, AVAILABLE_TECHS } from './config.js';
+import { init, update, status, listTechnologies } from './installer.js';
 
 function printUsage() {
   console.log(`
@@ -123,7 +123,7 @@ async function interactiveInit() {
   return { techs, options };
 }
 
-async function run(args) {
+export async function run(args) {
   if (args.includes('--help') || args.includes('-h')) {
     printUsage();
     return;
@@ -216,5 +216,3 @@ async function run(args) {
   printUsage();
   process.exit(1);
 }
-
-module.exports = { run };

package/src/config.js

@@ -1,29 +1,63 @@
-const fs = require('fs');
-const path = require('path');
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 
-const CONFIGS_DIR = path.join(__dirname, '..', 'configs');
-const AVAILABLE_TECHS = ['angular', 'nextjs', 'nestjs', 'dotnet', 'fastapi', 'flask'];
-const VERSION = require('../package.json').version;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
-const TECH_CONFIG = JSON.parse(
+const require = createRequire(import.meta.url);
+
+export const CONFIGS_DIR = path.join(__dirname, '..', 'configs');
+export const AVAILABLE_TECHS = ['angular', 'nextjs', 'nestjs', 'dotnet', 'fastapi', 'flask'];
+export const VERSION = require('../package.json').version;
+
+export const TECH_CONFIG = JSON.parse(
   fs.readFileSync(path.join(__dirname, 'tech-config.json'), 'utf8')
 );
 
-function getRuleCategoriesToInclude(techs) {
-  const categories = new Set();
+/**
+ * Get rule directories to include based on selected technologies.
+ * Returns paths relative to the rules directory (e.g., "lang/typescript", "domain/frontend").
+ */
+export function getRulePathsToInclude(techs) {
+  const paths = new Set();
+  const { ruleMapping, alwaysInclude } = TECH_CONFIG;
+
+  // Always include common rules
+  alwaysInclude.forEach((dir) => paths.add(dir));
+
+  // Add language and domain-specific rules based on selected techs
   for (const tech of techs) {
     const config = TECH_CONFIG.technologies[tech];
-    if (config?.includeRules) {
-      config.includeRules.forEach((cat) => categories.add(cat));
+    if (!config) continue;
+
+    // Add language-specific rules (e.g., "lang/typescript")
+    if (config.language && ruleMapping.language[config.language]) {
+      paths.add(ruleMapping.language[config.language]);
+    }
+
+    // Add domain-specific rules (e.g., "domain/frontend")
+    if (config.type && ruleMapping.type[config.type]) {
+      paths.add(ruleMapping.type[config.type]);
     }
   }
-  return categories;
+
+  return paths;
 }
 
-module.exports = {
-  CONFIGS_DIR,
-  AVAILABLE_TECHS,
-  VERSION,
-  TECH_CONFIG,
-  getRuleCategoriesToInclude,
-};
+/**
+ * Check if a rule path should be included for the given technologies.
+ * @param {string} rulePath - Path relative to rules dir (e.g., "lang/python/async.md")
+ * @param {Set<string>} includedPaths - Set of paths to include
+ * @returns {boolean}
+ */
+export function shouldIncludeRule(rulePath, includedPaths) {
+  // Check if the path starts with any of the included paths
+  for (const includedPath of includedPaths) {
+    if (rulePath === includedPath || rulePath.startsWith(includedPath + '/')) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/index.js

@@ -1,13 +1,4 @@
-const { run } = require('./cli');
-const { init, update, status } = require('./installer');
-const { readManifest } = require('./merge');
-const { VERSION } = require('./config');
-
-module.exports = {
-  run,
-  init,
-  update,
-  status,
-  readManifest,
-  VERSION,
-};
+export { run } from './cli.js';
+export { init, update, status } from './installer.js';
+export { readManifest } from './merge.js';
+export { VERSION } from './config.js';

package/src/installer.js

@@ -1,10 +1,95 @@
-const fs = require('fs');
-const path = require('path');
-const { colors, log, getFilesRecursive, copyDirRecursive, backupFile } = require('./utils');
-const { CONFIGS_DIR, AVAILABLE_TECHS, VERSION, TECH_CONFIG, getRuleCategoriesToInclude } = require('./config');
-const { mergeClaudeMd, mergeSettingsJson, readManifest, writeManifest } = require('./merge');
+import fs from 'fs';
+import path from 'path';
+import { colors, log, getFilesRecursive, copyDirRecursive, backupFile } from './utils.js';
+import { CONFIGS_DIR, AVAILABLE_TECHS, VERSION, getRulePathsToInclude, shouldIncludeRule } from './config.js';
+import { mergeClaudeMd, mergeSettingsJson, readManifest, writeManifest } from './merge.js';
+
+/**
+ * Copy skills to target directory with flat structure.
+ * Source: skills/<category>/<skill-name>/SKILL.md
+ * Target: .claude/skills/<skill-name>/SKILL.md
+ */
+function copySkillsToTarget(srcDir, destDir, options = {}) {
+  const { dryRun, backup, targetDir } = options;
+  const operations = [];
+
+  // getFilesRecursive returns paths relative to srcDir
+  const relativeFiles = getFilesRecursive(srcDir).filter((f) => f.endsWith('SKILL.md'));
+
+  for (const relativePath of relativeFiles) {
+    const srcFile = path.join(srcDir, relativePath);
+    const parts = relativePath.split(path.sep);
+
+    // Extract skill name from parent directory
+    // e.g., dev/debug/SKILL.md → debug
+    const skillName = parts[parts.length - 2];
+
+    // Create .claude/skills/<skill-name>/SKILL.md
+    const destSkillDir = path.join(destDir, skillName);
+    const destFile = path.join(destSkillDir, 'SKILL.md');
+    const exists = fs.existsSync(destFile);
+    const relativeDestPath = path.relative(targetDir, destFile);
+
+    if (dryRun) {
+      operations.push({ type: exists ? 'overwrite' : 'create', path: relativeDestPath });
+    } else {
+      if (exists && backup) {
+        backupFile(destFile, targetDir);
+      }
+      fs.mkdirSync(destSkillDir, { recursive: true });
+      fs.copyFileSync(srcFile, destFile);
+      operations.push({ type: exists ? 'overwrite' : 'create', path: relativeDestPath });
+    }
+  }
+
+  return operations;
+}
+
+/**
+ * Copy rules selectively based on technology configuration.
+ * Only copies rules that match the included paths.
+ */
+function copyRulesSelectively(srcDir, destDir, includedPaths, skippedPaths, options = {}) {
+  const { dryRun, backup, targetDir } = options;
+  const operations = [];
+
+  // getFilesRecursive returns paths relative to srcDir
+  const relativeFiles = getFilesRecursive(srcDir);
+
+  for (const relativePath of relativeFiles) {
+    const relativeDir = path.dirname(relativePath);
+
+    // Check if this file should be included
+    if (!shouldIncludeRule(relativeDir, includedPaths)) {
+      // Track skipped top-level directories for logging
+      const topLevel = relativePath.split(path.sep).slice(0, 2).join('/');
+      if (!skippedPaths.includes(topLevel)) {
+        skippedPaths.push(topLevel);
+      }
+      continue;
+    }
+
+    const srcFile = path.join(srcDir, relativePath);
+    const destFile = path.join(destDir, relativePath);
+    const exists = fs.existsSync(destFile);
+    const relativeDestPath = path.relative(targetDir, destFile);
 
-function listTechnologies() {
+    if (dryRun) {
+      operations.push({ type: exists ? 'overwrite' : 'create', path: relativeDestPath });
+    } else {
+      if (exists && backup) {
+        backupFile(destFile, targetDir);
+      }
+      fs.mkdirSync(path.dirname(destFile), { recursive: true });
+      fs.copyFileSync(srcFile, destFile);
+      operations.push({ type: exists ? 'overwrite' : 'create', path: relativeDestPath });
+    }
+  }
+
+  return operations;
+}
+
+export function listTechnologies() {
   console.log(`\n${colors.bold('Available technologies:')}\n`);
 
   const techInfo = {
@@ -26,15 +111,15 @@ function listTechnologies() {
   console.log(`\n${colors.bold('Shared resources:')}\n`);
 
   const sharedPath = path.join(CONFIGS_DIR, '_shared');
-  const skills = fs.existsSync(path.join(sharedPath, '.claude', 'skills'));
-  const rules = fs.existsSync(path.join(sharedPath, '.claude', 'rules'));
+  const skills = fs.existsSync(path.join(sharedPath, 'skills'));
+  const rules = fs.existsSync(path.join(sharedPath, 'rules'));
 
   console.log(`  ${skills ? colors.green('✓') : colors.red('✗')} skills     /learning, /review, /spec, /debug, and more`);
   console.log(`  ${rules ? colors.green('✓') : colors.red('✗')} rules      security, performance, accessibility`);
   console.log('');
 }
 
-function status(targetDir) {
+export function status(targetDir) {
   const manifest = readManifest(targetDir);
 
   console.log(`\n${colors.bold('AI Rules Status')}\n`);
@@ -84,7 +169,7 @@ function status(targetDir) {
   }
 }
 
-function init(techs, options) {
+export function init(techs, options) {
   const targetDir = path.resolve(options.target || process.cwd());
   const { dryRun, force } = options;
   const backup = !force;
@@ -132,7 +217,7 @@ function init(techs, options) {
       }
     }
 
-    const settingsPath = path.join(techDir, '.claude', 'settings.json');
+    const settingsPath = path.join(techDir, 'settings.json');
     if (fs.existsSync(settingsPath)) {
       const op = mergeSettingsJson(
         path.join(targetDir, '.claude', 'settings.json'),
@@ -148,7 +233,7 @@ function init(techs, options) {
       }
     }
 
-    const rulesDir = path.join(techDir, '.claude', 'rules');
+    const rulesDir = path.join(techDir, 'rules');
     if (fs.existsSync(rulesDir)) {
       const ops = copyDirRecursive(
         rulesDir,
@@ -165,9 +250,9 @@ function init(techs, options) {
     }
 
     if (options.withSkills) {
-      const techSkillsDir = path.join(techDir, '.claude', 'skills');
+      const techSkillsDir = path.join(techDir, 'skills');
       if (fs.existsSync(techSkillsDir)) {
-        const ops = copyDirRecursive(
+        const ops = copySkillsToTarget(
           techSkillsDir,
           path.join(targetDir, '.claude', 'skills'),
           { dryRun, backup, targetDir }
@@ -181,9 +266,9 @@ function init(techs, options) {
 
   if (options.withSkills) {
     log.info(`${dryRun ? 'Would install' : 'Installing'} skills...`);
-    const skillsDir = path.join(sharedDir, '.claude', 'skills');
+    const skillsDir = path.join(sharedDir, 'skills');
     if (fs.existsSync(skillsDir)) {
-      const ops = copyDirRecursive(
+      const ops = copySkillsToTarget(
         skillsDir,
         path.join(targetDir, '.claude', 'skills'),
         { dryRun, backup, targetDir }
@@ -200,54 +285,29 @@ function init(techs, options) {
 
   if (options.withRules) {
     log.info(`${dryRun ? 'Would install' : 'Installing'} shared rules...`);
-    const rulesDir = path.join(sharedDir, '.claude', 'rules');
+    const rulesDir = path.join(sharedDir, 'rules');
     if (fs.existsSync(rulesDir)) {
-      const categoriesToInclude = getRuleCategoriesToInclude(techs);
-      const selectiveCategories = Object.keys(TECH_CONFIG.ruleCategories);
-      const skippedCategories = [];
-
-      const entries = fs.readdirSync(rulesDir, { withFileTypes: true });
-      let totalOps = 0;
-
-      for (const entry of entries) {
-        if (selectiveCategories.includes(entry.name) && !categoriesToInclude.has(entry.name)) {
-          skippedCategories.push(entry.name);
-          continue;
-        }
-
-        const srcPath = path.join(rulesDir, entry.name);
-        const destPath = path.join(targetDir, '.claude', 'rules', entry.name);
-
-        if (entry.isDirectory()) {
-          const ops = copyDirRecursive(srcPath, destPath, { dryRun, backup, targetDir });
-          operations.push(...ops);
-          totalOps += ops.length;
-        } else {
-          const exists = fs.existsSync(destPath);
-          const relativePath = path.relative(targetDir, destPath);
-
-          if (dryRun) {
-            operations.push({ type: exists ? 'overwrite' : 'create', path: relativePath });
-          } else {
-            if (exists && backup) {
-              backupFile(destPath, targetDir);
-            }
-            fs.mkdirSync(path.dirname(destPath), { recursive: true });
-            fs.copyFileSync(srcPath, destPath);
-            operations.push({ type: exists ? 'overwrite' : 'create', path: relativePath });
-          }
-          totalOps++;
-        }
-      }
+      const includedPaths = getRulePathsToInclude(techs);
+      const skippedPaths = [];
+
+      const ops = copyRulesSelectively(
+        rulesDir,
+        path.join(targetDir, '.claude', 'rules'),
+        includedPaths,
+        skippedPaths,
+        { dryRun, backup, targetDir }
+      );
+      operations.push(...ops);
 
       if (dryRun) {
-        log.dry(`  shared rules/ (${totalOps} files)`);
+        log.dry(`  shared rules/ (${ops.length} files)`);
       } else {
         log.success(`  shared rules/`);
       }
 
-      if (skippedCategories.length > 0) {
-        log.info(`  (skipped: ${skippedCategories.join(', ')} - not applicable)`);
+      if (skippedPaths.length > 0) {
+        const uniqueSkipped = [...new Set(skippedPaths)];
+        log.info(`  (skipped: ${uniqueSkipped.join(', ')} - not applicable)`);
       }
     }
   }
@@ -317,7 +377,7 @@ function init(techs, options) {
   console.log('');
 }
 
-async function update(options) {
+export async function update(options) {
   const targetDir = path.resolve(options.target || process.cwd());
   const { dryRun, force } = options;
 
@@ -352,10 +412,3 @@ async function update(options) {
 
   init(manifest.technologies, initOptions);
 }
-
-module.exports = {
-  init,
-  update,
-  status,
-  listTechnologies,
-};

package/src/merge.js

@@ -1,9 +1,9 @@
-const fs = require('fs');
-const path = require('path');
-const { log, backupFile } = require('./utils');
-const { VERSION } = require('./config');
+import fs from 'fs';
+import path from 'path';
+import { log, backupFile } from './utils.js';
+import { VERSION } from './config.js';
 
-function mergeClaudeMd(targetPath, sourcePath, isFirst, options = {}) {
+export function mergeClaudeMd(targetPath, sourcePath, isFirst, options = {}) {
   const { dryRun = false, backup = false, targetDir } = options;
   const content = fs.readFileSync(sourcePath, 'utf8');
   const exists = fs.existsSync(targetPath);
@@ -26,7 +26,7 @@ function mergeClaudeMd(targetPath, sourcePath, isFirst, options = {}) {
   return { type: exists ? 'merge' : 'create', path: 'CLAUDE.md' };
 }
 
-function mergeSettingsJson(targetPath, sourcePath, options = {}) {
+export function mergeSettingsJson(targetPath, sourcePath, options = {}) {
   const { dryRun = false, backup = false, targetDir } = options;
   const exists = fs.existsSync(targetPath);
 
@@ -83,7 +83,7 @@ function getManifestPath(targetDir) {
   return path.join(targetDir, '.claude', '.ai-rules.json');
 }
 
-function readManifest(targetDir) {
+export function readManifest(targetDir) {
   const manifestPath = getManifestPath(targetDir);
   if (!fs.existsSync(manifestPath)) return null;
 
@@ -94,7 +94,7 @@ function readManifest(targetDir) {
   }
 }
 
-function writeManifest(targetDir, data, dryRun = false) {
+export function writeManifest(targetDir, data, dryRun = false) {
   if (dryRun) return;
 
   const manifestPath = getManifestPath(targetDir);
@@ -107,10 +107,3 @@ function writeManifest(targetDir, data, dryRun = false) {
   fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
 }
-
-module.exports = {
-  mergeClaudeMd,
-  mergeSettingsJson,
-  readManifest,
-  writeManifest,
-};