@aicgen/aicgen 1.0.0-beta.1

package/data/practices/documentation.md

@@ -0,0 +1,260 @@
+# Documentation Organization
+
+## Keep Root Clean
+
+**RULE: Documentation must NOT clutter the project root.**
+
+```
+❌ BAD: Root folder mess
+project/
+├── README.md
+├── ARCHITECTURE.md
+├── API_DOCS.md
+├── DEPLOYMENT.md
+├── TROUBLESHOOTING.md
+├── USER_GUIDE.md
+├── DATABASE_SCHEMA.md
+├── TESTING_GUIDE.md
+└── ... (20 more .md files)
+
+✅ GOOD: Organized structure
+project/
+├── README.md              (overview only)
+├── docs/
+│   ├── architecture/
+│   ├── api/
+│   ├── deployment/
+│   └── guides/
+└── src/
+```
+
+## Documentation Structure
+
+**Standard documentation folder:**
+
+```
+docs/
+├── architecture/
+│   ├── overview.md
+│   ├── decisions/         # Architecture Decision Records
+│   │   ├── 001-database-choice.md
+│   │   └── 002-api-design.md
+│   └── diagrams/
+│
+├── api/
+│   ├── endpoints.md
+│   ├── authentication.md
+│   └── examples/
+│
+├── guides/
+│   ├── getting-started.md
+│   ├── development.md
+│   ├── deployment.md
+│   └── troubleshooting.md
+│
+├── features/              # Organize by feature
+│   ├── user-auth/
+│   │   ├── overview.md
+│   │   ├── implementation.md
+│   │   └── testing.md
+│   ├── payments/
+│   └── notifications/
+│
+└── planning/              # Active work planning
+    ├── memory-lane.md     # Context preservation
+    ├── current-phase.md   # Active work
+    └── next-steps.md      # Backlog
+```
+
+## Memory Lane Document
+
+**CRITICAL: Maintain context across sessions**
+
+### Purpose
+When AI context limit is reached, reload from memory lane to restore working context.
+
+### Structure
+
+```markdown
+# Memory Lane - Project Context
+
+## Last Updated
+2024-12-10 15:30
+
+## Current Objective
+Implementing user authentication system with OAuth2 support
+
+## Recent Progress
+- ✅ Set up database schema (2024-12-08)
+- ✅ Implemented user registration (2024-12-09)
+- 🔄 Working on: OAuth2 integration (2024-12-10)
+- ⏳ Next: Session management
+
+## Key Decisions
+1. **Database**: PostgreSQL chosen for ACID compliance
+2. **Auth Strategy**: OAuth2 + JWT tokens
+3. **Session Store**: Redis for performance
+
+## Important Files
+- `src/auth/oauth.ts` - OAuth2 implementation (IN PROGRESS)
+- `src/models/user.ts` - User model and validation
+- `docs/architecture/decisions/003-auth-system.md` - Full context
+
+## Active Questions
+1. Should we support refresh tokens? (Pending user decision)
+2. Token expiry: 1h or 24h? (Pending user decision)
+
+## Technical Context
+- Using Passport.js for OAuth
+- Google and GitHub providers configured
+- Callback URLs: /auth/google/callback, /auth/github/callback
+
+## Known Issues
+- OAuth redirect not working in development (investigating)
+- Need to add rate limiting to prevent abuse
+
+## Next Session
+1. Fix OAuth redirect issue
+2. Implement refresh token rotation
+3. Add comprehensive auth tests
+```
+
+### Update Frequency
+- Update after each significant milestone
+- Update before context limit is reached
+- Update when switching between features
+
+## Context Reload Strategy
+
+**For AI Tools with Hooks:**
+
+Create a hook to reload memory lane on startup:
+
+```json
+{
+  "hooks": {
+    "startup": {
+      "command": "cat docs/planning/memory-lane.md"
+    }
+  }
+}
+```
+
+**For AI Tools with Agents:**
+
+Create a context restoration agent:
+
+```markdown
+# Context Restoration Agent
+
+Task: Read and summarize current project state
+
+Sources:
+1. docs/planning/memory-lane.md
+2. docs/architecture/decisions/ (recent ADRs)
+3. git log --oneline -10 (recent commits)
+
+Output: Concise summary of where we are and what's next
+```
+
+## Feature Documentation
+
+**Organize by feature/scope, not by type:**
+
+```
+❌ BAD: Organized by document type
+docs/
+├── specifications/
+│   ├── auth.md
+│   ├── payments.md
+│   └── notifications.md
+├── implementations/
+│   ├── auth.md
+│   ├── payments.md
+│   └── notifications.md
+└── tests/
+    ├── auth.md
+    └── payments.md
+
+✅ GOOD: Organized by feature
+docs/features/
+├── auth/
+│   ├── specification.md
+│   ├── implementation.md
+│   ├── api.md
+│   └── testing.md
+├── payments/
+│   ├── specification.md
+│   ├── implementation.md
+│   └── providers.md
+└── notifications/
+    ├── specification.md
+    └── channels.md
+```
+
+**Benefits:**
+- All related docs in one place
+- Easy to find feature-specific information
+- Natural scope boundaries
+- Easier to maintain
+
+## Planning Documents
+
+**Active planning should be in docs/planning/:**
+
+```
+docs/planning/
+├── memory-lane.md         # Context preservation
+├── current-sprint.md      # Active work
+├── backlog.md             # Future work
+└── spike-results/         # Research findings
+    ├── database-options.md
+    └── auth-libraries.md
+```
+
+## Documentation Principles
+
+1. **Separate folder**: All docs in `docs/` directory
+2. **Organize by scope**: Group by feature, not document type
+3. **Keep root clean**: Only README.md in project root
+4. **Maintain memory lane**: Update regularly for context preservation
+5. **Link related docs**: Use relative links between related documents
+
+## README Guidelines
+
+**Root README should be concise:**
+
+```markdown
+# Project Name
+
+Brief description
+
+## Quick Start
+[Link to docs/guides/getting-started.md]
+
+## Documentation
+- [Architecture](docs/architecture/overview.md)
+- [API Docs](docs/api/endpoints.md)
+- [Development Guide](docs/guides/development.md)
+
+## Contributing
+[Link to CONTRIBUTING.md or docs/guides/contributing.md]
+```
+
+**Keep it short, link to detailed docs.**
+
+## Anti-Patterns
+
+❌ **Don't:**
+- Put 10+ markdown files in project root
+- Mix documentation types in same folder
+- Forget to update memory lane before context expires
+- Create documentation without clear organization
+- Duplicate information across multiple docs
+
+✅ **Do:**
+- Use `docs/` directory for all documentation
+- Organize by feature/scope
+- Maintain memory lane for context preservation
+- Link related documents together
+- Update docs as code evolves

package/data/practices/index.md

@@ -0,0 +1,11 @@
+# Development Practices
+
+This directory contains development best practices.
+
+## Available Chunks
+
+- **planning.md** - Planning workflow, phases, asking for clarification, getting approval
+- **documentation.md** - Documentation organization, folder structure, memory lane
+- **code-review.md** - Review guidelines, PR templates, feedback
+- **refactoring.md** - Code smells, refactoring patterns
+- **version-control.md** - Git workflows, branching strategies

package/data/practices/planning.md

@@ -0,0 +1,142 @@
+# Planning Best Practices
+
+## Plan Before Implementation
+
+**ALWAYS design and plan before writing code:**
+
+1. **Understand Requirements**
+   - Clarify the goal and scope
+   - Identify constraints and dependencies
+   - Ask questions about ambiguous requirements
+
+2. **Break Down Into Phases**
+   - Divide work into logical phases
+   - Define deliverables for each phase
+   - Prioritize phases by value and dependencies
+
+3. **Design First**
+   - Sketch architecture and data flow
+   - Identify components and interfaces
+   - Consider edge cases and error scenarios
+
+4. **Get User Approval**
+   - Present the plan to stakeholders
+   - Explain trade-offs and alternatives
+   - Wait for approval before implementation
+
+## Never Make Assumptions
+
+**CRITICAL: When in doubt, ASK:**
+
+```typescript
+// ❌ BAD: Assuming what user wants
+async function processOrder(orderId: string) {
+  // Assuming we should send email, but maybe not?
+  await sendConfirmationEmail(orderId);
+  // Assuming payment is already captured?
+  await fulfillOrder(orderId);
+}
+
+// ✅ GOOD: Clarify requirements first
+// Q: Should we send confirmation email at this stage?
+// Q: Is payment already captured or should we capture it here?
+// Q: What happens if fulfillment fails?
+```
+
+**Ask about:**
+- Expected behavior in edge cases
+- Error handling strategy
+- Performance requirements
+- Security considerations
+- User experience preferences
+
+## Plan in Phases
+
+**Structure work into clear phases:**
+
+### Phase 1: Foundation
+- Set up project structure
+- Configure tooling and dependencies
+- Create basic types and interfaces
+
+### Phase 2: Core Implementation
+- Implement main business logic
+- Add error handling
+- Write unit tests
+
+### Phase 3: Integration
+- Connect components
+- Add integration tests
+- Handle edge cases
+
+### Phase 4: Polish
+- Performance optimization
+- Documentation
+- Final review
+
+**Checkpoint after each phase:**
+- Demo functionality
+- Get feedback
+- Adjust plan if needed
+
+## Planning Template
+
+```markdown
+## Goal
+[What are we building and why?]
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+- [ ] Requirement 3
+
+## Questions for Clarification
+1. [Question about requirement X]
+2. [Question about edge case Y]
+3. [Question about preferred approach for Z]
+
+## Proposed Approach
+[Describe the solution]
+
+## Phases
+1. **Phase 1**: [Description]
+   - Task 1
+   - Task 2
+
+2. **Phase 2**: [Description]
+   - Task 1
+   - Task 2
+
+## Risks & Mitigation
+- **Risk**: [Description]
+  **Mitigation**: [How to handle]
+
+## Alternatives Considered
+- **Option A**: [Pros/Cons]
+- **Option B**: [Pros/Cons]
+- **Chosen**: Option A because [reason]
+```
+
+## Communication Principles
+
+1. **Ask Early**: Don't wait until you're stuck
+2. **Be Specific**: "Should error X retry or fail immediately?"
+3. **Propose Options**: "Would you prefer A or B?"
+4. **Explain Trade-offs**: "Fast but risky vs. Slow but safe"
+5. **Document Decisions**: Record what was decided and why
+
+## Anti-Patterns
+
+❌ **Don't:**
+- Start coding without understanding requirements
+- Assume you know what the user wants
+- Skip the planning phase to "save time"
+- Make architectural decisions without discussion
+- Proceed with unclear requirements
+
+✅ **Do:**
+- Ask questions when requirements are vague
+- Create a plan and get it approved
+- Break work into reviewable phases
+- Document decisions and reasoning
+- Communicate early and often

package/data/practices/refactoring.md

@@ -0,0 +1,91 @@
+# Refactoring Patterns
+
+## Common Code Smells
+
+### Long Method
+Split into smaller, focused functions.
+
+```typescript
+// Before
+function processOrder(order: Order) {
+  // 100 lines of code...
+}
+
+// After
+function processOrder(order: Order) {
+  validateOrder(order);
+  calculateTotals(order);
+  applyDiscounts(order);
+  saveOrder(order);
+}
+```
+
+### Duplicate Code
+Extract common logic.
+
+```typescript
+// Before
+function getAdminUsers() {
+  return users.filter(u => u.role === 'admin' && u.active);
+}
+function getModeratorUsers() {
+  return users.filter(u => u.role === 'moderator' && u.active);
+}
+
+// After
+function getActiveUsersByRole(role: string) {
+  return users.filter(u => u.role === role && u.active);
+}
+```
+
+### Primitive Obsession
+Use value objects.
+
+```typescript
+// Before
+function sendEmail(email: string) { /* ... */ }
+
+// After
+class Email {
+  constructor(private value: string) {
+    if (!this.isValid(value)) throw new Error('Invalid email');
+  }
+}
+function sendEmail(email: Email) { /* ... */ }
+```
+
+### Feature Envy
+Move method to class it uses most.
+
+```typescript
+// Before - Order is accessing customer too much
+class Order {
+  getDiscount() {
+    return this.customer.isPremium() ?
+      this.customer.premiumDiscount :
+      this.customer.regularDiscount;
+  }
+}
+
+// After
+class Customer {
+  getDiscount(): number {
+    return this.isPremium() ? this.premiumDiscount : this.regularDiscount;
+  }
+}
+```
+
+## Safe Refactoring Steps
+
+1. Ensure tests pass before refactoring
+2. Make one small change at a time
+3. Run tests after each change
+4. Commit frequently
+5. Refactor in separate commits from feature work
+
+## Best Practices
+
+- Refactor when adding features, not separately
+- Keep refactoring commits separate
+- Use IDE refactoring tools when available
+- Write tests before refactoring if missing

package/data/practices/version-control.md

@@ -0,0 +1,55 @@
+# Version Control Patterns
+
+## Branching Strategies
+
+### GitHub Flow
+Simple: main + feature branches.
+
+```
+main ─────●─────●─────●─────●─────
+           \         /
+feature     ●───●───●
+```
+
+### Git Flow
+For scheduled releases: main, develop, feature, release, hotfix.
+
+```
+main    ─────●─────────────●─────
+              \           /
+release        ●─────────●
+                \       /
+develop  ●───●───●───●───●───●───
+          \     /
+feature    ●───●
+```
+
+## Commit Messages
+
+```
+feat: add user authentication
+
+- Implement JWT-based auth
+- Add login/logout endpoints
+- Include password hashing
+
+Closes #123
+```
+
+**Prefixes:**
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `refactor:` - Code change that doesn't fix bug or add feature
+- `docs:` - Documentation only
+- `test:` - Adding tests
+- `chore:` - Maintenance tasks
+
+## Best Practices
+
+- Keep commits atomic and focused
+- Write descriptive commit messages
+- Pull/rebase before pushing
+- Never force push to shared branches
+- Use pull requests for code review
+- Delete merged branches
+- Tag releases with semantic versions

package/data/security/auth-jwt.md

@@ -0,0 +1,159 @@
+# Authentication & JWT Security
+
+## Password Storage
+
+```typescript
+import bcrypt from 'bcrypt';
+
+const SALT_ROUNDS = 12; // Work factor
+
+// ✅ Hash password with bcrypt
+async function hashPassword(password: string): Promise<string> {
+  return bcrypt.hash(password, SALT_ROUNDS);
+}
+
+async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(password, hash);
+}
+
+// ✅ Validate password strength
+function validatePassword(password: string): void {
+  if (password.length < 12) {
+    throw new Error('Password must be at least 12 characters');
+  }
+  if (password.length > 160) {
+    throw new Error('Password too long'); // Prevent DoS via bcrypt
+  }
+}
+```
+
+## JWT Best Practices
+
+```typescript
+import jwt from 'jsonwebtoken';
+
+const JWT_SECRET = process.env.JWT_SECRET!;
+const ACCESS_TOKEN_EXPIRY = '15m';
+const REFRESH_TOKEN_EXPIRY = '7d';
+
+// ✅ Generate tokens
+function generateTokens(userId: string) {
+  const accessToken = jwt.sign(
+    { sub: userId, type: 'access' },
+    JWT_SECRET,
+    { expiresIn: ACCESS_TOKEN_EXPIRY }
+  );
+
+  const refreshToken = jwt.sign(
+    { sub: userId, type: 'refresh' },
+    JWT_SECRET,
+    { expiresIn: REFRESH_TOKEN_EXPIRY }
+  );
+
+  return { accessToken, refreshToken };
+}
+
+// ✅ Verify and decode token
+function verifyToken(token: string) {
+  try {
+    return jwt.verify(token, JWT_SECRET);
+  } catch (error) {
+    if (error instanceof jwt.TokenExpiredError) {
+      throw new UnauthorizedError('Token expired');
+    }
+    throw new UnauthorizedError('Invalid token');
+  }
+}
+```
+
+## Login Protection
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+// ✅ Rate limit login attempts
+const loginLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5, // 5 attempts
+  message: 'Too many login attempts, please try again later',
+});
+
+app.post('/login', loginLimiter, async (req, res) => {
+  const { email, password } = req.body;
+
+  const user = await userService.findByEmail(email);
+
+  // ✅ Generic error message (don't reveal if user exists)
+  if (!user || !await verifyPassword(password, user.passwordHash)) {
+    return res.status(401).json({ error: 'Invalid email or password' });
+  }
+
+  const tokens = generateTokens(user.id);
+
+  // Regenerate session to prevent fixation
+  req.session.regenerate(() => {
+    res.json({ ...tokens });
+  });
+});
+```
+
+## Session Security
+
+```typescript
+app.use(session({
+  secret: process.env.SESSION_SECRET!,
+  name: 'sessionId', // Don't use default 'connect.sid'
+
+  cookie: {
+    secure: true,        // HTTPS only
+    httpOnly: true,      // Prevent XSS access
+    sameSite: 'strict',  // CSRF protection
+    maxAge: 30 * 60 * 1000, // 30 minutes
+  },
+
+  resave: false,
+  saveUninitialized: false,
+  store: new RedisStore({ client: redisClient })
+}));
+
+// ✅ Session regeneration after login
+app.post('/login', async (req, res, next) => {
+  // ... authenticate user ...
+
+  req.session.regenerate((err) => {
+    req.session.userId = user.id;
+    res.json({ success: true });
+  });
+});
+```
+
+## Authorization Middleware
+
+```typescript
+// ✅ Require authentication
+const requireAuth = async (req: Request, res: Response, next: NextFunction) => {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+
+  if (!token) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+
+  try {
+    const payload = verifyToken(token);
+    req.user = await userService.findById(payload.sub);
+    next();
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+};
+
+// ✅ Require specific role
+const requireRole = (...roles: string[]) => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (!roles.includes(req.user.role)) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+    next();
+  };
+};
+```