start-vibing-stacks 1.0.0

package/dist/installer.js

@@ -0,0 +1,224 @@
+/**
+ * Start Vibing Stacks — Dependency Installer & Validator
+ *
+ * Validates system requirements and auto-installs missing dependencies.
+ * macOS-first with Homebrew, with Linux fallbacks.
+ */
+import { execSync } from 'child_process';
+import { platform } from 'os';
+import * as semver from 'semver';
+import ora from 'ora';
+import * as ui from './ui.js';
+const OS = platform();
+/**
+ * Get installed version of a tool
+ */
+function getVersion(command, versionFlag, regex) {
+    try {
+        const output = execSync(`${command} ${versionFlag} 2>&1`, {
+            encoding: 'utf8',
+            timeout: 10000,
+        }).trim();
+        const match = output.match(new RegExp(regex));
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if Homebrew is installed (macOS)
+ */
+function hasHomebrew() {
+    try {
+        execSync('which brew', { encoding: 'utf8', stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install Homebrew on macOS
+ */
+function installHomebrew() {
+    const spinner = ora('Installing Homebrew...').start();
+    try {
+        execSync('/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"', { stdio: 'inherit', timeout: 300000 });
+        spinner.succeed('Homebrew installed');
+        return true;
+    }
+    catch {
+        spinner.fail('Failed to install Homebrew');
+        return false;
+    }
+}
+/**
+ * Install a dependency using the appropriate system command
+ */
+function installDependency(req) {
+    const cmd = OS === 'darwin' ? req.installCommand.macos : req.installCommand.linux;
+    if (!cmd)
+        return false;
+    const spinner = ora(`Installing ${req.name}...`).start();
+    try {
+        execSync(cmd, { stdio: 'pipe', timeout: 300000 });
+        spinner.succeed(`${req.name} installed`);
+        return true;
+    }
+    catch (err) {
+        spinner.fail(`Failed to install ${req.name}`);
+        return false;
+    }
+}
+/**
+ * Validate all requirements for a stack
+ */
+export function validateRequirements(requirements) {
+    const results = [];
+    for (const req of requirements) {
+        const version = getVersion(req.command, req.versionFlag, req.versionRegex);
+        const installed = version !== null;
+        let meetsMinimum = false;
+        if (installed && version) {
+            try {
+                const cleaned = semver.coerce(version);
+                const minCleaned = semver.coerce(req.minVersion);
+                if (cleaned && minCleaned) {
+                    meetsMinimum = semver.gte(cleaned, minCleaned);
+                }
+            }
+            catch {
+                meetsMinimum = false;
+            }
+        }
+        results.push({
+            name: req.name,
+            installed,
+            version,
+            meetsMinimum,
+            minVersion: req.minVersion,
+        });
+    }
+    return results;
+}
+/**
+ * Auto-install missing or outdated requirements
+ */
+export async function autoInstall(requirements) {
+    ui.header('🔍 Validating Requirements');
+    // Ensure Homebrew on macOS
+    if (OS === 'darwin' && !hasHomebrew()) {
+        ui.warn('Homebrew not found. Installing...');
+        if (!installHomebrew()) {
+            ui.error('Cannot proceed without Homebrew on macOS');
+            return false;
+        }
+    }
+    const results = validateRequirements(requirements);
+    let allGood = true;
+    for (const result of results) {
+        if (result.installed && result.meetsMinimum) {
+            ui.success(`${result.name} ${result.version} (>= ${result.minVersion})`);
+        }
+        else if (result.installed && !result.meetsMinimum) {
+            ui.warn(`${result.name} ${result.version} is below minimum ${result.minVersion}`);
+            const req = requirements.find((r) => r.name === result.name);
+            if (!installDependency(req)) {
+                allGood = false;
+            }
+        }
+        else {
+            ui.warn(`${result.name} not found`);
+            const req = requirements.find((r) => r.name === result.name);
+            if (!installDependency(req)) {
+                allGood = false;
+            }
+        }
+    }
+    // Re-validate after installation
+    if (!allGood) {
+        console.log('');
+        ui.info('Re-validating after installation...');
+        const recheck = validateRequirements(requirements);
+        allGood = recheck.every((r) => r.installed && r.meetsMinimum);
+        if (!allGood) {
+            const failing = recheck.filter((r) => !r.installed || !r.meetsMinimum);
+            for (const f of failing) {
+                ui.error(`${f.name}: ${f.installed ? `v${f.version} < ${f.minVersion}` : 'not found'}`);
+            }
+        }
+    }
+    return allGood;
+}
+/**
+ * Install Composer using PHP 8.3+
+ */
+export async function installComposer() {
+    // Check if composer exists
+    const composerVersion = getVersion('composer', '--version', '(\\d+\\.\\d+\\.\\d+)');
+    if (composerVersion) {
+        ui.success(`Composer ${composerVersion} already installed`);
+        return true;
+    }
+    ui.warn('Composer not found. Installing via PHP...');
+    // Verify PHP is available first
+    const phpVersion = getVersion('php', '-v', 'PHP\\s+(\\d+\\.\\d+\\.\\d+)');
+    if (!phpVersion) {
+        ui.error('PHP not found. Install PHP first.');
+        return false;
+    }
+    const spinner = ora('Installing Composer...').start();
+    try {
+        // Official Composer install method
+        const commands = [
+            'php -r "copy(\'https://getcomposer.org/installer\', \'composer-setup.php\');"',
+            'php composer-setup.php',
+            'php -r "unlink(\'composer-setup.php\');"',
+        ];
+        if (OS === 'darwin') {
+            commands.push('sudo mv composer.phar /usr/local/bin/composer');
+        }
+        else {
+            commands.push('sudo mv composer.phar /usr/local/bin/composer');
+        }
+        for (const cmd of commands) {
+            execSync(cmd, { stdio: 'pipe', timeout: 60000 });
+        }
+        spinner.succeed('Composer installed globally');
+        return true;
+    }
+    catch {
+        spinner.fail('Failed to install Composer');
+        ui.info('Manual install: https://getcomposer.org/download/');
+        return false;
+    }
+}
+/**
+ * Install Claude Code if not present
+ */
+export function installClaudeCode() {
+    try {
+        execSync('which claude', { stdio: 'pipe' });
+        const version = getVersion('claude', '--version', '(\\d+\\.\\d+\\.\\d+)');
+        ui.success(`Claude Code ${version || 'installed'}`);
+        return true;
+    }
+    catch {
+        ui.warn('Claude Code not found. Installing...');
+        const spinner = ora('Installing Claude Code...').start();
+        try {
+            execSync('npm install -g @anthropic-ai/claude-code', {
+                stdio: 'pipe',
+                timeout: 120000,
+            });
+            spinner.succeed('Claude Code installed');
+            return true;
+        }
+        catch {
+            spinner.fail('Failed to install Claude Code');
+            ui.info('Manual install: npm install -g @anthropic-ai/claude-code');
+            return false;
+        }
+    }
+}

package/dist/setup.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Start Vibing Stacks — Setup Engine
+ *
+ * Copies and configures stack-specific files into the project.
+ */
+import type { ProjectConfig, StackConfig } from './types.js';
+/**
+ * Load a stack configuration from stacks/{id}/stack.json
+ */
+export declare function loadStackConfig(stackId: string): StackConfig | null;
+/**
+ * Setup the project with the selected configuration
+ */
+export declare function setupProject(projectDir: string, config: ProjectConfig, options?: {
+    force?: boolean;
+    noClaude?: boolean;
+}): Promise<boolean>;

package/dist/setup.js

@@ -0,0 +1,161 @@
+/**
+ * Start Vibing Stacks — Setup Engine
+ *
+ * Copies and configures stack-specific files into the project.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import ora from 'ora';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, '..');
+/**
+ * Load a stack configuration from stacks/{id}/stack.json
+ */
+export function loadStackConfig(stackId) {
+    const stackPath = join(PACKAGE_ROOT, 'stacks', stackId, 'stack.json');
+    if (!existsSync(stackPath))
+        return null;
+    try {
+        const raw = readFileSync(stackPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Copy directory recursively, preserving structure
+ */
+function copyDirRecursive(src, dest, overwrite = false) {
+    if (!existsSync(src))
+        return 0;
+    let count = 0;
+    mkdirSync(dest, { recursive: true });
+    const entries = readdirSync(src);
+    for (const entry of entries) {
+        const srcPath = join(src, entry);
+        const destPath = join(dest, entry);
+        const stat = statSync(srcPath);
+        if (stat.isDirectory()) {
+            count += copyDirRecursive(srcPath, destPath, overwrite);
+        }
+        else {
+            if (!existsSync(destPath) || overwrite) {
+                const content = readFileSync(srcPath, 'utf8');
+                mkdirSync(dirname(destPath), { recursive: true });
+                writeFileSync(destPath, content);
+                count++;
+            }
+        }
+    }
+    return count;
+}
+/**
+ * Setup the project with the selected configuration
+ */
+export async function setupProject(projectDir, config, options = {}) {
+    const spinner = ora('Setting up project...').start();
+    const claudeDir = join(projectDir, '.claude');
+    try {
+        // 1. Create .claude directory structure
+        mkdirSync(join(claudeDir, 'agents'), { recursive: true });
+        mkdirSync(join(claudeDir, 'skills'), { recursive: true });
+        mkdirSync(join(claudeDir, 'hooks'), { recursive: true });
+        mkdirSync(join(claudeDir, 'config'), { recursive: true });
+        mkdirSync(join(claudeDir, 'commands'), { recursive: true });
+        mkdirSync(join(claudeDir, 'skills', 'codebase-knowledge', 'domains'), { recursive: true });
+        spinner.text = 'Directory structure created';
+        // 2. Copy shared agents (universal)
+        const sharedAgentsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'agents');
+        const agentCount = copyDirRecursive(sharedAgentsDir, join(claudeDir, 'agents'), options.force);
+        spinner.text = `Copied ${agentCount} universal agents`;
+        // 3. Copy shared skills
+        const sharedSkillsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'skills');
+        const sharedSkillCount = copyDirRecursive(sharedSkillsDir, join(claudeDir, 'skills'), options.force);
+        // 4. Copy shared hooks
+        const sharedHooksDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'hooks');
+        const hookCount = copyDirRecursive(sharedHooksDir, join(claudeDir, 'hooks'), options.force);
+        // 5. Copy shared config
+        const sharedConfigDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'config');
+        copyDirRecursive(sharedConfigDir, join(claudeDir, 'config'), options.force);
+        // 6. Copy stack-specific skills
+        const stackSkillsDir = join(PACKAGE_ROOT, 'stacks', config.stack, 'skills');
+        const stackSkillCount = copyDirRecursive(stackSkillsDir, join(claudeDir, 'skills'), options.force);
+        // 7. Copy stack-specific config
+        const stackConfigDir = join(PACKAGE_ROOT, 'stacks', config.stack, 'config');
+        copyDirRecursive(stackConfigDir, join(claudeDir, 'config'), options.force);
+        // 8. Copy frontend-specific skills if applicable
+        if (config.frontend && config.frontend !== 'none') {
+            const frontendDir = join(PACKAGE_ROOT, 'stacks', 'frontend', config.frontend);
+            if (existsSync(frontendDir)) {
+                const feSkillCount = copyDirRecursive(join(frontendDir, 'skills'), join(claudeDir, 'skills'), options.force);
+                spinner.text = `Loaded ${feSkillCount} frontend skills`;
+            }
+        }
+        // 9. Write active-project.json
+        writeFileSync(join(claudeDir, 'config', 'active-project.json'), JSON.stringify(config, null, 2));
+        // 10. Write/merge CLAUDE.md from template
+        const claudeMdTemplate = join(PACKAGE_ROOT, 'templates', `CLAUDE-${config.stack}.md`);
+        const claudeMdFallback = join(PACKAGE_ROOT, 'templates', 'CLAUDE-default.md');
+        const templatePath = existsSync(claudeMdTemplate) ? claudeMdTemplate : claudeMdFallback;
+        const claudeMdDest = join(projectDir, 'CLAUDE.md');
+        if (!existsSync(claudeMdDest) || options.force) {
+            let template = readFileSync(templatePath, 'utf8');
+            // Replace placeholders
+            template = template
+                .replace(/\{\{PROJECT_NAME\}\}/g, config.name)
+                .replace(/\{\{STACK\}\}/g, config.stack.toUpperCase())
+                .replace(/\{\{FRAMEWORK\}\}/g, config.framework)
+                .replace(/\{\{DATABASE\}\}/g, config.database)
+                .replace(/\{\{DATE\}\}/g, new Date().toISOString().split('T')[0]);
+            writeFileSync(claudeMdDest, template);
+        }
+        else if (existsSync(claudeMdDest)) {
+            // Backup existing CLAUDE.md as template for smart merge
+            const existing = readFileSync(claudeMdDest, 'utf8');
+            if (existsSync(templatePath)) {
+                writeFileSync(join(claudeDir, 'CLAUDE.template.md'), readFileSync(templatePath, 'utf8'));
+            }
+        }
+        // 11. Handle .cursorrules integration
+        if (config.cursorRules) {
+            const cursorRulesPath = join(projectDir, '.cursorrules');
+            if (existsSync(cursorRulesPath)) {
+                const cursorContent = readFileSync(cursorRulesPath, 'utf8');
+                const cursorIntegrationPath = join(claudeDir, 'config', 'cursor-rules-imported.md');
+                writeFileSync(cursorIntegrationPath, `# Imported from .cursorrules\n\n${cursorContent}`);
+                spinner.text = 'Imported .cursorrules into Claude config';
+            }
+        }
+        // 12. Copy commands
+        const sharedCommandsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'commands');
+        if (existsSync(sharedCommandsDir)) {
+            copyDirRecursive(sharedCommandsDir, join(claudeDir, 'commands'), options.force);
+        }
+        // 13. Write settings.json for Claude Code
+        const settings = {
+            permissions: {
+                allow: [
+                    'Bash(*)',
+                    'Read(*)',
+                    'Write(*)',
+                    'Edit(*)',
+                    'Grep(*)',
+                    'Glob(*)',
+                    'WebSearch(*)',
+                    'WebFetch(*)',
+                ],
+                deny: [],
+            },
+        };
+        writeFileSync(join(claudeDir, 'settings.json'), JSON.stringify(settings, null, '\t'));
+        spinner.succeed(`Setup complete: ${agentCount} agents, ${sharedSkillCount + stackSkillCount} skills, ${hookCount} hooks`);
+        return true;
+    }
+    catch (err) {
+        spinner.fail(`Setup failed: ${err}`);
+        return false;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Start Vibing Stacks — Type Definitions
+ */
+export interface StackConfig {
+    id: string;
+    name: string;
+    icon: string;
+    runtime: string;
+    minVersion: string;
+    packageManager: string;
+    extensions: string[];
+    testExtensions: string[];
+    detectFiles: string[];
+    commands: Record<string, string | null>;
+    qualityGates: QualityGate[];
+    frameworks: FrameworkOption[];
+    databases: DatabaseOption[];
+    frontendOptions: FrontendOption[];
+    deployTargets: DeployTarget[];
+    skills: string[];
+    requirements: Requirement[];
+}
+export interface QualityGate {
+    name: string;
+    command: string;
+    required: boolean;
+    order: number;
+}
+export interface FrameworkOption {
+    id: string;
+    name: string;
+    icon: string;
+    detectFiles?: string[];
+    extra?: Record<string, unknown>;
+}
+export interface DatabaseOption {
+    id: string;
+    name: string;
+    icon: string;
+}
+export interface FrontendOption {
+    id: string;
+    name: string;
+    icon: string;
+}
+export interface DeployTarget {
+    id: string;
+    name: string;
+    icon: string;
+}
+export interface Requirement {
+    name: string;
+    command: string;
+    versionFlag: string;
+    minVersion: string;
+    installCommand: {
+        macos: string;
+        linux: string;
+    };
+    versionRegex: string;
+}
+export interface ProjectConfig {
+    name: string;
+    stack: string;
+    framework: string;
+    database: string;
+    frontend: string;
+    deploy: string;
+    path: string;
+    createdAt: string;
+    skills: string[];
+    qualityGates: string;
+    cursorRules: boolean;
+    domains: Record<string, {
+        patterns: string[];
+    }>;
+}
+export interface DetectionResult {
+    files: string[];
+    stacks: {
+        id: string;
+        confidence: number;
+        reason: string;
+    }[];
+    hasCursorRules: boolean;
+    hasClaudeMd: boolean;
+    hasGit: boolean;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Start Vibing Stacks — Type Definitions
+ */
+export {};

package/dist/ui.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Start Vibing Stacks — Terminal UI
+ */
+export declare const LOGO: string;
+export declare function header(text: string): void;
+export declare function success(text: string): void;
+export declare function warn(text: string): void;
+export declare function error(text: string): void;
+export declare function info(text: string): void;
+export declare function step(n: number, total: number, text: string): void;
+export declare function configSummary(config: Record<string, string>): void;

package/dist/ui.js

@@ -0,0 +1,47 @@
+/**
+ * Start Vibing Stacks — Terminal UI
+ */
+import chalk from 'chalk';
+export const LOGO = `
+${chalk.red('     /\\                              /\\')}
+${chalk.red('    / \\\\')}  ${chalk.white('██╗   ██╗')}${chalk.red('                / \\\\')}
+${chalk.red('   /   \\\\')} ${chalk.white('████╗ ████║')}${chalk.red('              /   \\\\')}
+${chalk.red('  / /\\  \\\\')}${chalk.white('██╔═██╔═██║')}${chalk.red('            / /\\  \\\\')}
+${chalk.red(' / /  \\  \\\\')}${chalk.white('██║ ██║ ██║')}${chalk.red('          / /  \\  \\\\')}
+${chalk.red('/_/    \\__\\\\')}${chalk.white('╚═╝ ╚═╝ ╚═╝')}${chalk.red('        /_/    \\__\\\\')}
+
+${chalk.bold('  START VIBING STACKS')}${chalk.dim('  ·  Multi-stack AI workflow  ·  v1.0.0')}
+`;
+export function header(text) {
+    console.log('');
+    console.log(chalk.cyan('  ┌' + '─'.repeat(48) + '┐'));
+    console.log(chalk.cyan('  │') + '  ' + chalk.bold(text).padEnd(54) + chalk.cyan('│'));
+    console.log(chalk.cyan('  └' + '─'.repeat(48) + '┘'));
+}
+export function success(text) {
+    console.log(chalk.green('  ✅ ') + text);
+}
+export function warn(text) {
+    console.log(chalk.yellow('  ⚠️  ') + text);
+}
+export function error(text) {
+    console.log(chalk.red('  ❌ ') + text);
+}
+export function info(text) {
+    console.log(chalk.blue('  ℹ️  ') + text);
+}
+export function step(n, total, text) {
+    console.log(chalk.dim(`  [${n}/${total}]`) + ' ' + text);
+}
+export function configSummary(config) {
+    console.log('');
+    console.log(chalk.cyan('  ╔' + '═'.repeat(48) + '╗'));
+    console.log(chalk.cyan('  ║') + chalk.bold('  📋 Project Configuration').padEnd(55) + chalk.cyan('║'));
+    console.log(chalk.cyan('  ╠' + '═'.repeat(48) + '╣'));
+    for (const [key, value] of Object.entries(config)) {
+        const line = `  ${chalk.dim(key + ':')}  ${value}`;
+        console.log(chalk.cyan('  ║') + line.padEnd(69) + chalk.cyan('║'));
+    }
+    console.log(chalk.cyan('  ╚' + '═'.repeat(48) + '╝'));
+    console.log('');
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "start-vibing-stacks",
+  "version": "1.0.0",
+  "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
+  "type": "module",
+  "bin": {
+    "start-vibing-stacks": "dist/index.js",
+    "svs": "dist/index.js"
+  },
+  "scripts": {
+    "build": "npx -p typescript tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude-code",
+    "ai",
+    "coding",
+    "agents",
+    "workflow",
+    "php",
+    "nodejs",
+    "typescript",
+    "vibing",
+    "cursor",
+    "multi-stack"
+  ],
+  "author": "FantasyLake",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "stacks/",
+    "templates/",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "inquirer": "^9.2.0",
+    "ora": "^7.0.0",
+    "semver": "^7.6.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^20.19.35",
+    "@types/semver": "^7.7.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/f1sc4ll-ai/start-vibing-stacks.git"
+  }
+}

package/stacks/_shared/agents/claude-md-compactor.md

@@ -0,0 +1,44 @@
+---
+name: claude-md-compactor
+description: "AUTOMATICALLY invoke when CLAUDE.md exceeds 40k chars. Compacts while preserving critical knowledge."
+model: sonnet
+tools: Read, Write, Edit, Bash, Grep
+---
+
+# Claude MD Compactor Agent
+
+Compact CLAUDE.md when it exceeds 40,000 characters.
+
+## Target Sizes
+
+| Section | Max Size |
+|---------|----------|
+| # Title | 1 line |
+| ## Last Change | 200 chars |
+| ## Overview | 300 chars |
+| ## Stack | 500 chars (table) |
+| ## Architecture | 800 chars (tree) |
+| ## Critical Rules | 2000 chars (bullets) |
+| ## FORBIDDEN | 1000 chars (table) |
+
+## Must Remove
+
+- Verbose explanations → bullet points
+- Code examples > 5 lines → file references
+- Old "Last Change" entries → git has history
+- Duplicate information
+- Commented-out sections
+
+## Must Keep
+
+- Project title, overview, stack table
+- Architecture tree
+- Critical rules (bullets)
+- FORBIDDEN actions table
+- Quality gate commands
+
+## After Compaction
+
+```bash
+wc -m CLAUDE.md  # Must be < 40000
+```