@vdkit/cli 3.0.0 → 3.0.2

package/src/scanner/core/RuleAdapter.js

@@ -730,7 +730,7 @@ export class RuleAdapter {
     }
 
     // Sort rules by priority (higher priority first)
-    const prioritizedRules = rules.sort((a, b) => {
+    const prioritizedRules = rules.toSorted((a, b) => {
       const aPriority = a.frontmatter?.priority || priority;
       const bPriority = b.frontmatter?.priority || priority;
       return bPriority - aPriority;
@@ -987,7 +987,7 @@ ${r.content}`
         const fileName = this.getCursorFileName(rule);
 
         adaptedFiles.push({
-          path: path.join(rulesDir, `${prefix}-${fileName}`),
+          path: path.join(rulesDir, `${prefix}-${fileName}.mdc`),
           content: result.content,
           type: 'rule',
           activation: activationType,
@@ -2039,7 +2039,7 @@ This project uses VDK CLI for AI assistant integration and follows specific patt
 @CLAUDE-personal.md
 
 ## Important Conventions
-- All AI rules are stored in \`.vdk/rules/\` directory
+- All AI rule artifacts are stored in \`.vdk/blueprints/rules/\` directory
 - Rules follow unified YAML frontmatter format
 - Project follows VDK CLI naming conventions
 - Memory persistence is enabled for context continuity
@@ -2418,7 +2418,7 @@ ${this.formatForWindsurf(keyContent)}
     // Prioritize rules based on their effectiveness for code review
     return rules
       .filter(rule => rule.frontmatter?.category !== 'assistant') // Skip assistant-specific rules
-      .sort((a, b) => {
+      .toSorted((a, b) => {
         const aPriority = this.getCopilotPriority(a);
         const bPriority = this.getCopilotPriority(b);
         return bPriority - aPriority;
@@ -2722,14 +2722,14 @@ This directory contains GitHub Copilot Enterprise coding guidelines generated by
   async adaptForGeneric(rules, projectContext, platformConfig = {}) {
     const adaptedFiles = [];
     const configPath = platformConfig.configPath || '.vdk';
-    const rulesPath = platformConfig.rulesPath || '.vdk/rules';
+    const rulesPath = platformConfig.rulesPath || '.vdk/blueprints/rules';
     const priority = platformConfig.priority || 5;
 
     const baseDir = path.join(this.projectPath, configPath);
     const rulesDir = path.join(this.projectPath, rulesPath);
 
     // Sort rules by priority
-    const prioritizedRules = rules.sort((a, b) => {
+    const prioritizedRules = rules.toSorted((a, b) => {
       const aPriority = a.frontmatter?.priority || priority;
       const bPriority = b.frontmatter?.priority || priority;
       return bPriority - aPriority;

package/src/scanner/core/RuleGenerator.js

@@ -20,10 +20,15 @@ import { TechnologyRuleMapper } from './TechnologyRuleMapper.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export class RuleGenerator {
-  constructor(outputPath = './.vdk/rules', template = 'default', overwrite = false, options = {}) {
+  constructor(
+    outputPath = './.vdk/blueprints/rules',
+    template = 'default',
+    overwrite = false,
+    options = {}
+  ) {
     if (typeof outputPath === 'object') {
       options = outputPath;
-      outputPath = options.outputPath || './.vdk/rules';
+      outputPath = options.outputPath || './.vdk/blueprints/rules';
       template = options.template || 'default';
       overwrite = options.overwrite;
     }
@@ -35,7 +40,7 @@ export class RuleGenerator {
     this.projectPath = options.projectPath || process.cwd();
     this.enableAnalytics = options.enableAnalytics !== false;
     this.hubEndpoint = options.hubEndpoint || 'https://vdk.tools';
-    this.ecosystemVersion = '2.1.0';
+    this.ecosystemVersion = '3.0.0';
 
     // Initialize Components
     this.mapper = new TechnologyRuleMapper();

package/src/scanner/core/TechnologyAnalyzer.js

@@ -72,7 +72,7 @@ export class TechnologyAnalyzer {
         console.error(chalk.red(`Error in technology analysis: ${error.message}`));
         console.error(chalk.gray(error.stack));
       }
-      throw new Error(`Technology analysis failed: ${error.message}`);
+      throw new Error(`Technology analysis failed: ${error.message}`, { cause: error });
     }
   }
 

package/src/scanner/utils/constants.js

@@ -113,6 +113,6 @@ export const PATTERN_RULE_MAP = {
 
 // Default values
 export const DEFAULTS = {
-  OUTPUT_PATH: './.vdk/rules',
+  OUTPUT_PATH: './.vdk/blueprints/rules',
   PROJECT_NAME: 'Your Project',
 };

package/src/scanner/utils/package-analyzer.js

@@ -594,8 +594,8 @@ export class PackageAnalyzer {
 
       // Extract dependencies
       const allDependencies = {
-        ...(packageJson.dependencies || {}),
-        ...(packageJson.devDependencies || {}),
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
       };
 
       // Detect technologies based on dependencies

package/src/scanner/utils/version.js

@@ -33,5 +33,5 @@ export async function getVersionAsync() {
 export function getVersion() {
   // For simplicity in the synchronous version, we'll just return the current version
   // This could be enhanced to use fs.readFileSync if needed
-  return '2.0.0';
+  return '3.0.1';
 }

package/src/shared/ProjectContextAnalyzer.js

@@ -333,6 +333,10 @@ export class ProjectContextAnalyzer {
       }
     }
 
+    if (platforms.length === 0) {
+      return ['claude-code', 'cursor'];
+    }
+
     return platforms;
   }
 

package/src/shared/blueprint-artifact-paths.js

@@ -0,0 +1,32 @@
+/**
+ * Canonical VDK blueprint artifact paths
+ * --------------------------------------
+ * Raw fetched/generated artifacts are stored by kind under:
+ * .vdk/blueprints/{rules,commands,agents,skills,workflows,plugins}
+ */
+
+export const VDK_ROOT_DIR = '.vdk';
+export const BLUEPRINT_ARTIFACTS_ROOT = `${VDK_ROOT_DIR}/blueprints`;
+
+export const BLUEPRINT_ARTIFACT_KINDS = Object.freeze([
+  'rules',
+  'commands',
+  'agents',
+  'skills',
+  'workflows',
+  'plugins',
+]);
+
+export const DEFAULT_BLUEPRINT_RULES_PATH = `${BLUEPRINT_ARTIFACTS_ROOT}/rules`;
+
+export function getBlueprintKindPath(kind) {
+  const normalizedKind = String(kind || '')
+    .toLowerCase()
+    .trim();
+
+  if (!BLUEPRINT_ARTIFACT_KINDS.includes(normalizedKind)) {
+    throw new Error(`Unsupported blueprint artifact kind: ${kind}`);
+  }
+
+  return `${BLUEPRINT_ARTIFACTS_ROOT}/${normalizedKind}`;
+}

package/src/shared/ide-configuration.js

@@ -359,17 +359,17 @@ const IDE_CONFIGURATIONS = [
   {
     id: 'generic-ai',
     name: 'Generic AI Platform',
-    configFolder: '.ai',
-    rulesFolder: '.ai/rules',
-    configFiles: ['.ai/config.json'],
+    configFolder: '.vdk',
+    rulesFolder: '.vdk/blueprints/rules',
+    configFiles: ['.vdk/config.json'],
     description: 'Works with most AI coding assistants and platforms.',
   },
   {
     id: 'generic',
     name: 'Generic AI Tool',
-    configFolder: '.ai',
-    rulesFolder: '.ai/rules',
-    configFiles: ['.ai/config.json'],
+    configFolder: '.vdk',
+    rulesFolder: '.vdk/blueprints/rules',
+    configFiles: ['.vdk/config.json'],
     description: 'Works with most AI coding assistants and is the VDK CLI standard.',
   },
 ];
@@ -532,7 +532,7 @@ function detectSpecificJetBrainsIDEs(projectPath) {
             });
             if (hasMatch) matchCount++;
           }
-        } catch (_error) {
+        } catch {
           // Ignore directory read errors
         }
       } else if (fs.existsSync(filePath)) {
@@ -559,7 +559,7 @@ function detectSpecificJetBrainsIDEs(projectPath) {
   }
 
   // Sort by confidence (highest first)
-  return detectedIDEs.sort((a, b) => b.confidence - a.confidence);
+  return detectedIDEs.toSorted((a, b) => b.confidence - a.confidence);
 }
 
 /**

package/src/shared/sync-operations.js

@@ -9,6 +9,7 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { downloadRule, fetchRuleList } from '../blueprints-client.js';
+import { BLUEPRINT_ARTIFACT_KINDS } from './blueprint-artifact-paths.js';
 
 /**
  * Base sync operations that both blueprint and team sync can use
@@ -45,14 +46,18 @@ export class SyncOperations {
   /**
    * Sync blueprints from Hub (original blueprint sync logic)
    */
-  async syncBlueprintsFromHub(rulesDir, options, spinner) {
+  async syncBlueprintsFromHub(artifactsRoot, options, spinner) {
     const hubResult = await this.hubOps.syncBlueprints(options);
     const synced = hubResult.blueprints.length;
 
-    // Save Hub blueprints
+    // Save Hub blueprints by kind
     for (const blueprint of hubResult.blueprints) {
+      const kind = this.resolveBlueprintKind(blueprint);
+      const kindDir = path.join(artifactsRoot, kind);
+      await fs.mkdir(kindDir, { recursive: true });
+
       const fileName = `${blueprint.slug || blueprint.id}.hub.md`;
-      const filePath = path.join(rulesDir, fileName);
+      const filePath = path.join(kindDir, fileName);
       await fs.writeFile(filePath, blueprint.content);
     }
 
@@ -73,7 +78,7 @@ export class SyncOperations {
    * Sync team configuration from Hub (team sync logic)
    */
   async syncTeamConfigFromHub(projectPath, options, spinner) {
-    const { teamId, force = false } = options;
+    const { teamId } = options;
     const finalTeamId = teamId || process.env.VDK_TEAM_ID;
 
     if (!finalTeamId) {
@@ -134,10 +139,13 @@ export class SyncOperations {
   /**
    * Sync blueprints from repository (original repository sync logic)
    */
-  async syncBlueprintsFromRepository(rulesDir, options, spinner) {
+  async syncBlueprintsFromRepository(artifactsRoot, options, spinner) {
     const { force, category } = options;
     const remoteRules = await fetchRuleList();
 
+    const rulesDir = path.join(artifactsRoot, 'rules');
+    await fs.mkdir(rulesDir, { recursive: true });
+
     if (remoteRules.length === 0) {
       spinner.fail('No blueprints found in repository or failed to connect');
       return { synced: 0 };
@@ -189,8 +197,6 @@ export class SyncOperations {
    * Sync team configuration from Git (team sync logic)
    */
   async syncTeamConfigFromGit(projectPath, options, spinner) {
-    const { force = false } = options;
-
     // Check if this is a Git repository
     try {
       execSync('git rev-parse --git-dir', { cwd: projectPath, stdio: 'ignore' });
@@ -202,14 +208,14 @@ export class SyncOperations {
     if (!options.dryRun) {
       try {
         execSync('git pull', { cwd: projectPath, stdio: 'inherit' });
-      } catch (_error) {
+      } catch {
         this.command.logWarning('⚠️  Git pull failed - continuing with local files');
       }
     }
 
     // Check for VDK files in repository
     const vdkFiles = [];
-    const filesToCheck = ['.vdk/rules/', '.vdk/config.json'];
+    const filesToCheck = ['.vdk/blueprints/', '.vdk/config.json'];
 
     for (const file of filesToCheck) {
       const fullPath = path.join(projectPath, file);
@@ -300,9 +306,11 @@ export class SyncOperations {
   async applyHubConfiguration(projectPath, teamConfig) {
     const appliedFiles = [];
     const vdkPath = path.join(projectPath, '.vdk');
+    const blueprintsPath = path.join(vdkPath, 'blueprints');
 
     // Ensure .vdk directory exists
     await fs.mkdir(vdkPath, { recursive: true });
+    await fs.mkdir(blueprintsPath, { recursive: true });
 
     // Apply main configuration
     if (teamConfig.main) {
@@ -311,18 +319,77 @@ export class SyncOperations {
       appliedFiles.push('.vdk/config.json');
     }
 
-    // Apply rules
+    // Apply rule artifacts from legacy team payload
     if (teamConfig.rules) {
-      const rulesPath = path.join(vdkPath, 'rules');
-      await fs.mkdir(rulesPath, { recursive: true });
+      await this.writeBlueprintKindFiles(blueprintsPath, 'rules', teamConfig.rules, appliedFiles);
+    }
 
-      for (const [filename, content] of Object.entries(teamConfig.rules)) {
-        const rulePath = path.join(rulesPath, filename);
-        await fs.writeFile(rulePath, content);
-        appliedFiles.push(`.vdk/rules/${filename}`);
+    // Apply structured artifact payload by kind
+    if (teamConfig.blueprints && typeof teamConfig.blueprints === 'object') {
+      for (const [kind, files] of Object.entries(teamConfig.blueprints)) {
+        await this.writeBlueprintKindFiles(blueprintsPath, kind, files, appliedFiles);
       }
     }
 
     return appliedFiles;
   }
+
+  resolveBlueprintKind(blueprint) {
+    const normalizedKind = String(blueprint?.kind || '')
+      .toLowerCase()
+      .trim();
+
+    if (BLUEPRINT_ARTIFACT_KINDS.includes(normalizedKind)) {
+      return normalizedKind;
+    }
+
+    const sourceCandidates = [
+      blueprint?.sourcePath,
+      blueprint?.path,
+      blueprint?.slug,
+      blueprint?.id,
+    ]
+      .filter(Boolean)
+      .map(value => String(value).toLowerCase());
+
+    for (const candidate of sourceCandidates) {
+      for (const kind of BLUEPRINT_ARTIFACT_KINDS) {
+        if (
+          candidate.includes(`/library/${kind}/`) ||
+          candidate.includes(`/${kind}/`) ||
+          candidate.startsWith(`${kind}/`)
+        ) {
+          return kind;
+        }
+      }
+    }
+
+    throw new Error(
+      `Unable to determine blueprint kind for item: ${blueprint?.id || blueprint?.slug || 'unknown'}`
+    );
+  }
+
+  async writeBlueprintKindFiles(blueprintsPath, kind, files, appliedFiles) {
+    const normalizedKind = String(kind || '')
+      .toLowerCase()
+      .trim();
+
+    if (!BLUEPRINT_ARTIFACT_KINDS.includes(normalizedKind)) {
+      throw new Error(`Unsupported blueprint artifact kind: ${kind}`);
+    }
+
+    if (!files || typeof files !== 'object') {
+      return;
+    }
+
+    const kindPath = path.join(blueprintsPath, normalizedKind);
+    await fs.mkdir(kindPath, { recursive: true });
+
+    for (const [relativeFilePath, content] of Object.entries(files)) {
+      const outputPath = path.join(kindPath, relativeFilePath);
+      await fs.mkdir(path.dirname(outputPath), { recursive: true });
+      await fs.writeFile(outputPath, content);
+      appliedFiles.push(`.vdk/blueprints/${normalizedKind}/${relativeFilePath}`);
+    }
+  }
 }

package/src/utils/file-system.js

@@ -20,7 +20,7 @@ export const fileSystem = {
     try {
       return await fs.readFile(filePath, encoding);
     } catch (error) {
-      throw new Error(`Failed to read file ${filePath}: ${error.message}`);
+      throw new Error(`Failed to read file ${filePath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -35,7 +35,7 @@ export const fileSystem = {
 
       return await fs.writeFile(filePath, data, options);
     } catch (error) {
-      throw new Error(`Failed to write file ${filePath}: ${error.message}`);
+      throw new Error(`Failed to write file ${filePath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -49,7 +49,7 @@ export const fileSystem = {
 
       return await fs.appendFile(filePath, data, options);
     } catch (error) {
-      throw new Error(`Failed to append to file ${filePath}: ${error.message}`);
+      throw new Error(`Failed to append to file ${filePath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -72,7 +72,7 @@ export const fileSystem = {
     try {
       return await fs.stat(filePath);
     } catch (error) {
-      throw new Error(`Failed to get stats for ${filePath}: ${error.message}`);
+      throw new Error(`Failed to get stats for ${filePath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -107,7 +107,7 @@ export const fileSystem = {
     try {
       await fs.mkdir(dirPath, { recursive: true });
     } catch (error) {
-      throw new Error(`Failed to create directory ${dirPath}: ${error.message}`);
+      throw new Error(`Failed to create directory ${dirPath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -119,7 +119,7 @@ export const fileSystem = {
       await fs.unlink(filePath);
     } catch (error) {
       if (error.code !== 'ENOENT') {
-        throw new Error(`Failed to remove file ${filePath}: ${error.message}`);
+        throw new Error(`Failed to remove file ${filePath}: ${error.message}`, { cause: error });
       }
     }
   },
@@ -131,7 +131,7 @@ export const fileSystem = {
     try {
       await fs.rm(dirPath, { recursive: true, force: true });
     } catch (error) {
-      throw new Error(`Failed to remove directory ${dirPath}: ${error.message}`);
+      throw new Error(`Failed to remove directory ${dirPath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -142,7 +142,7 @@ export const fileSystem = {
     try {
       return await fs.readdir(dirPath);
     } catch (error) {
-      throw new Error(`Failed to read directory ${dirPath}: ${error.message}`);
+      throw new Error(`Failed to read directory ${dirPath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -156,7 +156,7 @@ export const fileSystem = {
 
       await fs.copyFile(src, dest);
     } catch (error) {
-      throw new Error(`Failed to copy ${src} to ${dest}: ${error.message}`);
+      throw new Error(`Failed to copy ${src} to ${dest}: ${error.message}`, { cause: error });
     }
   },
 
@@ -170,7 +170,7 @@ export const fileSystem = {
 
       await fs.rename(src, dest);
     } catch (error) {
-      throw new Error(`Failed to move ${src} to ${dest}: ${error.message}`);
+      throw new Error(`Failed to move ${src} to ${dest}: ${error.message}`, { cause: error });
     }
   },
 
@@ -182,7 +182,7 @@ export const fileSystem = {
       const content = await this.readFile(filePath);
       return JSON.parse(content);
     } catch (error) {
-      throw new Error(`Failed to read JSON from ${filePath}: ${error.message}`);
+      throw new Error(`Failed to read JSON from ${filePath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -194,7 +194,7 @@ export const fileSystem = {
       const content = JSON.stringify(data, null, indent);
       await this.writeFile(filePath, content);
     } catch (error) {
-      throw new Error(`Failed to write JSON to ${filePath}: ${error.message}`);
+      throw new Error(`Failed to write JSON to ${filePath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -225,7 +225,7 @@ export const fileSystem = {
             }
           }
         }
-      } catch (_error) {
+      } catch {
         // Skip directories we can't read
       }
     }
@@ -242,7 +242,7 @@ export const fileSystem = {
       const stats = await fs.stat(filePath);
       return stats.size;
     } catch (error) {
-      throw new Error(`Failed to get size of ${filePath}: ${error.message}`);
+      throw new Error(`Failed to get size of ${filePath}: ${error.message}`, { cause: error });
     }
   },
 
@@ -254,7 +254,9 @@ export const fileSystem = {
       const stats = await fs.stat(filePath);
       return stats.mtime;
     } catch (error) {
-      throw new Error(`Failed to get modification time of ${filePath}: ${error.message}`);
+      throw new Error(`Failed to get modification time of ${filePath}: ${error.message}`, {
+        cause: error,
+      });
     }
   },
 

package/src/utils/filename-generator.js

@@ -25,7 +25,6 @@ export function generateSafeFilename(input, options = {}) {
     extension = '',
     preserveCase = false,
     separator = '-',
-    allowedChars = /[a-z0-9-_]/,
     fallbackName = 'untitled',
   } = options;
 
@@ -60,9 +59,9 @@ export function generateSafeFilename(input, options = {}) {
 
 /**
  * Generate unique filename for Cursor IDE rules
- * Handles the specific requirements for Cursor .cursorrules format
+ * Handles canonical Cursor `.cursor/rules/*.mdc` naming requirements
  * @param {Object} rule - Rule object with frontmatter
- * @returns {string} Unique filename
+ * @returns {string} Unique base filename (without extension)
  */
 export function generateCursorFilename(rule) {
   const category = rule.frontmatter?.category || 'general';
@@ -96,7 +95,6 @@ export function generateCursorFilename(rule) {
 
   return generateSafeFilename(baseName, {
     maxLength: 40,
-    extension: '.md',
     separator: '-',
   });
 }

package/src/utils/schema-validator.js

@@ -58,7 +58,7 @@ async function loadSchemaDefinition(schemaName) {
     const schemaContent = await fs.readFile(schemaPath, 'utf8');
     return JSON.parse(schemaContent);
   } catch (error) {
-    throw new Error(`Failed to load schema '${schemaName}': ${error.message}`);
+    throw new Error(`Failed to load schema '${schemaName}': ${error.message}`, { cause: error });
   }
 }
 

package/src/utils/update-mcp-config.js

@@ -133,7 +133,7 @@ async function updateMCPConfig() {
   // Then, check common rule directories if none found from IDEs
   if (ruleDirectories.length === 0) {
     const commonPaths = [
-      '.vdk/rules',
+      '.vdk/blueprints/rules',
       '.vscode/ai-rules',
       '.vscode-insiders/ai-rules',
       '.vscode-oss/ai-rules',
@@ -164,7 +164,7 @@ async function updateMCPConfig() {
 
     // If force option is provided, use the default path
     if (options.force) {
-      const defaultPath = path.join(options.path, '.vdk/rules');
+      const defaultPath = path.join(options.path, '.vdk/blueprints/rules');
       console.log(`${colors.yellow}Creating default rule directory: ${defaultPath}${colors.reset}`);
 
       if (!fs.existsSync(defaultPath)) {

package/src/validation/check-duplicates.js

@@ -39,7 +39,7 @@ async function checkDuplicateRules() {
     try {
       await fs.access(dirPath);
       dirExists = true;
-    } catch (_err) {
+    } catch {
       continue;
     }
 

package/src/validation/validate-rules.js

@@ -21,13 +21,13 @@ const __dirname = pathUtils.getDirname(__filename);
 // Rule repository paths
 const rulesRootDir = pathUtils.join(__dirname, '../..');
 const ruleDirectories = [
-  '.vdk/rules',
-  '.vdk/rules/assistants',
-  '.vdk/rules/languages',
-  '.vdk/rules/stacks',
-  '.vdk/rules/tasks',
-  '.vdk/rules/technologies',
-  '.vdk/rules/tools',
+  '.vdk/blueprints/rules',
+  '.vdk/blueprints/rules/assistants',
+  '.vdk/blueprints/rules/languages',
+  '.vdk/blueprints/rules/stacks',
+  '.vdk/blueprints/rules/tasks',
+  '.vdk/blueprints/rules/technologies',
+  '.vdk/blueprints/rules/tools',
 ];
 
 // Track all rule IDs to check for duplicates