@mytechtoday/augment-extensions 0.1.0 → 0.1.1

package/augment-extensions/coding-standards/react/rules/typescript-react.md

@@ -0,0 +1,271 @@
+# TypeScript with React
+
+Best practices for using TypeScript in React applications.
+
+## Component Props
+
+Always type component props explicitly.
+
+```tsx
+// Good - Explicit prop types
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  variant?: 'primary' | 'secondary';
+  disabled?: boolean;
+  children?: React.ReactNode;
+}
+
+export const Button: React.FC<ButtonProps> = ({ 
+  label, 
+  onClick, 
+  variant = 'primary',
+  disabled = false,
+  children 
+}) => {
+  return (
+    <button 
+      onClick={onClick} 
+      disabled={disabled}
+      className={`btn btn-${variant}`}
+    >
+      {children || label}
+    </button>
+  );
+};
+
+// Bad - No types
+export const Button = ({ label, onClick, variant }) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+```
+
+## Event Handlers
+
+Type event handlers correctly.
+
+```tsx
+// Good - Typed event handlers
+const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+  setQuery(e.target.value);
+};
+
+const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+  e.preventDefault();
+  submitForm();
+};
+
+const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+  console.log('Clicked at', e.clientX, e.clientY);
+};
+
+const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+  if (e.key === 'Enter') {
+    handleSubmit();
+  }
+};
+
+// Bad - Any type
+const handleChange = (e: any) => {
+  setQuery(e.target.value);
+};
+```
+
+## Hooks with TypeScript
+
+Type hooks properly.
+
+```tsx
+// Good - Typed useState
+const [user, setUser] = useState<User | null>(null);
+const [items, setItems] = useState<Item[]>([]);
+const [loading, setLoading] = useState<boolean>(false);
+
+// Good - Typed useRef
+const inputRef = useRef<HTMLInputElement>(null);
+const timerRef = useRef<NodeJS.Timeout | null>(null);
+
+// Good - Typed useReducer
+type State = { count: number; error: string | null };
+type Action = { type: 'increment' } | { type: 'error'; payload: string };
+
+const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case 'increment':
+      return { ...state, count: state.count + 1 };
+    case 'error':
+      return { ...state, error: action.payload };
+    default:
+      return state;
+  }
+};
+
+const [state, dispatch] = useReducer(reducer, { count: 0, error: null });
+
+// Good - Typed custom hook
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+  
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+  
+  return [value, setValue] as const;
+}
+```
+
+## Children Props
+
+Type children correctly.
+
+```tsx
+// Good - ReactNode for any children
+interface CardProps {
+  children: React.ReactNode;
+  title: string;
+}
+
+// Good - Specific child type
+interface ListProps {
+  children: React.ReactElement<ItemProps> | React.ReactElement<ItemProps>[];
+}
+
+// Good - Render prop
+interface DataProviderProps<T> {
+  data: T[];
+  children: (item: T) => React.ReactNode;
+}
+
+const DataProvider = <T,>({ data, children }: DataProviderProps<T>) => (
+  <>{data.map(children)}</>
+);
+```
+
+## Generic Components
+
+Create reusable generic components.
+
+```tsx
+// Good - Generic list component
+interface ListProps<T> {
+  items: T[];
+  renderItem: (item: T) => React.ReactNode;
+  keyExtractor: (item: T) => string;
+}
+
+function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
+  return (
+    <ul>
+      {items.map(item => (
+        <li key={keyExtractor(item)}>
+          {renderItem(item)}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+// Usage
+<List
+  items={users}
+  renderItem={(user) => <UserCard user={user} />}
+  keyExtractor={(user) => user.id}
+/>
+```
+
+## Context with TypeScript
+
+Type context properly.
+
+```tsx
+// Good - Typed context
+interface AuthContextValue {
+  user: User | null;
+  login: (email: string, password: string) => Promise<void>;
+  logout: () => void;
+  isAuthenticated: boolean;
+}
+
+const AuthContext = createContext<AuthContextValue | undefined>(undefined);
+
+export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [user, setUser] = useState<User | null>(null);
+  
+  const login = async (email: string, password: string) => {
+    const user = await api.login(email, password);
+    setUser(user);
+  };
+  
+  const logout = () => {
+    setUser(null);
+  };
+  
+  const value: AuthContextValue = {
+    user,
+    login,
+    logout,
+    isAuthenticated: !!user
+  };
+  
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+};
+
+export const useAuth = (): AuthContextValue => {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error('useAuth must be used within AuthProvider');
+  }
+  return context;
+};
+```
+
+## Utility Types
+
+Use TypeScript utility types.
+
+```tsx
+// Good - Utility types
+type UserFormData = Pick<User, 'name' | 'email' | 'age'>;
+type PartialUser = Partial<User>;
+type ReadonlyUser = Readonly<User>;
+type UserWithoutId = Omit<User, 'id'>;
+type RequiredUser = Required<User>;
+
+// Good - Component prop utilities
+type ButtonVariant = 'primary' | 'secondary' | 'danger';
+type ButtonSize = 'small' | 'medium' | 'large';
+
+interface BaseButtonProps {
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+type PrimaryButtonProps = BaseButtonProps & {
+  variant: 'primary';
+  icon?: React.ReactNode;
+};
+
+type SecondaryButtonProps = BaseButtonProps & {
+  variant: 'secondary';
+  outline?: boolean;
+};
+
+type ButtonProps = PrimaryButtonProps | SecondaryButtonProps;
+```
+
+## Best Practices
+
+1. **Always type props** - Use interfaces or types
+2. **Type event handlers** - Use React event types
+3. **Type hooks** - Provide generic types to hooks
+4. **Use strict mode** - Enable strict TypeScript settings
+5. **Avoid any** - Use unknown or proper types
+6. **Use utility types** - Pick, Omit, Partial, etc.
+7. **Type children** - Use React.ReactNode
+8. **Export types** - Make types reusable
+9. **Use const assertions** - For readonly arrays/objects
+10. **Enable ESLint** - Use @typescript-eslint rules
+

package/augment-extensions/domain-rules/api-design/README.md

@@ -0,0 +1,41 @@
+# API Design Guidelines
+
+Comprehensive guidelines for designing robust, scalable, and maintainable APIs.
+
+## Overview
+
+This module provides detailed guidelines for API design including REST principles, GraphQL best practices, versioning strategies, and general API design patterns.
+
+## Key Benefits
+
+- **RESTful Design**: Proper REST API architecture
+- **GraphQL Patterns**: Modern GraphQL API design
+- **Versioning**: API versioning strategies
+- **Security**: Authentication and authorization patterns
+- **Documentation**: API documentation best practices
+
+## Installation
+
+```bash
+augx link domain-rules/api-design
+```
+
+## Contents
+
+### Rules
+
+- **rest-api.md** - RESTful API design principles
+- **graphql-api.md** - GraphQL API best practices
+- **versioning.md** - API versioning strategies
+- **authentication.md** - Authentication and authorization
+- **error-handling.md** - API error handling patterns
+- **documentation.md** - API documentation guidelines
+
+## Character Count
+
+~35,000 characters
+
+## Version
+
+1.0.0
+

package/augment-extensions/domain-rules/api-design/module.json

@@ -0,0 +1,27 @@
+{
+  "name": "api-design",
+  "version": "1.0.0",
+  "displayName": "API Design Guidelines",
+  "description": "Comprehensive API design guidelines including REST, GraphQL, versioning, and best practices",
+  "type": "domain-rules",
+  "author": "Augment Extensions",
+  "license": "MIT",
+  "augment": {
+    "characterCount": 35000,
+    "priority": "high",
+    "category": "domain-rules"
+  },
+  "installation": {
+    "required": false,
+    "dependencies": []
+  },
+  "tags": [
+    "api",
+    "rest",
+    "graphql",
+    "versioning",
+    "http",
+    "best-practices"
+  ]
+}
+

package/augment-extensions/domain-rules/api-design/rules/authentication.md

@@ -0,0 +1,263 @@
+# API Authentication & Authorization
+
+Best practices for securing APIs with authentication and authorization.
+
+## Authentication Methods
+
+### JWT (JSON Web Tokens) - Recommended
+
+Stateless authentication using signed tokens.
+
+```
+# Request
+POST /api/v1/auth/login
+{
+  "email": "user@example.com",
+  "password": "secret"
+}
+
+# Response
+{
+  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "expiresIn": 3600
+}
+
+# Subsequent requests
+GET /api/v1/users/me
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# Advantages:
+- Stateless (no server-side session storage)
+- Scalable
+- Works across domains
+- Contains user claims
+
+# Disadvantages:
+- Cannot revoke before expiration (use short expiry + refresh tokens)
+- Larger than session IDs
+```
+
+### API Keys
+
+Simple authentication for service-to-service communication.
+
+```
+# Request
+GET /api/v1/data
+X-API-Key: sk_live_abc123def456
+
+# Or in query parameter (less secure)
+GET /api/v1/data?api_key=sk_live_abc123def456
+
+# Advantages:
+- Simple to implement
+- Good for service-to-service auth
+
+# Disadvantages:
+- No user context
+- Hard to rotate
+- Can be leaked in logs/URLs
+```
+
+### OAuth 2.0
+
+Delegated authorization for third-party access.
+
+```
+# Authorization Code Flow
+1. Client redirects to authorization server
+   GET /oauth/authorize?
+     response_type=code&
+     client_id=abc123&
+     redirect_uri=https://app.com/callback&
+     scope=read:users
+
+2. User approves, redirected back with code
+   https://app.com/callback?code=xyz789
+
+3. Exchange code for token
+   POST /oauth/token
+   {
+     "grant_type": "authorization_code",
+     "code": "xyz789",
+     "client_id": "abc123",
+     "client_secret": "secret",
+     "redirect_uri": "https://app.com/callback"
+   }
+
+4. Response with access token
+   {
+     "access_token": "...",
+     "refresh_token": "...",
+     "expires_in": 3600,
+     "token_type": "Bearer"
+   }
+
+# Use access token
+GET /api/v1/users
+Authorization: Bearer <access_token>
+```
+
+## Token Management
+
+### Access & Refresh Tokens
+
+```
+# Access Token (short-lived: 15 minutes - 1 hour)
+{
+  "sub": "user123",
+  "email": "user@example.com",
+  "role": "admin",
+  "exp": 1640000000,
+  "iat": 1639996400
+}
+
+# Refresh Token (long-lived: 7-30 days)
+- Stored securely (httpOnly cookie or secure storage)
+- Used to obtain new access tokens
+- Can be revoked
+
+# Refresh flow
+POST /api/v1/auth/refresh
+{
+  "refreshToken": "..."
+}
+
+Response:
+{
+  "accessToken": "...",
+  "expiresIn": 3600
+}
+```
+
+### Token Storage
+
+```
+# Good - Secure storage
+- Access token: Memory or sessionStorage (web)
+- Refresh token: httpOnly cookie (web) or secure storage (mobile)
+
+# Bad - Insecure storage
+- localStorage (vulnerable to XSS)
+- URL parameters (logged in server logs)
+- Unencrypted storage
+```
+
+## Authorization
+
+### Role-Based Access Control (RBAC)
+
+```
+# User roles
+{
+  "sub": "user123",
+  "role": "admin",
+  "permissions": ["read:users", "write:users", "delete:users"]
+}
+
+# Endpoint protection
+GET /api/v1/users          - Requires: read:users
+POST /api/v1/users         - Requires: write:users
+DELETE /api/v1/users/123   - Requires: delete:users
+
+# Implementation
+if (!user.permissions.includes('write:users')) {
+  return 403 Forbidden
+}
+```
+
+### Attribute-Based Access Control (ABAC)
+
+```
+# More granular control
+{
+  "sub": "user123",
+  "department": "engineering",
+  "level": "senior"
+}
+
+# Rules
+- Users can edit their own profile
+- Managers can edit profiles in their department
+- Admins can edit all profiles
+
+# Implementation
+if (resource.userId === user.id) {
+  return true; // Own resource
+}
+if (user.role === 'manager' && resource.department === user.department) {
+  return true; // Same department
+}
+if (user.role === 'admin') {
+  return true; // Admin access
+}
+return false;
+```
+
+## Security Best Practices
+
+### HTTPS Only
+
+```
+# Always use HTTPS
+https://api.example.com/v1/users ✅
+http://api.example.com/v1/users  ❌
+
+# Redirect HTTP to HTTPS
+# Set HSTS header
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+```
+
+### Rate Limiting
+
+```
+# Response headers
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1640000000
+
+# When exceeded
+HTTP/1.1 429 Too Many Requests
+Retry-After: 3600
+
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Too many requests. Please try again later."
+  }
+}
+```
+
+### CORS Configuration
+
+```
+# Proper CORS headers
+Access-Control-Allow-Origin: https://app.example.com
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE
+Access-Control-Allow-Headers: Authorization, Content-Type
+Access-Control-Max-Age: 86400
+
+# Don't use wildcard with credentials
+Access-Control-Allow-Origin: * ❌ (with credentials)
+Access-Control-Allow-Credentials: true
+```
+
+## Best Practices
+
+1. **Use HTTPS** - Always encrypt traffic
+2. **Use JWT** - For stateless authentication
+3. **Short-lived tokens** - Access tokens expire quickly
+4. **Refresh tokens** - For obtaining new access tokens
+5. **Secure storage** - httpOnly cookies or secure storage
+6. **Validate tokens** - Verify signature and expiration
+7. **Rate limiting** - Prevent abuse
+8. **CORS properly** - Don't use wildcard with credentials
+9. **Log auth events** - Track login attempts
+10. **Use strong secrets** - For signing tokens
+11. **Rotate secrets** - Periodically change signing keys
+12. **Implement logout** - Invalidate refresh tokens
+13. **Multi-factor auth** - For sensitive operations
+14. **Monitor suspicious activity** - Detect brute force
+15. **Document auth flow** - Clear documentation for clients
+