# StackScope Non-Interactive Quick Start

> **For CI/CD, Claude Code, automated tooling, and any non-interactive environment**

This guide provides a complete setup without any interactive prompts or TTY requirements.

## 🚀 5-Minute Setup

### 1. Install StackScope SDK
```bash
npm install stackscope
```

### 2. Create Worker (Non-Interactive)
```bash
# Creates complete worker setup without prompts
npm run setup-worker my-app-logs

# Or directly:
# node node_modules/stackscope/scripts/create-worker-noninteractive.js my-app-logs
```

### 3. Deploy Worker
```bash
cd my-app-logs
npm install

# Ensure you're authenticated (one-time setup)
npx wrangler auth login

# Deploy automatically
node deploy.js
```

### 4. Configure Your App
```bash
# Copy your worker URL from deploy output
echo "VITE_STACKSCOPE_WORKER_URL=https://my-app-logs.your-account.workers.dev" > .env.local
```

### 5. Initialize StackScope
```javascript
import { createStackScope } from 'stackscope';

// Auto-detects VITE_STACKSCOPE_WORKER_URL
const stackscope = createStackScope();

// Test it works
console.log('StackScope is ready!');
```

## ✅ Verification

Test everything works:

```bash
# Validate environment variables
npm run validate-env

# Test worker endpoints
cd my-app-logs
node test.js

# Monitor live logs
npx wrangler tail
```

## 🔧 Framework-Specific Setup

### Vite
```bash
# Environment
echo "VITE_STACKSCOPE_WORKER_URL=https://your-worker.workers.dev" >> .env.local
echo "VITE_STACKSCOPE_DEBUG=true" >> .env.local

# Initialize
import { createStackScope } from 'stackscope';
const stackscope = createStackScope();
```

### Next.js
```bash
# Environment  
echo "NEXT_PUBLIC_STACKSCOPE_WORKER_URL=https://your-worker.workers.dev" >> .env.local
echo "NEXT_PUBLIC_STACKSCOPE_DEBUG=true" >> .env.local

# Initialize
import { StackScopeProvider } from 'stackscope/react';
export default function MyApp({ Component, pageProps }) {
  return (
    <StackScopeProvider>
      <Component {...pageProps} />
    </StackScopeProvider>
  );
}
```

### Create React App
```bash
# Environment
echo "REACT_APP_STACKSCOPE_WORKER_URL=https://your-worker.workers.dev" >> .env.local  
echo "REACT_APP_STACKSCOPE_DEBUG=true" >> .env.local

# Initialize
import { createStackScope } from 'stackscope';
createStackScope(); // Auto-detects REACT_APP_* variables
```

## 🐛 Troubleshooting

### Worker Deployment Issues
```bash
# Check authentication
npx wrangler whoami

# Manual deployment
cd my-app-logs
npx wrangler deploy --env production

# View deployment logs
npx wrangler deployments list
```

### Environment Variable Issues
```bash
# Auto-detect and validate setup
npm run validate-env

# Generate framework-specific template
npm run validate-env -- --generate
```

### Testing Connection
```javascript
// Test with your deployed worker
const stackscope = createStackScope({
  debug: true,        // Shows logs in console AND sends to worker
  workerUrl: 'https://your-worker.workers.dev' // Required for full functionality
});

// Verify both console output and worker logs
console.log('Testing StackScope connection...');
// Check worker logs: npx wrangler tail
```

## ⚡ CI/CD Integration

### GitHub Actions
```yaml
name: Deploy StackScope Worker
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
    - run: npm install stackscope
    - run: npm run setup-worker stackscope-worker
    - run: cd stackscope-worker && npm install
    - run: cd stackscope-worker && npx wrangler deploy --env production
      env:
        CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
```

### Docker
```dockerfile
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
RUN npm run setup-worker stackscope-worker
WORKDIR /app/stackscope-worker
RUN npm install
# Add wrangler authentication and deploy steps
```

## 📚 What's Generated

The non-interactive setup creates:

```
my-app-logs/
├── src/index.js          # Complete worker code
├── wrangler.toml         # Cloudflare configuration  
├── package.json          # Dependencies and scripts
├── deploy.js             # Automated deployment
├── test.js               # Endpoint testing
└── README.md             # Generated documentation
```

All files are production-ready with:
- ✅ CORS handling
- ✅ Error handling  
- ✅ Request validation
- ✅ Signature verification
- ✅ Comprehensive logging
- ✅ Health checks
- ✅ Test suite

## 🔗 API Log Streaming (Optional but Recommended)

**NEW**: Stream logs from your Cloudflare Worker API to StackScope for complete observability.

```bash
# 1. Ensure your API worker is deployed
cd ../my-api-worker
npx wrangler deploy --env production

# 2. Return to StackScope directory and start streaming
cd ../my-app-logs
./stream-api-logs.sh ../my-api-worker production
```

### Automated Background Streaming

For production environments:

```bash
# Start streaming in background
nohup ./stream-api-logs.sh ../my-api-worker production > api-stream.log 2>&1 &

# Check streaming status
ps aux | grep stream-api-logs

# Stop streaming
pkill -f stream-api-logs
```

### CI/CD Integration for API Streaming

```yaml
# Add to your GitHub Actions workflow
- name: Start API Log Streaming
  run: |
    cd my-app-logs
    nohup ./stream-api-logs.sh ../my-api-worker production > /tmp/api-stream.log 2>&1 &
    echo $! > /tmp/stream.pid
    
- name: Stop API Log Streaming  
  if: always()
  run: |
    if [ -f /tmp/stream.pid ]; then
      kill $(cat /tmp/stream.pid) || true
    fi
```

### What You Get

- **Browser Logs**: Console, network, interactions (from SDK)
- **API Logs**: Requests, responses, worker console, exceptions (from streaming)
- **Complete Observability**: Full-stack visibility in one place

## 🚀 Next Steps

After successful setup:

1. **Monitor logs**: `npx wrangler tail` to see real-time activity
2. **Start API streaming**: `./stream-api-logs.sh ../your-api-worker production`
3. **Add secrets**: `npx wrangler secret put GITHUB_WEBHOOK_SECRET` for webhooks
4. **Scale up**: Configure custom domain, rate limiting, analytics
5. **Integration**: Add GitHub webhooks, custom log processing

## 💡 Why Non-Interactive?

The standard `stackscope-worker init` command:
- ❌ Requires TTY (interactive terminal)
- ❌ Uses prompts that break in CI/CD
- ❌ Fails in Claude Code and automation
- ❌ Creates incomplete setups on errors

This non-interactive approach:
- ✅ Works in any environment
- ✅ Generates complete, tested code
- ✅ Provides automated deployment
- ✅ Includes comprehensive testing
- ✅ Zero prompts or user input required