woopcode 0.1.0

package/onboarding/FLOW.md

@@ -0,0 +1,291 @@
+# Onboarding Flow Diagram
+
+## User Journey
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User runs: woopcode                      │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+                      ▼
+            ┌─────────────────────┐
+            │ Check configuration │
+            │ (ensureProvider     │
+            │  Configured())      │
+            └──────────┬──────────┘
+                       │
+            ┌──────────┴──────────┐
+            │                     │
+    ┌───────▼────────┐   ┌───────▼────────┐
+    │  Has API Key?  │   │  Has API Key?  │
+    │      YES       │   │       NO       │
+    └───────┬────────┘   └───────┬────────┘
+            │                     │
+            │              ┌──────▼──────┐
+            │              │   Welcome   │
+            │              │   Screen    │
+            │              └──────┬──────┘
+            │                     │
+            │              ┌──────▼──────────┐
+            │              │  Select         │
+            │              │  Provider       │
+            │              │  (Arrow Keys)   │
+            │              └──────┬──────────┘
+            │                     │
+            │              ┌──────▼──────────┐
+            │              │  Show API Key   │
+            │              │  URL            │
+            │              └──────┬──────────┘
+            │                     │
+            │              ┌──────▼──────────┐
+            │              │  Enter API Key  │
+            │              │  (Masked Input) │
+            │              └──────┬──────────┘
+            │                     │
+            │              ┌──────▼──────────┐
+            │              │  Validate Key   │
+            │              │  (Spinner)      │
+            │              └──────┬──────────┘
+            │                     │
+            │              ┌──────┴──────┐
+            │              │             │
+            │         ┌────▼────┐  ┌────▼────┐
+            │         │ Invalid │  │  Valid  │
+            │         │  Key    │  │   Key   │
+            │         └────┬────┘  └────┬────┘
+            │              │            │
+            │         ┌────▼────────┐   │
+            │         │ Show Error  │   │
+            │         │ Return to   │   │
+            │         │ Input       │   │
+            │         └────┬────────┘   │
+            │              │            │
+            │              └────────┬───┘
+            │                       │
+            │                ┌──────▼──────┐
+            │                │ Save Config │
+            │                └──────┬──────┘
+            │                       │
+            │                ┌──────▼──────┐
+            │                │   Success   │
+            │                │   Message   │
+            │                └──────┬──────┘
+            │                       │
+            └───────────────────────┘
+                            │
+                     ┌──────▼──────┐
+                     │   Launch    │
+                     │  Main Chat  │
+                     │  Interface  │
+                     └─────────────┘
+```
+
+## State Machine
+
+```
+┌─────────┐     Enter     ┌────────────────┐     ↑↓     ┌──────────────┐
+│ welcome ├──────────────►│select-provider ├───────────►│ highlighting │
+└─────────┘                └────────┬───────┘            │  provider    │
+                                    │                    └──────┬───────┘
+                                    │ Enter                     │
+                            ┌───────▼──────┐                    │
+                            │api-key-info  │◄───────────────────┘
+                            └───────┬──────┘
+                                    │ Enter
+                            ┌───────▼──────┐
+                            │  enter-key   │
+                            └───────┬──────┘
+                                    │ Submit
+                            ┌───────▼──────┐
+                            │ validating   │
+                            └───────┬──────┘
+                                    │
+                        ┌───────────┴───────────┐
+                        │                       │
+                   ┌────▼────┐             ┌───▼─────┐
+                   │  Error  │             │Complete │
+                   └────┬────┘             └───┬─────┘
+                        │                      │
+                   Back to                  Continue to
+                   enter-key                main app
+```
+
+## Error Handling Flow
+
+```
+┌──────────────┐
+│   API Call   │
+└──────┬───────┘
+       │
+       ├─────► Network Error ──────► Show "Check connection" ──► Retry
+       │
+       ├─────► Invalid Key  ──────► Show "Invalid key"     ──► Retry  
+       │
+       ├─────► Timeout      ──────► Show "Request timeout" ──► Retry
+       │
+       ├─────► 401/403      ──────► Show "Invalid key"     ──► Retry
+       │
+       ├─────► 500          ──────► Show "Provider error"  ──► Retry
+       │
+       └─────► Success      ──────► Save & Continue
+```
+
+## Component Tree
+
+```
+<SetupWizard>
+  │
+  ├─ step: "welcome"
+  │  └─ <Box>
+  │     ├─ Welcome message
+  │     ├─ Instructions
+  │     └─ "Press Enter" hint
+  │
+  ├─ step: "select-provider"
+  │  └─ <Box>
+  │     ├─ Provider list (map)
+  │     │  └─ Each provider:
+  │     │     ├─ Highlight if selected
+  │     │     └─ Show description
+  │     └─ Keyboard hints
+  │
+  ├─ step: "api-key-info"
+  │  └─ <Box>
+  │     ├─ Provider name
+  │     ├─ API key URL
+  │     └─ "Press Enter" hint
+  │
+  ├─ step: "enter-key"
+  │  └─ <Box>
+  │     ├─ Prompt
+  │     ├─ <TextInput mask="*" />
+  │     └─ Submit hint
+  │
+  ├─ step: "validating"
+  │  └─ <Box>
+  │     ├─ <Spinner />
+  │     └─ "Validating..." text
+  │
+  └─ step: "complete"
+     └─ <Box>
+        ├─ ✓ API key verified
+        ├─ ✓ Configuration saved
+        └─ Starting message
+```
+
+## Data Flow
+
+```
+┌─────────────┐
+│   User      │
+│   Input     │
+└──────┬──────┘
+       │
+       ▼
+┌────────────────┐
+│ SetupWizard    │ ──► state: { step, selectedIndex, 
+│ Component      │              selectedProvider, apiKey }
+└────────┬───────┘
+         │
+         ▼
+┌────────────────┐
+│ handleKeySubmit│
+└────────┬───────┘
+         │
+         ▼
+┌────────────────┐
+│ loginProvider()│ ──► Reuses existing validation
+└────────┬───────┘     from config/authProvider.ts
+         │
+         ├─► Invalid ─► onError() ─► Show error & retry
+         │
+         └─► Valid ───┐
+                      │
+                      ▼
+         ┌────────────────────┐
+         │ getConfig()        │
+         │ config.provider = X│
+         │ config.apiKey = Y  │
+         │ saveConfig()       │
+         └────────┬───────────┘
+                  │
+                  ▼
+         ┌────────────────┐
+         │ onComplete()   │ ──► Unmount wizard
+         └────────┬───────┘     Continue to app
+                  │
+                  ▼
+         ┌────────────────┐
+         │ Main App       │
+         │ (agent.tsx)    │
+         └────────────────┘
+```
+
+## Keyboard Shortcuts
+
+```
+┌──────────────┬─────────────────────────────────┐
+│   Key        │   Action                        │
+├──────────────┼─────────────────────────────────┤
+│   Enter      │ Confirm / Next step             │
+│   ↑          │ Previous provider (select step) │
+│   ↓          │ Next provider (select step)     │
+│   Ctrl+C     │ Cancel onboarding, exit         │
+│   Type       │ Input API key (masked)          │
+└──────────────┴─────────────────────────────────┘
+```
+
+## Integration Points
+
+```
+cli.ts (Entry)
+   │
+   ▼
+agent.tsx
+   │
+   ├─► ensureProviderConfigured()  ──────┐
+   │                                     │
+   │   ┌───────────────────────────────┘
+   │   │
+   │   ▼
+   │ onboarding/index.ts
+   │   │
+   │   ├─► Check config exists? ───► Yes ───► Return (skip)
+   │   │
+   │   └─► No ───► Launch wizard
+   │               │
+   │               ▼
+   │         onboarding/setupWizard.tsx
+   │               │
+   │               ├─► providers.ts (data)
+   │               │
+   │               ├─► loginProvider() (validation)
+   │               │
+   │               └─► saveConfig() (persistence)
+   │
+   ▼
+Continue to main app
+```
+
+## File Dependencies
+
+```
+onboarding/index.ts
+   ├─► ink (render)
+   ├─► react
+   ├─► ./setupWizard (component)
+   └─► ../config/config (getConfig)
+
+onboarding/setupWizard.tsx
+   ├─► react (useState)
+   ├─► ink (Box, Text, useInput)
+   ├─► ink-text-input (TextInput)
+   ├─► ink-spinner (Spinner)
+   ├─► chalk
+   ├─► ./providers (getEnabledProviders, ProviderInfo)
+   ├─► ../config/authProvider (loginProvider)
+   └─► ../config/config (getConfig, saveConfig)
+
+onboarding/providers.ts
+   └─► No dependencies (pure data)
+```

package/onboarding/index.ts

@@ -0,0 +1,56 @@
+import { render } from "ink";
+import React from "react";
+import { SetupWizard } from "./setupWizard";
+import { getConfig } from "../config/config";
+
+/**
+ * Ensures a provider is configured. If not, launches the onboarding wizard.
+ * This function is reusable across any command that requires authentication.
+ *
+ * @returns Promise that resolves when a provider is configured
+ * @throws If the user cancels onboarding (Ctrl+C)
+ */
+export async function ensureProviderConfigured(): Promise<void> {
+  const config = await getConfig();
+  const provider = config.defaultProvider;
+  const apiKey = config.providers[provider]?.apiKey;
+
+  // Already configured
+  if (provider && apiKey) {
+    return;
+  }
+
+  // Launch onboarding
+  return new Promise<void>((resolve, reject) => {
+    let hasCompleted = false;
+
+    const { unmount, waitUntilExit } = render(
+      React.createElement(SetupWizard, {
+        onComplete: () => {
+          hasCompleted = true;
+          unmount();
+          resolve();
+        },
+        onError: (error: string) => {
+          console.error(`\n✖ ${error}\n`);
+          // Don't unmount - let user try again
+        },
+      }),
+    );
+
+    // Handle Ctrl+C gracefully
+    const handleExit = () => {
+      if (!hasCompleted) {
+        unmount();
+        console.log("\n\nSetup cancelled. Run 'woopcode' again when you're ready.\n");
+        process.exit(0);
+      }
+    };
+
+    process.once("SIGINT", handleExit);
+
+    waitUntilExit().then(() => {
+      process.off("SIGINT", handleExit);
+    });
+  });
+}

package/onboarding/providers.ts

@@ -0,0 +1,47 @@
+// Provider registry for onboarding
+export interface ProviderInfo {
+  id: string;
+  name: string;
+  enabled: boolean;
+  keyUrl: string;
+  description: string;
+}
+
+export const PROVIDERS: ProviderInfo[] = [
+  {
+    id: "google",
+    name: "Google Gemini",
+    enabled: true,
+    keyUrl: "https://aistudio.google.com/apikey",
+    description: "Fast and capable, with a generous free tier",
+  },
+  {
+    id: "openai",
+    name: "OpenAI",
+    enabled: false,
+    keyUrl: "https://platform.openai.com/api-keys",
+    description: "GPT-4 and GPT-3.5 models",
+  },
+  {
+    id: "anthropic",
+    name: "Anthropic Claude",
+    enabled: false,
+    keyUrl: "https://console.anthropic.com/settings/keys",
+    description: "Claude 3 family of models",
+  },
+  {
+    id: "groq",
+    name: "Groq",
+    enabled: false,
+    keyUrl: "https://console.groq.com/keys",
+    description: "Ultra-fast inference for open models",
+  },
+];
+
+export function getEnabledProviders(): ProviderInfo[] {
+  return PROVIDERS.filter((p) => p.enabled);
+}
+
+export function getProviderInfo(id: string): ProviderInfo | undefined {
+  return PROVIDERS.find((p) => p.id === id);
+}

package/onboarding/setupWizard.tsx

@@ -0,0 +1,193 @@
+import React, { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import TextInput from "ink-text-input";
+import Spinner from "ink-spinner";
+import chalk from "chalk";
+import { getEnabledProviders, type ProviderInfo } from "./providers";
+import { loginProvider } from "../config/authProvider";
+import { getConfig, saveConfig } from "../config/config";
+
+type WizardStep =
+  | "welcome"
+  | "select-provider"
+  | "api-key-info"
+  | "enter-key"
+  | "validating"
+  | "complete";
+
+interface SetupWizardProps {
+  onComplete: () => void;
+  onError: (error: string) => void;
+}
+
+export function SetupWizard({ onComplete, onError }: SetupWizardProps) {
+  const [step, setStep] = useState<WizardStep>("welcome");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [selectedProvider, setSelectedProvider] = useState<ProviderInfo | null>(
+    null,
+  );
+  const [apiKey, setApiKey] = useState("");
+
+  const enabledProviders = getEnabledProviders();
+
+  useInput((input, key) => {
+    if (step === "welcome") {
+      if (key.return) {
+        setStep("select-provider");
+      }
+    } else if (step === "select-provider") {
+      if (key.upArrow) {
+        setSelectedIndex((prev) => Math.max(0, prev - 1));
+      } else if (key.downArrow) {
+        setSelectedIndex((prev) =>
+          Math.min(enabledProviders.length - 1, prev + 1),
+        );
+      } else if (key.return) {
+        setSelectedProvider(enabledProviders[selectedIndex]!);
+        setStep("api-key-info");
+      }
+    } else if (step === "api-key-info") {
+      if (key.return) {
+        setStep("enter-key");
+      }
+    }
+  });
+
+  const handleKeySubmit = async (value: string) => {
+    if (!selectedProvider || !value.trim()) {
+      return;
+    }
+
+    setApiKey(value);
+    setStep("validating");
+
+    try {
+      const isValid = await loginProvider(selectedProvider.id, value.trim());
+
+      if (!isValid) {
+        onError("Invalid API key. Please try again.");
+        setStep("enter-key");
+        setApiKey("");
+        return;
+      }
+
+      // Save configuration
+      const config = await getConfig();
+      config.defaultProvider = selectedProvider.id;
+      config.providers[selectedProvider.id].apiKey = value.trim();
+      await saveConfig(config);
+
+      setStep("complete");
+      setTimeout(onComplete, 1000);
+    } catch (error) {
+      onError(
+        error instanceof Error
+          ? `Validation failed: ${error.message}`
+          : "Network error. Please check your connection and try again.",
+      );
+      setStep("enter-key");
+      setApiKey("");
+    }
+  };
+
+  if (step === "welcome") {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Text bold color="cyan">
+          Welcome to Woopcode!
+        </Text>
+        <Text dimColor> </Text>
+        <Text>You'll need an AI provider to use Woopcode.</Text>
+        <Text>We'll only ask for this once.</Text>
+        <Text dimColor> </Text>
+        <Text dimColor>Press Enter to continue...</Text>
+      </Box>
+    );
+  }
+
+  if (step === "select-provider") {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Text bold>Select an AI provider:</Text>
+        <Text dimColor> </Text>
+        {enabledProviders.map((provider, index) => (
+          <Box key={provider.id} flexDirection="column">
+            <Text color={index === selectedIndex ? "cyan" : undefined}>
+              {index === selectedIndex ? "❯ " : "  "}
+              {provider.name}
+            </Text>
+            {index === selectedIndex && (
+              <Text dimColor> {provider.description}</Text>
+            )}
+          </Box>
+        ))}
+        <Text dimColor> </Text>
+        <Text dimColor>Use ↑↓ arrows to select, Enter to confirm</Text>
+      </Box>
+    );
+  }
+
+  if (step === "api-key-info" && selectedProvider) {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Text bold color="cyan">
+          Setting up {selectedProvider.name}
+        </Text>
+        <Text dimColor> </Text>
+        <Text>You can create a free API key at:</Text>
+        <Text color="blue" underline>
+          {selectedProvider.keyUrl}
+        </Text>
+        <Text dimColor> </Text>
+        <Text dimColor>Press Enter once you have it...</Text>
+      </Box>
+    );
+  }
+
+  if (step === "enter-key" && selectedProvider) {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Text bold>Paste your {selectedProvider.name} API key:</Text>
+        <Text dimColor> </Text>
+        <Box>
+          <Text dimColor>Key: </Text>
+          <TextInput
+            value={apiKey}
+            onChange={setApiKey}
+            onSubmit={handleKeySubmit}
+            placeholder="Enter your API key..."
+            mask="*"
+          />
+        </Box>
+        <Text dimColor> </Text>
+        <Text dimColor>Press Enter to validate</Text>
+      </Box>
+    );
+  }
+
+  if (step === "validating") {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Box>
+          <Text color="cyan">
+            <Spinner type="dots" />
+          </Text>
+          <Text> Validating API key...</Text>
+        </Box>
+      </Box>
+    );
+  }
+
+  if (step === "complete") {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Text color="green">✓ API key verified</Text>
+        <Text color="green">✓ Configuration saved</Text>
+        <Text dimColor> </Text>
+        <Text>Starting Woopcode...</Text>
+      </Box>
+    );
+  }
+
+  return null;
+}

package/onboarding/test-reset.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+/**
+ * Utility script to reset provider configuration for testing onboarding.
+ * 
+ * Usage:
+ *   bun onboarding/test-reset.ts           # Clear all API keys
+ *   bun onboarding/test-reset.ts restore   # Restore from backup
+ */
+
+import { existsSync } from "fs";
+
+const CONFIG_PATH = "./config/providers.json";
+const BACKUP_PATH = "./config/providers.json.backup";
+
+const command = process.argv[2];
+
+async function clearKeys() {
+  // Backup current config
+  if (existsSync(CONFIG_PATH)) {
+    const current = await Bun.file(CONFIG_PATH).text();
+    await Bun.write(BACKUP_PATH, current);
+    console.log("✓ Backed up current configuration");
+  }
+
+  // Clear all API keys
+  const config = JSON.parse(await Bun.file(CONFIG_PATH).text());
+  
+  for (const provider in config.providers) {
+    config.providers[provider].apiKey = "";
+  }
+
+  await Bun.write(CONFIG_PATH, JSON.stringify(config, null, 2));
+  console.log("✓ Cleared all API keys");
+  console.log("\nYou can now test the onboarding flow:");
+  console.log("  bun cli.ts");
+  console.log("\nTo restore your keys:");
+  console.log("  bun onboarding/test-reset.ts restore");
+}
+
+async function restore() {
+  if (!existsSync(BACKUP_PATH)) {
+    console.error("✖ No backup found");
+    process.exit(1);
+  }
+
+  const backup = await Bun.file(BACKUP_PATH).text();
+  await Bun.write(CONFIG_PATH, backup);
+  console.log("✓ Restored configuration from backup");
+}
+
+if (command === "restore") {
+  await restore();
+} else {
+  await clearKeys();
+}