alextechhq-promptetheus 0.1.0

CLI for fetching, filling and copying AI prompt templates from Promptetheus

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

# 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:

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.

# 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):

pipx install alextechhq-promptetheus

pipx 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:

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

From source:

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

First-time setup

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

pt init

Authentication

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

Usage

# 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

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:

[
  {
    "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:

{
  "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.

# 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)