@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/naming-analyzer/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: naming-analyzer
+context: fork
+description: Suggest better variable, function, and class names based on context and conventions.
+---
+
+# Naming Analyzer Skill
+
+Suggest better variable, function, and class names based on context and conventions.
+
+**Works with:** Any AI coding agent (Claude, Cursor, GitHub Copilot, Windsurf, etc.)
+
+## Instructions
+
+You are a naming convention expert. When invoked:
+
+1. **Analyze Existing Names**:
+   - Variables, constants, functions, methods
+   - Classes, interfaces, types
+   - Files and directories
+   - Database tables and columns
+   - API endpoints
+
+2. **Identify Issues**:
+   - Unclear or vague names
+   - Abbreviations that obscure meaning
+   - Inconsistent naming conventions
+   - Misleading names (name doesn't match behavior)
+   - Too short or too long names
+   - Hungarian notation misuse
+   - Single-letter variables outside loops
+
+3. **Check Conventions**:
+   - Language-specific conventions (camelCase, snake_case, PascalCase)
+   - Framework conventions (React components, Vue props)
+   - Project-specific patterns
+   - Industry standards
+
+4. **Provide Suggestions**:
+   - Better alternative names
+   - Reasoning for each suggestion
+   - Consistency improvements
+   - Contextual appropriateness
+
+## Triggers
+
+Use this skill when:
+- "analyze naming in [file/directory]"
+- "suggest better names for this code"
+- "check naming conventions"
+- "review variable names"
+- "find naming issues"
+- "improve naming consistency"
+
+## Naming Conventions by Language
+
+### JavaScript/TypeScript
+- Variables/functions: `camelCase`
+- Classes/interfaces: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Private fields: `_prefixUnderscore` or `#privateField`
+- Boolean: `is`, `has`, `can`, `should` prefixes
+
+### Python
+- Variables/functions: `snake_case`
+- Classes: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Private: `_prefix_underscore`
+- Boolean: `is_`, `has_`, `can_` prefixes
+
+### Java
+- Variables/methods: `camelCase`
+- Classes/interfaces: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Packages: `lowercase`
+
+### Go
+- Exported: `PascalCase`
+- Unexported: `camelCase`
+- Acronyms: All caps (`HTTPServer`, not `HttpServer`)
+
+### C#
+- Public members: `PascalCase`
+- Private fields: `_camelCase` or `camelCase`
+- Constants: `PascalCase` or `UPPER_SNAKE_CASE`
+- Interfaces: `IPascalCase` (I prefix)
+
+### Ruby
+- Variables/methods: `snake_case`
+- Classes/modules: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Predicate methods: `?` suffix (e.g., `valid?`)
+
+### Rust
+- Variables/functions: `snake_case`
+- Types/traits: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Macros: `snake_case!`
+
+## Common Naming Issues
+
+### Too Vague
+```javascript
+// ❌ Bad - Too generic
+function process(data) { }
+const info = getData();
+let temp = x;
+
+// ✓ Good - Specific and clear
+function processPayment(transaction) { }
+const userProfile = getUserProfile();
+let previousValue = x;
+```
+
+### Misleading Names
+```javascript
+// ❌ Bad - Name doesn't match behavior
+function getUser(id) {
+  const user = fetchUser(id);
+  user.lastLogin = Date.now();
+  saveUser(user); // Side effect! Not just "getting"
+  return user;
+}
+
+// ✓ Good - Name reflects actual behavior
+function fetchAndUpdateUserLogin(id) {
+  const user = fetchUser(id);
+  user.lastLogin = Date.now();
+  saveUser(user);
+  return user;
+}
+```
+
+### Abbreviations
+```javascript
+// ❌ Bad - Unclear abbreviations
+const usrCfg = loadConfig();
+function calcTtl(arr) { }
+
+// ✓ Good - Clear and readable
+const userConfig = loadConfig();
+function calculateTotal(amounts) { }
+
+// ✓ Acceptable - Well-known abbreviations
+const htmlElement = document.getElementById('main');
+const apiUrl = process.env.API_URL;
+```
+
+### Boolean Naming
+```javascript
+// ❌ Bad - Unclear state
+const login = user.authenticated;
+const status = checkUser();
+
+// ✓ Good - Clear boolean intent
+const isLoggedIn = user.authenticated;
+const isUserValid = checkUser();
+const hasPermission = user.roles.includes('admin');
+const canEditPost = isOwner || isAdmin;
+const shouldShowNotification = isEnabled && hasUnread;
+```
+
+### Magic Numbers
+```javascript
+// ❌ Bad - Unnamed constants
+if (age > 18) { }
+setTimeout(callback, 3600000);
+
+// ✓ Good - Named constants
+const LEGAL_AGE = 18;
+const ONE_HOUR_IN_MS = 60 * 60 * 1000;
+
+if (age > LEGAL_AGE) { }
+setTimeout(callback, ONE_HOUR_IN_MS);
+```
+
+## Report Format
+
+```markdown
+# Naming Analysis Report
+
+## Summary
+- Items analyzed: 156
+- Issues found: 23
+- Critical: 5 (misleading names)
+- Major: 12 (unclear/vague)
+- Minor: 6 (convention violations)
+
+---
+
+## Critical Issues (5)
+
+### src/services/UserService.js:45
+**Current**: `getUser(id)`
+**Issue**: Function name implies read-only but has side effects (updates lastLogin)
+**Severity**: Critical - Misleading
+**Suggestion**: `fetchAndUpdateUserLogin(id)`
+**Reason**: Name should reflect the mutation
+
+### src/utils/helpers.js:23
+**Current**: `validate(x)`
+**Issue**: Generic parameter name, unclear what's being validated
+**Severity**: Critical - Too vague
+**Suggestion**: `validateEmail(emailAddress)`
+**Reason**: Specific names improve clarity
+
+---
+
+## Major Issues (12)
+
+### src/components/DataList.jsx:12
+**Current**: `const d = new Date()`
+**Issue**: Single-letter variable in large scope
+**Severity**: Major
+**Suggestion**: `const currentDate = new Date()`
+**Reason**: Clarity and searchability
+
+### src/api/client.js:67
+**Current**: `function proc(data) {}`
+**Issue**: Abbreviated function name
+**Severity**: Major
+**Suggestion**: `function processApiResponse(data) {}`
+**Reason**: Full words are more readable
+
+### src/models/User.js:34
+**Current**: `user.active`
+**Issue**: Boolean property without prefix
+**Severity**: Major
+**Suggestion**: `user.isActive`
+**Reason**: Follow boolean naming convention
+
+### src/utils/format.js:89
+**Current**: `const MAX = 100`
+**Issue**: Generic constant name
+**Severity**: Major
+**Suggestion**: `const MAX_RETRY_ATTEMPTS = 100`
+**Reason**: Specific purpose is clearer
+
+---
+
+## Minor Issues (6)
+
+### src/config/settings.js:12
+**Current**: `const API_url = '...'`
+**Issue**: Inconsistent casing (mixing UPPER and lower)
+**Severity**: Minor
+**Suggestion**: `const API_URL = '...'` or `const apiUrl = '...'`
+**Reason**: Consistency in convention
+
+### src/helpers/string.js:45
+**Current**: `function strToNum(s) {}`
+**Issue**: Abbreviated function and parameter
+**Severity**: Minor
+**Suggestion**: `function stringToNumber(value) {}`
+**Reason**: Clarity over brevity
+
+---
+
+## Convention Violations
+
+### Inconsistent Boolean Prefixes
+**Locations**: 8 files
+**Issue**: Mixed use of `is`, `has`, `can` vs no prefix
+**Recommendation**: Standardize on boolean prefixes
+- Use `is` for state: `isActive`, `isVisible`
+- Use `has` for possession: `hasPermission`, `hasError`
+- Use `can` for ability: `canEdit`, `canDelete`
+- Use `should` for decisions: `shouldRender`, `shouldValidate`
+
+### Mixed Naming Conventions
+**Location**: src/legacy/
+**Issue**: Mix of camelCase and snake_case in JavaScript
+**Recommendation**: Convert all to camelCase for consistency
+
+---
+
+## Suggested Renaming
+
+### High Priority (Misleading or Critical)
+1. `getUser` → `fetchAndUpdateUserLogin` (src/services/UserService.js:45)
+2. `validate` → `validateEmail` (src/utils/helpers.js:23)
+3. `process` → `processPaymentTransaction` (src/payment/processor.js:67)
+
+### Medium Priority (Clarity)
+1. `d` → `currentDate` (7 locations)
+2. `temp` → `previousValue` (4 locations)
+3. `data` → `apiResponse` or more specific (12 locations)
+4. `arr` → `items`, `values`, or more specific (8 locations)
+
+### Low Priority (Convention)
+1. `active` → `isActive` (12 locations)
+2. `error` → `hasError` (6 locations)
+3. `API_url` → `API_URL` (3 locations)
+
+---
+
+## Naming Patterns to Follow
+
+### Functions/Methods
+- Verbs: `get`, `set`, `create`, `update`, `delete`, `fetch`, `calculate`, `validate`
+- Clear action: `sendEmail()`, `parseJSON()`, `formatCurrency()`
+
+### Classes
+- Nouns: `UserService`, `PaymentProcessor`, `EmailValidator`
+- Avoid generic: Don't use `Manager`, `Helper`, `Utility` unless necessary
+
+### Variables
+- Nouns or noun phrases: `user`, `emailAddress`, `totalAmount`
+- Descriptive: `userList` not `list`, `activeUsers` not `users2`
+
+### Constants
+- All caps with underscores: `MAX_RETRY_ATTEMPTS`, `DEFAULT_TIMEOUT`
+- Include units: `CACHE_DURATION_MS`, `MAX_FILE_SIZE_MB`
+
+### Booleans
+- Question form: `isValid`, `hasPermission`, `canEdit`
+- Affirmative: `isEnabled` not `isDisabled` (prefer positive)
+
+---
+
+## Refactoring Options
+
+Would you like me to:
+1. **Generate a refactoring script** to apply these changes automatically
+2. **Create a migration guide** with step-by-step manual instructions
+3. **Apply changes directly** using your agent's refactoring capabilities
+
+This will:
+- Rename all suggested items
+- Update all references
+- Maintain git history (if applicable)
+- Ensure no breaking changes
+
+---
+
+## Best Practices
+
+✓ **DO**:
+- Use full words over abbreviations
+- Be specific and descriptive
+- Follow language conventions
+- Use consistent patterns
+- Make booleans obvious
+- Include units in constants
+
+✗ **DON'T**:
+- Use single letters (except in loops: i, j, k)
+- Use vague names (data, info, temp, x)
+- Mix naming conventions
+- Use misleading names
+- Over-abbreviate
+- Use Hungarian notation in modern code
+```
+
+## Naming Decision Tree
+
+```
+Is it a boolean?
+├─ Yes → Use is/has/can/should prefix
+└─ No → Is it a function?
+    ├─ Yes → Use verb phrase (action)
+    └─ No → Is it a class?
+        ├─ Yes → Use noun (PascalCase)
+        └─ No → Is it a constant?
+            ├─ Yes → Use UPPER_SNAKE_CASE
+            └─ No → Use descriptive noun (camelCase/snake_case)
+```
+
+## Notes
+
+- Prioritize clarity over brevity
+- Context matters (loop counters can be `i`, `j`)
+- Well-known abbreviations are okay (`html`, `api`, `url`, `id`)
+- Consistency within a project is more important than perfect naming
+- Refactor names as understanding improves
+- Use your agent's rename refactoring to safely update all references

package/bundles/antigravity-plugin-extras/skills/nextjs-app-router/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: nextjs-app-router
+description: Next.js 13+ App Router conventions, Server vs Client Components, Server Actions, Middleware, data fetching, Metadata API, and route handlers. Use for Next.js App Router directory structure, Server Actions, SSR/RSC patterns, generateMetadata, layout/page/error/loading.tsx conventions, route groups, parallel routes, or hydration issues. Companion to react-dev and react-best-practices.
+---
+
+# Next.js App Router Skill
+
+Covers Next.js 13+ App Router conventions. Companion to `react-dev` (typing) and `react-best-practices` (patterns). Always read those for React-level decisions.
+
+## 1. File Conventions
+
+```
+app/
+├── layout.tsx          # Root shell — fonts, providers, global nav. Always present.
+├── page.tsx            # Default route segment UI
+├── loading.tsx         # Suspense boundary UI while segment loads
+├── error.tsx           # Error boundary ('use client' required)
+├── not-found.tsx       # 404 for segment
+├── template.tsx        # Re-mounts on navigation (vs layout which persists)
+├── (marketing)/        # Route group — no URL segment, just org
+│   ├── about/page.tsx
+│   └── pricing/page.tsx
+├── dashboard/
+│   ├── layout.tsx      # Nested layout (persists across dashboard routes)
+│   └── settings/page.tsx
+└── api/
+    └── webhook/route.ts  # Route handler
+```
+
+### Key Rules
+- `error.tsx` **must** be `'use client'` — React error boundaries require it.
+- `loading.tsx` wraps the segment's `page.tsx` in `<Suspense>` automatically.
+- `template.tsx` re-mounts children on every navigation; use only when fresh mount is needed.
+- Route groups `(group)` do not affect URL paths — use for layout isolation or code organisation.
+
+## 2. Server vs Client Components — Decision Tree
+
+```
+Does this component need:
+  - useState / useReducer?           → 'use client'
+  - useEffect?                       → 'use client'
+  - Browser APIs (window, document)? → 'use client'
+  - Event listeners?                 → 'use client'
+  - Framer Motion / animation libs?  → 'use client'
+  - Third-party client-side context? → 'use client'
+  Otherwise:                         → Server Component (default)
+```
+
+### Composition Pattern
+```tsx
+// ✅ GOOD: Push 'use client' to the leaf
+// app/dashboard/page.tsx — Server Component
+import { InteractiveChart } from './interactive-chart'
+
+export default async function DashboardPage() {
+  const data = await fetchData()  // Direct async/await — no useEffect needed
+  return <InteractiveChart initialData={data} />
+}
+
+// interactive-chart.tsx
+'use client'
+export function InteractiveChart({ initialData }: { initialData: Data }) {
+  const [filter, setFilter] = useState('all')
+  // ...
+}
+```
+
+```tsx
+// ❌ BAD: Marking the whole page client just for one button
+'use client'
+export default async function Page() {  // 'async' is invalid in client components
+  const data = await fetchData()  // This won't work in client components
+}
+```
+
+## 3. Server Actions
+
+Server Actions are async functions that run on the server, callable from Client Components.
+
+```tsx
+// app/actions/user.ts
+'use server'
+
+import { revalidatePath, revalidateTag } from 'next/cache'
+
+export async function updateUser(userId: string, formData: FormData) {
+  const name = formData.get('name') as string
+  await db.user.update({ where: { id: userId }, data: { name } })
+  revalidatePath('/dashboard/profile')  // Revalidate specific path
+}
+
+export async function deletePost(postId: string) {
+  await db.post.delete({ where: { id: postId } })
+  revalidateTag('posts')  // Revalidate by cache tag
+}
+```
+
+### `useActionState` (React 19 / Next.js 14+)
+```tsx
+'use client'
+import { useActionState } from 'react'
+import { updateUser } from '@/app/actions/user'
+
+type State = { error?: string; success?: boolean }
+
+export function ProfileForm({ userId }: { userId: string }) {
+  const [state, action, isPending] = useActionState<State, FormData>(
+    async (_, formData) => {
+      try {
+        await updateUser(userId, formData)
+        return { success: true }
+      } catch {
+        return { error: 'Update failed' }
+      }
+    },
+    {}
+  )
+
+  return (
+    <form action={action}>
+      <input name="name" disabled={isPending} />
+      {state.error && <p role="alert">{state.error}</p>}
+      <button type="submit" disabled={isPending}>{isPending ? 'Saving…' : 'Save'}</button>
+    </form>
+  )
+}
+```
+
+## 4. Middleware
+
+```ts
+// middleware.ts (at project root, NOT in app/)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl
+
+  // Auth guard
+  const token = request.cookies.get('auth-token')?.value
+  if (pathname.startsWith('/dashboard') && !token) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+
+  // A/B test header
+  const response = NextResponse.next()
+  response.headers.set('x-variant', 'control')
+  return response
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+  // Use edge runtime for simple string ops — avoids cold start
+}
+```
+
+## 5. Data Fetching
+
+### Server Component Fetch with Caching
+```tsx
+// Cached fetch: deduplicated across the request lifecycle
+async function getUser(id: string) {
+  const res = await fetch(`https://api.example.com/users/${id}`, {
+    next: { revalidate: 3600 },  // ISR: revalidate every hour
+    // next: { tags: ['user'] },  // Tag-based revalidation
+    // cache: 'no-store',         // Dynamic — no cache
+  })
+  if (!res.ok) throw new Error('Failed to fetch')
+  return res.json()
+}
+```
+
+### Parallel Data Fetching
+```tsx
+// ✅ GOOD: Parallel — not waterfall
+export default async function Page({ params }: { params: { id: string } }) {
+  const [user, posts, analytics] = await Promise.all([
+    getUser(params.id),
+    getPosts(params.id),
+    getAnalytics(params.id),
+  ])
+  return <Dashboard user={user} posts={posts} analytics={analytics} />
+}
+```
+
+### Suspense Streaming
+```tsx
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <>
+      <Header />
+      <Suspense fallback={<Skeleton />}>
+        <AsyncDataTable />  {/* Streams in when ready */}
+      </Suspense>
+      <Suspense fallback={<ChartSkeleton />}>
+        <AsyncChart />
+      </Suspense>
+    </>
+  )
+}
+```
+
+## 6. Metadata API
+
+```tsx
+// Static metadata
+export const metadata = {
+  title: 'Dashboard',
+  description: 'Your personalised dashboard',
+}
+
+// Dynamic metadata
+export async function generateMetadata({ params }: { params: { slug: string } }) {
+  const post = await getPost(params.slug)
+  return {
+    title: post.title,
+    description: post.excerpt,
+    openGraph: {
+      title: post.title,
+      images: [{ url: post.coverImage, width: 1200, height: 630 }],
+    },
+    twitter: { card: 'summary_large_image', title: post.title },
+  }
+}
+```
+
+## 7. Route Handlers
+
+```ts
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url)
+  const page = Number(searchParams.get('page') ?? '1')
+  const users = await db.user.findMany({ skip: (page - 1) * 20, take: 20 })
+  return NextResponse.json({ users, page })
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json()
+  // Validate with zod before DB write
+  const parsed = CreateUserSchema.safeParse(body)
+  if (!parsed.success) return NextResponse.json({ error: parsed.error.flatten() }, { status: 422 })
+  const user = await db.user.create({ data: parsed.data })
+  return NextResponse.json(user, { status: 201 })
+}
+```
+
+## 8. Common Pitfalls
+
+| Pitfall | Cause | Fix |
+|---------|-------|-----|
+| Hydration mismatch | Server HTML ≠ client render (dates, random IDs, browser-only APIs) | Wrap in `<ClientOnly>` component or use `useEffect` for client-only values |
+| `'use client'` creep | Adding hooks to parent forces entire tree client | Push boundary to leaf — pass serialisable data as props |
+| Nested layout confusion | Inner `layout.tsx` doesn't wrap sibling `page.tsx` at same level | Layouts only wrap children segments, not siblings |
+| Stale cache | `fetch` cached too aggressively | Use `revalidateTag` on mutation, or `cache: 'no-store'` for real-time data |
+| Server Action in Server Component | Calling a Server Action from a Server Component via form is fine; importing into client requires `'use server'` import | Declare `'use server'` at top of action file, not per-function |
+| Missing error handling in route handler | Unhandled error returns 500 with Next.js HTML error page | Always return `NextResponse.json({ error: ... }, { status })` |
+
+## 9. Quick Reference Checklist
+
+- [ ] `error.tsx` has `'use client'` directive
+- [ ] No `async`/`await` inside Client Components — lift to Server Component or Server Action
+- [ ] Parallel fetches use `Promise.all`, not sequential `await`
+- [ ] `revalidatePath` or `revalidateTag` called after every mutating Server Action
+- [ ] Middleware `matcher` is as specific as possible — avoid `'/'` matching everything
+- [ ] `generateMetadata` defined for every public-facing page
+- [ ] Route handlers validate input with zod before touching the database