ultra-dex 1.7.1 → 1.7.3

package/README.md

@@ -13,12 +13,12 @@ cd your-project
 cat QUICK-START.md
 
 # 3. Load Cursor rules for AI assistance (1 min)
-# Download from: https://github.com/Srujan0798/Ultra-Dex/tree/main/cursor-rules
-# Then: ./load.sh database api auth
+npx degit Srujan0798/Ultra-Dex/cursor-rules .cursor/rules
+# Then: cd .cursor/rules && ./load.sh database api auth
 
 # 4. Start building with AI agents (4 min)
 # Use @Backend, @Frontend, @Database agents
-# See: npx ultra-dex agents
+npx ultra-dex agents
 
 # You're ready to code!
 ```
@@ -92,6 +92,42 @@ npx ultra-dex agent backend
 
 Prints the full agent prompt. Copy and paste into your AI tool (Cursor, Claude, ChatGPT).
 
+### Set up git hooks
+
+```bash
+npx ultra-dex hooks
+```
+
+Installs a pre-commit hook that:
+- Validates project structure before each commit
+- Blocks commits if required files are missing
+- Can be bypassed with `git commit --no-verify`
+
+Remove with: `npx ultra-dex hooks --remove`
+
+### Fetch assets for offline use
+
+```bash
+npx ultra-dex fetch
+```
+
+Downloads all Ultra-Dex assets locally for offline development:
+- Cursor rules (12 .mdc files)
+- Agent prompts (16 agents)
+- Documentation and guides
+
+Options:
+- `--dir <path>` - Target directory (default: `.ultra-dex`)
+- `--agents` - Fetch only agent prompts
+- `--rules` - Fetch only cursor rules
+- `--docs` - Fetch only documentation
+
+After fetching, copy to your project:
+```bash
+cp -r .ultra-dex/cursor-rules .cursor/rules
+cp -r .ultra-dex/agents .agents
+```
+
 ## Commands
 
 | Command | Description |
@@ -101,6 +137,12 @@ Prints the full agent prompt. Copy and paste into your AI tool (Cursor, Claude,
 | `ultra-dex examples` | List available examples |
 | `ultra-dex agents` | List available AI agents |
 | `ultra-dex agent <name>` | Show specific agent prompt |
+| `ultra-dex pack <agent>` | Package context + agent for any AI |
+| `ultra-dex hooks` | Set up git pre-commit hooks |
+| `ultra-dex fetch` | Download assets for offline use |
+| `ultra-dex validate` | Validate project structure |
+| `ultra-dex workflow <feature>` | Show workflow for a feature |
+| `ultra-dex suggest` | Get AI agent suggestions |
 | `ultra-dex --help` | Show help |
 | `ultra-dex --version` | Show version |
 

package/bin/ultra-dex.js

@@ -300,10 +300,21 @@ ${answers.ideaWhat} for ${answers.ideaFor}.
               path.join(rulesDir, file)
             );
           }
+        // Also generate .github/copilot-instructions.md for Copilot users
+          const coreRulePath = path.join(cursorRulesPath, '00-ultra-dex-core.mdc');
+          try {
+            const coreContent = await fs.readFile(coreRulePath, 'utf-8');
+            const dotGithub = path.join(outputDir, '.github');
+            await fs.mkdir(dotGithub, { recursive: true });
+            await fs.writeFile(path.join(dotGithub, 'copilot-instructions.md'), coreContent);
+          } catch (e) {
+            // Core rule not available - skip Copilot setup
+          }
         } catch (err) {
-          // Cursor rules not available (npm package, not local) - this is expected
-          console.log(chalk.gray('\n  Cursor rules: Download from GitHub for AI-assisted development'));
-          console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex/tree/main/cursor-rules'));
+          // Cursor rules not bundled - intentional design choice for npm package size
+          console.log(chalk.gray('\n  📦 Cursor rules not bundled (keeps npm package <50KB)'));
+          console.log(chalk.cyan('  Quick setup: npx degit Srujan0798/Ultra-Dex/cursor-rules .cursor/rules'));
+          console.log(chalk.blue('  Or download: https://github.com/Srujan0798/Ultra-Dex/tree/main/cursor-rules'));
         }
       }
 
@@ -313,9 +324,10 @@ ${answers.ideaWhat} for ${answers.ideaFor}.
         try {
           await fs.copyFile(templatePath, path.join(outputDir, 'docs', 'MASTER-PLAN.md'));
         } catch (err) {
-          // Template not available locally - this is expected for npm installs
-          console.log(chalk.gray('\n  Full 34-section template: Download from GitHub'));
-          console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex/blob/main/%40%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md'));
+          // Template not bundled - keeps npm package lightweight
+          console.log(chalk.gray('\n  📦 Full template not bundled (5,500 lines - too large for npm)'));
+          console.log(chalk.cyan('  Quick fetch: curl -O https://raw.githubusercontent.com/Srujan0798/Ultra-Dex/main/%40%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md'));
+          console.log(chalk.blue('  Or view: https://github.com/Srujan0798/Ultra-Dex/blob/main/%40%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md'));
         }
       }
 
@@ -327,9 +339,10 @@ ${answers.ideaWhat} for ${answers.ideaFor}.
           await fs.copyFile(verificationPath, path.join(outputDir, 'docs', 'CHECKLIST.md'));
           await fs.copyFile(agentPath, path.join(outputDir, 'docs', 'AI-PROMPTS.md'));
         } catch (err) {
-          // Docs not available locally - this is expected for npm installs
-          console.log(chalk.gray('\n  Verification checklist & agent instructions: Download from GitHub'));
-          console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex/tree/main/docs'));
+          // Docs not bundled - intentional for npm package size
+          console.log(chalk.gray('\n  📦 Verification & instructions not bundled (npm size optimization)'));
+          console.log(chalk.cyan('  Quick setup: npx degit Srujan0798/Ultra-Dex/docs docs'));
+          console.log(chalk.blue('  Or view: https://github.com/Srujan0798/Ultra-Dex/tree/main/docs'));
         }
       }
 
@@ -366,9 +379,10 @@ ${answers.ideaWhat} for ${answers.ideaFor}.
             path.join(agentsDir, 'README.md')
           );
         } catch (err) {
-          // Agents not available locally - this is expected for npm installs
-          console.log(chalk.gray('\n  15 AI agent prompts: Download from GitHub'));
-          console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex/tree/main/agents'));
+          // Agents not bundled - intentional for npm package size
+          console.log(chalk.gray('\n  📦 Agent prompts not bundled (npm size optimization)'));
+          console.log(chalk.cyan('  Quick setup: npx degit Srujan0798/Ultra-Dex/agents .agents'));
+          console.log(chalk.blue('  Or view: https://github.com/Srujan0798/Ultra-Dex/tree/main/agents'));
         }
       }
 
@@ -651,6 +665,80 @@ program
     }
   });
 
+// Pack command - assemble context for any AI tool
+program
+  .command('pack <agent>')
+  .description('Package project context + agent prompt for any AI tool')
+  .option('-c, --clipboard', 'Copy to clipboard (requires pbcopy/xclip)')
+  .action(async (agentName, options) => {
+    // Find agent
+    const agent = AGENTS.find(a => a.name.toLowerCase() === agentName.toLowerCase());
+    if (!agent) {
+      console.log(chalk.red(`\n❌ Agent "${agentName}" not found.\n`));
+      console.log(chalk.gray('Available agents:'));
+      AGENTS.forEach(a => console.log(chalk.cyan(`  - ${a.name}`)));
+      process.exit(1);
+    }
+
+    let output = '';
+
+    // 1. Read Agent Prompt
+    const agentPath = path.resolve(__dirname, '../../agents', agent.file);
+    try {
+      const agentPrompt = await fs.readFile(agentPath, 'utf-8');
+      output += agentPrompt + '\n\n';
+    } catch (err) {
+      output += `# ${agent.name.toUpperCase()} Agent\n\nSee: https://github.com/Srujan0798/Ultra-Dex/blob/main/agents/${agent.file}\n\n`;
+    }
+
+    output += '---\n\n';
+
+    // 2. Read CONTEXT.md
+    try {
+      const context = await fs.readFile('CONTEXT.md', 'utf-8');
+      output += '# PROJECT CONTEXT\n\n' + context + '\n\n';
+    } catch (err) {
+      output += '# PROJECT CONTEXT\n\n*No CONTEXT.md found. Run `ultra-dex init` first.*\n\n';
+    }
+
+    output += '---\n\n';
+
+    // 3. Read IMPLEMENTATION-PLAN.md
+    try {
+      const plan = await fs.readFile('IMPLEMENTATION-PLAN.md', 'utf-8');
+      output += '# IMPLEMENTATION PLAN\n\n' + plan + '\n';
+    } catch (err) {
+      output += '# IMPLEMENTATION PLAN\n\n*No IMPLEMENTATION-PLAN.md found. Run `ultra-dex init` first.*\n';
+    }
+
+    // Output
+    console.log(chalk.bold(`\n📦 Packed context for @${agent.name}\n`));
+    console.log(chalk.gray('─'.repeat(60)));
+    console.log(output);
+    console.log(chalk.gray('─'.repeat(60)));
+
+    // Try to copy to clipboard if requested
+    if (options.clipboard) {
+      try {
+        const { execSync } = require('child_process');
+        const platform = process.platform;
+        if (platform === 'darwin') {
+          execSync('pbcopy', { input: output });
+          console.log(chalk.green('\n✅ Copied to clipboard!\n'));
+        } else if (platform === 'linux') {
+          execSync('xclip -selection clipboard', { input: output });
+          console.log(chalk.green('\n✅ Copied to clipboard!\n'));
+        } else {
+          console.log(chalk.yellow('\n⚠️  Clipboard not supported on this platform. Copy manually.\n'));
+        }
+      } catch (err) {
+        console.log(chalk.yellow('\n⚠️  Could not copy to clipboard. Copy manually.\n'));
+      }
+    } else {
+      console.log(chalk.cyan('\n💡 Tip: Use --clipboard flag to copy directly\n'));
+    }
+  });
+
 // Workflow examples map
 const WORKFLOWS = {
   auth: {
@@ -1090,4 +1178,300 @@ program
     console.log('\n' + chalk.gray('Run "ultra-dex init" to set up a proper Ultra-Dex project.\n'));
   });
 
+// ========================================
+// HOOKS COMMAND - Automated Verification
+// ========================================
+program
+  .command('hooks')
+  .description('Set up git hooks for automated verification')
+  .option('--remove', 'Remove Ultra-Dex git hooks')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n🪝 Ultra-Dex Git Hooks Setup\n'));
+
+    const gitDir = path.join(process.cwd(), '.git');
+    const hooksDir = path.join(gitDir, 'hooks');
+
+    // Check if git repo exists
+    try {
+      await fs.access(gitDir);
+    } catch {
+      console.log(chalk.red('❌ Not a git repository. Run "git init" first.\n'));
+      process.exit(1);
+    }
+
+    // Create hooks directory if it doesn't exist
+    await fs.mkdir(hooksDir, { recursive: true });
+
+    const preCommitPath = path.join(hooksDir, 'pre-commit');
+
+    if (options.remove) {
+      // Remove hooks
+      try {
+        const content = await fs.readFile(preCommitPath, 'utf-8');
+        if (content.includes('ultra-dex')) {
+          await fs.unlink(preCommitPath);
+          console.log(chalk.green('✅ Ultra-Dex pre-commit hook removed.\n'));
+        } else {
+          console.log(chalk.yellow('⚠️  Pre-commit hook exists but is not from Ultra-Dex.\n'));
+        }
+      } catch {
+        console.log(chalk.gray('No Ultra-Dex hooks found.\n'));
+      }
+      return;
+    }
+
+    // Generate pre-commit hook
+    const preCommitScript = `#!/bin/sh
+# Ultra-Dex Pre-Commit Hook
+# Validates project structure before allowing commits
+# Remove with: npx ultra-dex hooks --remove
+
+echo "🔍 Ultra-Dex: Validating project structure..."
+
+# Run validation
+npx ultra-dex validate --dir . > /tmp/ultra-dex-validate.log 2>&1
+RESULT=$?
+
+if [ $RESULT -ne 0 ]; then
+  echo ""
+  echo "❌ Ultra-Dex validation failed. Commit blocked."
+  echo ""
+  echo "Run 'npx ultra-dex validate' to see details."
+  echo "Fix issues or bypass with: git commit --no-verify"
+  echo ""
+  exit 1
+fi
+
+# Check for required files
+if [ ! -f "QUICK-START.md" ]; then
+  echo "⚠️  Warning: QUICK-START.md not found"
+fi
+
+if [ ! -f "IMPLEMENTATION-PLAN.md" ]; then
+  echo "⚠️  Warning: IMPLEMENTATION-PLAN.md not found"
+fi
+
+echo "✅ Ultra-Dex validation passed."
+exit 0
+`;
+
+    // Check if pre-commit already exists
+    try {
+      const existing = await fs.readFile(preCommitPath, 'utf-8');
+      if (existing.includes('ultra-dex')) {
+        console.log(chalk.yellow('⚠️  Ultra-Dex pre-commit hook already exists.\n'));
+        console.log(chalk.gray('  Use --remove to remove it first.\n'));
+        return;
+      } else {
+        // Append to existing hook
+        const combined = existing + '\n\n' + preCommitScript;
+        await fs.writeFile(preCommitPath, combined);
+        await fs.chmod(preCommitPath, '755');
+        console.log(chalk.green('✅ Ultra-Dex hook appended to existing pre-commit.\n'));
+      }
+    } catch {
+      // No existing hook, create new
+      await fs.writeFile(preCommitPath, preCommitScript);
+      await fs.chmod(preCommitPath, '755');
+      console.log(chalk.green('✅ Pre-commit hook installed.\n'));
+    }
+
+    console.log(chalk.bold('What this does:\n'));
+    console.log(chalk.gray('  • Runs "ultra-dex validate" before each commit'));
+    console.log(chalk.gray('  • Blocks commits if required files are missing'));
+    console.log(chalk.gray('  • Warns about incomplete sections\n'));
+
+    console.log(chalk.bold('To bypass (not recommended):\n'));
+    console.log(chalk.cyan('  git commit --no-verify\n'));
+
+    console.log(chalk.bold('To remove:\n'));
+    console.log(chalk.cyan('  npx ultra-dex hooks --remove\n'));
+  });
+
+// ========================================
+// FETCH COMMAND - Offline Mode Support
+// ========================================
+program
+  .command('fetch')
+  .description('Download all Ultra-Dex assets for offline use')
+  .option('-d, --dir <directory>', 'Target directory', '.ultra-dex')
+  .option('--agents', 'Fetch only agent prompts')
+  .option('--rules', 'Fetch only cursor rules')
+  .option('--docs', 'Fetch only documentation')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n📦 Ultra-Dex Asset Fetcher\n'));
+
+    const targetDir = path.resolve(options.dir);
+    const fetchAll = !options.agents && !options.rules && !options.docs;
+
+    // GitHub raw URLs
+    const GITHUB_RAW = 'https://raw.githubusercontent.com/Srujan0798/Ultra-Dex/main';
+
+    // Helper to download a file
+    async function downloadFile(url, destPath) {
+      try {
+        const response = await fetch(url);
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const content = await response.text();
+        await fs.mkdir(path.dirname(destPath), { recursive: true });
+        await fs.writeFile(destPath, content);
+        return true;
+      } catch (err) {
+        return false;
+      }
+    }
+
+    const spinner = ora('Preparing to fetch assets...').start();
+
+    // Create target directory
+    await fs.mkdir(targetDir, { recursive: true });
+
+    let downloaded = 0;
+    let failed = 0;
+
+    // Fetch cursor rules
+    if (fetchAll || options.rules) {
+      spinner.text = 'Fetching cursor rules...';
+      const rulesDir = path.join(targetDir, 'cursor-rules');
+      await fs.mkdir(rulesDir, { recursive: true });
+
+      const ruleFiles = [
+        '00-ultra-dex-core.mdc',
+        '01-database.mdc',
+        '02-api.mdc',
+        '03-auth.mdc',
+        '04-frontend.mdc',
+        '05-payments.mdc',
+        '06-testing.mdc',
+        '07-security.mdc',
+        '08-deployment.mdc',
+        '09-error-handling.mdc',
+        '10-performance.mdc',
+        '11-nextjs-v15.mdc',
+        '12-multi-tenancy.mdc',
+      ];
+
+      for (const file of ruleFiles) {
+        const url = `${GITHUB_RAW}/cursor-rules/${file}`;
+        const dest = path.join(rulesDir, file);
+        if (await downloadFile(url, dest)) {
+          downloaded++;
+        } else {
+          failed++;
+        }
+      }
+
+      // Also fetch load.sh
+      await downloadFile(`${GITHUB_RAW}/cursor-rules/load.sh`, path.join(rulesDir, 'load.sh'));
+      try {
+        await fs.chmod(path.join(rulesDir, 'load.sh'), '755');
+      } catch {}
+    }
+
+    // Fetch agent prompts
+    if (fetchAll || options.agents) {
+      spinner.text = 'Fetching agent prompts...';
+      const agentsDir = path.join(targetDir, 'agents');
+
+      const agentPaths = [
+        '00-AGENT_INDEX.md',
+        'README.md',
+        'AGENT-INSTRUCTIONS.md',
+        '0-orchestration/orchestrator.md',
+        '1-leadership/cto.md',
+        '1-leadership/planner.md',
+        '1-leadership/research.md',
+        '2-development/backend.md',
+        '2-development/frontend.md',
+        '2-development/database.md',
+        '3-security/security.md',
+        '4-devops/devops.md',
+        '5-quality/reviewer.md',
+        '5-quality/testing.md',
+        '5-quality/debugger.md',
+        '6-specialist/performance.md',
+        '6-specialist/refactoring.md',
+        '6-specialist/documentation.md',
+      ];
+
+      for (const agentPath of agentPaths) {
+        const url = `${GITHUB_RAW}/agents/${agentPath}`;
+        const dest = path.join(agentsDir, agentPath);
+        if (await downloadFile(url, dest)) {
+          downloaded++;
+        } else {
+          failed++;
+        }
+      }
+    }
+
+    // Fetch documentation
+    if (fetchAll || options.docs) {
+      spinner.text = 'Fetching documentation...';
+      const docsDir = path.join(targetDir, 'docs');
+
+      const docFiles = [
+        'VERIFICATION.md',
+        'BUILD-AUTH-30M.md',
+        'QUICK-REFERENCE.md',
+        'TROUBLESHOOTING.md',
+      ];
+
+      for (const file of docFiles) {
+        const url = `${GITHUB_RAW}/docs/${file}`;
+        const dest = path.join(docsDir, file);
+        if (await downloadFile(url, dest)) {
+          downloaded++;
+        } else {
+          failed++;
+        }
+      }
+
+      // Fetch guides
+      const guidesDir = path.join(targetDir, 'guides');
+      const guideFiles = [
+        'PROJECT-ORCHESTRATION.md',
+        'ADVANCED-WORKFLOWS.md',
+        'DATABASE-DECISION-FRAMEWORK.md',
+        'ARCHITECTURE-PATTERNS.md',
+      ];
+
+      for (const file of guideFiles) {
+        const url = `${GITHUB_RAW}/guides/${file}`;
+        const dest = path.join(guidesDir, file);
+        if (await downloadFile(url, dest)) {
+          downloaded++;
+        } else {
+          failed++;
+        }
+      }
+    }
+
+    if (failed === 0) {
+      spinner.succeed(chalk.green(`Downloaded ${downloaded} files to ${targetDir}`));
+    } else {
+      spinner.warn(chalk.yellow(`Downloaded ${downloaded} files, ${failed} failed`));
+    }
+
+    console.log(chalk.bold('\n📁 Assets downloaded to:\n'));
+    if (fetchAll || options.rules) {
+      console.log(chalk.gray(`  ${targetDir}/cursor-rules/  (12 .mdc files)`));
+    }
+    if (fetchAll || options.agents) {
+      console.log(chalk.gray(`  ${targetDir}/agents/        (16 agent prompts)`));
+    }
+    if (fetchAll || options.docs) {
+      console.log(chalk.gray(`  ${targetDir}/docs/          (documentation)`));
+      console.log(chalk.gray(`  ${targetDir}/guides/        (guides)`));
+    }
+
+    console.log(chalk.bold('\n💡 Usage:\n'));
+    console.log(chalk.cyan('  # Copy cursor rules to project'));
+    console.log(chalk.gray(`  cp -r ${targetDir}/cursor-rules .cursor/rules`));
+    console.log(chalk.cyan('\n  # Copy agents to project'));
+    console.log(chalk.gray(`  cp -r ${targetDir}/agents .agents`));
+    console.log(chalk.cyan('\n  # Works offline now!'));
+    console.log(chalk.gray('  No GitHub access needed after fetch.\n'));
+  });
+
 program.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra-dex",
-  "version": "1.7.1",
-  "description": "CLI for Ultra-Dex SaaS Implementation Framework with 15 Production Agents",
+  "version": "1.7.3",
+  "description": "CLI for Ultra-Dex SaaS Implementation Framework with 16 Production Agents",
   "keywords": [
     "saas",
     "template",