@l4yercak3/cli 1.0.0

package/docs/DETECTOR_ARCHITECTURE.md

@@ -0,0 +1,326 @@
+# Project Detector Architecture
+
+## Overview
+
+The CLI uses a **plugin-based detector system** that can identify different project types (Next.js, React, Vue, Svelte, etc.) and generate appropriate boilerplate for each.
+
+## Design Principles
+
+1. **Extensibility**: Easy to add new project types without modifying core code
+2. **Separation of Concerns**: Detectors detect, generators generate
+3. **Type Safety**: Each project type has its own detector and generator
+4. **Graceful Degradation**: CLI works even if project type isn't fully supported
+
+---
+
+## Architecture
+
+### 1. Base Detector Interface
+
+All project detectors implement a common interface:
+
+```javascript
+{
+  name: string,              // e.g., "nextjs", "react", "vue"
+  priority: number,          // Detection priority (higher = checked first)
+  detect(projectPath): {
+    detected: boolean,       // Is this project type?
+    confidence: number,      // 0-1, how confident are we?
+    metadata: object,        // Type-specific metadata
+  }
+}
+```
+
+### 2. Detector Registry
+
+Detectors are registered in a central registry:
+
+```javascript
+// src/detectors/registry.js
+const detectors = [
+  require('./nextjs-detector'),
+  require('./react-detector'),      // Future
+  require('./vue-detector'),        // Future
+  // ... more detectors
+];
+```
+
+### 3. Detection Flow
+
+```
+1. User runs `l4yercak3 spread`
+2. CLI scans project directory
+3. Runs all detectors (sorted by priority)
+4. First detector with confidence > 0.8 wins
+5. If no match, prompt user to select type
+6. Use matched detector's metadata for generation
+```
+
+### 4. Generator Mapping
+
+Each project type maps to specific generators:
+
+```javascript
+{
+  nextjs: {
+    generators: ['api-client', 'nextauth', 'env'],
+    supportedFeatures: ['oauth', 'stripe', 'crm', 'projects', 'invoices']
+  },
+  react: {
+    generators: ['api-client', 'env'],
+    supportedFeatures: ['oauth', 'crm', 'projects']  // No NextAuth
+  },
+  vue: {
+    generators: ['api-client', 'env'],
+    supportedFeatures: ['oauth', 'crm', 'projects']
+  }
+}
+```
+
+---
+
+## Current Implementation (MVP)
+
+### Phase 1: Next.js Only
+
+- ✅ `nextjs-detector.js` - Detects Next.js projects
+- ✅ `github-detector.js` - Detects Git/GitHub (framework-agnostic)
+- ✅ `api-client-detector.js` - Detects existing API clients (framework-agnostic)
+
+**Current Flow:**
+- If Next.js detected → Full feature support
+- If not Next.js → Warn user, but still allow basic setup
+
+### Future: Multi-Framework Support
+
+When adding new frameworks:
+
+1. **Create Detector** (`src/detectors/react-detector.js`)
+   ```javascript
+   class ReactDetector {
+     name = 'react';
+     priority = 50;  // Lower than Next.js (100)
+     
+     detect(projectPath) {
+       // Check for React-specific files
+       return {
+         detected: hasReact,
+         confidence: 0.9,
+         metadata: { version, hasTypeScript, ... }
+       };
+     }
+   }
+   ```
+
+2. **Register Detector** (`src/detectors/registry.js`)
+   ```javascript
+   const detectors = [
+     require('./nextjs-detector'),
+     require('./react-detector'),  // Add here
+   ];
+   ```
+
+3. **Create Generators** (if needed)
+   - React might need different OAuth setup (no NextAuth)
+   - React might need different file structure
+   - API client generator can be shared
+
+4. **Update Feature Matrix** (`src/generators/feature-matrix.js`)
+   ```javascript
+   {
+     react: {
+       oauth: 'manual',  // No NextAuth, manual setup
+       stripe: 'full',
+       crm: 'full',
+     }
+   }
+   ```
+
+---
+
+## Detector Interface Specification
+
+### Required Methods
+
+```javascript
+class BaseDetector {
+  /**
+   * Unique identifier for this project type
+   */
+  get name() {
+    return 'project-type';
+  }
+
+  /**
+   * Detection priority (higher = checked first)
+   * Range: 0-100
+   */
+  get priority() {
+    return 50;
+  }
+
+  /**
+   * Detect if project matches this type
+   * @param {string} projectPath - Path to project directory
+   * @returns {object} Detection result
+   */
+  detect(projectPath) {
+    return {
+      detected: boolean,      // Is this the project type?
+      confidence: number,      // 0-1, how sure are we?
+      metadata: {             // Type-specific info
+        version: string,
+        hasTypeScript: boolean,
+        // ... more metadata
+      }
+    };
+  }
+
+  /**
+   * Get supported features for this project type
+   * @returns {object} Feature support matrix
+   */
+  getSupportedFeatures() {
+    return {
+      oauth: boolean | 'manual',  // true = full support, 'manual' = guide only, false = not supported
+      stripe: boolean,
+      crm: boolean,
+      projects: boolean,
+      invoices: boolean,
+    };
+  }
+
+  /**
+   * Get available generators for this project type
+   * @returns {string[]} List of generator names
+   */
+  getAvailableGenerators() {
+    return ['api-client', 'env'];
+  }
+}
+```
+
+---
+
+## Generator Interface Specification
+
+Generators are framework-agnostic where possible, but can be framework-specific when needed.
+
+### Shared Generators (Work for all frameworks)
+
+- `api-client-generator.js` - Generates API client (framework-agnostic)
+- `env-generator.js` - Generates `.env.local.example` (framework-agnostic)
+
+### Framework-Specific Generators
+
+- `nextauth-generator.js` - Next.js only (NextAuth.js)
+- `react-auth-generator.js` - React only (manual OAuth)
+- `vue-auth-generator.js` - Vue only (manual OAuth)
+
+---
+
+## Detection Priority System
+
+Detectors run in priority order. First match wins (if confidence > 0.8).
+
+**Priority Levels:**
+- **100**: Very specific frameworks (Next.js, Nuxt, SvelteKit)
+- **75**: Framework with build tool (Vite + React, Webpack + Vue)
+- **50**: Pure frameworks (React, Vue, Svelte)
+- **25**: Generic JavaScript/TypeScript projects
+
+**Example:**
+```
+Next.js (100) → Detected first
+React + Vite (75) → Only checked if Next.js not detected
+React (50) → Only checked if above not detected
+Generic JS (25) → Fallback
+```
+
+---
+
+## Adding a New Project Type
+
+### Step-by-Step Guide
+
+1. **Create Detector** (`src/detectors/myframework-detector.js`)
+   ```javascript
+   const BaseDetector = require('./base-detector');
+   
+   class MyFrameworkDetector extends BaseDetector {
+     get name() { return 'myframework'; }
+     get priority() { return 50; }
+     
+     detect(projectPath) {
+       // Detection logic
+       return {
+         detected: true,
+         confidence: 0.9,
+         metadata: { version: '1.0.0' }
+       };
+     }
+     
+     getSupportedFeatures() {
+       return {
+         oauth: 'manual',
+         stripe: true,
+         crm: true,
+         projects: true,
+         invoices: false,
+       };
+     }
+   }
+   
+   module.exports = new MyFrameworkDetector();
+   ```
+
+2. **Register Detector** (`src/detectors/registry.js`)
+   ```javascript
+   const detectors = [
+     require('./nextjs-detector'),
+     require('./myframework-detector'),  // Add here
+   ];
+   ```
+
+3. **Create Generators** (if needed)
+   - Check if existing generators work
+   - Create framework-specific generators if needed
+
+4. **Test**
+   - Run `l4yercak3 spread` in a MyFramework project
+   - Verify detection works
+   - Verify generation works
+
+---
+
+## Current Status
+
+### ✅ Implemented (Phase 1)
+- Next.js detector (full support)
+- GitHub detector (framework-agnostic)
+- API client detector (framework-agnostic)
+- Basic registry system
+
+### 🚧 Future (Phase 4+)
+- React detector
+- Vue detector
+- Svelte detector
+- Generic JavaScript/TypeScript detector
+- Framework-specific generators
+
+---
+
+## Benefits of This Architecture
+
+1. **Easy to Extend**: Add new detectors without touching core code
+2. **Type Safety**: Each framework has its own detection logic
+3. **Feature Gating**: Can disable features per framework
+4. **Graceful Degradation**: Works even if framework not fully supported
+5. **Maintainable**: Clear separation between detection and generation
+
+---
+
+**Last Updated:** 2025-01-14  
+**Status:** Phase 1 (Next.js only)  
+**Next:** Ready for multi-framework support when needed
+

package/docs/DEVELOPMENT.md

@@ -0,0 +1,194 @@
+# Development Guide
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Run the CLI locally
+npm start
+
+# Or link globally for testing
+npm link
+l4yercak3
+```
+
+## Development Standards
+
+### Quality Checks
+
+Before committing, always run:
+
+```bash
+npm run verify
+```
+
+This runs:
+- ✅ Linting (`npm run lint`)
+- ✅ Type checking (`npm run type-check`)
+- ✅ Build verification (`npm run build`)
+
+### Individual Commands
+
+```bash
+# Lint code
+npm run lint
+
+# Fix linting issues automatically
+npm run lint:fix
+
+# Check types
+npm run type-check
+
+# Verify build
+npm run build
+```
+
+## Project Structure
+
+```
+l4yercak3-cli/
+├── .cursor/
+│   └── rules.md              # Development rules for Cursor AI
+├── bin/
+│   └── cli.js                # CLI entry point
+├── src/
+│   └── logo.js               # Logo display module
+├── .eslintrc.js              # ESLint configuration
+├── .gitignore                # Git ignore rules
+├── package.json              # Package configuration
+├── PLAN.md                   # Strategic plan document
+├── README.md                 # User documentation
+└── DEVELOPMENT.md            # This file
+```
+
+## Adding New Features
+
+### 1. Create Feature Branch
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 2. Implement Feature
+- Follow code standards in `.cursor/rules.md`
+- Add JSDoc comments
+- Keep functions small and focused
+
+### 3. Test Locally
+```bash
+npm link
+# Test in a real project
+cd ~/Development/test-project
+l4yercak3 your-command
+```
+
+### 4. Run Quality Checks
+```bash
+npm run verify
+```
+
+### 5. Commit and Push
+```bash
+git add .
+git commit -m "feat: add your feature"
+git push origin feature/your-feature-name
+```
+
+## Code Style
+
+### JavaScript/Node.js
+- Use CommonJS (`require`/`module.exports`)
+- Use async/await for async operations
+- Handle errors with try/catch
+- Use meaningful variable names
+
+### Example
+```javascript
+const chalk = require('chalk');
+
+async function doSomething() {
+  try {
+    console.log(chalk.green('Success!'));
+  } catch (error) {
+    console.error(chalk.red('Error:'), error.message);
+  }
+}
+```
+
+## Testing
+
+### Manual Testing
+1. Link package: `npm link`
+2. Test in example project
+3. Verify all features work
+4. Check error handling
+
+### Example Projects
+- `~/Development/l4yercak3-landing`
+- `~/Development/freelancer-client-portal`
+
+## Publishing
+
+### Before Publishing
+1. Update version in `package.json`
+2. Update CHANGELOG.md (if exists)
+3. Run `npm run verify`
+4. Test installation: `npm pack` then `npm install -g *.tgz`
+
+### Publishing Steps
+```bash
+# Login to npm (if needed)
+npm login
+
+# Publish
+npm publish --access public
+```
+
+### Version Management
+```bash
+# Patch version (1.0.0 → 1.0.1)
+npm version patch
+
+# Minor version (1.0.0 → 1.1.0)
+npm version minor
+
+# Major version (1.0.0 → 2.0.0)
+npm version major
+```
+
+## Troubleshooting
+
+### Command Not Found After `npm link`
+```bash
+# Check executable permissions
+chmod +x bin/cli.js
+
+# Verify npm bin path
+npm bin -g
+
+# Try unlinking and relinking
+npm unlink
+npm link
+```
+
+### Linting Errors
+```bash
+# Auto-fix what can be fixed
+npm run lint:fix
+
+# Check specific file
+npx eslint bin/cli.js
+```
+
+### Build Errors
+- Check Node.js version: `node --version` (should be >=14)
+- Verify package.json structure
+- Check for syntax errors
+
+## Resources
+
+- [Plan Document](./PLAN.md) - Strategic plan and roadmap
+- [Development Rules](./.cursor/rules.md) - Detailed coding standards
+- [README](./README.md) - User documentation
+