Cursor rule

1---
2alwaysApply: true
3description: Core development principles for building PRPM (Prompt Package Manager)
4---
5 
6# PRPM Development Core Principles
7 
8You are developing PRPM (Prompt Package Manager), a universal package manager for AI prompts, agents, and cursor rules across all AI code editors.
9 
10## Mission
11 
12Build the npm/cargo/pip equivalent for AI development artifacts. Enable developers to discover, install, share, and manage prompts across Cursor, Claude Code, Continue, Windsurf, and future AI editors.
13 
14## Core Architecture Principles
15 
16### 1. Universal Format Philosophy
17- **Canonical Format**: All packages stored in a universal canonical format
18- **Smart Conversion**: Server-side format conversion with quality scoring
19- **Zero Lock-In**: Users can convert between any format without data loss
20- **Format-Specific Optimization**: IDE-specific variants (e.g., Claude MCP integrations)
21 
22### 2. Package Manager Best Practices
23- **Semantic Versioning**: Strict semver for all packages
24- **Dependency Resolution**: Smart conflict resolution like npm/cargo
25- **Lock Files**: Reproducible installs with version locking
26- **Registry-First**: All operations through central registry API
27- **Caching**: Redis caching for converted packages (1-hour TTL)
28 
29### 3. Developer Experience
30- **One Command Install**: `prpm install @collection/nextjs-pro` gets everything
31- **Auto-Detection**: Detect IDE from directory structure (.cursor/, .claude/)
32- **Format Override**: `--as claude` to force specific format
33- **Telemetry Opt-Out**: Privacy-first with easy opt-out
34- **Beautiful CLI**: Clear progress indicators and colored output
35 
36### 4. Registry Design
37- **GitHub OAuth**: Single sign-on, no password management
38- **Full-Text Search**: PostgreSQL GIN indexes + optional Elasticsearch
39- **Package Discovery**: Trending, featured, categories, tags
40- **Quality Metrics**: Download counts, stars, verified badges
41- **Analytics**: Track usage patterns while respecting privacy
42 
43### 5. Collections System
44- **Curated Bundles**: Official collections maintained by PRPM team
45- **IDE-Specific**: Different package variants per editor
46- **Required + Optional**: Core packages + optional enhancements
47- **Installation Order**: Sequential or parallel package installation
48- **Reason Documentation**: Every package explains why it's included
49 
50## Technical Stack
51 
52### CLI (TypeScript + Node.js)
53- **Commander.js**: CLI framework for commands
54- **Fastify Client**: HTTP client for registry API
55- **Tar**: Package tarball creation/extraction
56- **Chalk**: Terminal colors and formatting
57- **Ora**: Spinners for async operations
58 
59### Registry (TypeScript + Fastify + PostgreSQL)
60- **Fastify**: High-performance web framework
61- **PostgreSQL**: Primary database with triggers, views, GIN indexes
62- **Redis**: Caching layer for converted packages
63- **GitHub OAuth**: Authentication provider
64- **Docker**: Containerized deployment
65 
66### Testing
67- **Vitest**: Unit and integration tests
68- **100% Coverage Goal**: Especially for format converters
69- **Round-Trip Tests**: Ensure conversion quality
70- **Fixtures**: Real-world package examples
71 
72## Quality Standards
73 
74### Code Quality
75- **TypeScript Strict Mode**: No implicit any, strict null checks
76- **Error Handling**: Proper error messages with context
77- **Retry Logic**: Exponential backoff for network requests
78- **Input Validation**: Validate all user inputs and API responses
79 
80### Format Conversion
81- **Lossless When Possible**: Preserve all semantic information
82- **Quality Scoring**: 0-100 score for conversion quality
83- **Warnings**: Clear warnings about lossy conversions
84- **Round-Trip Testing**: Test canonical → format → canonical
85 
86### Security
87- **No Secrets in DB**: Never store GitHub tokens, use session IDs
88- **SQL Injection**: Parameterized queries only
89- **Rate Limiting**: Prevent abuse of registry API
90- **Content Security**: Validate package contents before publishing
91 
92## Development Workflow
93 
94### When Adding Features
951. **Check Existing Patterns**: Look at similar commands/routes
962. **Update Types First**: TypeScript interfaces drive implementation
973. **Write Tests**: Create test fixtures and cases
984. **Document**: Update README and relevant docs
995. **Telemetry**: Add tracking for new commands (with privacy)
100 
101### When Fixing Bugs
1021. **Write Failing Test**: Reproduce the bug in a test
1032. **Fix Minimally**: Smallest change that fixes the issue
1043. **Check Round-Trip**: Ensure conversions still work
1054. **Update Fixtures**: Add bug case to test fixtures
106 
107### When Designing APIs
108- **REST Best Practices**: Use proper HTTP methods and status codes
109- **Versioning**: All routes under `/api/v1/`
110- **Pagination**: Limit/offset for list endpoints
111- **Filtering**: Support query params for filtering
112- **OpenAPI**: Document with Swagger/OpenAPI specs
113 
114## Common Patterns
115 
116### CLI Command Structure
117```typescript
118export async function handleCommand(args: Args, options: Options) {
119  const startTime = Date.now();
120  try {
121    // 1. Load config
122    const config = await loadUserConfig();
123    const client = getRegistryClient(config);
124 
125    // 2. Fetch data
126    const result = await client.fetchData();
127 
128    // 3. Display results
129    console.log('✅ Success');
130 
131    // 4. Track telemetry
132    await telemetry.track({ command: 'name', success: true });
133  } catch (error) {
134    console.error('❌ Failed:', error.message);
135    await telemetry.track({ command: 'name', success: false });
136    process.exit(1);
137  }
138}
139```
140 
141### Registry Route Structure
142```typescript
143export async function routes(server: FastifyInstance) {
144  server.get('/:id', {
145    schema: { /* OpenAPI schema */ },
146  }, async (request, reply) => {
147    const { id } = request.params;
148 
149    // 1. Validate input
150    if (!id) return reply.code(400).send({ error: 'Missing ID' });
151 
152    // 2. Query database
153    const result = await server.pg.query('SELECT...');
154 
155    // 3. Return response
156    return result.rows[0];
157  });
158}
159```
160 
161### Format Converter Structure
162```typescript
163export function toFormat(pkg: CanonicalPackage): ConversionResult {
164  const warnings: string[] = [];
165  let qualityScore = 100;
166 
167  // Convert each section
168  const content = convertSections(pkg.content.sections, warnings);
169 
170  // Track lossy conversions
171  const lossyConversion = warnings.some(w => w.includes('not supported'));
172  if (lossyConversion) qualityScore -= 10;
173 
174  return { content, format: 'target', warnings, qualityScore, lossyConversion };
175}
176```
177 
178## Naming Conventions
179 
180- **Files**: kebab-case (`registry-client.ts`, `to-cursor.ts`)
181- **Types**: PascalCase (`CanonicalPackage`, `ConversionResult`)
182- **Functions**: camelCase (`getPackage`, `convertToFormat`)
183- **Constants**: UPPER_SNAKE_CASE (`DEFAULT_REGISTRY_URL`)
184- **Database**: snake_case (`package_id`, `created_at`)
185 
186## Documentation Standards
187 
188- **Inline Comments**: Explain WHY, not WHAT
189- **JSDoc**: Required for public APIs
190- **README**: Keep examples up-to-date
191- **Markdown Docs**: Use code blocks with language tags
192- **Changelog**: Follow Keep a Changelog format
193 
194## Performance Considerations
195 
196- **Batch Operations**: Use Promise.all for independent operations
197- **Database Indexes**: GIN for full-text, B-tree for lookups
198- **Caching Strategy**: Cache converted packages, not raw data
199- **Lazy Loading**: Don't load full package data until needed
200- **Connection Pooling**: Reuse PostgreSQL connections
201 
202Remember: PRPM is infrastructure. It must be rock-solid, fast, and trustworthy like npm or cargo.
203