Skip to content

Commit 0812fd9

Browse files
yannvryannvr
committed
chore: add .cursorrules and CLAUDE.md agent config
1 parent b1dd1f2 commit 0812fd9

2 files changed

Lines changed: 314 additions & 0 deletions

File tree

‎.cursorrules‎

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
# Auto-generated from AGENTS.md — do not edit directly
2+
# AGENTS.md - HyperPost
3+
4+
> Guidelines for AI agents working in this codebase.
5+
6+
## Project Overview
7+
8+
**HyperPost** is a unified social media posting CLI tool that publishes content to multiple social networks simultaneously. Built with TypeScript, it uses Prisma for database operations and supports Mastodon, Bluesky, Discord, Reddit, Dev.to, and Medium.
9+
10+
Part of the **HyperDrift** ecosystem - open-source tools for independent developers.
11+
12+
## Essential Commands
13+
14+
```bash
15+
# Package manager - ALWAYS use pnpm
16+
pnpm install # Install dependencies
17+
pnpm build # Build with tsup (outputs to dist/)
18+
pnpm dev # Watch mode development
19+
pnpm test # Run Jest tests
20+
pnpm lint # ESLint on src/**/*.ts
21+
pnpm typecheck # TypeScript type checking (tsc --noEmit)
22+
23+
# Database (Prisma with SQLite)
24+
pnpm db:generate # Generate Prisma client after schema changes
25+
pnpm db:push # Push schema to database
26+
pnpm db:studio # Open Prisma Studio GUI
27+
pnpm db:migrate # Create migrations for production
28+
29+
# CLI testing
30+
pnpm cli # Run CLI directly (node dist/cli.js)
31+
hyper-post setup # Interactive setup wizard
32+
hyper-post post -c "..." # Post to all platforms
33+
hyper-post platforms # List configured platforms
34+
```
35+
36+
## Project Structure
37+
38+
```
39+
src/
40+
├── HyperPost.ts # Main class - orchestrates multi-platform posting
41+
├── cli.ts # Commander-based CLI implementation
42+
├── database.ts # Prisma client singleton
43+
├── index.ts # Public API exports
44+
├── setup.ts # Interactive setup wizard
45+
├── signup-manager.ts # Manages credentials in ~/.config/hyper-post/
46+
├── signup-templates.ts # Platform signup requirements and templates
47+
├── platforms/
48+
│ ├── BasePlatform.ts # Abstract base class for all platforms
49+
│ ├── BlueskyPlatform.ts
50+
│ ├── MastodonPlatform.ts
51+
│ ├── DiscordPlatform.ts
52+
│ ├── RedditPlatform.ts
53+
│ ├── DevtoPlatform.ts
54+
│ ├── MediumPlatform.ts
55+
│ └── index.ts # Platform exports
56+
├── types/
57+
│ └── index.ts # TypeScript interfaces (SocialPost, PostingResult, etc.)
58+
└── utils/
59+
└── contentFormat.ts # MDX/Markdown detection and conversion for Medium
60+
61+
schema.prisma # Database schema (SQLite default)
62+
tsup.config.ts # Build configuration (CJS + ESM)
63+
```
64+
65+
## Architecture Patterns
66+
67+
### Platform Pattern
68+
69+
All platforms extend `BasePlatform` and implement:
70+
71+
```typescript
72+
abstract class BasePlatform {
73+
abstract get name(): string; // lowercase identifier
74+
abstract get displayName(): string; // human-readable name
75+
abstract post(content: SocialPost): Promise<PostingResult>;
76+
abstract gatherAnalytics(postUrl: string): Promise<PostAnalytics>;
77+
abstract discoverPosts(limit?: number): Promise<...>;
78+
protected abstract getRequiredCredentials(): string[];
79+
}
80+
```
81+
82+
### Adding a New Platform
83+
84+
1. Create `src/platforms/NewPlatform.ts` extending `BasePlatform`
85+
2. Export from `src/platforms/index.ts`
86+
3. Add to `SupportedPlatforms` type in `src/types/index.ts`
87+
4. Add initialization in `HyperPost.initializePlatforms()`
88+
5. Add platform data in `HyperPost.initializeDatabase()`
89+
6. Add signup requirements in `src/signup-templates.ts`
90+
91+
### Credential Storage
92+
93+
- User credentials stored in `~/.config/hyper-post/signup-data.json`
94+
- Config defaults in `~/.config/hyper-post/config.json`
95+
- `SignupManager` class handles all credential operations
96+
- Environment variables override stored credentials
97+
98+
### Database Schema
99+
100+
```prisma
101+
Post # Content with SHA-256 hash for deduplication
102+
Platform # Platform metadata (mastodon, bluesky, etc.)
103+
PostPlatform # Many-to-many: which posts went to which platforms
104+
PostAnalytics # Engagement metrics per post-platform
105+
ScheduledPost # Future posts with status tracking
106+
```
107+
108+
## Key Types
109+
110+
```typescript
111+
interface SocialPost {
112+
content: string;
113+
title?: string;
114+
url?: string;
115+
imageUrl?: string;
116+
tags?: string[];
117+
}
118+
119+
interface PostingResult {
120+
platform: string;
121+
success: boolean;
122+
postId?: string;
123+
url?: string;
124+
error?: string;
125+
}
126+
127+
type SupportedPlatforms = 'mastodon' | 'bluesky' | 'discord' | 'reddit' | 'devto' | 'medium' | ...;
128+
```
129+
130+
## Build System
131+
132+
- **tsup** bundles the project into `dist/`
133+
- Three entry points: `index.ts` (library), `cli.ts` (CLI), `setup.ts` (wizard)
134+
- CLI and setup get `#!/usr/bin/env node` banner
135+
- Library outputs both CJS and ESM
136+
- TypeScript target: ES2022
137+
138+
## Coding Conventions
139+
140+
### TypeScript
141+
- Strict mode enabled
142+
- Use `async/await` for all async operations
143+
- Return `PostingResult` objects from platform `post()` methods
144+
- Use `createResult()` helper in platforms for consistent returns
145+
146+
### Error Handling
147+
- Platforms catch errors and return failure results (don't throw)
148+
- Use `console.warn()` for non-fatal issues (analytics failures, etc.)
149+
- CLI uses `process.exit(1)` for fatal errors
150+
151+
### Naming
152+
- Platform classes: `{Name}Platform` (e.g., `BlueskyPlatform`)
153+
- Platform identifiers: lowercase (e.g., `bluesky`)
154+
- Credential keys: camelCase (e.g., `accessToken`, `integrationToken`)
155+
156+
### Imports
157+
- Use named imports
158+
- Platform implementations use `require()` for some packages (e.g., `mastodon-api`)
159+
- Group imports: external packages, then internal modules
160+
161+
## Testing
162+
163+
- Jest is configured but no test files exist yet
164+
- Test commands exist in `package.json`
165+
- Recommended: add tests in `__tests__/` or `*.test.ts` files
166+
167+
## CLI Commands
168+
169+
| Command | Description |
170+
|---------|-------------|
171+
| `post` | Post content to platforms (`-c`, `-t`, `-u`, `--tags`, `-p`, `--dry-run`) |
172+
| `platforms` | List/test configured platforms |
173+
| `setup` | Interactive setup wizard |
174+
| `history` | View posting history |
175+
| `analytics` | View engagement data |
176+
| `gather-analytics` | Fetch fresh metrics from platforms |
177+
| `discover-posts` | Find existing posts on platforms |
178+
| `import-post` | Import external post for tracking |
179+
| `repost` | Repost content to additional platforms |
180+
| `schedule` | Schedule future posts |
181+
| `schedule-list` | List scheduled posts |
182+
| `schedule-cancel` | Cancel scheduled post |
183+
| `schedule-run` | Process due posts (for cron) |
184+
| `promote` | **Blog promotion** - parse MDX posts and share to platforms |
185+
186+
### Blog Promotion (`promote`)
187+
188+
The `promote` command reads MDX blog posts from a content directory and posts them to social platforms:
189+
190+
```bash
191+
# List available blog posts
192+
hyper-post promote --list
193+
194+
# Promote a specific article
195+
hyper-post promote --slug revela-part-1-architecture --dry-run
196+
197+
# Promote with full content to Dev.to/Medium
198+
hyper-post promote --slug my-article --full-content
199+
200+
# Schedule promotion for later
201+
hyper-post promote --slug my-article --schedule "2025-02-01 10:00"
202+
203+
# Promote recent posts (last 7 days)
204+
hyper-post promote --recent 7
205+
206+
# Custom blog directory
207+
hyper-post promote --blog-dir /path/to/content/blog --base-url https://mysite.com
208+
```
209+
210+
Default blog directory: `/Users/yann/dev/hyperdrift-io/hyper-drift/content/blog`
211+
212+
## Platform-Specific Notes
213+
214+
### Medium
215+
- Requires Markdown content format
216+
- Uses `contentFormat.ts` utilities for MDX → Markdown conversion
217+
- Tags limited to 5, max 25 chars each
218+
- Hashtags extracted from content automatically
219+
220+
### Bluesky
221+
- Uses `@atproto/api` SDK
222+
- Creates rich text with facets for link detection
223+
- URL embeds created as `app.bsky.embed.external`
224+
225+
### Mastodon
226+
- Uses `mastodon-api` npm package
227+
- Instance URL required in credentials
228+
- Tags appended as hashtags to status text
229+
230+
### Discord
231+
- Uses `discord.js`
232+
- Requires bot token and channel ID
233+
- Posts as bot messages
234+
235+
## Gotchas
236+
237+
1. **Build before CLI testing**: Always run `pnpm build` before testing CLI changes
238+
2. **Prisma generation**: Run `pnpm db:generate` after any `schema.prisma` changes
239+
3. **Duplicate detection**: Content is hashed (title + content + url) with 24-hour window
240+
4. **Platform initialization**: Database platforms are upserted on `HyperPost` construction
241+
5. **Medium content**: Must be Markdown - MDX auto-converted, plain text rejected
242+
6. **Credential precedence**: Environment variables override stored credentials
243+
7. **pnpm only**: Project uses pnpm workspace - don't use npm or yarn
244+
245+
## Dependencies
246+
247+
Key production dependencies:
248+
- `@atproto/api` - Bluesky API
249+
- `@prisma/client` - Database ORM
250+
- `axios` - HTTP client (Medium, Dev.to, Reddit)
251+
- `commander` - CLI framework
252+
- `discord.js` - Discord API
253+
- `mastodon-api` - Mastodon API
254+
- `@mdx-js/mdx` / `remark` - Content format conversion
255+
- `zod` - Schema validation
256+
257+
## File Locations
258+
259+
- Config: `~/.config/hyper-post/`
260+
- Database: `./hyperpost.db` (SQLite, in project root)
261+
- Built output: `./dist/`
262+
- Source: `./src/`
263+
264+
## Integration with HyperDrift Blog
265+
266+
HyperPost is designed to promote articles from the HyperDrift blog (`/Users/yann/dev/hyperdrift-io/hyper-drift/content/blog`).
267+
268+
### Workflow for New Blog Posts
269+
270+
1. **Write the article** in MDX format with frontmatter:
271+
```yaml
272+
---
273+
title: "Article Title"
274+
date: "2025-02-01T10:00:00Z"
275+
excerpt: "Brief summary for social posts"
276+
tags: ["tag1", "tag2"]
277+
---
278+
```
279+
280+
2. **Preview the promotion**:
281+
```bash
282+
hyper-post promote --slug article-slug --dry-run
283+
```
284+
285+
3. **Post to all platforms**:
286+
```bash
287+
hyper-post promote --slug article-slug
288+
```
289+
290+
4. **Or schedule for optimal timing**:
291+
```bash
292+
hyper-post promote --slug article-slug --schedule "2025-02-01 10:00"
293+
```
294+
295+
### Platform Strategy
296+
297+
- **Short-form** (Mastodon, Bluesky): Uses excerpt
298+
- **Long-form** (Dev.to, Medium): Use `--full-content` for cross-posting the full article
299+
300+
### Currently Configured Platforms
301+
302+
Run `hyper-post platforms` to see active platforms. As of now:
303+
- Mastodon (mastodon.social/@hyperdrift)
304+
- Bluesky (hyper-drift.bsky.social)
305+
- Dev.to (dev.to/hyperdrift)
306+
307+
### Missing Platforms to Consider
308+
309+
- **Reddit** - Requires OAuth setup (client_id, client_secret, username, password)
310+
- **Medium** - Requires integration token
311+
- **Discord** - Requires bot token and channel ID
312+
- **Hashnode** - Developer blogging platform (not yet implemented)
313+
- **Daily.dev** - Content aggregation via Squads (not yet implemented)

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)