Skip to content

Commit ecb373a

Browse files
cameronryecameronrye
authored
Merge pull request #1 from cameronrye/docs/prepare-for-open-source-release
📚 Prepare project for open source release
2 parents 9f58787 + 9c375c0 commit ecb373a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

73 files changed

+27738
-26
lines changed

‎.augment/rules/always-core-standards.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Core Development Standards (Always Applied)
2+
3+
## TypeScript Standards
4+
- Use strict TypeScript configuration with `noImplicitAny`, `strictNullChecks`, and `noImplicitReturns`
5+
- Prefer explicit return types for all public functions and methods
6+
- Use `const` assertions for immutable data structures
7+
- Implement proper error handling with custom error classes extending `Error`
8+
- Use branded types for domain-specific identifiers (DIDs, ATURIs, etc.)
9+
10+
## AT Protocol Integration
11+
- Always use the official `@atproto/api` package for AT Protocol interactions
12+
- Implement proper authentication flow with session management
13+
- Use proper AT Protocol identifiers (DIDs, AT-URIs, NSIDs) with type safety
14+
- Handle AT Protocol rate limits gracefully with exponential backoff
15+
- Validate all AT Protocol responses against expected schemas
16+
17+
## MCP Server Architecture
18+
- Follow the official MCP specification strictly
19+
- Implement all required MCP server capabilities (tools, resources, prompts)
20+
- Use proper JSON-RPC 2.0 message formatting
21+
- Implement comprehensive error handling with proper MCP error codes
22+
- Provide detailed tool descriptions and parameter schemas using Zod
23+
24+
## Code Organization
25+
- Use barrel exports (`index.ts`) for clean module interfaces
26+
- Organize code by feature/domain, not by file type
27+
- Keep functions pure and side-effect free where possible
28+
- Use dependency injection for testability
29+
- Implement proper separation of concerns (data, business logic, presentation)
30+
31+
## Error Handling
32+
- Create custom error classes for different error types
33+
- Always include context in error messages
34+
- Log errors with appropriate severity levels
35+
- Implement graceful degradation for non-critical failures
36+
- Use Result/Either patterns for operations that can fail
37+
38+
## Security
39+
- Validate all inputs using Zod schemas
40+
- Sanitize data before AT Protocol operations
41+
- Implement proper authentication and authorization
42+
- Never log sensitive information (tokens, passwords, private keys)
43+
- Use environment variables for all configuration secrets
44+
45+
## Performance
46+
- Implement connection pooling for AT Protocol clients
47+
- Use streaming for large data operations
48+
- Implement proper caching strategies with TTL
49+
- Avoid blocking operations in the main thread
50+
- Use async/await consistently, never mix with callbacks
51+
52+
## Documentation
53+
- Document all public APIs with JSDoc comments
54+
- Include usage examples in documentation
55+
- Maintain up-to-date README with setup instructions
56+
- Document all environment variables and configuration options
57+
- Provide troubleshooting guides for common issues

‎.augment/rules/auto-atproto-integration.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# AT Protocol Integration Guidelines (Auto-Applied)
2+
3+
**Description**: Automatically applied when working with AT Protocol integration, Bluesky API, or social networking features
4+
5+
## AT Protocol Client Setup
6+
- Use `@atproto/api` version 0.14.0 or later for latest features
7+
- Initialize `AtpAgent` with proper service endpoint configuration
8+
- Implement session persistence for authentication tokens
9+
- Configure proper user agent strings identifying the MCP server
10+
- Handle service discovery for custom PDS instances
11+
12+
## Authentication & Sessions
13+
- Implement OAuth flow for user authentication when required
14+
- Store session tokens securely (never in plain text)
15+
- Handle token refresh automatically before expiration
16+
- Implement proper logout and session cleanup
17+
- Support both app passwords and OAuth tokens
18+
19+
## Data Models & Types
20+
- Use AT Protocol's official TypeScript types from `@atproto/api`
21+
- Create branded types for AT Protocol identifiers:
22+
```typescript
23+
type DID = string & { readonly brand: unique symbol }
24+
type ATURI = string & { readonly brand: unique symbol }
25+
type NSID = string & { readonly brand: unique symbol }
26+
```
27+
- Validate AT-URIs using proper regex patterns
28+
- Implement proper CID (Content Identifier) handling
29+
- Use proper datetime formatting (ISO 8601 with timezone)
30+
31+
## Repository Operations
32+
- Use proper NSID (Namespaced Identifier) formatting
33+
- Implement CRUD operations for records (create, read, update, delete)
34+
- Handle record versioning and CAS (Compare-and-Swap) operations
35+
- Implement proper blob upload and management
36+
- Use batch operations for bulk record operations
37+
38+
## Social Features Implementation
39+
- Implement proper post creation with rich text support
40+
- Handle mentions, hashtags, and links correctly
41+
- Implement follow/unfollow operations with proper notifications
42+
- Handle likes, reposts, and replies with threading
43+
- Implement proper content moderation and filtering
44+
45+
## Firehose & Real-time Data
46+
- Use WebSocket connections for real-time data streams
47+
- Implement proper backpressure handling for high-volume streams
48+
- Parse CAR (Content Addressable aRchive) files correctly
49+
- Handle stream reconnection and error recovery
50+
- Implement efficient data processing pipelines
51+
52+
## Rate Limiting & Performance
53+
- Respect AT Protocol rate limits (varies by endpoint)
54+
- Implement exponential backoff for failed requests
55+
- Use connection pooling for multiple concurrent requests
56+
- Cache frequently accessed data with appropriate TTL
57+
- Implement request deduplication for identical operations
58+
59+
## Error Handling
60+
- Handle AT Protocol specific errors (InvalidRequest, AuthRequired, etc.)
61+
- Implement proper retry logic for transient failures
62+
- Log AT Protocol errors with request context
63+
- Provide meaningful error messages to MCP clients
64+
- Handle network timeouts and connection failures gracefully
65+
66+
## Content & Moderation
67+
- Implement content labeling and filtering
68+
- Handle NSFW and sensitive content appropriately
69+
- Respect user blocking and muting preferences
70+
- Implement proper content warnings and labels
71+
- Handle takedown requests and content removal
72+
73+
## Privacy & Security
74+
- Never expose private user data without explicit consent
75+
- Implement proper data retention policies
76+
- Handle user privacy settings correctly
77+
- Secure all AT Protocol communications with HTTPS
78+
- Validate all user inputs before AT Protocol operations

‎.augment/rules/auto-mcp-server-development.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# MCP Server Development Guidelines (Auto-Applied)
2+
3+
**Description**: Automatically applied when working with MCP server implementation, tools, resources, or protocol handling
4+
5+
## MCP Server Architecture
6+
- Use `@modelcontextprotocol/sdk` for all MCP server functionality
7+
- Implement the `Server` class with proper initialization
8+
- Define clear separation between MCP protocol and business logic
9+
- Use proper TypeScript types from the MCP SDK
10+
- Implement graceful server shutdown and cleanup
11+
12+
## Tool Implementation
13+
- Define tools with comprehensive Zod schemas for parameters
14+
- Provide detailed descriptions for each tool and parameter
15+
- Implement proper input validation using the defined schemas
16+
- Return structured responses with consistent error handling
17+
- Use meaningful tool names that clearly indicate functionality
18+
19+
## Resource Management
20+
- Implement resources for exposing AT Protocol data to LLMs
21+
- Use proper resource URIs following MCP conventions
22+
- Implement efficient resource caching and invalidation
23+
- Handle resource subscriptions for real-time updates
24+
- Provide comprehensive resource metadata
25+
26+
## Prompt Templates
27+
- Create reusable prompt templates for common AT Protocol operations
28+
- Use proper parameter substitution in templates
29+
- Provide clear template descriptions and usage examples
30+
- Implement template validation and error handling
31+
- Support dynamic template generation based on context
32+
33+
## JSON-RPC Protocol Handling
34+
- Follow JSON-RPC 2.0 specification strictly
35+
- Implement proper request/response correlation
36+
- Handle batch requests efficiently
37+
- Provide detailed error responses with proper error codes
38+
- Log all protocol interactions for debugging
39+
40+
## Error Management
41+
- Use MCP-specific error codes and messages
42+
- Implement proper error propagation from AT Protocol to MCP
43+
- Provide actionable error messages for LLM clients
44+
- Log errors with sufficient context for troubleshooting
45+
- Handle protocol-level errors gracefully
46+
47+
## Configuration & Environment
48+
- Use environment variables for all configuration
49+
- Implement proper configuration validation at startup
50+
- Support different environments (development, staging, production)
51+
- Provide clear documentation for all configuration options
52+
- Use secure defaults for all settings
53+
54+
## Logging & Monitoring
55+
- Implement structured logging with appropriate levels
56+
- Log all MCP tool invocations with parameters and results
57+
- Monitor AT Protocol API usage and rate limits
58+
- Track server performance metrics
59+
- Implement health check endpoints
60+
61+
## Security Considerations
62+
- Validate all MCP client requests thoroughly
63+
- Implement proper authentication if required
64+
- Sanitize all data before AT Protocol operations
65+
- Never expose sensitive AT Protocol credentials
66+
- Implement request rate limiting to prevent abuse
67+
68+
## Performance Optimization
69+
- Implement connection pooling for AT Protocol clients
70+
- Use async/await for all I/O operations
71+
- Cache frequently accessed AT Protocol data
72+
- Implement request batching where possible
73+
- Monitor and optimize memory usage
74+
75+
## Development Workflow
76+
- Use hot reloading for development efficiency
77+
- Implement comprehensive debugging support
78+
- Provide clear development setup instructions
79+
- Use consistent code formatting and linting
80+
- Implement proper dependency management

‎.augment/rules/auto-testing-quality.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Testing & Quality Assurance (Auto-Applied)
2+
3+
**Description**: Automatically applied when working with tests, quality assurance, or code reliability
4+
5+
## Testing Strategy
6+
- Write tests first (TDD approach) for all new features
7+
- Maintain minimum 90% code coverage for critical paths
8+
- Use Vitest as the primary testing framework
9+
- Implement unit, integration, and end-to-end tests
10+
- Mock external dependencies (AT Protocol API calls) in unit tests
11+
12+
## Test Structure
13+
- Follow the AAA pattern (Arrange, Act, Assert)
14+
- Use descriptive test names that explain the scenario
15+
- Group related tests using `describe` blocks
16+
- Use `beforeEach`/`afterEach` for test setup and cleanup
17+
- Create test utilities for common setup patterns
18+
19+
## MCP Server Testing
20+
- Test all MCP tools with various input scenarios
21+
- Verify proper JSON-RPC message handling
22+
- Test error conditions and edge cases
23+
- Mock AT Protocol responses for consistent testing
24+
- Validate tool output schemas match specifications
25+
26+
## AT Protocol Testing
27+
- Mock AT Protocol API responses using MSW (Mock Service Worker)
28+
- Test authentication flows including token refresh
29+
- Verify proper handling of AT Protocol errors
30+
- Test rate limiting and retry mechanisms
31+
- Validate AT Protocol data transformations
32+
33+
## Quality Gates
34+
- All tests must pass before merging
35+
- No TypeScript errors or warnings allowed
36+
- ESLint rules must pass with zero violations
37+
- Prettier formatting must be consistent
38+
- No console.log statements in production code
39+
40+
## Test Data Management
41+
- Use factories for creating test data
42+
- Store test fixtures in dedicated directories
43+
- Use realistic but anonymized data for tests
44+
- Implement test database seeding for integration tests
45+
- Clean up test data after each test run
46+
47+
## Performance Testing
48+
- Benchmark critical operations (AT Protocol calls, data processing)
49+
- Test memory usage and potential leaks
50+
- Verify response times meet acceptable thresholds
51+
- Test concurrent request handling
52+
- Monitor resource usage during test runs
53+
54+
## Security Testing
55+
- Test input validation with malicious payloads
56+
- Verify authentication and authorization flows
57+
- Test for common vulnerabilities (injection, XSS, etc.)
58+
- Validate secure handling of sensitive data
59+
- Test rate limiting and abuse prevention
60+
61+
## Continuous Integration
62+
- Run full test suite on every pull request
63+
- Generate and publish test coverage reports
64+
- Fail builds on test failures or coverage drops
65+
- Run tests against multiple Node.js versions
66+
- Include security scanning in CI pipeline

‎.augment/rules/manual-documentation-site.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Documentation Site Development (Manual)
2+
3+
**Description**: Guidelines for developing and maintaining the VitePress documentation site
4+
5+
## VitePress Configuration
6+
- Use VitePress 1.0+ with TypeScript support
7+
- Configure proper routing for API documentation
8+
- Implement custom theme with AT Protocol branding
9+
- Use proper SEO meta tags and social sharing
10+
- Configure search functionality with local search
11+
12+
## Content Structure
13+
- Organize documentation by user journey (Getting Started, API Reference, Examples)
14+
- Use clear hierarchical navigation structure
15+
- Implement proper cross-referencing between sections
16+
- Provide comprehensive API documentation with examples
17+
- Include troubleshooting and FAQ sections
18+
19+
## API Documentation
20+
- Auto-generate API docs from TypeScript interfaces
21+
- Include code examples for all MCP tools and resources
22+
- Document all AT Protocol operations with request/response examples
23+
- Provide interactive examples where possible
24+
- Include error handling examples and common pitfalls
25+
26+
## Code Examples
27+
- Provide working code examples for all features
28+
- Use syntax highlighting for all code blocks
29+
- Include both TypeScript and JavaScript examples where relevant
30+
- Test all code examples to ensure they work
31+
- Provide downloadable example projects
32+
33+
## Deployment & CI/CD
34+
- Deploy to GitHub Pages with automatic builds
35+
- Implement preview deployments for pull requests
36+
- Use GitHub Actions for automated deployment
37+
- Configure proper caching for static assets
38+
- Implement broken link checking in CI
39+
40+
## Content Guidelines
41+
- Write clear, concise documentation
42+
- Use consistent terminology throughout
43+
- Include visual diagrams for complex concepts
44+
- Provide step-by-step tutorials for common tasks
45+
- Keep documentation up-to-date with code changes
46+
47+
## User Experience
48+
- Implement responsive design for mobile devices
49+
- Use proper typography and spacing
50+
- Include dark/light mode toggle
51+
- Implement proper accessibility features
52+
- Provide clear navigation and search functionality
53+
54+
## Maintenance
55+
- Review and update documentation with each release
56+
- Monitor user feedback and common questions
57+
- Keep external links up-to-date
58+
- Implement analytics to track popular content
59+
- Regular content audits for accuracy and relevance

0 commit comments

Comments
 (0)