Skip to content

Commit 9a753fc

Browse files
Oba-OneOba-One
committed
feat: Enhance accessibility features and improve development scripts
- Updated the `dev` script in `package.json` to ensure processes are stopped before starting the development server. - Introduced a new `dev:stop` script to streamline the termination of conflicting processes. - Improved UI accessibility by adjusting button styles and ensuring minimum touch target sizes. - Refactored tests to conditionally skip integration tests based on environment variables. - Updated documentation to reflect changes in development process management. These changes enhance the development workflow and improve accessibility across the application.
1 parent 44fae83 commit 9a753fc

File tree

6 files changed

+501
-0
lines changed

6 files changed

+501
-0
lines changed

‎.cursor/cursor-config.json‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
{
2+
"rules": [
3+
{
4+
"include": ".cursor/rules.md",
5+
"description": "Greenpill Dev Guild coding standards and best practices"
6+
}
7+
],
8+
"composer": {
9+
"includeEditedFiles": true,
10+
"maxTokens": 100000
11+
},
12+
"chat": {
13+
"maxTokens": 100000,
14+
"temperature": 0.3
15+
},
16+
"features": {
17+
"codeActions": true,
18+
"diagnostics": true,
19+
"hover": true,
20+
"signatureHelp": true,
21+
"documentSymbol": true,
22+
"workspaceSymbol": true,
23+
"references": true,
24+
"rename": true,
25+
"foldingRange": true,
26+
"selectionRange": true,
27+
"semanticTokens": true,
28+
"inlayHints": true
29+
},
30+
"integrations": {
31+
"mcp": {
32+
"enabled": true,
33+
"servers": [
34+
{
35+
"name": "cookie-jar-context",
36+
"config": "mcp-server.json"
37+
}
38+
]
39+
},
40+
"github": {
41+
"enabled": true,
42+
"autoLink": true,
43+
"prTemplates": true
44+
}
45+
},
46+
"project": {
47+
"type": "monorepo",
48+
"structure": {
49+
"client": "Next.js + React + TypeScript",
50+
"contracts": "Foundry + Solidity",
51+
"docs": "Markdown documentation",
52+
"e2e": "Playwright tests"
53+
},
54+
"packageManager": "pnpm",
55+
"nodeVersion": ">=18.0.0"
56+
},
57+
"ai": {
58+
"codeGeneration": {
59+
"style": "functional",
60+
"testing": "comprehensive",
61+
"documentation": "minimal-but-clear",
62+
"errorHandling": "explicit",
63+
"security": "strict"
64+
},
65+
"preferences": {
66+
"codeFirst": true,
67+
"explainTradeoffs": true,
68+
"assumptionsInComments": true,
69+
"breakDownComplexTasks": true
70+
}
71+
},
72+
"guild": {
73+
"name": "Greenpill Dev Guild",
74+
"standards": "open-source, transparent, regen-positive",
75+
"projects": ["Green Goods", "Cookie Jar", "Community Host", "Allo Yeeter", "GreenWill"]
76+
}
77+
}

‎.cursor/rules.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Cookie Jar - Root Level Rules
2+
3+
## Greenpill Dev Guild Principles
4+
- Open source, transparent, regen-positive development
5+
- Work in public with clear documentation
6+
- Mobile-first PWA approach
7+
- Web3-native with ethical considerations
8+
9+
## Monorepo Structure & Workflow
10+
- Use pnpm for package management
11+
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`
12+
- All PRs require passing CI: build, test, lint, type-check
13+
- Never decrease test coverage below current levels
14+
- Scripts coordination: `pnpm dev` starts full stack (Anvil + Client)
15+
16+
## Development Commands
17+
```bash
18+
# Development (auto-starts Anvil + deploys contracts)
19+
pnpm dev # Local with fresh chain
20+
pnpm dev:ethereum # Fork Ethereum mainnet
21+
pnpm dev:base # Fork Base network
22+
23+
# Testing & Quality
24+
pnpm test # All tests across packages
25+
pnpm test:coverage # Coverage report
26+
pnpm lint # Lint all packages
27+
pnpm build # Build all packages
28+
```
29+
30+
## Environment & Security
31+
- Use `.env.local` for local development
32+
- Never commit secrets or private keys
33+
- Default to testnets (Base Sepolia, Celo Alfajores)
34+
- Require `// I ACKNOWLEDGE MAINNET` for mainnet operations
35+
- Use Foundry keystore for production deployments
36+
37+
## Tech Stack Standards
38+
- **Frontend**: Next.js 15 + React 18 + TypeScript + Tailwind
39+
- **Web3**: viem + wagmi (NOT ethers)
40+
- **Smart Contracts**: Foundry + Solidity ^0.8.0 + OpenZeppelin
41+
- **Testing**: Vitest (unit) + Playwright (e2e) + Foundry (contracts)
42+
- **Protocols**: POAP, Unlock, Hypercerts, Hats via official SDKs
43+
44+
## Quality Gates
45+
- TypeScript strict mode across all packages
46+
- 90%+ test coverage for new code
47+
- All builds must succeed without warnings
48+
- Accessibility: WCAG 2.1 AA compliance minimum
49+
- Performance: Core Web Vitals targets met

‎AGENTS.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Cookie Jar - AI Agent Integration Guide
2+
3+
> **Comprehensive guidelines for AI coding agents working on the Cookie Jar protocol**
4+
5+
## 📋 Quick Reference
6+
7+
- **Root Rules**: [`.cursor/rules.md`](.cursor/rules.md) - Monorepo workflow & Guild standards
8+
- **Frontend Rules**: [`client/.cursor/rules.md`](client/.cursor/rules.md) - Next.js + React + Web3 patterns
9+
- **Contract Rules**: [`contracts/.cursor/rules.md`](contracts/.cursor/rules.md) - Solidity + Foundry standards
10+
- **E2E Rules**: [`e2e/.cursor/rules.md`](e2e/.cursor/rules.md) - Playwright testing patterns
11+
12+
## 🎯 Project Context
13+
14+
**Cookie Jar Protocol**: Decentralized funding pools with smart access control supporting allowlist, NFT, POAP, Unlock Protocol, Hypercerts, and Hats Protocol gating plus configurable withdrawal rules.
15+
16+
**Architecture**: Monorepo with client (Next.js), contracts (Foundry), and e2e (Playwright) packages.
17+
18+
## 🚀 Development Environment Setup
19+
20+
```bash
21+
# Zero-configuration setup
22+
git clone https://github.com/greenpill-dev-guild/cookie-jar.git
23+
cd cookie-jar
24+
npm install # Auto-installs pnpm + Foundry + dependencies
25+
npm run dev # Starts Anvil + deploys contracts + launches frontend
26+
```
27+
28+
**Auto-included**: Local blockchain, pre-seeded demo jars, hot reload, type generation.
29+
30+
## 🏗️ Architecture Overview
31+
32+
### Core Components
33+
1. **CookieJarFactory**: Protocol access control + jar deployments
34+
2. **CookieJar**: Individual jar logic + withdrawal controls
35+
3. **CookieJarRegistry**: Metadata storage + jar lookup
36+
4. **Frontend**: Next.js PWA with Web3 integrations
37+
5. **E2E Tests**: Comprehensive Playwright test suite
38+
39+
### Tech Stack
40+
- **Frontend**: Next.js 15 + React 18 + TypeScript + Tailwind + viem/wagmi
41+
- **Contracts**: Foundry + Solidity ^0.8.0 + OpenZeppelin
42+
- **Testing**: Vitest + React Testing Library + Playwright + Foundry
43+
- **Protocols**: POAP + Unlock + Hypercerts + Hats + Alchemy NFT API
44+
45+
## 🎨 AI Agent Workflow
46+
47+
### 1. Understanding Context
48+
Before making changes:
49+
- Review the specific `.cursor/rules.md` file for the area you're working in
50+
- Check existing patterns in similar components/contracts
51+
- Understand the user flow impact of your changes
52+
53+
### 2. Development Approach
54+
```bash
55+
# Always start development environment first
56+
pnpm dev # This is critical - starts blockchain + contracts + frontend
57+
58+
# Run relevant tests frequently
59+
pnpm test # All packages
60+
pnpm test:coverage # Ensure 90%+ coverage maintained
61+
pnpm test:e2e # Full user flow validation
62+
```
63+
64+
### 3. Code Quality Checklist
65+
- [ ] **TypeScript strict mode** - No `any` types, explicit interfaces
66+
- [ ] **Tests written** - Unit tests + integration tests as needed
67+
- [ ] **Documentation updated** - NatSpec for contracts, JSDoc for complex functions
68+
- [ ] **Accessibility verified** - WCAG 2.1 AA compliance for UI changes
69+
- [ ] **Security reviewed** - Especially for smart contract modifications
70+
- [ ] **Performance considered** - Bundle size impact, gas optimization
71+
72+
### 4. Web3-Specific Considerations
73+
- **Always use viem/wagmi** (never ethers.js)
74+
- **Default to testnets** unless explicitly confirmed for mainnet
75+
- **Include gas estimation** and error handling for all transactions
76+
- **Validate chain IDs** before any blockchain interactions
77+
- **Use official protocol SDKs** (POAP, Unlock, etc.) not custom implementations
78+
79+
## 📚 Domain-Specific Guidance
80+
81+
### Frontend Development (`client/`)
82+
- Follow [client rules](client/.cursor/rules.md) for Next.js patterns
83+
- Use shadcn/ui components for complex UI elements
84+
- Implement proper loading/error states for all async operations
85+
- Ensure mobile-first responsive design
86+
87+
### Smart Contract Development (`contracts/`)
88+
- Follow [contract rules](contracts/.cursor/rules.md) for Solidity patterns
89+
- Use OpenZeppelin libraries for standard functionality
90+
- Include comprehensive NatSpec documentation
91+
- Implement proper access controls and security measures
92+
93+
### Testing (`__tests__/`, `e2e/`)
94+
- Follow [e2e rules](e2e/.cursor/rules.md) for testing patterns
95+
- Write user-centric test flows, not component-specific tests
96+
- Ensure accessibility compliance in e2e tests
97+
- Maintain high test coverage across all packages
98+
99+
## 🔒 Security & Best Practices
100+
101+
### Smart Contract Security
102+
- **Reentrancy protection**: Use OpenZeppelin's ReentrancyGuard
103+
- **Access control**: Implement role-based permissions properly
104+
- **Input validation**: Validate all parameters with custom errors
105+
- **Gas optimization**: Consider gas costs in all implementations
106+
107+
### Frontend Security
108+
- **Environment variables**: Never expose private keys or secrets
109+
- **Input sanitization**: Validate all user inputs
110+
- **Error handling**: Don't expose internal errors to users
111+
- **CSP headers**: Implement proper content security policies
112+
113+
## 🎯 Common Patterns & Conventions
114+
115+
### Naming Conventions
116+
- **Files**: kebab-case (`cookie-jar-factory.ts`)
117+
- **Components**: PascalCase (`CookieJarCard.tsx`)
118+
- **Functions**: camelCase (`getUserJars()`)
119+
- **Constants**: UPPER_SNAKE_CASE (`MAX_WITHDRAWAL_AMOUNT`)
120+
- **Contracts**: PascalCase (`CookieJarFactory.sol`)
121+
122+
### Git & PR Workflow
123+
- **Conventional commits**: `feat:`, `fix:`, `chore:`, `docs:`
124+
- **Small focused PRs**: One feature/fix per PR
125+
- **Comprehensive descriptions**: Explain what, why, and how
126+
- **Link issues**: Always reference related GitHub issues
127+
128+
## 🚨 Critical Reminders
129+
130+
### Before Any Deployment
131+
- [ ] All tests passing (`pnpm test`)
132+
- [ ] No TypeScript errors (`pnpm type-check`)
133+
- [ ] Linting passes (`pnpm lint`)
134+
- [ ] Coverage maintained (`pnpm test:coverage`)
135+
- [ ] E2E tests validate user flows (`pnpm test:e2e`)
136+
137+
### Web3 Deployment Checklist
138+
- [ ] Contracts verified on block explorer
139+
- [ ] Gas estimation reasonable for target users
140+
- [ ] Access controls properly configured
141+
- [ ] Emergency pause functionality tested (if applicable)
142+
143+
### Frontend Deployment Checklist
144+
- [ ] Core Web Vitals meet targets
145+
- [ ] Accessibility compliance verified
146+
- [ ] Mobile responsiveness tested
147+
- [ ] Error boundaries handle edge cases
148+
149+
## 📞 Getting Help & Resources
150+
151+
- **Codebase Questions**: Search existing code patterns before creating new ones
152+
- **Protocol Integration**: Refer to official SDK documentation
153+
- **Testing Issues**: Check existing test files for similar patterns
154+
- **Performance Problems**: Use Next.js bundle analyzer and Foundry gas reports
155+
156+
## 🔄 Continuous Improvement
157+
158+
As you work on Cookie Jar:
159+
- **Learn from patterns**: Study existing successful implementations
160+
- **Share improvements**: Document new patterns that work well
161+
- **Ask when uncertain**: Better to clarify than assume
162+
- **Test thoroughly**: User experience is paramount
163+
164+
---
165+
166+
*This guide evolves with the project. When you discover better patterns or practices, update the relevant rule files to help future development.*

‎client/.cursor/rules.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Cookie Jar Client - Frontend Rules
2+
3+
## Next.js App Router Structure
4+
```
5+
client/
6+
├── app/ # App Router (Next.js 15)
7+
│ ├── create/ # Jar creation flow
8+
│ ├── jar/[address]/ # Individual jar pages
9+
│ ├── jars/ # Jar listing
10+
│ └── profile/ # User profile
11+
├── components/ # Reusable UI components
12+
│ ├── ui/ # shadcn/ui primitives
13+
│ ├── create/ # Creation flow components
14+
│ ├── jar/ # Jar-specific components
15+
│ └── nft/ # NFT-related components
16+
├── hooks/ # Custom React hooks
17+
│ ├── app/ # App-level hooks
18+
│ ├── jar/ # Jar interaction hooks
19+
│ └── nft/ # NFT validation hooks
20+
└── lib/ # Utility functions
21+
```
22+
23+
## Component Patterns
24+
- **Functional components only** - no class components
25+
- **Named exports preferred** for better tree-shaking
26+
- **Co-locate tests**: `Component.tsx` → `Component.test.tsx`
27+
- **Props interfaces**: Define explicit TypeScript interfaces
28+
- **Error boundaries**: Wrap route components
29+
- **Loading states**: Show skeletons, not spinners
30+
31+
## Web3 Integration Standards
32+
- **viem + wagmi** (never ethers.js) for blockchain interactions
33+
- **RainbowKit** for wallet connection UI
34+
- **Chain validation**: Always verify chainId before transactions
35+
- **Gas estimation**: Include gas limits and error handling
36+
- **Transaction states**: Loading, success, error with user feedback
37+
38+
## Protocol Integration Patterns
39+
```typescript
40+
// Use official SDKs, not custom implementations
41+
import { POAPEvent } from '@poap-xyz/poap-sdk'
42+
import { UnlockLock } from '@unlock-protocol/unlock-js'
43+
import { Hypercert } from '@hypercerts-org/sdk'
44+
import { Hat } from '@hatsprotocol/sdk-v1-subgraph'
45+
```
46+
47+
## State Management Rules
48+
- **TanStack Query** for server/blockchain state
49+
- **React hooks** for local component state
50+
- **No prop drilling** - use context sparingly
51+
- **Immutable updates** - never mutate state directly
52+
53+
## Styling & UI Standards
54+
- **Tailwind CSS** utility-first approach
55+
- **shadcn/ui** for complex components (dialogs, forms)
56+
- **Mobile-first** responsive design
57+
- **Theme support**: Light/dark mode via CSS variables
58+
- **Consistent spacing**: Use Tailwind spacing scale
59+
60+
## Testing Requirements
61+
```bash
62+
pnpm test # Run all unit tests
63+
pnpm test:watch # Watch mode during development
64+
pnpm test:coverage # Generate coverage report (90%+ required)
65+
```
66+
67+
## Performance & Accessibility
68+
- **Core Web Vitals**: LCP < 2.5s, FID < 100ms, CLS < 0.1
69+
- **Image optimization**: Use Next.js Image component
70+
- **Bundle size**: Monitor with `@next/bundle-analyzer`
71+
- **Keyboard navigation**: All interactive elements accessible
72+
- **Screen reader support**: Proper ARIA labels and semantic HTML

0 commit comments

Comments
 (0)