@riligar/agents-kit 1.9.0 → 1.10.0

package/.agent/rules/code-style.md

@@ -0,0 +1,127 @@
+# Code Style
+
+All code must follow the RiLiGar formatting standards enforced by Prettier.
+
+## Formatting Rules
+
+| Rule | Value | Example |
+| --- | --- | --- |
+| Indentation | 4 spaces | `    const x = 1` |
+| Tabs | Never | Use spaces only |
+| Semicolons | Never | `const x = 1` not `const x = 1;` |
+| Quotes | Single | `'string'` not `"string"` |
+| Trailing Commas | ES5 | Arrays and objects, not function params |
+| Bracket Spacing | Yes | `{ key: value }` not `{key: value}` |
+| Arrow Parens | Avoid | `x => x` not `(x) => x` |
+| Line Endings | LF | Unix-style |
+| Print Width | 300 | Long lines allowed |
+| JSX Attributes | One per line | See below |
+
+## JSX Formatting
+
+```jsx
+// Good - one attribute per line
+<Button
+    variant="filled"
+    color="blue"
+    onClick={handleClick}
+>
+    Submit
+</Button>
+
+// Bad - multiple attributes on same line
+<Button variant="filled" color="blue" onClick={handleClick}>Submit</Button>
+```
+
+## Code Examples
+
+```javascript
+// Good
+const getUserData = async id => {
+    const response = await fetch(`/api/users/${id}`)
+    return response.json()
+}
+
+const config = {
+    apiUrl: 'https://api.example.com',
+    timeout: 5000,
+    retries: 3,
+}
+
+// Bad
+const getUserData = async (id) => {
+    const response = await fetch("/api/users/" + id);
+    return response.json();
+};
+
+const config = {apiUrl: "https://api.example.com", timeout: 5000, retries: 3}
+```
+
+## Object and Array Formatting
+
+```javascript
+// Good - trailing comma
+const options = {
+    name: 'app',
+    version: '1.0.0',
+    debug: true,
+}
+
+const items = [
+    'first',
+    'second',
+    'third',
+]
+
+// Bad - no trailing comma
+const options = {
+    name: 'app',
+    version: '1.0.0',
+    debug: true
+}
+```
+
+## Import Organization
+
+```javascript
+// 1. External dependencies
+import { useState, useEffect } from 'react'
+import { Button, Text } from '@mantine/core'
+
+// 2. Internal modules
+import { useAuth } from '@/hooks/useAuth'
+import { api } from '@/services/api'
+
+// 3. Components
+import { Header } from '@/components/Header'
+
+// 4. Styles, assets, types (if any)
+import styles from './styles.module.css'
+```
+
+## Prettier Config Reference
+
+```json
+{
+    "printWidth": 300,
+    "singleAttributePerLine": true,
+    "tabWidth": 4,
+    "useTabs": false,
+    "semi": false,
+    "singleQuote": true,
+    "quoteProps": "as-needed",
+    "trailingComma": "es5",
+    "bracketSpacing": true,
+    "bracketSameLine": false,
+    "arrowParens": "avoid",
+    "endOfLine": "lf"
+}
+```
+
+## Auto-Format
+
+Run Prettier before committing:
+
+```bash
+bunx prettier --write .
+```

package/.agent/rules/conventional-commits.md

@@ -1,18 +1,96 @@
-# Conventional Commits Standards
+# Conventional Commits
 
-All commits in this repository must follow the Conventional Commits specification. This ensures that our automated release pipeline can correctly calculate version bumps and generate changelogs.
+All commits must follow the Conventional Commits specification for automated releases and changelogs.
 
 ## Format
 
-`<type>(<scope>): <description>`
+```
+<type>(<scope>): <description>
 
-## Types
+[optional body]
 
-- `feat`: A new feature (triggers a MINOR version bump)
-- `fix`: A bug fix (triggers a PATCH version bump)
-- `docs`: Documentation only changes
-- `style`: Changes that do not affect the meaning of the code
-- `refactor`: A code change that neither fixes a bug nor adds a feature
-- `perf`: A code change that improves performance
-- `test`: Adding missing tests or correcting existing tests
-- `chore`: Changes to the build process or auxiliary tools and libraries
+[optional footer(s)]
+```
+
+## Types and Version Bumps
+
+| Type | Description | Version Bump |
+| --- | --- | --- |
+| `feat` | New feature | MINOR |
+| `fix` | Bug fix | PATCH |
+| `docs` | Documentation changes | PATCH (if scope: README) |
+| `style` | Code style (formatting, no logic change) | PATCH |
+| `refactor` | Code refactoring (no new feature, no fix) | PATCH |
+| `perf` | Performance improvement | PATCH |
+| `test` | Adding or fixing tests | No release |
+| `chore` | Build process, dependencies, tooling | No release |
+| `chore(release)` | Automated release commits | No release (skip CI) |
+
+## Breaking Changes
+
+For MAJOR version bumps, add `BREAKING CHANGE:` in the footer or `!` after type:
+
+```
+feat!: remove deprecated API endpoints
+
+BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.
+```
+
+## Scope (Optional)
+
+Scope provides context. Common scopes:
+
+- `feat(auth)`: Authentication feature
+- `fix(api)`: API bug fix
+- `docs(README)`: README update
+- `refactor(components)`: Component refactoring
+
+## Examples
+
+```bash
+# Feature (MINOR bump)
+feat: add dark mode toggle to settings
+
+# Bug fix (PATCH bump)
+fix: resolve race condition in form submission
+
+# Documentation (PATCH bump if README)
+docs(README): update installation instructions
+
+# Refactor (PATCH bump)
+refactor: extract validation logic to separate module
+
+# Style (PATCH bump)
+style: format code with prettier
+
+# Chore (no release)
+chore: update dependencies
+
+# Breaking change (MAJOR bump)
+feat!: redesign authentication flow
+
+BREAKING CHANGE: Session tokens now use JWT format.
+```
+
+## Branches
+
+| Branch | Release Type | Tag |
+| --- | --- | --- |
+| `prod` | Production release | `v1.2.3` |
+| `main` | Pre-release | `v1.2.3-rc.1` |
+
+## Quick Reference
+
+```bash
+# Good
+feat: add user profile page
+fix(auth): handle expired tokens gracefully
+docs: update API documentation
+refactor(utils): simplify date formatting
+
+# Bad
+added new feature          # no type
+feat add something         # missing colon
+Feat: Add Something        # wrong case
+feat(): empty scope        # don't use empty scope
+```

package/.agent/rules/javascript-only.md

@@ -0,0 +1,116 @@
+# JavaScript Only
+
+RiLiGar projects use **JavaScript ES6+ exclusively**. TypeScript is prohibited.
+
+## Why No TypeScript
+
+- **Simplicity** — Less tooling, faster builds, no compilation step
+- **Bun Native** — Bun runs JavaScript directly with excellent performance
+- **Reduced Complexity** — No type gymnastics, no `any` escapes, no config overhead
+- **Runtime Validation** — Use runtime checks where needed (Zod, validators)
+
+## Allowed
+
+```javascript
+// Modern JavaScript ES6+
+const fetchUser = async id => {
+    const response = await fetch(`/api/users/${id}`)
+    return response.json()
+}
+
+// Destructuring
+const { name, email } = user
+
+// Spread operator
+const newConfig = { ...config, debug: true }
+
+// Optional chaining
+const city = user?.address?.city
+
+// Nullish coalescing
+const value = input ?? 'default'
+
+// Array methods
+const names = users.map(u => u.name).filter(Boolean)
+```
+
+## Prohibited
+
+```typescript
+// NO TypeScript files
+// ❌ .ts, .tsx files
+// ❌ tsconfig.json
+// ❌ Type annotations
+
+// Bad
+const fetchUser = async (id: string): Promise<User> => { ... }
+interface User { name: string; email: string }
+type Status = 'active' | 'inactive'
+
+// Good (JavaScript)
+const fetchUser = async id => { ... }
+```
+
+## File Extensions
+
+| Allowed | Prohibited |
+| --- | --- |
+| `.js` | `.ts` |
+| `.jsx` | `.tsx` |
+| `.mjs` | `.mts` |
+| `.cjs` | `.cts` |
+
+## Runtime Validation (When Needed)
+
+For API boundaries or user input, use runtime validation:
+
+```javascript
+// Using Zod for runtime validation
+import { z } from 'zod'
+
+const UserSchema = z.object({
+    name: z.string().min(1),
+    email: z.string().email(),
+    age: z.number().optional(),
+})
+
+const validateUser = data => {
+    return UserSchema.parse(data)
+}
+```
+
+## JSDoc (Optional)
+
+If documentation is needed, use JSDoc comments:
+
+```javascript
+/**
+ * Fetches user data from the API
+ * @param {string} id - The user ID
+ * @returns {Promise<Object>} The user data
+ */
+const fetchUser = async id => {
+    const response = await fetch(`/api/users/${id}`)
+    return response.json()
+}
+```
+
+## IDE Support
+
+For better IDE experience without TypeScript:
+
+1. Use JSDoc annotations where helpful
+2. Configure VS Code `jsconfig.json` for path aliases
+3. Rely on Prettier for consistent formatting
+
+```json
+// jsconfig.json
+{
+    "compilerOptions": {
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["src/*"]
+        }
+    }
+}
+```

package/.agent/rules/naming-conventions.md

@@ -0,0 +1,168 @@
+# Naming Conventions
+
+Consistent naming across all RiLiGar projects.
+
+## Quick Reference
+
+| Element | Convention | Example |
+| --- | --- | --- |
+| Components | PascalCase | `UserProfile`, `NavBar` |
+| Functions | camelCase | `getUserData`, `handleSubmit` |
+| Variables | camelCase | `userName`, `isLoading` |
+| Constants | SCREAMING_SNAKE | `API_URL`, `MAX_RETRIES` |
+| Files (components) | PascalCase | `UserProfile.jsx` |
+| Files (utilities) | camelCase | `formatDate.js` |
+| Directories | kebab-case | `user-profile/`, `api-utils/` |
+| CSS classes | kebab-case | `nav-bar`, `user-card` |
+| Database tables | snake_case | `user_profiles`, `order_items` |
+| API endpoints | kebab-case | `/api/user-profiles`, `/api/order-items` |
+
+## Components
+
+```javascript
+// File: UserProfile.jsx
+// Component name matches file name
+
+// Good
+const UserProfile = ({ user }) => {
+    return <div>{user.name}</div>
+}
+
+export default UserProfile
+
+// Bad
+const userProfile = ({ user }) => { ... }  // lowercase
+const User_Profile = ({ user }) => { ... } // underscore
+```
+
+## Functions and Variables
+
+```javascript
+// Good
+const getUserById = async id => { ... }
+const isAuthenticated = true
+const handleFormSubmit = event => { ... }
+const totalItemCount = items.length
+
+// Bad
+const GetUserById = async id => { ... }    // PascalCase
+const is_authenticated = true               // snake_case
+const handle_form_submit = event => { ... } // snake_case
+```
+
+## Constants
+
+```javascript
+// Good
+const API_BASE_URL = 'https://api.example.com'
+const MAX_RETRY_ATTEMPTS = 3
+const DEFAULT_PAGE_SIZE = 20
+
+// Bad
+const apiBaseUrl = 'https://api.example.com'  // camelCase
+const maxRetryAttempts = 3                    // camelCase
+```
+
+## Booleans
+
+Prefix with `is`, `has`, `can`, `should`:
+
+```javascript
+// Good
+const isLoading = true
+const hasPermission = user.role === 'admin'
+const canEdit = hasPermission && !isLocked
+const shouldRefresh = lastUpdate < threshold
+
+// Bad
+const loading = true
+const permission = true
+const edit = true
+```
+
+## Event Handlers
+
+Prefix with `handle` or `on`:
+
+```javascript
+// In component definition - use "handle"
+const handleClick = () => { ... }
+const handleSubmit = event => { ... }
+const handleInputChange = value => { ... }
+
+// In props - use "on"
+<Button onClick={handleClick} />
+<Form onSubmit={handleSubmit} />
+<Input onChange={handleInputChange} />
+```
+
+## Hooks
+
+Prefix with `use`:
+
+```javascript
+// Good
+const useAuth = () => { ... }
+const useLocalStorage = key => { ... }
+const useFetch = url => { ... }
+
+// Bad
+const auth = () => { ... }
+const getFromLocalStorage = key => { ... }
+```
+
+## Directory Structure
+
+```
+src/
+├── components/           # kebab-case directories
+│   ├── user-profile/
+│   │   ├── UserProfile.jsx      # PascalCase component
+│   │   └── UserAvatar.jsx
+│   └── nav-bar/
+│       └── NavBar.jsx
+├── hooks/
+│   ├── useAuth.js               # camelCase hook files
+│   └── useFetch.js
+├── utils/
+│   ├── formatDate.js            # camelCase utility files
+│   └── validateEmail.js
+└── services/
+    └── api.js
+```
+
+## Database and API
+
+```javascript
+// Database tables - snake_case
+// user_profiles, order_items, payment_transactions
+
+// API endpoints - kebab-case
+// GET /api/user-profiles
+// POST /api/order-items
+// GET /api/payment-transactions/:id
+
+// API response keys - camelCase (for JavaScript consumption)
+{
+    "userId": 123,
+    "userName": "john",
+    "createdAt": "2024-01-01"
+}
+```
+
+## Abbreviations
+
+Treat abbreviations as words:
+
+```javascript
+// Good
+const userId = 123
+const apiUrl = '/api'
+const htmlContent = '<div>...</div>'
+const xmlParser = new Parser()
+
+// Bad
+const userID = 123    // ID should be Id
+const APIURL = '/api' // Should be ApiUrl
+const HTMLContent = '<div>...</div>'
+```

package/.agent/rules/pr-guidelines.md

@@ -0,0 +1,121 @@
+# Pull Request Guidelines
+
+Standards for creating and reviewing Pull Requests in RiLiGar projects.
+
+## PR Title
+
+Follow Conventional Commits format:
+
+```
+<type>(<scope>): <description>
+```
+
+Examples:
+- `feat(auth): add magic link authentication`
+- `fix(api): handle timeout errors gracefully`
+- `refactor(components): extract shared button styles`
+
+## PR Description Template
+
+```markdown
+## Summary
+<!-- 1-3 bullet points describing what this PR does -->
+
+- Add magic link authentication flow
+- Create email template for magic links
+- Update auth middleware to handle magic tokens
+
+## Test Plan
+<!-- How to verify this PR works -->
+
+- [ ] Sign up with email and verify magic link arrives
+- [ ] Click magic link and verify redirect to dashboard
+- [ ] Verify expired links show appropriate error
+- [ ] Test on mobile browsers
+```
+
+## PR Size
+
+Keep PRs small and focused:
+
+| Size | Lines Changed | Recommendation |
+| --- | --- | --- |
+| Small | < 100 | Ideal |
+| Medium | 100-300 | Acceptable |
+| Large | 300-500 | Split if possible |
+| Too Large | > 500 | Must split |
+
+## Branch Naming
+
+```
+<type>/<short-description>
+
+feat/magic-link-auth
+fix/timeout-handling
+refactor/button-components
+docs/api-documentation
+```
+
+## Checklist Before Submitting
+
+```markdown
+- [ ] Code follows RiLiGar style guidelines
+- [ ] No TypeScript (JavaScript only)
+- [ ] Prettier formatting applied
+- [ ] No console.log or debug code
+- [ ] Tests pass locally
+- [ ] Self-reviewed the diff
+- [ ] PR title follows Conventional Commits
+- [ ] Description includes test plan
+```
+
+## Review Process
+
+### For Authors
+
+1. **Self-review first** — Read your own diff before requesting review
+2. **Small PRs** — Easier to review, faster to merge
+3. **Clear description** — Explain the "why", not just the "what"
+4. **Respond promptly** — Address feedback within 24 hours
+
+### For Reviewers
+
+1. **Be constructive** — Suggest improvements, don't just criticize
+2. **Ask questions** — If something is unclear, ask
+3. **Approve when ready** — Don't block on nitpicks
+4. **Review within 24h** — Keep the flow moving
+
+## Comment Prefixes
+
+Use prefixes to clarify intent:
+
+| Prefix | Meaning |
+| --- | --- |
+| `nit:` | Minor suggestion, non-blocking |
+| `question:` | Seeking clarification |
+| `suggestion:` | Alternative approach to consider |
+| `issue:` | Must be addressed before merge |
+| `praise:` | Highlighting good code |
+
+Examples:
+```
+nit: Could rename this to `fetchUserData` for clarity
+
+question: Is there a reason we're not using the existing `useAuth` hook here?
+
+issue: This will cause a memory leak - need to cleanup the subscription
+
+praise: Nice use of early returns here, very readable!
+```
+
+## Merge Strategy
+
+- **Squash and merge** — Default for feature branches
+- **Merge commit** — For release branches
+- **Rebase** — Avoid (rewrites history)
+
+## After Merge
+
+1. Delete the feature branch
+2. Verify deployment (if applicable)
+3. Close related issues

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@riligar/agents-kit",
-    "version": "1.9.0",
+    "version": "1.10.0",
     "publishConfig": {
         "access": "public"
     },