Metadata-Version: 2.4
Name: alextechhq-promptetheus
Version: 0.1.0
Summary: CLI for fetching, filling and copying AI prompt templates from Promptetheus
Author-email: alextechhq <alex@alextechhq.com>
License: MIT
Project-URL: Homepage, https://promptetheus.com
Project-URL: Source, https://github.com/hashtag32/promptetheus
Project-URL: Bug Tracker, https://github.com/hashtag32/promptetheus/issues
Keywords: prompt,ai,cli,promptetheus,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Promptetheus

A Next.js + Supabase SaaS for creating, sharing, and discovering AI prompt templates.

---

## Tech Stack

- **Next.js 15** (App Router) + TypeScript
- **Supabase** (Postgres, Auth, RLS)
- **Tailwind CSS** + shadcn/ui
- **Recharts** for analytics
- **Vercel** for hosting

---

## Local Development

```bash
# 1. Install deps
pnpm install

# 2. Start local Supabase (Docker required)
pnpm dev:supabase        # or: supabase start

# 3. Start Next.js dev server (uses .env.local)
pnpm dev:next

# Or start both together:
pnpm dev:local           # runs scripts/dev-local.sh
```

**`.env.local`** — copy the values from `supabase status` after `supabase start`:

```env
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_...
SUPABASE_SERVICE_ROLE_KEY=sb_secret_...
```

---

## Vercel Development (`vercel dev`)

> ⚠️ **Important**: `vercel dev` downloads your Vercel project's environment variables from the Vercel dashboard and injects them **before** Next.js boots. This means **`.env.local` is completely ignored** — the app will always hit the **remote** Supabase.

Use `pnpm dev:next` when you want to work against the local Supabase instance.

---

## E2E Tests (Playwright)

Tests live in `tests/e2e/` and run against the local dev server and local Supabase.

**Prerequisites**: Dev server must be running (`pnpm dev:local`) and local Supabase must be up.

```bash
# Run all tests headlessly (CI-friendly)
pnpm test             # or: pnpm exec playwright test

# Run with the Playwright interactive UI (step-through, trace viewer)
pnpm test:ui

# Run in headed browser (watch the browser open)
pnpm test:headed

# Run a specific test file
pnpm exec playwright test tests/e2e/01-library-upvote.spec.ts --project=chromium

# Show the last HTML report
pnpm exec playwright show-report
```

**Test files**:

| File | What it tests |
|---|---|
| `01-library-upvote.spec.ts` | Upvote a community prompt → appears in Starred |
| `02-create-prompt.spec.ts` | Create a prompt → appears in My Prompts |
| `03-delete-prompt.spec.ts` | Delete a prompt → removed from My Prompts |
| `04-saves-reflect-in-stats.spec.ts` | Another user saves a prompt → `stat_saves` increments |
| `05-authorization.spec.ts` | Auth guards redirect to `/login`; Supabase RLS enforced |
| `06-prompt-detail.spec.ts` | `/prompt/[id]` renders without React hooks errors |

Each test uses `createTestUser` / `deleteTestUser` helpers that create and clean up isolated Supabase auth users. If a test fails mid-run and leaves stale users, subsequent runs auto-detect and delete them before re-creating.

---

## `pt` CLI

`pt` is a zero-dependency CLI (pure Python ≥ 3.10, stdlib only) for fetching, filling, and copying AI prompt templates from the command line.

### Installation

**From PyPI (recommended):**

```bash
pipx install alextechhq-promptetheus
```

> [pipx](https://pipx.pypa.io) manages an isolated venv automatically — no manual venv setup needed.  
> Install pipx: `sudo apt install pipx && pipx ensurepath` (Debian/Ubuntu) · `brew install pipx` (macOS)

**Alternative — pip in a venv:**

```bash
python3 -m venv ~/.venv/pt
~/.venv/pt/bin/pip install alextechhq-promptetheus
# Add ~/.venv/pt/bin to your PATH
```

**From source:**

```bash
pipx install git+https://github.com/hashtag32/promptetheus.git
```

### First-time setup

Run once to save the product credentials to `~/.config/pt/config.json`:

```bash
pt init
```

### Authentication

```bash
pt login     # sign in with your Promptetheus account
pt logout    # remove the local session
pt whoami    # show current user and token expiry
```

### Usage

```bash
# List all your prompts (shows stable #ID and required variables)
pt list
pt list --cat=debugging

# Get a prompt by stable numeric ID — copies template to clipboard
pt get 3
pt get 3 --no-copy       # print only, don't copy

# Get by text — shows all matches if ambiguous
pt get youtube

# Fill variables and copy to clipboard
pt fill 8 topic="How to become an AI engineer"

# Alias: fill + copy
pt copy 8 topic="How to become an AI engineer"

# Search by title or description
pt search "debugging"

# Pipe to another tool
pt fill 8 topic="AI tools" | llm
pt get 3 > prompt.txt
```

### Security model

| Credential | What it is | Where it lives |
|---|---|---|
| `PT_SUPABASE_URL` | Fixed product URL (same for all users) | `~/.config/pt/config.json` (written by `pt init`) |
| `PT_ANON_KEY` | Shared, **public** project anon key | `~/.config/pt/config.json` (written by `pt init`) |
| Access token | User-specific JWT from Supabase Auth | `~/.config/pt/session.json` (mode 0600) |
| Refresh token | Used to silently refresh the access token | `~/.config/pt/session.json` (mode 0600) |

The anon key is not a secret — it is the same key the website sends in every browser request and cannot bypass Row-Level Security policies.

Config resolution order (highest → lowest priority):

1. Environment variables (`PT_SUPABASE_URL`, `PT_ANON_KEY`)
2. `~/.config/pt/config.json` — set by `pt init`
3. `.env.local` / `.env.remote` / `.env` — repo-level dev fallbacks

### Contributing

```bash
git clone https://github.com/hashtag32/promptetheus.git
cd promptetheus
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

PRs welcome. Please keep the CLI dependency-free (stdlib only).

---

## MCP Endpoint (Model Context Protocol)

The app exposes a read-only MCP endpoint for IDE integrations (e.g. VS Code Copilot, Cursor):

```
GET /api/mcp/prompts
```

Returns all static prompts as JSON:

```json
[
  {
    "name": "YouTube Script Generator",
    "description": "...",
    "variables": ["topic", "length"],
    "template": "Act as a YouTube scriptwriter..."
  }
]
```

### VS Code Copilot integration

Add to your VS Code settings (`settings.json`) or `.vscode/settings.json`:

```json
{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "url": "http://localhost:3000/api/mcp/prompts"
    }
  ]
}
```

Or configure as an MCP server if your tool supports the protocol directly (e.g. Cursor, Continue.dev).

---



Migrations live in `supabase/migrations/`. They run in filename-timestamp order.

```bash
# Apply pending migrations to remote (linked project)
supabase db push

# Check migration status (local vs remote)
supabase migration list

# Apply SQL to local DB only (no migration file created)
supabase db query "ALTER TABLE ..."

# Reset local DB and replay all migrations
supabase db reset
```

**Schema cache**: After schema changes, Supabase PostgREST needs to reload its schema cache. If you get `PGRST205 – table not found`, the migration hasn't run on the target environment yet (local vs. remote mismatch). Run `supabase db push` to push to remote.

---

## Key Lessons Learned

| Problem | Cause | Fix |
|---|---|---|
| `user_prompts` table not found | Table existed locally only; app was hitting remote via `vercel dev` | `supabase db push` to sync migration to remote |
| `vercel dev` ignores `.env.local` | Vercel CLI injects remote env vars first | Use `pnpm dev:next` for local Supabase dev |
| `PGRST205` after migration | Schema cache not refreshed | Supabase auto-refreshes; or restart with `supabase stop && supabase start` |
| RLS blocking inserts | Missing `WITH CHECK` clause on INSERT policy | Always pair `USING` (SELECT/DELETE) with `WITH CHECK` (INSERT/UPDATE) |
| Old catch-all `ALL` policy conflicts | Existing `Users manage own prompts` policy overlapped new scoped policies | Drop old policies before creating per-operation ones |

---

## Project Structure

```
app/
  api/               # Route handlers (auth, saved-prompts, etc.)
  dashboard/
    create/          # Create prompt form
    my-prompts/
      [id]/          # Edit prompt + analytics
    saved/           # Saved prompts
    settings/
components/
  dashboard-create-page-client.tsx   # Create form
  dashboard-edit-prompt-client.tsx   # Edit form + delete + analytics tabs
  prompt-card.tsx                    # Reusable prompt card (hideActions prop)
  prompt-stats-panel.tsx             # Analytics chart panel
lib/
  prompts.ts         # Types, model definitions, category labels
  supabase.ts        # Supabase client (anon key, session-managed auth)
  auth-context.tsx   # Auth React context
supabase/
  migrations/        # SQL migration files (applied in order)
```

