@l4yercak3/cli 1.0.0

package/docs/OAUTH_CLARIFICATION.md

@@ -0,0 +1,258 @@
+# OAuth Automation & CLI Onboarding - Clarification
+
+## Two Different OAuth Systems
+
+### 1. **Backend OAuth (Platform OAuth)** ✅ Already Exists
+**Purpose:** Platform administrators/staff connecting their Microsoft/Google accounts to the backend
+- **Use Case:** Staff members sync their Microsoft 365 account to send emails, access calendars, etc.
+- **Storage:** `users` table + `oauthConnections` table
+- **Handler:** Convex backend (`convex/oauth/microsoft.ts`)
+- **Status:** ✅ Fully implemented
+
+**This is NOT what we're automating with the CLI.**
+
+---
+
+### 2. **Frontend OAuth (Customer OAuth)** 🎯 What We're Automating
+**Purpose:** End users (customers/freelancers) logging into FRONTEND applications
+- **Use Case:** Freelancers log into the freelancer portal with Google/Microsoft
+- **Storage:** `objects` table with `type: "frontend_user"`
+- **Handler:** NextAuth.js on the frontend + Backend sync endpoint
+- **Status:** Backend ready, frontend needs OAuth app setup
+
+**This IS what we want to automate with the CLI.**
+
+---
+
+## The OAuth App Setup Problem
+
+When a developer wants to add OAuth login to their frontend app, they currently need to:
+
+1. **Go to Google Cloud Console**
+   - Create OAuth client ID
+   - Configure redirect URIs
+   - Copy Client ID and Secret
+
+2. **Go to Microsoft Azure Portal**
+   - Register application
+   - Configure redirect URIs
+   - Create client secret
+   - Copy Client ID, Secret, and Tenant ID
+
+3. **Add to `.env.local`**
+   ```bash
+   GOOGLE_CLIENT_ID=...
+   GOOGLE_CLIENT_SECRET=...
+   AZURE_CLIENT_ID=...
+   AZURE_CLIENT_SECRET=...
+   ```
+
+**This is manual, tedious, and error-prone.**
+
+---
+
+## OAuth Automation Goal
+
+**Automate steps 1-2 above** by using provider APIs to create OAuth apps programmatically.
+
+### What We Can Automate
+
+#### Google OAuth
+- **API:** Google Cloud API
+- **Can Create:** OAuth client IDs programmatically
+- **Requires:** Google Cloud project access (user grants permission)
+- **Result:** Client ID and Secret automatically generated
+
+#### Microsoft OAuth
+- **API:** Microsoft Graph API / Azure AD API
+- **Can Create:** App registrations programmatically
+- **Requires:** Azure AD admin access (user grants permission)
+- **Result:** Client ID, Secret, Tenant ID automatically generated
+
+#### GitHub OAuth
+- **API:** GitHub API
+- **Can Create:** OAuth apps programmatically
+- **Requires:** GitHub account access
+- **Result:** Client ID and Secret automatically generated
+
+### What We Still Need User Input For
+
+- **User's Google Cloud Project** (or create one)
+- **User's Azure AD Tenant** (or use default)
+- **User's GitHub Account** (for GitHub OAuth)
+- **Permission to create OAuth apps** (one-time grant)
+
+---
+
+## CLI-Based Onboarding Flow
+
+### Complete Onboarding via CLI 🚀
+
+```
+1. Developer runs: npx @l4yercak3/cli spread
+   ↓
+2. CLI asks: "Do you have an account?"
+   - [ ] Yes, I'll log in
+   - [ ] No, create one for me
+   ↓
+3. If "No":
+   - CLI asks for email, name, organization name
+   - CLI calls backend: POST /api/v1/auth/create-account
+   - Backend creates:
+     - User account
+     - Organization
+     - Initial API key
+   - CLI stores session token
+   ↓
+4. CLI asks: "What features do you want?"
+   - [ ] CRM Integration
+   - [ ] OAuth Login (Google/Microsoft)
+   - [ ] Project Management
+   - [ ] Invoicing
+   ↓
+5. If OAuth selected:
+   - CLI asks: "Which providers?"
+     - [ ] Google
+     - [ ] Microsoft
+     - [ ] GitHub
+   - CLI opens browser for OAuth app creation
+   - User grants permission once
+   - CLI creates OAuth apps automatically
+   - CLI stores credentials securely
+   ↓
+6. CLI generates:
+   - API client code
+   - Environment files (with OAuth credentials pre-filled!)
+   - NextAuth.js configuration
+   - Type definitions
+   ↓
+7. Integration complete! 🎉
+```
+
+---
+
+## Schema Endpoint Security Clarification
+
+### What a Schema Endpoint Would Return
+
+**NOT database access!** Just API structure/types:
+
+```json
+{
+  "endpoints": {
+    "/api/v1/crm/contacts": {
+      "method": "POST",
+      "request": {
+        "type": "object",
+        "properties": {
+          "firstName": { "type": "string" },
+          "lastName": { "type": "string" },
+          "email": { "type": "string" }
+        }
+      },
+      "response": {
+        "type": "object",
+        "properties": {
+          "_id": { "type": "string" },
+          "name": { "type": "string" },
+          "email": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+**This is just documentation/structure** - no actual data, no database access.
+
+### Security Considerations
+
+1. **Authentication Required:** Schema endpoint should require API key or session
+2. **Read-Only:** Only returns API structure, never actual data
+3. **Rate Limited:** Prevent abuse
+4. **Scoped:** Only show endpoints user has access to
+
+**It's like an OpenAPI spec** - just describes the API, doesn't access the database.
+
+---
+
+## Updated CLI Onboarding Features
+
+### Account Creation via CLI
+
+```bash
+npx @l4yercak3/cli spread
+
+# If no account:
+? Create new account? (y/n) y
+? Email: user@example.com
+? Name: John Doe
+? Organization Name: Acme Corp
+✅ Account created! Organization ID: org_123
+✅ API key generated: l4y_abc123...
+```
+
+**Backend Endpoint Needed:**
+```typescript
+POST /api/v1/auth/create-account
+Body: {
+  email: string;
+  name: string;
+  organizationName: string;
+}
+Response: {
+  userId: string;
+  organizationId: string;
+  apiKey: string;
+  sessionToken: string;
+}
+```
+
+### OAuth App Creation via CLI
+
+```bash
+? Enable OAuth login? (y/n) y
+? Which providers? [Google, Microsoft]
+? Grant permission to create OAuth apps? (opens browser)
+✅ Google OAuth app created!
+   Client ID: 123456.apps.googleusercontent.com
+   Client Secret: GOCSPX-abc123...
+✅ Microsoft OAuth app created!
+   Client ID: abcd-1234-...
+   Client Secret: xyz~ABC...
+✅ Credentials saved to .env.local
+```
+
+**This requires:**
+1. User grants CLI permission to create OAuth apps (one-time)
+2. CLI uses provider APIs to create apps
+3. CLI stores credentials securely
+
+---
+
+## Summary
+
+### What We're Automating
+
+1. ✅ **Account Creation** - Create user account + organization via CLI
+2. ✅ **API Key Generation** - Generate API keys automatically
+3. ✅ **OAuth App Creation** - Create OAuth apps with Google/Microsoft/GitHub APIs
+4. ✅ **Environment Setup** - Generate `.env.local` with all credentials
+5. ✅ **Code Generation** - Generate API client, NextAuth config, types
+
+### What We're NOT Automating
+
+- ❌ Backend OAuth (platform OAuth) - that's separate
+- ❌ Database access - schema endpoint is read-only API structure
+- ❌ User's provider accounts - they still need Google/Microsoft/GitHub accounts
+
+### Security Notes
+
+- **Schema Endpoint:** Read-only API structure, requires auth, no database access
+- **OAuth Automation:** Requires user permission, one-time grant
+- **Account Creation:** Secure endpoint, creates proper user/org structure
+
+---
+
+**The goal:** Make onboarding as smooth as possible, with UI as fallback if CLI fails or user gets stuck.
+

package/docs/OAUTH_SETUP_GUIDE_TEMPLATE.md

@@ -0,0 +1,211 @@
+# OAuth Setup Guide - Template
+
+This is a template for the OAuth setup guide that the CLI will generate. It will be customized based on the user's provider choices.
+
+---
+
+# 🔐 OAuth Authentication Setup Guide
+
+## Overview
+
+This guide will walk you through setting up OAuth authentication for your frontend application. You'll need to create OAuth apps with each provider and add the credentials to your `.env.local` file.
+
+**Estimated Time:** 15-20 minutes per provider
+
+---
+
+## ✅ Setup Checklist
+
+- [ ] Google OAuth setup
+- [ ] Microsoft OAuth setup  
+- [ ] GitHub OAuth setup (if selected)
+
+---
+
+## 1. Google OAuth Setup
+
+### Step 1: Go to Google Cloud Console
+
+1. Navigate to: https://console.cloud.google.com/
+2. Select your project or create a new one
+
+### Step 2: Enable Google+ API
+
+1. Go to "APIs & Services" → "Enable APIs and Services"
+2. Search for "Google+ API" and enable it
+
+### Step 3: Create OAuth Client ID
+
+1. Go to "APIs & Services" → "Credentials"
+2. Click "Create Credentials" → "OAuth client ID"
+3. Application type: **Web application**
+4. Name: `{{APP_NAME}} - Frontend`
+
+### Step 4: Configure Redirect URIs
+
+Add these redirect URIs:
+
+**Production:**
+```
+https://{{PRODUCTION_DOMAIN}}/api/auth/callback/google
+```
+
+**Development:**
+```
+http://localhost:3000/api/auth/callback/google
+```
+
+### Step 5: Save Credentials
+
+1. Copy the **Client ID** and **Client Secret**
+2. Add them to your `.env.local` file (see below)
+
+---
+
+## 2. Microsoft Entra ID (Azure AD) Setup
+
+### Step 1: Go to Azure Portal
+
+1. Navigate to: https://portal.azure.com/
+2. Go to "Microsoft Entra ID" (formerly Azure AD)
+
+### Step 2: Register Application
+
+1. Go to "App registrations" → "New registration"
+2. Name: `{{APP_NAME}} - Frontend`
+3. Supported account types: Choose based on your needs
+4. Redirect URI: **Web**
+
+### Step 3: Configure Redirect URIs
+
+Add these redirect URIs:
+
+**Production:**
+```
+https://{{PRODUCTION_DOMAIN}}/api/auth/callback/azure-ad
+```
+
+**Development:**
+```
+http://localhost:3000/api/auth/callback/azure-ad
+```
+
+### Step 4: Create Client Secret
+
+1. Go to "Certificates & secrets" → "New client secret"
+2. Description: `Frontend OAuth Secret`
+3. Expires: Choose expiration (recommend 24 months)
+4. Copy the **Value** (not the Secret ID) - you won't see it again!
+
+### Step 5: Save Credentials
+
+1. Copy the **Application (client) ID**, **Directory (tenant) ID**, and **Client Secret Value**
+2. Add them to your `.env.local` file (see below)
+
+---
+
+## 3. GitHub OAuth Setup
+
+### Step 1: Go to GitHub Developer Settings
+
+1. Navigate to: https://github.com/settings/developers
+2. Click "New OAuth App"
+
+### Step 2: Create OAuth App
+
+1. **Application name:** `{{APP_NAME}} - Frontend`
+2. **Homepage URL:** `https://{{PRODUCTION_DOMAIN}}`
+3. **Authorization callback URL:**
+   ```
+   https://{{PRODUCTION_DOMAIN}}/api/auth/callback/github
+   ```
+
+### Step 3: Save Credentials
+
+1. Copy the **Client ID**
+2. Click "Generate a new client secret"
+3. Copy the **Client Secret** (you won't see it again!)
+4. Add them to your `.env.local` file (see below)
+
+---
+
+## 4. Update Environment Variables
+
+Add these to your `.env.local` file:
+
+```bash
+# Google OAuth
+GOOGLE_CLIENT_ID=your_google_client_id_here
+GOOGLE_CLIENT_SECRET=your_google_client_secret_here
+
+# Microsoft OAuth
+AZURE_CLIENT_ID=your_azure_client_id_here
+AZURE_CLIENT_SECRET=your_azure_client_secret_value_here
+AZURE_TENANT_ID=your_azure_tenant_id_here
+
+# GitHub OAuth (if using)
+GITHUB_CLIENT_ID=your_github_client_id_here
+GITHUB_CLIENT_SECRET=your_github_client_secret_here
+```
+
+**⚠️ Important:** Never commit `.env.local` to git! It's already in `.gitignore`.
+
+---
+
+## 5. Test Your Setup
+
+1. Start your development server: `npm run dev`
+2. Navigate to: `http://localhost:3000/auth/signin`
+3. Try signing in with each provider
+4. Verify that users are created in your backend
+
+---
+
+## Troubleshooting
+
+### Redirect URI Mismatch
+
+**Error:** "Redirect URI mismatch"
+
+**Solution:** Make sure the redirect URI in your OAuth app matches exactly:
+- Check for trailing slashes
+- Check http vs https
+- Check localhost vs 127.0.0.1
+
+### Invalid Client Secret
+
+**Error:** "Invalid client secret"
+
+**Solution:** 
+- Make sure you copied the **Value** (not Secret ID) for Azure
+- Regenerate the secret if needed
+- Restart your dev server after updating `.env.local`
+
+### Provider Not Found
+
+**Error:** "Provider not found"
+
+**Solution:**
+- Check that the provider is configured in `app/api/auth/[...nextauth]/route.ts`
+- Verify environment variables are set correctly
+
+---
+
+## Next Steps
+
+Once OAuth is set up:
+1. ✅ Users can sign in with their Google/Microsoft/GitHub accounts
+2. ✅ User accounts are automatically created in your backend
+3. ✅ Users are linked to CRM contacts
+4. ✅ You can use protected routes and API calls
+
+---
+
+## Video Tutorial
+
+📹 **Coming Soon:** Step-by-step video tutorial for OAuth setup
+
+---
+
+**Need Help?** Check the [L4YERCAK3 Documentation](https://docs.l4yercak3.com) or contact support.
+

package/docs/PHASE_0_PROGRESS.md

@@ -0,0 +1,120 @@
+# Phase 0 Implementation Progress
+
+## ✅ Completed
+
+### Project Structure
+- [x] Created directory structure:
+  - `src/commands/` - CLI commands
+  - `src/config/` - Configuration management
+  - `src/api/` - Backend API client
+  - `src/detectors/` - Project detection (ready for Phase 1)
+  - `src/generators/` - Code generators (ready for Phase 1)
+
+### Configuration Management
+- [x] `ConfigManager` class (`src/config/config-manager.js`)
+  - Stores session in `~/.l4yercak3/config.json`
+  - Handles session validation and expiration
+  - Manages organizations and settings
+  - Secure file permissions (0o600)
+
+### Backend API Client
+- [x] `BackendClient` class (`src/api/backend-client.js`)
+  - Handles API requests with authentication
+  - Session validation and refresh
+  - Organization management methods
+  - API key generation (ready for backend integration)
+
+### CLI Commands
+- [x] `login` command (`src/commands/login.js`)
+  - Opens browser for OAuth flow
+  - Starts local callback server (port 3001)
+  - Receives and stores session token
+  - Validates session with backend
+
+- [x] `logout` command (`src/commands/logout.js`)
+  - Clears session from config
+
+- [x] `auth status` command (`src/commands/status.js`)
+  - Shows authentication status
+  - Displays session info and expiration
+  - Validates session with backend
+
+- [x] `spread` command (`src/commands/spread.js`)
+  - Placeholder for Phase 1 implementation
+  - Checks authentication before proceeding
+
+### CLI Framework
+- [x] Integrated `commander` for command parsing
+- [x] Integrated `open` for browser opening
+- [x] Integrated `node-fetch` for API calls
+- [x] Updated main CLI entry point (`bin/cli.js`)
+
+## 🚧 In Progress / Pending
+
+### Backend Endpoints Needed
+- [ ] `GET /auth/cli-login` - Initiate CLI OAuth flow
+- [ ] `GET /auth/cli/callback` - Handle OAuth callback, return CLI session token
+- [ ] `GET /api/v1/auth/cli/validate` - Validate CLI session
+- [ ] `POST /api/v1/auth/cli/refresh` - Refresh expired session
+- [ ] `GET /api/v1/organizations` - Get user's organizations
+- [ ] `POST /api/v1/organizations` - Create organization
+- [ ] `POST /api/v1/api-keys/generate` - Generate API key (or call Convex action directly)
+
+### CLI Enhancements
+- [ ] Handle deep link callback (`l4yercak3://auth/callback`) as alternative to local server
+- [ ] OS keychain integration for secure token storage (macOS)
+- [ ] Better error handling and user feedback
+- [ ] Session refresh on expiration
+- [ ] 2FA support during login
+
+## 📝 Testing
+
+### Manual Testing Checklist
+- [ ] `l4yercak3 login` - Opens browser, receives token
+- [ ] `l4yercak3 logout` - Clears session
+- [ ] `l4yercak3 auth status` - Shows status correctly
+- [ ] `l4yercak3 spread` - Requires login, shows placeholder
+
+### Backend Integration Testing
+- [ ] Test with real backend OAuth endpoints
+- [ ] Test session validation
+- [ ] Test session refresh
+- [ ] Test organization creation
+- [ ] Test API key generation
+
+## 🎯 Next Steps (Phase 1)
+
+1. **Project Detection** (`src/detectors/`)
+   - Detect Next.js projects
+   - Detect GitHub repository
+   - Detect existing API client patterns
+
+2. **Configuration Wizard** (`src/commands/spread.js`)
+   - Interactive prompts
+   - Organization selection/creation
+   - Feature selection
+
+3. **File Generation** (`src/generators/`)
+   - API client generation
+   - Environment file generation
+   - NextAuth.js configuration
+
+## 📦 Dependencies Added
+
+- `commander` - CLI command parsing
+- `open` - Open browser for OAuth
+- `node-fetch@2` - HTTP requests (CommonJS compatible)
+
+## 🔒 Security Considerations
+
+- Config file stored with 0o600 permissions (owner read/write only)
+- Session tokens stored locally (not in git)
+- Config directory excluded from git
+- Session expiration checking
+- Secure token handling
+
+---
+
+**Status:** Phase 0 Foundation Complete ✅  
+**Next:** Backend endpoints + Phase 1 implementation
+