ai-wingman 0.0.2

package/README.md

@@ -0,0 +1,231 @@
+# ai-wingman
+
+Scaffold production-ready AI patterns into your existing Next.js app — one command per pattern.
+
+```bash
+npx ai-wingman add chat
+```
+
+ai-wingman wires together the right SDK primitives, generates plain TypeScript files you own, and exits. There is no runtime dependency on ai-wingman after scaffolding.
+
+---
+
+## Patterns
+
+| Command | Core primitive | What you get |
+|---------|---------------|-------------|
+| `wingman add chat` | `streamText` | Streaming chat route, conversation storage, multi-turn page |
+| `wingman add structured-output` | `generateText + Output.object` | Typed JSON route, Zod schema, React hook |
+| `wingman add tools` | `streamText + tools` | Tool-calling route, typed tool stubs |
+| `wingman add stream-object` | `streamObject + useObject` | Streaming structured JSON route and hook |
+| `wingman add rag` | `embed + cosineSimilarity` | Embed route, query route, vector store, client hook |
+| `wingman add interrupt` | `tool({ needsApproval: true }) + addToolApprovalResponse` | Human-in-the-loop approval route, widget, page |
+| `wingman add agent` | `streamText + stopWhen: stepCountIs(N)` | Autonomous agent route, tool stubs, storage, page |
+| `wingman add multimodal` | `convertToModelMessages` | Vision-aware chat route and page with image upload |
+| `wingman add audio` | `experimental_transcribe` / `experimental_generateSpeech` | Transcription route, TTS route, recording page |
+| `wingman add eval` | `generateText` (LLM judge) | Runnable eval script with string-match and judge scoring |
+| `wingman add image-gen` | `generateImage` | Prompt-to-image route (DALL·E), display page with download |
+| `wingman add generative-ui` | `streamUI` (ai/rsc) | Server action that streams React component trees to the client |
+| `wingman add document-processing` | `generateText + Output.object` | File upload route, schema, and hook for PDF / document extraction |
+
+---
+
+## Quick start
+
+Run inside an existing Next.js + TypeScript project:
+
+```bash
+npx ai-wingman add chat
+```
+
+The CLI will:
+
+1. Detect Next.js, TypeScript, and shadcn/ui prerequisites
+2. Ask which provider (Anthropic / OpenAI / Google)
+3. Ask pattern-specific questions (storage, auth, output paths)
+4. Show the full plan and ask for confirmation
+5. Install packages, run `npx ai-elements@latest` and `npx shadcn@latest add`
+6. Write your files
+7. Print the env vars you need to set
+
+---
+
+## CLI commands
+
+```bash
+wingman add <pattern>               # scaffold a pattern interactively
+wingman list                        # list all available patterns
+wingman add <pattern> --overwrite   # re-scaffold, overwriting existing files
+```
+
+Pass flags to skip prompts. `-y` / `--yes` accepts all defaults.
+
+```bash
+# Fully non-interactive
+npx ai-wingman add chat --provider anthropic --storage memory --yes
+
+# Custom output paths
+npx ai-wingman add chat --provider anthropic --api-route app/api/assistant/route.ts --yes
+
+# Different storage backend
+npx ai-wingman add rag --provider openai --storage pgvector --yes
+
+# Re-scaffold after an update
+npx ai-wingman add chat --provider anthropic --overwrite --yes
+```
+
+---
+
+## Providers
+
+| Flag | Package installed | Env var |
+|------|------------------|---------|
+| `anthropic` | `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY` |
+| `openai` | `@ai-sdk/openai` | `OPENAI_API_KEY` |
+| `google` | `@ai-sdk/google` | `GOOGLE_GENERATIVE_AI_API_KEY` |
+
+---
+
+## Common flags
+
+| Flag | Applies to | Description |
+|------|-----------|-------------|
+| `--provider <id>` | all | `anthropic` / `openai` / `google` |
+| `--auth` | all | Include NextAuth v5 session check (default: off) |
+| `--no-page` | patterns with pages | Omit the generated page component |
+| `--storage <id>` | `rag` | `memory` / `sqlite` / `pgvector` |
+| `--storage memory` | `chat` | Include conversation storage (default: off) |
+| `--interrupt` | `chat` | Embed a human-in-the-loop approval gate in the chat route |
+| `--stream` | `rag` | Use `streamText` instead of `generateText` in query route |
+| `--schema-name <name>` | `structured-output`, `stream-object` | Name for the schema, hook, and type |
+| `--no-hook` | `structured-output`, `stream-object` | Omit the generated client hook |
+| `--tool-name <name>` | `tools` | Name for the generated tool stub file |
+| `--image-model <model>` | `image-gen` | `dall-e-3` (default) or `dall-e-2` |
+| `--overwrite` | all | Overwrite existing files without prompting |
+| `-y, --yes` | all | Accept all defaults |
+
+---
+
+## File conflict handling
+
+Before writing each file, the CLI checks if it already exists:
+
+- If taken, a warning appears inline
+- You can overwrite, enter a different path, or skip the component
+- `--overwrite` bypasses this prompt silently
+- The CLI never silently overwrites without permission
+
+---
+
+## Prerequisites
+
+| Requirement | Check | Auto-install |
+|-------------|-------|-------------|
+| React in `package.json` | Required — exits if missing | No |
+| `tsconfig.json` | Required — exits if missing | No |
+| shadcn/ui (`components.json`) | Required for page components | Prompted |
+
+---
+
+## Development
+
+### Local dev loop
+
+```bash
+# 1. Build and link the CLI globally (run once)
+bash scripts/dev-link.sh
+
+# 2. Start watch mode
+pnpm --filter ai-wingman watch
+
+# 3. Create a fresh test project
+bash scripts/new-fixture.sh
+cd /tmp/wingman-fixture
+
+# 4. Run against it
+ai-wingman add chat --provider anthropic --storage memory --yes
+```
+
+Or point directly at the built binary from any project:
+
+```bash
+node /path/to/wingman/packages/ai-wingman/dist/wingman.js add chat --yes
+```
+
+### Tests
+
+```bash
+pnpm --filter ai-wingman test
+```
+
+330 tests across all 13 generators. Generators are pure `(config) => string` functions — fast, deterministic, snapshot-tested.
+
+### Project structure
+
+```
+packages/ai-wingman/
+├── bin/
+│   └── wingman.ts              # CLI entry point (commander)
+├── src/
+│   ├── types.ts                # Config types for all patterns
+│   ├── registry/
+│   │   ├── providers.ts        # Anthropic, OpenAI, Google
+│   │   ├── storage-adapters.ts
+│   │   ├── patterns.ts         # Pattern registry + resolvers
+│   │   └── index.ts
+│   ├── generators/             # Pure (config) => string functions
+│   ├── patterns/               # One dir per pattern
+│   │   ├── chat/
+│   │   ├── structured-output/
+│   │   ├── tools/
+│   │   ├── stream-object/
+│   │   ├── rag/
+│   │   ├── interrupt/
+│   │   ├── agent/
+│   │   ├── multimodal/
+│   │   ├── audio/
+│   │   ├── eval/
+│   │   ├── image-gen/
+│   │   ├── generative-ui/
+│   │   └── document-processing/
+│   ├── commands/
+│   │   ├── add/                # Main orchestrator
+│   │   └── list/
+│   ├── planner/                # Builds ExecutionPlan before writing
+│   ├── steps/                  # Shared interactive steps
+│   └── utils/
+└── tests/
+    └── unit/generators/        # Snapshot tests per generator
+```
+
+### Adding a provider
+
+Add an entry to `src/registry/providers.ts`:
+
+```ts
+{
+  id: 'mistral',
+  label: 'Mistral',
+  package: '@ai-sdk/mistral',
+  importName: 'mistral',
+  envVar: 'MISTRAL_API_KEY',
+  defaultModel: 'mistral-large-latest',
+  modelFactory: 'mistral("mistral-large-latest")',
+}
+```
+
+No other changes needed — the prompt and all generators pick it up automatically.
+
+### Adding a pattern
+
+1. Create `src/patterns/<name>/index.ts` implementing the `Pattern` interface
+2. Add `prompt-config.ts` and `execute.ts` alongside it
+3. Add generators to `src/generators/` as needed
+4. Register the pattern in `src/registry/patterns.ts`
+5. Add snapshot tests in `tests/unit/generators/<name>.test.ts`
+
+---
+
+## License
+
+MIT