npm package: @gace/vaac
Description: Vibe as a Code - AI-powered code generation at build time
Latest version: 0.1.0

# VAAC - Vibe as a Code

**Keep AI-generated code separate from human code.**

Versioned. Reviewable. Reproducible.

---

## The Problem

AI-generated code is everywhere, but it's a mess:
- ChatGPT snippets copy-pasted inline
- Copilot suggestions scattered across files  
- No way to track what's AI vs human
- Impossible to audit or review

**VAAC fixes this.** All AI-generated code lives in one place: the `.ai/` directory.

---

## How It Works

```
your-project/
├── src/
│   └── utils.ts           ← You write the prompt here
└── .ai/
    └── slugify-01.ts      ← AI generates code here
```

**1. Annotate your function:**

```typescript
import { Ai } from '@gace/vaac';

@Ai({
  id: 'slugify-01',
  prompt: 'Convert text to URL-friendly slug. Lowercase, replace spaces with dashes, remove special characters.'
})
export function slugify(text: string): string {}
```

**2. Run your build:**

```bash
npm run build
```

**3. VAAC generates `.ai/slugify-01.ts`:**

```typescript
export function slugify(text: string): string {
  return text
    .toLowerCase()
    .trim()
    .replace(/[^\w\s-]/g, '')
    .replace(/\s+/g, '-');
}
```

**4. At build time, your function body is replaced with the generated code.**

Your source stays clean. AI code stays separate.

---

## Installation

```bash
npm install @gace/vaac
```

Add to your `vite.config.ts`:

```typescript
import { defineConfig } from 'vite';
import { vaac } from '@gace/vaac/vite';
import 'dotenv/config';

export default defineConfig({
  plugins: [
    vaac({
      model: 'openai/gpt-4-turbo',
      verbose: true,        // Optional: enable debug logging
      // apiKey: '...',     // Optional: auto-detects from env vars
    }),
  ],
});
```

Create a `.env` file with your API key:

```
# OpenRouter (recommended - access to multiple models)
OPENROUTER_API_KEY=sk-or-...

# Or use OpenAI directly
# OPENAI_API_KEY=sk-...
```

---

## Philosophy

> As AI-generated code becomes ubiquitous, mixing it with human-written code creates chaos - hard to track, hard to audit, hard to manage.
>
> **VAAC isolates AI code.** Every generated function lives in `.ai/`, committed to Git, reviewed like any other code. Your human code stays clean.

---

## Key Features

| Feature | Description |
|---------|-------------|
| **Separation** | AI code in `.ai/`, human code everywhere else |
| **Versioned** | Generated files are committed to Git |
| **Reproducible** | Same commit = same build output |
| **CI-safe** | Build fails if `.ai/` files are missing - no surprise AI calls |
| **Zero runtime** | Generated code is compiled in, no runtime dependency |
| **Editable** | Don't like the AI output? Edit `.ai/` files directly |

---

## Developer Flow

| Action | How |
|--------|-----|
| **Generate code** | Run `npm run build` - missing `.ai/` files are created |
| **Review AI code** | Open `.ai/[id].ts` - it's just TypeScript |
| **Edit AI code** | Modify `.ai/[id].ts` directly - your changes persist |
| **Regenerate** | Delete `.ai/[id].ts` and rebuild |
| **Commit** | Add both source and `.ai/` files to Git |

---

## Configuration

```typescript
vaac({
  // AI model (default: gpt-4-turbo)
  model: 'openai/gpt-4-turbo',
  
  // Output directory (default: .ai)
  outputDir: '.ai',
  
  // Enable debug logging (default: false)
  verbose: true,
  
  // API key - auto-detects from env vars
  // Priority: OPENROUTER_API_KEY > OPENAI_API_KEY
  // Or pass explicitly:
  // apiKey: process.env.OPENROUTER_API_KEY,
  
  // CI mode: error if files missing instead of generating
  ciMode: process.env.CI === 'true',
})
```

---

## License

MIT

---

Built with the belief that **AI and human code shouldn't mix.**