popeye-cli 1.1.0 → 1.2.0

package/.env.example

@@ -5,14 +5,37 @@
 # Get your key from: https://platform.openai.com/api-keys
 POPEYE_OPENAI_KEY=
 
+# Gemini API Key (optional - can also use keychain)
+# Get your key from: https://aistudio.google.com/app/apikey
+POPEYE_GEMINI_KEY=
+
+# Grok API Key (optional - can also use keychain)
+# Get your key from: https://console.x.ai/
+POPEYE_GROK_KEY=
+
 # Default output language for generated projects
-# Options: python, typescript
+# Options: python, typescript, fullstack
 POPEYE_DEFAULT_LANGUAGE=python
 
 # Default OpenAI model for consensus reviews
 # Options: gpt-4o, gpt-4o-mini, gpt-4-turbo, o1-preview, o1-mini
 POPEYE_OPENAI_MODEL=gpt-4o
 
+# Default Gemini model (optional)
+POPEYE_GEMINI_MODEL=gemini-2.0-flash
+
+# Default Grok model (optional)
+# Common models: grok-3, grok-2
+POPEYE_GROK_MODEL=grok-3
+
+# Consensus reviewer provider
+# Options: openai, gemini, grok
+POPEYE_CONSENSUS_REVIEWER=openai
+
+# Consensus arbitrator provider (for tie-breaking)
+# Options: openai, gemini, grok, off
+POPEYE_CONSENSUS_ARBITRATOR=off
+
 # Consensus threshold (percentage required for approval)
 # Default: 95
 POPEYE_CONSENSUS_THRESHOLD=95

package/CONTRIBUTING.md

@@ -0,0 +1,275 @@
+# Contributing to Popeye CLI
+
+First off, thank you for considering contributing to Popeye CLI! It's people like you that make Popeye such a great tool.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Pull Request Process](#pull-request-process)
+- [Style Guidelines](#style-guidelines)
+- [Testing](#testing)
+- [Questions?](#questions)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our commitment to providing a welcoming and inclusive environment. By participating, you are expected to:
+
+- Be respectful and considerate in your communication
+- Accept constructive criticism gracefully
+- Focus on what is best for the community
+- Show empathy towards other community members
+
+## Getting Started
+
+Popeye CLI is built with TypeScript and uses several AI providers (Claude, OpenAI, Gemini) for its consensus-based code generation workflow.
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+- API keys for at least one AI provider (Claude recommended)
+
+### Development Setup
+
+1. **Fork and clone the repository**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/popeye.git
+   cd popeye
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Set up environment variables**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys
+   ```
+
+4. **Build the project**
+   ```bash
+   npm run build
+   ```
+
+5. **Run tests**
+   ```bash
+   npm test
+   ```
+
+6. **Link for local development**
+   ```bash
+   npm link
+   # Now you can run 'popeye' command locally
+   ```
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues to avoid duplicates. When you create a bug report, include as many details as possible:
+
+- **Use a clear and descriptive title**
+- **Describe the exact steps to reproduce the problem**
+- **Provide specific examples** (project idea, configuration, etc.)
+- **Describe the behavior you observed and what you expected**
+- **Include logs** from `~/.popeye/logs/` if available
+- **Include your environment** (OS, Node version, npm version)
+
+### Suggesting Features
+
+Feature suggestions are welcome! Please provide:
+
+- **A clear and descriptive title**
+- **Detailed description of the proposed feature**
+- **Explain why this feature would be useful** to most users
+- **List any alternatives you've considered**
+
+### Your First Code Contribution
+
+Unsure where to begin? Look for issues labeled:
+
+- `good first issue` - Good for newcomers
+- `help wanted` - Extra attention needed
+- `documentation` - Improvements to docs
+
+### Areas We'd Love Help With
+
+- **New AI Provider Adapters** - Add support for more AI providers
+- **Language Support** - Extend beyond TypeScript/Python
+- **UI Components** - Add more shadcn/ui components to the setup
+- **Testing** - Improve test coverage
+- **Documentation** - Tutorials, examples, translations
+- **Bug Fixes** - Check the issues page
+
+## Pull Request Process
+
+1. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes**
+   - Write clear, readable code
+   - Add tests for new functionality
+   - Update documentation as needed
+
+3. **Test your changes**
+   ```bash
+   npm run build
+   npm test
+   npm run lint
+   ```
+
+4. **Commit with a clear message**
+   ```bash
+   git commit -m "feat: add support for X"
+   ```
+
+   We follow [Conventional Commits](https://www.conventionalcommits.org/):
+   - `feat:` - New feature
+   - `fix:` - Bug fix
+   - `docs:` - Documentation only
+   - `style:` - Formatting, no code change
+   - `refactor:` - Code change that neither fixes a bug nor adds a feature
+   - `test:` - Adding or updating tests
+   - `chore:` - Maintenance tasks
+
+5. **Push and create a Pull Request**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **In your PR description**
+   - Describe what changes you made and why
+   - Reference any related issues (`Fixes #123`)
+   - Include screenshots for UI changes
+   - Note any breaking changes
+
+## Style Guidelines
+
+### TypeScript
+
+- Use TypeScript strict mode
+- Prefer `const` over `let`, avoid `var`
+- Use meaningful variable and function names
+- Add JSDoc comments for public functions
+- Keep functions focused and small
+
+```typescript
+/**
+ * Generate a development plan from a specification
+ *
+ * @param spec - The project specification
+ * @param context - Additional context for planning
+ * @returns The generated plan
+ */
+export async function createPlan(
+  spec: string,
+  context: string
+): Promise<string> {
+  // Implementation
+}
+```
+
+### File Organization
+
+```
+src/
+├── adapters/      # AI provider integrations
+├── auth/          # Authentication handling
+├── cli/           # CLI commands and interface
+├── config/        # Configuration management
+├── generators/    # Project scaffolding
+├── state/         # State management
+├── types/         # TypeScript type definitions
+└── workflow/      # Core workflow logic
+```
+
+### Formatting
+
+We use Prettier for code formatting:
+
+```bash
+npm run format
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Writing Tests
+
+- Place tests in `tests/` directory mirroring `src/` structure
+- Use descriptive test names
+- Test both success and failure cases
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { myFunction } from '../src/myModule';
+
+describe('myFunction', () => {
+  it('should return expected result for valid input', () => {
+    const result = myFunction('valid input');
+    expect(result).toBe('expected output');
+  });
+
+  it('should throw error for invalid input', () => {
+    expect(() => myFunction('')).toThrow('Invalid input');
+  });
+});
+```
+
+## Project Architecture
+
+Understanding the codebase:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLI Layer                             │
+│  (cli/commands/*.ts - User interaction)                     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Workflow Layer                           │
+│  (workflow/*.ts - Plan mode, Execution mode, Consensus)     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Adapter Layer                            │
+│  (adapters/*.ts - Claude, OpenAI, Gemini)                   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      State Layer                             │
+│  (state/*.ts - Project state, persistence)                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Questions?
+
+Feel free to:
+
+- Open an issue for questions
+- Start a discussion on GitHub
+- Reach out to maintainers
+
+Thank you for contributing to Popeye CLI!

package/OPEN_SOURCE_MANIFESTO.md

@@ -0,0 +1,172 @@
+# Popeye CLI – Open Source Manifesto
+
+## Why Popeye Exists
+
+Popeye was built out of frustration.
+
+Not with coding itself — but with everything that blocks coding:
+
+- endless project setup
+- boilerplate before logic
+- tooling debates before value
+- unfinished ideas piling up in repos
+
+We believe ideas should turn into working software faster.
+And modern AI makes that possible — if used responsibly, transparently, and collaboratively.
+
+**Popeye exists to remove friction between intention and execution.**
+
+---
+
+## What Popeye Is (and Is Not)
+
+**Popeye is:**
+
+- an AI-powered CLI that turns plain-English ideas into real projects
+- a system that plans, reviews, builds, tests, and fixes code automatically
+- a developer tool focused on production-ready outcomes
+- an open, inspectable, hackable codebase
+
+**Popeye is not:**
+
+- a black-box "magic" code generator
+- a replacement for developers
+- a closed SaaS disguised as open source
+- a shortcut that hides complexity instead of managing it
+
+We believe developers stay in control.
+AI is a collaborator — not an oracle.
+
+---
+
+## Core Principles
+
+### 1. Open by Default
+
+Popeye is:
+
+- open source
+- publicly auditable
+- forkable
+- extensible
+
+If it runs on your machine, you should be able to:
+
+- read it
+- modify it
+- improve it
+- disagree with it
+
+No hidden logic. No locked workflows.
+
+### 2. Humans Own the Vision, AI Does the Heavy Lifting
+
+Popeye assumes:
+
+- humans define what should be built
+- AI helps decide how to build it
+- humans always have the final say
+
+You describe intent.
+Popeye handles the grind.
+
+### 3. Opinions Are Explicit, Not Hidden
+
+Every tool has opinions.
+
+Popeye:
+
+- encodes its assumptions openly
+- documents why decisions are made
+- welcomes debate and alternative approaches
+
+If you disagree with a default:
+
+- change it
+- propose an improvement
+- fork it
+
+Open source thrives on disagreement done well.
+
+### 4. Quality Over Demos
+
+Popeye prioritizes:
+
+- clean project structure
+- testable code
+- predictable builds
+- real developer workflows
+
+This is not about generating screenshots.
+It's about generating maintainable software.
+
+### 5. Community > Perfection
+
+Popeye will evolve in public.
+
+That means:
+
+- some rough edges
+- ongoing refactors
+- design discussions in the open
+
+We value:
+
+- contributors over polish
+- feedback over silence
+- progress over purity
+
+---
+
+## How You Can Contribute
+
+You don't need to be an AI expert to help.
+
+You can:
+
+- improve prompts or planning logic
+- add frontend or backend templates
+- extend language or framework support
+- improve test strategies
+- tighten docs and examples
+- report bugs or weird behavior
+- challenge architectural decisions
+
+If you've ever thought:
+
+> "I wish dev tools worked this way instead…"
+
+Popeye wants your opinion.
+
+---
+
+## The Long-Term Vision
+
+We believe the future of software looks like this:
+
+- ideas → specs → code → tests → running apps
+- fewer abandoned repos
+- fewer "weekend projects" that never start
+- more people shipping things they actually care about
+
+Popeye is one step in that direction.
+
+Not the final answer — but an open experiment.
+
+---
+
+## An Invitation
+
+If this resonates with you:
+
+- Star the repo
+- Try it
+- Break it
+- Fix it
+- Open discussions
+- Build with us
+
+Open source doesn't grow because code is perfect.
+It grows because people feel welcome to shape it.
+
+**Welcome aboard.**