@forloop-cc/forloop-opencode-plugin-planner 2.2.1

package/docs/IMPROVED-AUTHENTICATION.md

@@ -0,0 +1,317 @@
+# Improved Token Authentication System
+
+## Problem Statement
+
+The ForLoop opencode plugin runs in **two different execution contexts**:
+
+1. **Local Workspace** (user's machine)
+   - User has `floop_*` API key token
+   - Token stored in `~/.config/forloop/tokens.json`
+   - Used for direct API calls
+
+2. **AWS Lambda** (serverless execution)
+   - Client sends JWT Bearer token (from user login)
+   - Token passed via EventBridge from `server_lambda`
+   - Used for authenticated API calls on behalf of user
+
+**Previous Issue**: The `validateToken()` function only accepted `floop_*` tokens, which would reject JWT tokens in Lambda execution.
+
+## Solution: Dual Token Support
+
+### Token Types
+
+```typescript
+export type TokenType = 'api_key' | 'jwt';
+
+// API Key: floop_abc123xyz
+// JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM...
+```
+
+### Detection Logic (`auth.ts:detectTokenType`)
+
+```typescript
+export function detectTokenType(token: string): TokenType | null {
+  if (!token) return null;
+  
+  // API Key format: floop_xxx
+  if (token.startsWith('floop_')) {
+    return 'api_key';
+  }
+  
+  // JWT format: xxx.yyy.zzz (base64url.base64url.base64url)
+  const parts = token.split('.');
+  if (parts.length === 3 && parts.every(p => p.length > 0)) {
+    const base64urlRegex = /^[A-Za-z0-9_-]+$/;
+    if (parts.every(p => base64urlRegex.test(p))) {
+      return 'jwt';
+    }
+  }
+  
+  return null;
+}
+```
+
+### Context-Aware Validation
+
+**Local Execution:**
+- ✅ Accepts: `floop_*` API keys
+- ❌ Rejects: JWT tokens (with helpful error message)
+
+**Lambda Execution:**
+- ✅ Accepts: JWT tokens (from EventBridge)
+- ✅ Accepts: `floop_*` API keys (backward compatible)
+
+```typescript
+export async function validateToken(providedToken?: string): Promise<TokenValidationResult> {
+  const token = providedToken || (await getToken());
+  
+  const tokenType = detectTokenType(token);
+  
+  if (!tokenType) {
+    return { valid: false, error: 'Unrecognized token format...' };
+  }
+
+  // JWT only allowed in Lambda
+  if (tokenType === 'jwt' && !isLambdaExecution()) {
+    return {
+      valid: false,
+      error: 'JWT tokens are only supported in Lambda execution...',
+    };
+  }
+
+  return { valid: true, token, tokenType };
+}
+```
+
+### Lambda Detection (`config.ts`)
+
+```typescript
+export const isLambdaExecution = (): boolean => {
+  return !!(
+    process.env.AWS_LAMBDA_FUNCTION_NAME ||
+    process.env.AWS_EXECUTION_ENV ||
+    process.env.LAMBDA_TASK_ROOT
+  );
+};
+```
+
+## HTTP Header Strategy
+
+Different token types require different HTTP headers:
+
+| Token Type | Header | Example |
+|------------|--------|---------|
+| JWT | `Authorization: Bearer` | `Bearer eyJhbGciOiJIUzI1NiIs...` |
+| API Key | `X-API-Token` | `floop_abc123xyz` |
+
+### Dynamic Header Selection (`api-client.ts`)
+
+```typescript
+export class ForLoopAPIClient {
+  private tokenType: TokenType | null;
+
+  constructor(config: ClientConfig) {
+    this.tokenType = detectTokenType(config.token);
+  }
+
+  private getAuthHeaders(): HeadersInit {
+    const headers: HeadersInit = {};
+    
+    if (this.tokenType === 'jwt') {
+      headers['Authorization'] = `Bearer ${this.config.token}`;
+    } else {
+      headers['X-API-Token'] = this.config.token;
+    }
+    
+    return headers;
+  }
+
+  public async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        ...this.defaultHeaders,
+        ...this.getAuthHeaders(),  // ← Dynamic based on token type
+      },
+    });
+    return response.json();
+  }
+}
+```
+
+## Execution Flow
+
+### Local Workspace
+```
+┌─────────────────────────────────────┐
+│  User runs opencode locally         │
+│  $ opencode run --agent forloop...  │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  Plugin loads ~/.config/forloop/    │
+│  tokens.json → gets floop_* token   │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  validateToken() checks:            │
+│  - isLambdaExecution() = false      │
+│  - tokenType = 'api_key' ✓          │
+│  - Returns valid ✓                  │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  API calls use header:              │
+│  X-API-Token: floop_***             │
+└─────────────────────────────────────┘
+```
+
+### AWS Lambda
+```
+┌─────────────────────────────────────┐
+│  Client sends POST /api/ai/chat     │
+│  Authorization: Bearer eyJ...       │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  server_lambda extracts JWT,        │
+│  includes in EventBridge detail     │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  Lambda receives JWT, seeds to      │
+│  /tmp/forloop-sandbox/.../tokens.json
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  Plugin reads JWT token             │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  validateToken() checks:            │
+│  - isLambdaExecution() = true       │
+│  - tokenType = 'jwt' ✓              │
+│  - JWT allowed in Lambda ✓          │
+│  - Returns valid ✓                  │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  API calls use header:              │
+│  Authorization: Bearer eyJ...       │
+└─────────────────────────────────────┘
+```
+
+## Error Messages
+
+### Missing Token
+```
+No API token configured. Please create a token at https://forloop.cc/profile?tab=api-tokens
+```
+
+### Unrecognized Format
+```
+Unrecognized token format. Use either a ForLoop API key (floop_*) or a valid JWT token.
+```
+
+### JWT in Local Context
+```
+JWT tokens are only supported in Lambda execution. Please use a ForLoop API key (floop_*) for local execution.
+```
+
+## Backward Compatibility
+
+✅ **Existing functionality preserved:**
+- `floop_*` tokens work in both local and Lambda
+- `X-API-Token` header still used for API keys
+- Token file location unchanged (`~/.config/forloop/tokens.json`)
+- Profile support maintained
+
+✅ **New features:**
+- JWT tokens now accepted in Lambda
+- Automatic header selection based on token type
+- Clear error messages for wrong token type in wrong context
+
+## Testing
+
+### Local Testing with API Key
+```bash
+# Set API key
+export FORLOOP_API_URL=https://api.forloop.cc
+echo '{"default":"floop_test123"}' > ~/.config/forloop/tokens.json
+
+# Run opencode locally
+opencode run --agent forLoopPlanner -- "Create a story..."
+```
+
+### Lambda Testing with JWT
+```bash
+# Lambda automatically detects execution context
+# No manual configuration needed
+# JWT passed from client → server_lambda → EventBridge → Lambda
+```
+
+### Type Detection Unit Test
+```typescript
+import { detectTokenType } from './auth';
+
+describe('detectTokenType', () => {
+  it('detects API key', () => {
+    expect(detectTokenType('floop_abc123')).toBe('api_key');
+  });
+
+  it('detects JWT', () => {
+    const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U';
+    expect(detectTokenType(jwt)).toBe('jwt');
+  });
+
+  it('rejects invalid format', () => {
+    expect(detectTokenType('invalid')).toBe(null);
+    expect(detectTokenType('')).toBe(null);
+  });
+});
+```
+
+## Security Considerations
+
+### JWT Validation
+- ✅ Format checked (3 parts, base64url encoding)
+- ✅ Context checked (only in Lambda)
+- ⚠️ Signature not validated (done by API server)
+- ⚠️ Expiration not checked (done by API server)
+
+### API Key Validation
+- ✅ Prefix checked (`floop_`)
+- ✅ File permissions (`0o600`)
+- ✅ Isolated in Lambda sandbox
+
+### Token Storage
+- Lambda: Ephemeral `/tmp/` storage (cleared after execution)
+- Local: Persistent `~/.config/forloop/` (user-managed)
+
+## Migration
+
+**No migration required** - changes are fully backward compatible.
+
+Existing users with `floop_*` tokens will continue to work without any changes.
+
+## Related Files
+
+### Core Authentication
+- `plugins/capabilities/auth.ts` - Token validation and type detection
+- `plugins/capabilities/config.ts` - Lambda detection
+- `plugins/capabilities/api-client.ts` - HTTP client with dynamic headers
+- `plugins/capabilities/token-storage.ts` - Token file management
+
+### Lambda
+- `forloop-opencode-lambda-planner/src/lambda-handler.mjs` - JWT seeding (lines 92-108)
+
+### Tools
+- All tools in `plugins/tools/*.ts` use `validateToken()` for authentication

package/docs/INSTALLATION-SCRIPTS.md

@@ -0,0 +1,304 @@
+# Installation Scripts Reference
+
+This document describes the installation and update scripts for the ForLoop Plugin.
+
+## install.sh
+
+One-line installation script for the ForLoop Plugin.
+
+### Quick Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin/main/install.sh | bash
+```
+
+### Usage
+
+```bash
+# Interactive install (asks questions)
+curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin/main/install.sh | bash
+
+# Global install (all projects)
+bash install.sh --global
+
+# Local install (current project only)
+bash install.sh --local
+
+# Custom directory
+bash install.sh --dir /path/to/plugins
+
+# Force reinstall (overwrite existing)
+bash install.sh --force
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-g, --global` | Install to `~/.config/opencode` (all projects) |
+| `-l, --local` | Install to `.opencode` (current project) |
+| `-d, --dir PATH` | Install to custom directory |
+| `-f, --force` | Force installation (overwrite without asking) |
+| `-h, --help` | Show help message |
+
+### What It Does
+
+1. **Checks prerequisites**
+   - git (required)
+   - Node.js (required for npm install)
+   - opencode CLI (optional, warns if missing)
+
+2. **Clones the plugin**
+   - Git clone from GitHub
+   - Shallow clone (faster)
+
+3. **Installs dependencies**
+   - Runs `npm install --production`
+   - No build step required (TypeScript runs directly)
+
+4. **Sets up token** (interactive only)
+   - Guides you through token creation
+   - Can optionally save token during install
+
+5. **Verifies installation**
+   - Checks entry point exists
+   - Provides next steps
+
+### Token Setup
+
+During interactive installation, you can set up your API token:
+
+1. Script prompts: "Have you created a token? [y/N]"
+2. If yes, prompts for token value
+3. Saves to `~/.config/forloop/tokens.json`
+4. Sets permissions to `600` (secure)
+
+**If you skip token setup:**
+```bash
+forloopTokenSet --token floop_YOUR_TOKEN_HERE
+```
+
+### Prerequisites
+
+| Requirement | Required? | Why |
+|-------------|-----------|-----|
+| git | ✅ Yes | Clones plugin repository |
+| Node.js 18+ | ✅ Yes | Runs npm install |
+| opencode CLI | ⚠️ Recommended | Using the plugin requires it |
+| ForLoop account | ⚠️ Recommended | Need API token to use features |
+
+### Troubleshooting
+
+**"git is required but not installed"**
+```bash
+# macOS
+brew install git
+
+# Ubuntu/Debian
+apt-get install git
+
+# Windows
+# Download from https://git-scm.com/download/win
+```
+
+**"Node.js not found"**
+```bash
+# Install from https://nodejs.org
+# Or use nvm: https://github.com/nvm-sh/nvm
+```
+
+**"Existing forloop plugin found"**
+```bash
+# Use --force to overwrite
+bash install.sh --force
+```
+
+**Installation failed verification**
+```bash
+# Check installation directory
+ls -la ~/.config/opencode/plugins/forloop/
+# Or for local:
+ls -la .opencode/plugins/forloop/
+
+# Entry point should exist:
+# plugins/forloop/plugins/forloop-plugin.ts
+```
+
+---
+
+## update.sh
+
+Update an existing ForLoop Plugin installation.
+
+### Quick Update
+
+```bash
+# Auto-detect installation location
+bash update.sh
+
+# Update global installation
+bash update.sh --global
+
+# Update local installation
+bash update.sh --local
+
+# Update custom directory
+bash update.sh --dir /path/to/plugins
+```
+
+### Usage
+
+```bash
+# Check for updates and update if newer
+bash update.sh
+
+# Force update to latest version
+bash update.sh --force
+
+# Show changelog after update
+bash update.sh --changelog
+
+# Update and show changelog
+bash update.sh --global --changelog
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-g, --global` | Update global installation (`~/.config/opencode`) |
+| `-l, --local` | Update local installation (`.opencode`) |
+| `-d, --dir PATH` | Update custom directory |
+| `-f, --force` | Force update even if already up to date |
+| `-c, --changelog` | Show changelog after update |
+| `-h, --help` | Show help message |
+
+### What It Does
+
+1. **Finds installation**
+   - Checks global location
+   - Checks local location
+   - Or uses specified directory
+
+2. **Checks for updates**
+   - Fetches latest from git
+   - Compares current vs latest version
+   - Only updates if newer
+
+3. **Updates plugin**
+   - Switches to main branch
+   - Pulls latest changes or checks out tag
+   - Reinstalls dependencies
+
+4. **Verifies update**
+   - Checks entry point exists
+   - Shows changelog (if requested)
+
+### Update Behavior
+
+**With tags (releases):**
+- Updates to latest tagged version
+- Example: `v2.2.0`
+
+**Without tags (development):**
+- Updates to latest commit on main branch
+
+**Already up to date:**
+- Script exits with "Already up to date!" message
+
+**Force mode:**
+- Reinstalls dependencies
+- Useful if dependencies changed
+
+### Troubleshooting
+
+**"No ForLoop plugin installation found"**
+```bash
+# Specify directory explicitly
+bash update.sh --dir ~/.config/opencode/plugins/forloop
+```
+
+**"Not a git repository"**
+```bash
+# Directory is not a git clone
+# Reinstall instead:
+bash install.sh --force
+```
+
+**Update fails**
+```bash
+# Reset to clean state
+cd ~/.config/opencode/plugins/forloop
+git reset --hard HEAD
+git clean -fd
+
+# Then update
+bash update.sh --force
+```
+
+---
+
+## Script Comparison
+
+| Feature | install.sh | update.sh |
+|---------|------------|-----------|
+| Clone repository | ✅ Yes | ❌ No (already exists) |
+| Install dependencies | ✅ Yes | ✅ Yes |
+| Setup token | ✅ Interactive | ❌ No |
+| Force mode | ✅ Overwrite | ✅ Reinstall |
+| Find installation | ❌ Specify type | ✅ Auto-detect |
+| Show changelog | ❌ No | ✅ Optional |
+| Verify installation | ✅ Yes | ✅ Yes |
+
+---
+
+## Best Practices
+
+### For Users
+
+1. **Initial install:** Use `install.sh`
+2. **Updates:** Use `update.sh --changelog` to see what changed
+3. **Token setup:** Easiest to do during interactive install
+4. **Global vs Local:**
+   - Global: One install, all projects
+   - Local: Per-project, can use different versions
+
+### For Developers
+
+1. **Development:** Use `npm run install:local` for linking
+2. **Testing changes:** Edit files, run tests, then reinstall
+3. **Publish:** Use `npm publish`, then users can update
+
+### Production Deployments
+
+For team deployments:
+
+```bash
+#!/bin/bash
+# deploy-forloop.sh
+
+# Install globally on all team machines
+curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin/main/install.sh | bash -s -- --global
+
+# Set token (from secret manager)
+export TOKEN=$(aws secretsmanager get-secret-value --secret-id forloop-token)
+forloopTokenSet --token $TOKEN
+```
+
+---
+
+## Script Locations
+
+| Location | Purpose |
+|----------|---------|
+| [install.sh](../install.sh) | Installation script |
+| [update.sh](../update.sh) | Update script |
+| [QUICKSTART-NON-DEV.md](QUICKSTART-NON-DEV.md) | User setup guide |
+
+---
+
+## Getting Help
+
+- **Issues:** [GitHub Issues](https://github.com/forloop-cc/forloop-opencode-plugin/issues)
+- **Documentation:** [docs/](../docs/)
+- **Quick Start:** [QUICKSTART-NON-DEV.md](QUICKSTART-NON-DEV.md)

package/docs/PLANNER-AGENT-IMPROVEMENTS.md

@@ -0,0 +1,88 @@
+# Planner Agent Skill Improvements
+
+## Issues & Fixes
+
+### 1. Plugin Folder Structure ✅ VERIFIED
+
+**Current Implementation** (lambda-handler.mjs:58-66):
+```javascript
+function copyPluginRuntimeAssets(homeDir) {
+  copyDirRecursive('/var/task/forloop-opencode-plugin-planner/agent', runtimeAgentDir);
+  copyDirRecursive('/var/task/forloop-opencode-plugin-planner/skills', runtimeSkillsDir);
+  copyDirRecursive('/var/task/forloop-opencode-plugin-planner/plugins', runtimePluginsDir);
+}
+```
+
+**Target Locations**:
+- Agents: `$HOME/.config/opencode/agent/` ✓ (opencode expects `agent/` not `agents/`)
+- Skills: `$HOME/.config/opencode/skills/` ✓
+- Plugins: `$HOME/.config/opencode/plugins/` ✓
+
+**✅ Status**: Copied correctly! The opencode runtime uses `agent/` (singular) not `agents/`.
+
+### 2. Agent Selection (ID vs Name) ⚠️ NEEDS FIX
+
+**Current** (lambda-handler.mjs:439):
+```javascript
+const args = ['run', '--agent', agentId, '--', prompt];
+```
+
+**Opencode expects**: Agent name (from agent definition), not ID
+
+**Fix**:
+```javascript
+// Use agent name from agent definition
+const args = ['run', '--agent', agentName, '--', prompt];
+```
+
+**Agent Definition** (forLoopPlanner.md):
+```markdown
+---
+id: forLoopPlanner
+name: ForLoop Planner  ← THIS should be passed
+---
+```
+
+### 3. S3 Sync on Startup ❌ MISSING
+
+**Problem**: `forloop-context` skill only checks local `.forloop/`, doesn't sync from S3 first
+
+**Fix**: Update `forloop-context` skill to:
+```typescript
+1. Check if .forloop/manifest.json exists
+2. If NOT exists or empty:
+   - Call forloopSprintList to get sprints
+   - Call forloopSyncS3ToLocal to sync latest context
+3. Load context files
+```
+
+### 4. Story Creation with Doc Folder Link ❌ MISSING
+
+**Problem**: `task-tracking` skill creates stories but doesn't link to doc_folder
+
+**Fix**: Update `story-creation` and `task-tracking` skills:
+```typescript
+1. Before creating stories, get doc_folder ID
+2. Pass storyId: docFolderId to story creation
+```
+
+### 5. task.md Updates ❌ NOT TRACKED
+
+**Problem**: After stories created, task.md not updated with story IDs
+
+**Fix**: Update `task-tracking` skill to:
+```typescript
+1. After story creation, update task.md with:
+   - Story IDs
+   - Story titles
+   - Status (todo/in_progress/done)
+2. Upload updated task.md to S3
+```
+
+## Implementation Checklist
+
+- [ ] Fix Lambda agent invocation (pass name not id)
+- [ ] Update forloop-context skill (sync from S3)
+- [ ] Update task-tracking skill (link doc_folder, update task.md)
+- [ ] Update story-creation tool (accept storyId for linking)
+- [ ] Test end-to-end flow