class-ai-agent 1.2.3 → 1.4.0

package/.kiro/skills/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/.kiro/steering/agent-continuity.md

@@ -0,0 +1,44 @@
+---
+inclusion: always
+description: "Agent session continuity — cross-tool handoff via .agent/SESSION.md"
+---
+
+# Agent continuity
+
+Cross-tool handoff lives in **`.agent/SESSION.md`** (committed). Cursor, Claude Code, and Kiro agents share this file.
+
+## Session start
+
+1. If **`.agent/SESSION.md`** exists, read it **before** planning or editing code.
+2. When the user says **continue**, **resume**, or **pick up**, use **`.kiro/commands/resume.md`** (or equivalent in `.claude/` / `.kiro/`).
+3. Then read **`tasks/todo.md`** and linked **SPEC** paths from SESSION **Pointers**.
+
+**Do not** call `codegraph_context` with `query` / `limit` for session resume — that tool requires **`task`** and is for code symbols, not handoff state. For continuity, **Read** `.agent/SESSION.md` (and `tasks/todo.md`); use `codegraph_context` only when you need structural code context for the work described in SESSION.
+
+## Session end and phase changes
+
+1. Update **`.agent/SESSION.md`** before ending a session or switching tools — use **`.kiro/commands/handoff.md`** when possible.
+2. Keep **Done**, **In progress**, and **Next** accurate; do not leave stale **In progress** items.
+3. Sync **`tasks/todo.md`** checkboxes when tasks change.
+
+## Security (SESSION.md)
+
+**Never** store in `.agent/SESSION.md`:
+
+- API keys, passwords, tokens, credentials
+- PII or customer data
+
+Use issue links, commit SHAs, and file paths instead.
+
+## Workflow integration
+
+| Phase | SESSION `phase` value |
+|-------|------------------------|
+| Spec | `spec` |
+| Plan | `plan` |
+| Build | `build` |
+| Test | `test` |
+| Review | `review` |
+| Debug | `debug` |
+
+Set **Meta → Tool** to `cursor`, `claude`, or `kiro` as appropriate.

package/.kiro/steering/api-conventions.md

@@ -0,0 +1,85 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "**/*.{ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}"
+description: "API Conventions"
+---
+
+# API Conventions
+
+## REST API Design Standards
+
+### URL Structure
+- Use **kebab-case** for URL paths: `/api/user-profiles`
+- Use **plural nouns** for resource collections: `/api/users`, `/api/products`
+- Nest related resources: `/api/users/:id/orders`
+- API version prefix: `/api/v1/...`
+
+### HTTP Methods
+| Method | Usage |
+|--------|-------|
+| GET | Read resources (idempotent) |
+| POST | Create new resource |
+| PUT | Replace entire resource |
+| PATCH | Partial update |
+| DELETE | Remove resource |
+
+### HTTP Status Codes
+| Code | Meaning |
+|------|---------|
+| 200 | OK — Successful GET/PUT/PATCH |
+| 201 | Created — Successful POST |
+| 204 | No Content — Successful DELETE |
+| 400 | Bad Request — Invalid input |
+| 401 | Unauthorized — Not authenticated |
+| 403 | Forbidden — No permission |
+| 404 | Not Found |
+| 409 | Conflict |
+| 422 | Unprocessable Entity — Validation failed |
+| 500 | Internal Server Error |
+
+### Request/Response Format
+```json
+// Success response
+{
+  "success": true,
+  "data": { ... },
+  "message": "Optional message"
+}
+
+// Error response
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human readable message",
+    "details": [ ... ]
+  }
+}
+
+// Paginated list response
+{
+  "success": true,
+  "data": [ ... ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+### Naming Conventions
+- Request/response body fields: **camelCase**
+- Query parameters: **camelCase**
+- Always return consistent field names
+
+### Filtering & Pagination
+```
+GET /api/users?page=1&limit=20&sortBy=createdAt&order=desc
+GET /api/products?category=electronics&minPrice=100
+```
+
+### Documentation
+- Every endpoint MUST have JSDoc/Swagger annotations
+- Include request body schema, response schema, and error codes

package/.kiro/steering/clean-code.md

@@ -0,0 +1,211 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "**/*.{ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}"
+description: "Clean Code — JavaScript Rules"
+---
+
+# Clean Code — JavaScript Rules
+> Source: [clean-code-javascript](https://github.com/ryanmcdermott/clean-code-javascript) by Ryan McDermott
+
+## 📦 Variables
+
+### ✅ Use meaningful, pronounceable names
+```js
+// ❌ Bad
+const yyyymmdstr = moment().format('YYYY/MM/DD');
+
+// ✅ Good
+const currentDate = moment().format('YYYY/MM/DD');
+```
+
+### ✅ Same vocabulary for same type
+```js
+// ❌ getUserInfo(), getClientData(), getCustomerRecord()
+// ✅ getUser()
+```
+
+### ✅ Use searchable names (no magic numbers)
+```js
+// ❌ setTimeout(blastOff, 86400000);
+const MILLISECONDS_PER_DAY = 60 * 60 * 24 * 1000;
+setTimeout(blastOff, MILLISECONDS_PER_DAY); // ✅
+```
+
+### ✅ Use explanatory variables
+```js
+// ❌ Bad
+saveCityZipCode(address.match(regex)[1], address.match(regex)[2]);
+
+// ✅ Good
+const [_, city, zipCode] = address.match(cityZipCodeRegex) || [];
+saveCityZipCode(city, zipCode);
+```
+
+### ✅ Avoid mental mapping — be explicit
+```js
+// ❌ locations.forEach(l => { dispatch(l); });
+// ✅ locations.forEach(location => { dispatch(location); });
+```
+
+### ✅ Don't add redundant context
+```js
+// ❌ const Car = { carMake, carModel, carColor }
+// ✅ const Car = { make, model, color }
+```
+
+### ✅ Use default parameters
+```js
+// ❌ const name = name || 'Default';
+// ✅ function create(name = 'Default') {}
+```
+
+---
+
+## 🔧 Functions
+
+### ✅ 2 arguments or fewer — use object destructuring for more
+```js
+// ❌ function createMenu(title, body, buttonText, cancellable) {}
+// ✅ function createMenu({ title, body, buttonText, cancellable }) {}
+```
+
+### ✅ Functions should do ONE thing
+```js
+// ❌ emailClients() — fetches DB + checks active + sends email
+// ✅ emailActiveClients() calls isActiveClient() separately
+```
+
+### ✅ Function names should say what they do
+```js
+// ❌ addToDate(date, 1)     → unclear what is added
+// ✅ addMonthToDate(1, date) → crystal clear
+```
+
+### ✅ One level of abstraction per function
+```js
+// ❌ parseBetterJSAlternative() — tokenizes + parses + AST walks in one function
+// ✅ parseBetterJSAlternative() → calls tokenize() → calls parse()
+```
+
+### ✅ Remove duplicate code — extract shared logic
+### ✅ No flag parameters — split into separate functions
+```js
+// ❌ function createFile(name, isTemp) { if (isTemp) ... }
+// ✅ function createFile(name) {}
+//    function createTempFile(name) {}
+```
+
+### ✅ Avoid Side Effects
+- Don't mutate global state
+- Don't mutate function arguments (use copies)
+```js
+// ✅ Return new array instead of mutating
+function addItemToCart(cart, item) {
+  return [...cart, { item, date: Date.now() }];
+}
+```
+
+### ✅ Favor functional programming
+```js
+// ❌ for loop with mutations
+// ✅ filter(), map(), reduce()
+const totalOutput = programmerOutput
+  .filter(p => p.linesOfCode > 0)
+  .reduce((acc, p) => acc + p.linesOfCode, 0);
+```
+
+### ✅ Encapsulate conditionals
+```js
+// ❌ if (fsm.state === 'fetching' && isEmpty(listNode)) {}
+// ✅ if (shouldShowSpinner(fsmInstance, listNodeInstance)) {}
+```
+
+### ✅ Avoid negative conditionals
+```js
+// ❌ if (!isNotDOMNodePresent(node)) {}
+// ✅ if (isDOMNodePresent(node)) {}
+```
+
+### ✅ Remove dead code immediately
+
+---
+
+## 🏛️ Classes
+
+### ✅ Prefer ES6 classes
+### ✅ Use method chaining (builder pattern)
+```js
+class QueryBuilder {
+  select(fields) { this.fields = fields; return this; }
+  from(table) { this.table = table; return this; }
+  build() { return `SELECT ${this.fields} FROM ${this.table}`; }
+}
+new QueryBuilder().select('*').from('users').build();
+```
+
+### ✅ Prefer composition over inheritance
+> "Favor has-a over is-a"
+
+---
+
+## 🧱 SOLID Principles
+
+| Principle | Rule |
+|-----------|------|
+| **S** — Single Responsibility | One class = one job. Never combine unrelated concerns |
+| **O** — Open/Closed | Open for extension, closed for modification |
+| **L** — Liskov Substitution | Subclasses must be substitutable for their base class |
+| **I** — Interface Segregation | Clients shouldn't depend on interfaces they don't use |
+| **D** — Dependency Inversion | Depend on abstractions, not concretions |
+
+```js
+// ✅ D — Dependency Inversion
+class InventoryService {
+  constructor(inventoryRequester) { // inject the dependency
+    this.inventoryRequester = inventoryRequester;
+  }
+  requestItems(customer) {
+    return this.inventoryRequester.requestItem(customer.purchaseHistory);
+  }
+}
+```
+
+---
+
+## ⚡ Concurrency
+
+### ✅ Use Promises over callbacks
+### ✅ Use async/await over Promises
+```js
+// ✅ Clearest form
+async function getCleanCodeArticle() {
+  try {
+    const response = await request.get(cleanCodeUrl);
+    await fs.writeFile('article.html', response);
+  } catch (err) {
+    console.error(err);
+  }
+}
+```
+
+---
+
+## 🗒️ Comments
+
+### ✅ Only comment business logic complexity
+### ❌ Never leave commented-out code
+### ❌ No journal comments (use git log instead)
+### ❌ No positional markers (`/////`)
+```js
+// ✅ Good comment — explains WHY
+// We retry 3x because OAuth2 tokens can have clock skew
+const MAX_RETRIES = 3;
+```
+
+---
+
+## 📐 Formatting
+
+- Use consistent capitalization (camelCase for vars/fns, PascalCase for classes, UPPER_SNAKE for constants)
+- Keep callers and callees close in the file
+- Related code should appear together

package/.kiro/steering/code-style.md

@@ -0,0 +1,92 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "**/*.{ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}"
+description: "Code Style Guide"
+---
+
+# Code Style Guide
+
+## General Principles
+- **Clarity over cleverness** — Write code that is easy to read and understand
+- **Consistency** — Follow existing patterns in the codebase
+- **DRY** — Don't Repeat Yourself, but don't over-abstract
+
+## JavaScript / TypeScript
+
+### Formatting
+- Indentation: **2 spaces** (no tabs)
+- Max line length: **100 characters**
+- Use **single quotes** for strings
+- Always use **semicolons**
+- Trailing commas in multi-line structures
+
+### Naming
+```js
+// Variables and functions: camelCase
+const userProfile = {};
+function getUserById(id) {}
+
+// Classes and interfaces: PascalCase
+class UserService {}
+interface UserRepository {}
+
+// Constants: UPPER_SNAKE_CASE
+const MAX_RETRY_COUNT = 3;
+const API_BASE_URL = 'https://api.example.com';
+
+// Files: kebab-case
+// user-service.js, auth-middleware.js
+```
+
+### Functions
+```js
+// ✅ Good — Arrow functions for simple operations
+const double = (x) => x * 2;
+
+// ✅ Good — Named functions for complex logic
+function processUserData(user) {
+  // ...
+}
+
+// ❌ Avoid — Functions longer than 30 lines (extract helpers)
+```
+
+### Async/Await
+```js
+// ✅ Always use async/await over raw promises
+async function fetchUser(id) {
+  try {
+    const user = await userRepository.findById(id);
+    return user;
+  } catch (error) {
+    throw new AppError('User not found', 404);
+  }
+}
+
+// ❌ Avoid promise chains
+fetchUser(id).then(...).catch(...);
+```
+
+### Imports
+```js
+// Order: 1. Node built-ins, 2. External deps, 3. Internal modules
+import path from 'path';
+import express from 'express';
+import { UserService } from './user-service.js';
+```
+
+## Comments
+```js
+// ✅ Explain WHY, not WHAT
+// We retry 3 times because the external API has transient failures
+const MAX_RETRIES = 3;
+
+// ❌ Avoid obvious comments
+// Set x to 5
+const x = 5;
+```
+
+## File Organization
+- One class/service per file
+- Group related files in feature folders
+- Index files for clean imports

package/.kiro/steering/codegraph.md

@@ -0,0 +1,47 @@
+---
+inclusion: always
+description: "CodeGraph MCP usage guide — when to use which tool"
+---
+ 
+## CodeGraph
+
+This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
+
+### When to prefer codegraph over native search
+
+Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
+
+| Question | Tool |
+|---|---|
+| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
+| "What calls function Y?" | `codegraph_callers` |
+| "What does Y call?" | `codegraph_callees` |
+| "How does X reach/become Y? / trace the flow from X to Y" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |
+| "What would break if I changed Z?" | `codegraph_impact` |
+| "Show me Y's signature / source / docstring" | `codegraph_node` |
+| "Give me focused context for a task/area" | `codegraph_context` |
+| "See several related symbols' source at once" | `codegraph_explore` |
+| "What files exist under path/" | `codegraph_files` |
+| "Is the index healthy?" | `codegraph_status` |
+
+### Tool parameters (do not mix)
+
+| Tool | Required arg | Optional cap | Wrong args → error |
+|------|--------------|--------------|-------------------|
+| `codegraph_search` | **`query`** (symbol name) | `limit` (default 10) | — |
+| `codegraph_context` | **`task`** (feature/bug description) | `maxNodes` (default 20) | `query` / `limit` → **`task must be a non-empty string`** |
+
+`codegraph_context` is for **code structure** around a task — not for loading **`.agent/SESSION.md`** or `/resume` handoff (use **Read** + `.kiro/commands/resume.md`).
+
+### Rules of thumb
+
+- **Answer directly — don't delegate exploration.** For "how does X work" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** ("how does X reach Y") start with `codegraph_trace` from→to — one call returns the whole path with dynamic hops bridged — then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
+- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
+- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
+- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
+- **Don't loop `codegraph_node` over many symbols** — one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
+- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. `codegraph_status` also lists pending files under "Pending sync".
+
+### If `.codegraph/` doesn't exist
+
+The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*

package/.kiro/steering/database.md

@@ -0,0 +1,66 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "**/*.{ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}"
+description: "doc# Database Rules"
+---
+
+doc# Database Rules
+
+## General Rules
+- **Never** write raw SQL strings directly in business logic
+- Always use an ORM (Prisma/Sequelize/TypeORM) or query builder
+- All database calls must be inside try/catch blocks
+- Use **transactions** for multi-step operations
+
+## Connection Management
+```js
+// ✅ Use connection pooling
+const pool = new Pool({ max: 10, idleTimeoutMillis: 30000 });
+
+// ❌ Never create a new connection per request
+```
+
+## Query Best Practices
+```js
+// ✅ Select only needed fields
+const user = await db.user.findUnique({
+  where: { id },
+  select: { id: true, email: true, name: true }
+});
+
+// ❌ Avoid SELECT *
+const user = await db.user.findUnique({ where: { id } });
+
+// ✅ Use pagination for lists
+const users = await db.user.findMany({
+  take: limit,
+  skip: (page - 1) * limit,
+  orderBy: { createdAt: 'desc' }
+});
+```
+
+## Transactions
+```js
+// ✅ Use transactions for atomic operations
+await db.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+  await tx.inventory.update({ where: { id: productId }, data: { stock: { decrement: 1 } } });
+  return order;
+});
+```
+
+## Migrations
+- Always use migration files, never modify the database schema directly
+- Migration files are version-controlled and immutable
+- Run migrations in CI/CD before deploying
+
+## Naming Conventions
+- Tables: **snake_case** plural (`user_profiles`, `order_items`)
+- Columns: **snake_case** (`created_at`, `user_id`)
+- Indexes: `idx_[table]_[column]`
+- Foreign keys: `fk_[table]_[referenced_table]`
+
+## Security
+- Never log query results containing sensitive data (passwords, tokens)
+- Use parameterized queries — never string concatenation
+- Apply row-level security where applicable