start-vibing-stacks 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# 🎸 Start Vibing Stacks
+
+**Multi-stack AI-powered development workflow for Claude Code.**
+
+One command to set up agents, skills, hooks, and quality gates — tailored to your stack.
+
+## 🚀 Quick Start
+
+```bash
+npx start-vibing-stacks
+```
+
+Or install globally:
+
+```bash
+npm install -g start-vibing-stacks
+svs  # shortcut
+```
+
+## ✨ Features
+
+- **🔍 Auto-detection** — Scans your project files to suggest the right stack
+- **🐘 PHP 8.3+** — PHPStan, PHPUnit, Composer, Laravel/Octane, Symfony, Vanilla
+- **📦 Node.js/TS** — Vitest, TypeScript, Bun, Next.js, Express
+- **🎯 Multi-framework** — Choose your framework, database, frontend, deploy target
+- **🤖 6 Universal Agents** — research, documenter, domain-updater, commit-manager, tester, compactor
+- **🛡️ Quality Gates** — Stack-specific validation before every commit
+- **🔒 Security Skills** — OWASP checks adapted per language
+- **📝 .cursorrules support** — Imports existing Cursor IDE rules
+- **⚡ Auto-install** — Validates and installs missing deps (Homebrew on macOS)
+
+## 📋 Supported Stacks
+
+| Stack | Status | Frameworks |
+|-------|--------|------------|
+| 🐘 PHP 8.3+ | ✅ Ready | Laravel, Laravel+Octane, Symfony, CodeIgniter, Vanilla |
+| 📦 Node.js/TS | ✅ Ready | Next.js, Nuxt, Astro, Express, Fastify |
+| 🐍 Python | 🔜 Soon | Django, FastAPI, Flask |
+| 🦀 Rust | 🔜 Soon | Actix, Axum |
+| 🐹 Go | 🔜 Soon | Gin, Echo |
+
+## 🏗️ What It Creates
+
+```
+.claude/
+├── agents/          # 6 universal agents (stack-aware)
+├── skills/          # Stack-specific + shared skills
+├── hooks/           # stop-validator + prompt-inject
+├── config/          # Project config, quality gates, security rules
+├── commands/        # /feature, /fix, /validate
+└── settings.json    # Claude Code permissions
+```
+
+## 🔧 Options
+
+```bash
+npx start-vibing-stacks [options]
+
+--force           Overwrite existing configuration
+--no-claude       Skip Claude Code installation
+--no-install      Skip dependency installation
+--help, -h        Show help
+--version, -v     Show version
+```
+
+## 🐘 PHP Requirements
+
+When selecting the PHP stack, the tool validates and auto-installs:
+
+- **PHP >= 8.3** (via `brew install php@8.3` on macOS)
+- **Composer >= 2.0** (auto-installed using PHP if missing)
+- **Node.js >= 18** (for frontend tooling)
+
+### Laravel + Octane (RoadRunner)
+
+Select "Laravel + Octane (RoadRunner)" in the framework menu for:
+- RoadRunner server configuration
+- Octane-specific skills and patterns
+- High-performance deployment guides
+
+## 📝 Cursor IDE Support
+
+If `.cursorrules` is detected in your project, the rules are automatically imported into the Claude agent configuration. Both AI tools work with the same context.
+
+## 🔄 How It Works
+
+1. **Detect** — Scans project for `composer.json`, `package.json`, etc.
+2. **Select** — You choose stack, framework, database, frontend, deploy
+3. **Validate** — Checks system requirements, installs missing tools
+4. **Configure** — Copies agents, skills, hooks tailored to your choices
+5. **Launch** — Starts Claude Code with everything pre-configured
+
+## 📄 License
+
+MIT
+
+## 🏠 Credits
+
+Inspired by [start-vibing](https://www.npmjs.com/package/start-vibing).
+Built by [FantasyLake](https://github.com/f1sc4ll-ai).

package/dist/detector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Start Vibing Stacks — Project Detector
+ *
+ * Auto-detects project stack by scanning for known files.
+ * Also detects .cursorrules, CLAUDE.md, and git presence.
+ */
+import type { DetectionResult } from './types.js';
+export declare function detectProject(projectDir: string): DetectionResult;
+/**
+ * Detect framework within a PHP project
+ */
+export declare function detectPhpFramework(projectDir: string): string | null;
+/**
+ * Detect framework within a Node.js project
+ */
+export declare function detectNodeFramework(projectDir: string): string | null;

package/dist/detector.js

@@ -0,0 +1,103 @@
+/**
+ * Start Vibing Stacks — Project Detector
+ *
+ * Auto-detects project stack by scanning for known files.
+ * Also detects .cursorrules, CLAUDE.md, and git presence.
+ */
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+const STACK_SIGNATURES = [
+    // PHP
+    { id: 'php', files: ['composer.json'], weight: 90, reason: 'composer.json detected' },
+    { id: 'php', files: ['index.php'], weight: 60, reason: 'index.php detected' },
+    { id: 'php', files: ['artisan'], weight: 95, reason: 'Laravel artisan detected' },
+    { id: 'php', files: ['symfony.lock'], weight: 95, reason: 'Symfony lock detected' },
+    { id: 'php', files: ['public/index.php'], weight: 70, reason: 'public/index.php detected' },
+    { id: 'php', files: ['.php-version'], weight: 80, reason: '.php-version detected' },
+    // Node.js / TypeScript
+    { id: 'nodejs', files: ['package.json'], weight: 80, reason: 'package.json detected' },
+    { id: 'nodejs', files: ['tsconfig.json'], weight: 85, reason: 'tsconfig.json detected' },
+    { id: 'nodejs', files: ['bun.lockb'], weight: 90, reason: 'Bun lockfile detected' },
+    { id: 'nodejs', files: ['next.config.js'], weight: 95, reason: 'Next.js config detected' },
+    { id: 'nodejs', files: ['next.config.ts'], weight: 95, reason: 'Next.js TS config detected' },
+    { id: 'nodejs', files: ['next.config.mjs'], weight: 95, reason: 'Next.js config detected' },
+    // Python
+    { id: 'python', files: ['requirements.txt'], weight: 80, reason: 'requirements.txt detected' },
+    { id: 'python', files: ['pyproject.toml'], weight: 90, reason: 'pyproject.toml detected' },
+    { id: 'python', files: ['Pipfile'], weight: 85, reason: 'Pipfile detected' },
+    { id: 'python', files: ['setup.py'], weight: 75, reason: 'setup.py detected' },
+    // Rust
+    { id: 'rust', files: ['Cargo.toml'], weight: 95, reason: 'Cargo.toml detected' },
+    // Go
+    { id: 'go', files: ['go.mod'], weight: 95, reason: 'go.mod detected' },
+];
+export function detectProject(projectDir) {
+    const result = {
+        files: [],
+        stacks: [],
+        hasCursorRules: false,
+        hasClaudeMd: false,
+        hasGit: false,
+    };
+    // Scan top-level files
+    try {
+        result.files = readdirSync(projectDir);
+    }
+    catch {
+        return result;
+    }
+    // Check for Cursor IDE rules
+    result.hasCursorRules =
+        existsSync(join(projectDir, '.cursorrules')) ||
+            existsSync(join(projectDir, '.cursor', 'rules'));
+    // Check for existing CLAUDE.md
+    result.hasClaudeMd = existsSync(join(projectDir, 'CLAUDE.md'));
+    // Check for git
+    result.hasGit = existsSync(join(projectDir, '.git'));
+    // Score each stack
+    const stackScores = new Map();
+    for (const sig of STACK_SIGNATURES) {
+        const allExist = sig.files.every((f) => existsSync(join(projectDir, f)));
+        if (allExist) {
+            const existing = stackScores.get(sig.id) || { confidence: 0, reasons: [] };
+            existing.confidence = Math.min(100, existing.confidence + sig.weight);
+            existing.reasons.push(sig.reason);
+            stackScores.set(sig.id, existing);
+        }
+    }
+    // Convert to sorted array
+    result.stacks = Array.from(stackScores.entries())
+        .map(([id, data]) => ({
+        id,
+        confidence: Math.min(100, data.confidence),
+        reason: data.reasons.join(', '),
+    }))
+        .sort((a, b) => b.confidence - a.confidence);
+    return result;
+}
+/**
+ * Detect framework within a PHP project
+ */
+export function detectPhpFramework(projectDir) {
+    if (existsSync(join(projectDir, 'artisan')))
+        return 'laravel';
+    if (existsSync(join(projectDir, 'symfony.lock')))
+        return 'symfony';
+    if (existsSync(join(projectDir, 'spark')))
+        return 'codeigniter';
+    return null;
+}
+/**
+ * Detect framework within a Node.js project
+ */
+export function detectNodeFramework(projectDir) {
+    if (existsSync(join(projectDir, 'next.config.js')) ||
+        existsSync(join(projectDir, 'next.config.ts')) ||
+        existsSync(join(projectDir, 'next.config.mjs')))
+        return 'nextjs';
+    if (existsSync(join(projectDir, 'nuxt.config.ts')))
+        return 'nuxt';
+    if (existsSync(join(projectDir, 'astro.config.mjs')))
+        return 'astro';
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Start Vibing Stacks — CLI Entry Point
+ *
+ * Multi-stack AI-powered development workflow for Claude Code.
+ * Detects project stack, validates requirements, and configures agents.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Start Vibing Stacks — CLI Entry Point
+ *
+ * Multi-stack AI-powered development workflow for Claude Code.
+ * Detects project stack, validates requirements, and configures agents.
+ */
+import { basename } from 'path';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import * as ui from './ui.js';
+import { detectProject, detectPhpFramework, detectNodeFramework } from './detector.js';
+import { autoInstall, installComposer, installClaudeCode } from './installer.js';
+import { loadStackConfig, setupProject } from './setup.js';
+// =============================================================================
+// CLI Arguments
+// =============================================================================
+const args = process.argv.slice(2);
+const FLAGS = {
+    force: args.includes('--force'),
+    noClaude: args.includes('--no-claude'),
+    noInstall: args.includes('--no-install'),
+    help: args.includes('--help') || args.includes('-h'),
+    version: args.includes('--version') || args.includes('-v'),
+};
+if (FLAGS.version) {
+    console.log('1.0.0');
+    process.exit(0);
+}
+if (FLAGS.help) {
+    console.log(ui.LOGO);
+    console.log(`
+  ${chalk.bold('Usage:')}
+    npx start-vibing-stacks [options]
+
+  ${chalk.bold('Options:')}
+    --force           Overwrite existing configuration
+    --no-claude       Skip Claude Code installation
+    --no-install      Skip dependency installation
+    --help, -h        Show this help
+    --version, -v     Show version
+
+  ${chalk.bold('Supported Stacks:')}
+    🐘 PHP 8.3+       Laravel, Symfony, CodeIgniter, Vanilla
+    📦 Node.js/TS     Next.js, Nuxt, Express, Fastify
+    🐍 Python         Django, FastAPI, Flask (coming soon)
+    🦀 Rust           (coming soon)
+    🐹 Go             (coming soon)
+  `);
+    process.exit(0);
+}
+const AVAILABLE_STACKS = [
+    { id: 'php', name: 'PHP 8.3+', icon: '🐘', available: true },
+    { id: 'nodejs', name: 'Node.js / TypeScript', icon: '📦', available: true },
+    { id: 'python', name: 'Python', icon: '🐍', available: false },
+    { id: 'rust', name: 'Rust', icon: '🦀', available: false },
+    { id: 'go', name: 'Go', icon: '🐹', available: false },
+];
+// =============================================================================
+// Main Flow
+// =============================================================================
+async function main() {
+    console.log(ui.LOGO);
+    const projectDir = process.cwd();
+    const projectName = basename(projectDir);
+    // ─── Step 1: Detect Project ─────────────────────────────────────────────
+    ui.header('🔍 Scanning project directory...');
+    const detection = detectProject(projectDir);
+    if (detection.hasCursorRules) {
+        ui.info('.cursorrules detected — will import into Claude config');
+    }
+    if (detection.hasClaudeMd) {
+        ui.info('Existing CLAUDE.md found — will merge with template');
+    }
+    if (!detection.hasGit) {
+        ui.warn('No .git found — recommend initializing git first');
+    }
+    if (detection.stacks.length > 0) {
+        const topStack = detection.stacks[0];
+        console.log('');
+        ui.success(`Detected: ${topStack.id.toUpperCase()} (${topStack.confidence}% confidence)`);
+        ui.info(`Reason: ${topStack.reason}`);
+    }
+    // ─── Step 2: Select Stack ───────────────────────────────────────────────
+    console.log('');
+    const { stackId } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'stackId',
+            message: 'Select your primary stack:',
+            default: detection.stacks.length > 0 ? detection.stacks[0].id : undefined,
+            choices: AVAILABLE_STACKS.map((s) => ({
+                name: `${s.icon}  ${s.name}${!s.available ? chalk.dim(' (coming soon)') : ''}`,
+                value: s.id,
+                disabled: !s.available ? 'Coming soon' : false,
+            })),
+        },
+    ]);
+    const stackConfig = loadStackConfig(stackId);
+    if (!stackConfig) {
+        ui.error(`Stack config not found for: ${stackId}`);
+        process.exit(1);
+    }
+    // ─── Step 3: Select Framework ──────────────────────────────────────────
+    const detectedFramework = stackId === 'php'
+        ? detectPhpFramework(projectDir)
+        : stackId === 'nodejs'
+            ? detectNodeFramework(projectDir)
+            : null;
+    const { framework } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'framework',
+            message: 'Select framework:',
+            default: detectedFramework || undefined,
+            choices: stackConfig.frameworks.map((f) => ({
+                name: `${f.icon}  ${f.name}`,
+                value: f.id,
+            })),
+        },
+    ]);
+    // ─── Step 4: Select Database ───────────────────────────────────────────
+    const { database } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'database',
+            message: 'Select database:',
+            choices: stackConfig.databases.map((d) => ({
+                name: `${d.icon}  ${d.name}`,
+                value: d.id,
+            })),
+        },
+    ]);
+    // ─── Step 5: Frontend ──────────────────────────────────────────────────
+    const { frontend } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'frontend',
+            message: 'Frontend included?',
+            choices: stackConfig.frontendOptions.map((f) => ({
+                name: `${f.icon}  ${f.name}`,
+                value: f.id,
+            })),
+        },
+    ]);
+    // ─── Step 6: Deploy Target ─────────────────────────────────────────────
+    const { deploy } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'deploy',
+            message: 'Deployment target?',
+            choices: stackConfig.deployTargets.map((d) => ({
+                name: `${d.icon}  ${d.name}`,
+                value: d.id,
+            })),
+        },
+    ]);
+    // ─── Step 7: Show Summary & Confirm ────────────────────────────────────
+    const config = {
+        name: projectName,
+        stack: stackId,
+        framework,
+        database,
+        frontend,
+        deploy,
+        path: projectDir,
+        createdAt: new Date().toISOString(),
+        skills: [...stackConfig.skills],
+        qualityGates: `stacks/${stackId}/config/quality-gates.json`,
+        cursorRules: detection.hasCursorRules,
+        domains: {},
+    };
+    ui.configSummary({
+        'Stack': `${stackConfig.icon}  ${stackConfig.name} (${stackConfig.runtime})`,
+        'Framework': framework,
+        'Database': database,
+        'Frontend': frontend,
+        'Deploy': deploy,
+        'Agents': '6 universal',
+        'Skills': `${stackConfig.skills.length} stack + shared`,
+        'Hooks': 'stop-validator + prompt-inject',
+        'Gates': stackConfig.qualityGates.map((g) => g.name).join(' → '),
+    });
+    const { confirmed } = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'confirmed',
+            message: 'Confirm configuration?',
+            default: true,
+        },
+    ]);
+    if (!confirmed) {
+        ui.info('Setup cancelled.');
+        process.exit(0);
+    }
+    // ─── Step 8: Validate & Install Requirements ──────────────────────────
+    if (!FLAGS.noInstall) {
+        const reqOk = await autoInstall(stackConfig.requirements);
+        if (!reqOk) {
+            ui.error('Some requirements could not be installed. Fix manually and retry.');
+            process.exit(1);
+        }
+        // PHP-specific: install Composer
+        if (stackId === 'php') {
+            const composerOk = await installComposer();
+            if (!composerOk) {
+                ui.warn('Composer installation failed — you may need to install it manually');
+            }
+        }
+    }
+    // ─── Step 9: Setup Project ─────────────────────────────────────────────
+    ui.header('⚡ Configuring project...');
+    const setupOk = await setupProject(projectDir, config, {
+        force: FLAGS.force,
+        noClaude: FLAGS.noClaude,
+    });
+    if (!setupOk) {
+        ui.error('Setup failed.');
+        process.exit(1);
+    }
+    // ─── Step 10: Install Claude Code ──────────────────────────────────────
+    if (!FLAGS.noClaude) {
+        console.log('');
+        installClaudeCode();
+    }
+    // ─── Done ──────────────────────────────────────────────────────────────
+    console.log('');
+    console.log(chalk.green.bold('  🎸 Ready to vibe!'));
+    console.log('');
+    if (!FLAGS.noClaude) {
+        console.log(chalk.dim('  Launching Claude Code...'));
+        console.log(chalk.dim('  Run: claude --dangerously-skip-permissions'));
+    }
+    console.log('');
+}
+main().catch((err) => {
+    ui.error(`Unexpected error: ${err}`);
+    process.exit(1);
+});

package/dist/installer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Start Vibing Stacks — Dependency Installer & Validator
+ *
+ * Validates system requirements and auto-installs missing dependencies.
+ * macOS-first with Homebrew, with Linux fallbacks.
+ */
+import type { Requirement } from './types.js';
+export interface ValidationResult {
+    name: string;
+    installed: boolean;
+    version: string | null;
+    meetsMinimum: boolean;
+    minVersion: string;
+}
+/**
+ * Validate all requirements for a stack
+ */
+export declare function validateRequirements(requirements: Requirement[]): ValidationResult[];
+/**
+ * Auto-install missing or outdated requirements
+ */
+export declare function autoInstall(requirements: Requirement[]): Promise<boolean>;
+/**
+ * Install Composer using PHP 8.3+
+ */
+export declare function installComposer(): Promise<boolean>;
+/**
+ * Install Claude Code if not present
+ */
+export declare function installClaudeCode(): boolean;