@aicgen/aicgen 1.0.0-beta.1

package/data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lahiru Pathirage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/data/README.md

@@ -0,0 +1,203 @@
+# aicgen Guidelines Repository
+
+This repository contains coding guidelines and best practices that power aicgen configurations.
+
+## Directory Structure
+
+```
+data/
+├── guideline-mappings.yml    # Maps guideline IDs to files and filters
+├── api/                      # API design patterns
+├── architecture/             # Architecture patterns (clean, DDD, etc.)
+├── database/                 # Database guidelines
+├── devops/                   # CI/CD and deployment
+├── error-handling/           # Error handling strategies
+├── language/                 # Language-specific (typescript, python)
+├── patterns/                 # Design patterns
+├── performance/              # Performance optimization
+├── practices/                # Best practices
+├── security/                 # Security guidelines
+├── style/                    # Code style guidelines
+├── templates/                # Reusable templates
+└── testing/                  # Testing strategies
+```
+
+## Contributing Guidelines
+
+### Step 1: Create Your Guideline File
+
+Create a markdown file in the appropriate category folder:
+
+```bash
+# Example: Adding a new TypeScript guideline
+data/language/typescript/my-guideline.md
+```
+
+**Guideline Format:**
+
+```markdown
+# Guideline Title
+
+Brief description of what this guideline covers.
+
+## Section 1
+
+Clear, actionable instructions with code examples:
+
+\`\`\`typescript
+// Good example
+function goodExample(): string {
+  return "well-structured code";
+}
+
+// Bad example - explain why
+function badExample() {  // Missing return type
+  return "unclear code";
+}
+\`\`\`
+
+## Section 2
+
+More sections as needed...
+```
+
+**Writing Tips:**
+- Be concise and actionable
+- Include both good and bad code examples
+- Use language-appropriate code blocks
+- Focus on the "why" not just the "what"
+
+### Step 2: Add to Mappings
+
+Add your guideline to `guideline-mappings.yml`:
+
+```yaml
+my-guideline-id:
+  path: language/typescript/my-guideline.md
+  category: Language
+  languages:
+    - typescript
+  levels:
+    - standard
+    - expert
+    - full
+  tags:
+    - typescript
+    - relevant-tag
+```
+
+### Mapping Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `path` | Yes | Relative path to the guideline file |
+| `category` | Yes | Display category (Language, Architecture, Testing, etc.) |
+| `languages` | No | Which languages this applies to. Omit for all languages |
+| `levels` | No | Instruction levels: `basic`, `standard`, `expert`, `full`. Omit for all |
+| `architectures` | No | Architecture types. Omit for all |
+| `tags` | No | Search/organization tags |
+
+### Available Values
+
+**Languages:**
+- `typescript`, `python`, `go`, `rust`, `java`, `csharp`, `ruby`, `php`, `swift`, `kotlin`
+
+**Levels:**
+- `basic` - Essential guidelines only
+- `standard` - Common best practices
+- `expert` - Advanced patterns
+- `full` - Comprehensive coverage
+
+**Architectures:**
+- `layered`, `clean-architecture`, `hexagonal`, `ddd`, `microservices`
+- `modular-monolith`, `event-driven`, `serverless`, `other`
+
+**Categories:**
+- `Language`, `Architecture`, `Testing`, `Security`, `Performance`
+- `Database`, `API Design`, `Code Style`, `Error Handling`, `DevOps`
+- `Best Practices`, `Design Patterns`
+
+## Examples
+
+### Language-Specific Guideline
+
+```yaml
+typescript-decorators:
+  path: language/typescript/decorators.md
+  category: Language
+  languages:
+    - typescript
+  levels:
+    - expert
+    - full
+  tags:
+    - typescript
+    - decorators
+    - metadata
+```
+
+### Universal Guideline (All Languages)
+
+```yaml
+solid-principles:
+  path: architecture/solid/principles.md
+  category: Architecture
+  levels:
+    - standard
+    - expert
+    - full
+  tags:
+    - solid
+    - design-principles
+    - oop
+```
+
+### Architecture-Specific Guideline
+
+```yaml
+ddd-aggregates:
+  path: architecture/ddd/aggregates.md
+  category: Architecture
+  architectures:
+    - ddd
+    - clean-architecture
+  levels:
+    - expert
+    - full
+  tags:
+    - ddd
+    - aggregates
+    - domain-model
+```
+
+## Testing Your Changes
+
+After adding a guideline:
+
+1. **Rebuild aicgen:**
+   ```bash
+   bun run build
+   ```
+
+2. **Check it's loaded:**
+   ```bash
+   bun run start stats
+   ```
+
+3. **Test generation:**
+   ```bash
+   bun run start init --force
+   ```
+
+## Guideline Quality Checklist
+
+- [ ] Clear, descriptive title
+- [ ] Actionable instructions
+- [ ] Code examples (good and bad)
+- [ ] Appropriate language/level targeting
+- [ ] Meaningful category and tags
+- [ ] No duplicate content with existing guidelines
+
+## License
+
+MIT License - See LICENSE file

package/data/api/basics.md

@@ -0,0 +1,292 @@
+# API Basics
+
+## HTTP Methods
+
+Use the right method for each operation:
+
+| Method | Purpose | Example |
+|--------|---------|---------|
+| GET | Read data | Get list of users |
+| POST | Create new resource | Create a new user |
+| PUT | Replace entire resource | Update all user fields |
+| PATCH | Update part of resource | Update user's email only |
+| DELETE | Remove resource | Delete a user |
+
+## GET - Reading Data
+
+```pseudocode
+// Get all items
+route GET "/api/users":
+    users = getAllUsers()
+    return JSON(users)
+
+// Get single item by ID
+route GET "/api/users/:id":
+    user = getUserById(params.id)
+    if user is null:
+        return status 404, JSON({ error: "User not found" })
+    return JSON(user)
+```
+
+## POST - Creating Data
+
+```pseudocode
+route POST "/api/users":
+    name = request.body.name
+    email = request.body.email
+
+    // Validate input
+    if name is empty or email is empty:
+        return status 400, JSON({ error: "Name and email required" })
+
+    newUser = createUser({ name, email })
+
+    // Return 201 Created with new resource
+    return status 201, JSON(newUser)
+```
+
+## PUT - Replacing Data
+
+```pseudocode
+route PUT "/api/users/:id":
+    id = params.id
+    name = request.body.name
+    email = request.body.email
+
+    user = getUserById(id)
+    if user is null:
+        return status 404, JSON({ error: "User not found" })
+
+    updated = replaceUser(id, { name, email })
+    return JSON(updated)
+```
+
+## PATCH - Updating Data
+
+```pseudocode
+route PATCH "/api/users/:id":
+    id = params.id
+    updates = request.body  // Only fields to update
+
+    user = getUserById(id)
+    if user is null:
+        return status 404, JSON({ error: "User not found" })
+
+    updated = updateUser(id, updates)
+    return JSON(updated)
+```
+
+## DELETE - Removing Data
+
+```pseudocode
+route DELETE "/api/users/:id":
+    id = params.id
+
+    user = getUserById(id)
+    if user is null:
+        return status 404, JSON({ error: "User not found" })
+
+    deleteUser(id)
+
+    // 204 No Content - successful deletion
+    return status 204
+```
+
+## HTTP Status Codes
+
+### Success Codes (2xx)
+
+```pseudocode
+// 200 OK - Request succeeded
+return status 200, JSON(data)
+
+// 201 Created - New resource created
+return status 201, JSON(newResource)
+
+// 204 No Content - Success with no response body
+return status 204
+```
+
+### Client Error Codes (4xx)
+
+```pseudocode
+// 400 Bad Request - Invalid input
+return status 400, JSON({ error: "Invalid email format" })
+
+// 401 Unauthorized - Not authenticated
+return status 401, JSON({ error: "Login required" })
+
+// 403 Forbidden - Authenticated but not allowed
+return status 403, JSON({ error: "Admin access required" })
+
+// 404 Not Found - Resource doesn't exist
+return status 404, JSON({ error: "User not found" })
+
+// 409 Conflict - Resource already exists
+return status 409, JSON({ error: "Email already registered" })
+```
+
+### Server Error Codes (5xx)
+
+```pseudocode
+// 500 Internal Server Error - Unexpected error
+return status 500, JSON({ error: "Internal server error" })
+
+// 503 Service Unavailable - Temporary issue
+return status 503, JSON({ error: "Database unavailable" })
+```
+
+## URL Structure
+
+Use clear, hierarchical URLs:
+
+```
+✅ Good
+GET  /api/users           # List all users
+GET  /api/users/123       # Get user 123
+POST /api/users           # Create user
+GET  /api/users/123/posts # Get posts by user 123
+
+❌ Bad
+GET  /api/getUsers
+POST /api/createUser
+GET  /api/user?id=123
+```
+
+## Request and Response Format
+
+### JSON Request Body
+
+```
+// Client sends
+POST /api/users
+Content-Type: application/json
+
+{
+  "name": "Alice",
+  "email": "alice@example.com"
+}
+```
+
+### JSON Response
+
+```
+// Server responds
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+  "id": 123,
+  "name": "Alice",
+  "email": "alice@example.com",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+
+## Query Parameters
+
+Use query parameters for filtering, sorting, and pagination:
+
+```pseudocode
+// Filter by status
+// GET /api/orders?status=pending
+route GET "/api/orders":
+    status = query.status
+    orders = getOrders({ status })
+    return JSON(orders)
+
+// Sort by field
+// GET /api/users?sort=name
+
+// Pagination
+// GET /api/users?page=2&limit=20
+```
+
+## Error Responses
+
+Always return consistent error format:
+
+```pseudocode
+// ✅ Good: Structured error
+return status 400, JSON({
+    error: {
+        code: "VALIDATION_ERROR",
+        message: "Invalid input",
+        details: {
+            email: "Email format is invalid"
+        }
+    }
+})
+
+// ❌ Bad: Inconsistent
+return status 400, "Bad request"
+return status 400, JSON({ msg: "Error" })
+```
+
+## Best Practices
+
+1. **Use correct HTTP methods** - GET for reading, POST for creating, etc.
+2. **Use appropriate status codes** - 200 for success, 404 for not found, etc.
+3. **Return JSON** - Standard format for APIs
+4. **Validate input** - Check data before processing
+5. **Handle errors** - Return clear error messages
+
+```pseudocode
+// Complete example
+route POST "/api/products":
+    name = request.body.name
+    price = request.body.price
+
+    // Validate
+    if name is empty or price is empty:
+        return status 400, JSON({
+            error: "Name and price are required"
+        })
+
+    if price < 0:
+        return status 400, JSON({
+            error: "Price cannot be negative"
+        })
+
+    // Check for duplicates
+    if productExists(name):
+        return status 409, JSON({
+            error: "Product already exists"
+        })
+
+    // Create
+    product = createProduct({ name, price })
+
+    // Return success
+    return status 201, JSON(product)
+```
+
+## Common Mistakes
+
+```pseudocode
+// ❌ Wrong method for operation
+route GET "/api/users/delete/:id"  // Should be DELETE
+
+// ❌ Wrong status code
+route POST "/api/users":
+    user = createUser(body)
+    return status 200, JSON(user)  // Should be 201
+
+// ❌ Not handling missing resources
+route GET "/api/users/:id":
+    user = getUserById(params.id)
+    return JSON(user)  // What if user is null?
+
+// ✅ Correct
+route DELETE "/api/users/:id"
+
+route POST "/api/users":
+    user = createUser(body)
+    return status 201, JSON(user)
+
+route GET "/api/users/:id":
+    user = getUserById(params.id)
+    if user is null:
+        return status 404, JSON({ error: "User not found" })
+    return JSON(user)
+```

package/data/api/index.md

@@ -0,0 +1,8 @@
+# API Design Guidelines
+
+This directory contains REST API design patterns.
+
+## Available Chunks
+
+- **rest.md** - Resource-oriented design, HTTP methods, status codes
+- **pagination.md** - Offset-based, cursor-based, HATEOAS links

package/data/api/pagination.md

@@ -0,0 +1,142 @@
+# API Pagination
+
+## Always Paginate Collections
+
+```typescript
+// ✅ Paginated endpoint
+app.get('/api/v1/books', async (req, res) => {
+  const page = parseInt(req.query.page as string) || 1;
+  const limit = Math.min(parseInt(req.query.limit as string) || 20, 100);
+
+  const { data, total } = await bookService.findAll({ page, limit });
+
+  res.json({
+    data,
+    pagination: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+      hasNext: page * limit < total,
+      hasPrevious: page > 1
+    }
+  });
+});
+```
+
+## Offset-Based Pagination
+
+```typescript
+// Simple but has issues with large datasets
+GET /api/v1/books?page=1&limit=20
+GET /api/v1/books?page=2&limit=20
+
+// Implementation
+const getBooks = async (page: number, limit: number) => {
+  const offset = (page - 1) * limit;
+
+  const [data, total] = await Promise.all([
+    db.query('SELECT * FROM books ORDER BY id LIMIT ? OFFSET ?', [limit, offset]),
+    db.query('SELECT COUNT(*) FROM books')
+  ]);
+
+  return { data, total };
+};
+```
+
+## Cursor-Based Pagination
+
+```typescript
+// Better for large datasets and real-time data
+GET /api/v1/books?cursor=eyJpZCI6MTIzfQ&limit=20
+
+// Response includes next cursor
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6MTQzfQ",
+    "hasMore": true
+  }
+}
+
+// Implementation
+const getBooks = async (cursor: string | null, limit: number) => {
+  let query = 'SELECT * FROM books';
+
+  if (cursor) {
+    const { id } = decodeCursor(cursor);
+    query += ` WHERE id > ${id}`;
+  }
+
+  query += ` ORDER BY id LIMIT ${limit + 1}`;
+  const data = await db.query(query);
+
+  const hasMore = data.length > limit;
+  const items = hasMore ? data.slice(0, limit) : data;
+
+  return {
+    data: items,
+    pagination: {
+      nextCursor: hasMore ? encodeCursor({ id: items[items.length - 1].id }) : null,
+      hasMore
+    }
+  };
+};
+```
+
+## Keyset Pagination
+
+```sql
+-- Most efficient for large tables
+-- First page
+SELECT * FROM products
+ORDER BY created_at DESC, id DESC
+LIMIT 20;
+
+-- Next page (using last item's values)
+SELECT * FROM products
+WHERE (created_at, id) < ('2024-01-15 10:00:00', 12345)
+ORDER BY created_at DESC, id DESC
+LIMIT 20;
+```
+
+## HATEOAS Links
+
+```typescript
+// Include navigation links
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "limit": 20,
+    "total": 150
+  },
+  "links": {
+    "self": "/api/v1/books?page=2&limit=20",
+    "first": "/api/v1/books?page=1&limit=20",
+    "prev": "/api/v1/books?page=1&limit=20",
+    "next": "/api/v1/books?page=3&limit=20",
+    "last": "/api/v1/books?page=8&limit=20"
+  }
+}
+```
+
+## Pagination Best Practices
+
+```typescript
+// ✅ Set reasonable defaults and limits
+const page = parseInt(req.query.page) || 1;
+const limit = Math.min(parseInt(req.query.limit) || 20, 100);
+
+// ✅ Include total count (when practical)
+const total = await db.count('books');
+
+// ✅ Use consistent response structure
+{
+  "data": [],
+  "pagination": { ... }
+}
+
+// ❌ Don't return unlimited results
+// ❌ Don't allow page < 1 or limit < 1
+```