aiblueprint-cli 1.4.11 → 1.4.13

package/claude-code-config/skills/claude-memory/references/comprehensive-example.md

@@ -0,0 +1,175 @@
+<comprehensive_example>
+This is a full-featured CLAUDE.md example for a production SaaS application. Use as inspiration, adapting to your specific project.
+
+```markdown
+# Thumbnail.io - AI Thumbnail Generator
+
+## About
+AI-powered YouTube thumbnail generator SaaS. Users create thumbnails via text prompts, reference persons, and inspiration images.
+
+## Tech Stack
+- **Framework**: Next.js 15 with App Router
+- **Language**: TypeScript (strict mode)
+- **Styling**: TailwindCSS v4 + shadcn/ui
+- **Database**: PostgreSQL with Prisma ORM
+- **Auth**: Better Auth with organization support
+- **Email**: React Email with Resend
+- **Payments**: Stripe (subscriptions + credits)
+- **Testing**: Vitest (unit), Playwright (e2e)
+- **Package Manager**: pnpm
+
+## Directory Structure
+```
+app/                  # Next.js App Router pages
+src/
+├── components/       # UI components (shadcn in ui/, custom in nowts/)
+├── features/         # Feature modules with actions, queries, schemas
+├── lib/              # Utilities and configurations
+├── hooks/            # Custom React hooks
+emails/               # React Email templates
+prisma/               # Database schema and migrations
+e2e/                  # End-to-end tests
+__tests__/            # Unit tests
+```
+
+## Key Features
+- **Editor**: `@/features/editor/` - Main thumbnail generation
+- **Persons**: `@/features/person/` - Reference person management
+- **Credits**: `@/features/credits/` - Usage-based credit system
+- **Forms**: `@/features/form/tanstack-form.tsx` - TanStack Form setup
+
+## Commands
+
+### Development
+- `pnpm dev` - Start development server with Turbopack
+- `pnpm build` - Build application
+- `pnpm ts` - TypeScript type checking
+- `pnpm lint` - ESLint with auto-fix
+- `pnpm clean` - Lint + type check + format
+
+### Testing
+**CRITICAL - Always use CI commands:**
+- `pnpm test:ci` - Unit tests (non-interactive)
+- `pnpm test:e2e:ci` - E2E tests (headless)
+
+**NEVER use interactive commands:**
+- ~~`pnpm test`~~ - Interactive mode breaks Claude Code
+- ~~`pnpm test:e2e`~~ - Interactive mode breaks Claude Code
+
+### Database
+- `pnpm prisma:seed` - Seed database
+- `pnpm better-auth:migrate` - Generate auth schema
+
+## Code Conventions
+
+### TypeScript
+- Use `type` over `interface` (enforced by ESLint)
+- No enums - use maps instead
+- Strict mode - no `any` types
+- Prefer `??` over `||`
+
+### React/Next.js
+- Prefer Server Components over Client Components
+- Use `"use client"` only for Web API access
+- Wrap client components in `Suspense` with fallback
+- **ALWAYS** use `PageProps<"/route/path">` for page components
+
+### Forms
+**CRITICAL - Use TanStack Form for ALL forms:**
+
+```tsx
+import { Form, useForm } from "@/features/form/tanstack-form";
+
+const form = useForm({
+  schema: MySchema,
+  defaultValues: { field: "" },
+  onSubmit: async (values) => { /* handle */ },
+});
+
+return (
+  <Form form={form}>
+    <form.AppField name="field">
+      {(field) => (
+        <field.Field>
+          <field.Label>Label</field.Label>
+          <field.Content>
+            <field.Input placeholder="..." />
+            <field.Message />
+          </field.Content>
+        </field.Field>
+      )}
+    </form.AppField>
+    <form.SubmitButton>Submit</form.SubmitButton>
+  </Form>
+);
+```
+
+**NEVER use React Hook Form directly.**
+
+### Server Actions
+- Suffix files with `.action.ts`
+- Use `@src/lib/actions/safe-actions.ts` for all actions
+- Use `resolveActionResult` helper for mutations
+
+### API Routes
+- All routes in `/app/api` MUST use `@src/lib/zod-route.ts`
+- All HTTP requests MUST use `@src/lib/up-fetch.ts` (never raw `fetch`)
+
+### Authentication
+- Server: `getUser()` (optional) or `getRequiredUser()` (required)
+- Client: `useSession()` from auth-client.ts
+- Organization: `getCurrentOrgCache()`
+
+## Styling Preferences
+- Use typography components from `@src/components/ui/typography.tsx`
+- Prefer `flex flex-col gap-4` over `space-y-4`
+- Use Card component from `@src/components/ui/card.tsx`
+- Never use emojis (prefer Lucide icons)
+- Never use gradients unless explicitly requested
+
+## TypeScript Imports
+- `@/*` → `@src`
+- `@email/*` → `@emails`
+- `@app/*` → `@app`
+
+## Workflow
+
+### Before Editing Files
+🚨 **CRITICAL** 🚨
+**Read at least 3 files** before editing:
+1. Similar files (understand patterns)
+2. Imported dependencies (understand APIs)
+
+### Debugging
+- Add logs at each step
+- Ask user to send logs for debugging
+
+## Important Files
+- `src/lib/auth.ts` - Auth configuration
+- `src/features/dialog-manager/` - Global dialog system
+- `src/features/form/tanstack-form.tsx` - Form setup (**CRITICAL**)
+- `src/lib/actions/safe-actions.ts` - Server action utilities
+- `src/lib/zod-route.ts` - API route utilities
+- `src/site-config.ts` - Site configuration
+
+## Database
+- Main schema: `prisma/schema/schema.prisma`
+- Auth schema: `prisma/schema/better-auth.prisma` (auto-generated)
+- All queries must include `tenant_id` for multi-tenant support
+```
+</comprehensive_example>
+
+<usage_notes>
+This example demonstrates:
+
+- Clear tech stack documentation
+- Directory structure visualization
+- Critical command distinctions (CI vs interactive)
+- Specific code patterns with examples
+- Emphasis on critical rules
+- File location references
+- Workflow requirements
+- Import path conventions
+
+Adapt sections to match your project's actual structure and conventions.
+</usage_notes>

package/claude-code-config/skills/claude-memory/references/project-patterns.md

@@ -0,0 +1,334 @@
+<project_patterns>
+CLAUDE.md patterns optimized for specific project types.
+
+<nextjs_app_router>
+```markdown
+# [Project Name] - Next.js App Router
+
+## Tech Stack
+- Next.js 15 with App Router
+- TypeScript (strict mode)
+- TailwindCSS + shadcn/ui
+- [Database solution]
+
+## Commands
+- `pnpm dev` - Start dev server
+- `pnpm build` - Production build
+- `pnpm lint` - Check code
+- `pnpm test:ci` - Run tests
+
+## Directory Structure
+```
+app/
+├── (auth)/        # Auth routes
+├── (dashboard)/   # Dashboard routes
+├── api/           # API routes
+└── layout.tsx     # Root layout
+src/
+├── components/    # UI components
+├── lib/           # Utilities
+└── hooks/         # React hooks
+```
+
+## Conventions
+
+### Components
+- Prefer Server Components
+- Use `"use client"` only for interactivity
+- Keep components under 300 lines
+
+### Data Fetching
+- Server Components: Direct database access
+- Client Components: TanStack Query
+- Mutations: Server Actions
+
+### File Naming
+- `page.tsx` - Route pages
+- `layout.tsx` - Layouts
+- `loading.tsx` - Loading states
+- `error.tsx` - Error boundaries
+
+## Important
+- **NEVER** use `use client` for data fetching
+- Always add `loading.tsx` for async pages
+- Use `generateMetadata` for SEO
+```
+</nextjs_app_router>
+
+<nextjs_pages_router>
+```markdown
+# [Project Name] - Next.js Pages Router
+
+## Tech Stack
+- Next.js 14 with Pages Router
+- TypeScript
+- TailwindCSS
+
+## Commands
+- `pnpm dev` - Development
+- `pnpm build` - Production build
+- `pnpm test` - Run tests
+
+## Directory Structure
+```
+pages/
+├── api/           # API routes
+├── _app.tsx       # App wrapper
+├── _document.tsx  # Document
+└── index.tsx      # Home page
+src/
+├── components/    # Components
+├── lib/           # Utilities
+└── hooks/         # Hooks
+```
+
+## Data Fetching
+- `getServerSideProps` - SSR data
+- `getStaticProps` - SSG data
+- `useSWR` or TanStack Query - Client data
+
+## API Routes
+- Located in `pages/api/`
+- Use `NextApiRequest` and `NextApiResponse` types
+```
+</nextjs_pages_router>
+
+<react_vite>
+```markdown
+# [Project Name] - React + Vite
+
+## Tech Stack
+- React 18 + TypeScript
+- Vite for bundling
+- TailwindCSS
+- TanStack Query
+
+## Commands
+- `pnpm dev` - Start dev server
+- `pnpm build` - Production build
+- `pnpm preview` - Preview build
+- `pnpm test` - Run tests
+
+## Directory Structure
+```
+src/
+├── components/    # UI components
+├── features/      # Feature modules
+├── hooks/         # Custom hooks
+├── lib/           # Utilities
+├── routes/        # Route components
+└── main.tsx       # Entry point
+```
+
+## Conventions
+- Functional components only
+- Custom hooks for logic reuse
+- TanStack Query for server state
+- Zustand for client state
+```
+</react_vite>
+
+<node_express>
+```markdown
+# [Project Name] - Node.js API
+
+## Tech Stack
+- Node.js + Express
+- TypeScript
+- PostgreSQL + Prisma
+- Jest for testing
+
+## Commands
+- `pnpm dev` - Start with hot reload
+- `pnpm build` - Compile TypeScript
+- `pnpm start` - Start production
+- `pnpm test` - Run tests
+
+## Directory Structure
+```
+src/
+├── controllers/   # Route handlers
+├── middleware/    # Express middleware
+├── models/        # Data models
+├── routes/        # Route definitions
+├── services/      # Business logic
+├── utils/         # Helpers
+└── index.ts       # Entry point
+```
+
+## Conventions
+- Controllers handle HTTP only
+- Services contain business logic
+- Middleware for cross-cutting concerns
+- Always validate input with Zod
+
+## Error Handling
+- Use custom error classes
+- Central error middleware
+- Always return consistent error format
+```
+</node_express>
+
+<python_fastapi>
+```markdown
+# [Project Name] - Python FastAPI
+
+## Tech Stack
+- Python 3.11+
+- FastAPI
+- SQLAlchemy + PostgreSQL
+- Pytest
+
+## Commands
+- `uvicorn main:app --reload` - Development
+- `pytest` - Run tests
+- `ruff check .` - Lint
+- `ruff format .` - Format
+
+## Directory Structure
+```
+app/
+├── api/           # Route handlers
+├── core/          # Config, security
+├── db/            # Database models
+├── schemas/       # Pydantic models
+├── services/      # Business logic
+└── main.py        # Entry point
+```
+
+## Conventions
+- Pydantic for validation
+- Dependency injection for services
+- Async where beneficial
+- Type hints everywhere
+```
+</python_fastapi>
+
+<monorepo_turborepo>
+```markdown
+# [Project Name] - Turborepo Monorepo
+
+## Tech Stack
+- Turborepo for build orchestration
+- pnpm workspaces
+- TypeScript
+
+## Commands
+- `pnpm install` - Install all deps
+- `pnpm dev` - Start all apps
+- `pnpm build` - Build all packages
+- `pnpm test` - Test all packages
+- `pnpm --filter web dev` - Start specific app
+
+## Directory Structure
+```
+apps/
+├── web/           # Main frontend
+├── api/           # Backend API
+└── admin/         # Admin panel
+packages/
+├── ui/            # Shared components
+├── config/        # Shared config
+├── types/         # Shared types
+└── utils/         # Shared utilities
+```
+
+## Package Development
+- Changes to `packages/*` require rebuild
+- Use `pnpm --filter` for targeted commands
+- Shared types in `packages/types`
+
+## Conventions
+- Each app has its own CLAUDE.md
+- Root CLAUDE.md for universal rules
+- Keep packages focused and minimal
+```
+</monorepo_turborepo>
+
+<cli_tool>
+```markdown
+# [Tool Name] - CLI Tool
+
+## Tech Stack
+- TypeScript
+- Commander.js for CLI
+- Chalk for colors
+
+## Commands
+- `pnpm dev` - Watch mode
+- `pnpm build` - Compile
+- `pnpm link` - Link globally
+- `[tool-name] --help` - Show help
+
+## Directory Structure
+```
+src/
+├── commands/      # CLI commands
+├── lib/           # Core logic
+├── utils/         # Helpers
+└── index.ts       # Entry point
+```
+
+## Adding Commands
+1. Create command in `src/commands/`
+2. Register in `src/index.ts`
+3. Add tests in `__tests__/`
+
+## Output Conventions
+- Use chalk for colors
+- Errors to stderr
+- Progress with ora spinners
+```
+</cli_tool>
+
+<library_package>
+```markdown
+# [Library Name] - npm Package
+
+## Tech Stack
+- TypeScript
+- tsup for bundling
+- Vitest for testing
+
+## Commands
+- `pnpm build` - Build package
+- `pnpm test` - Run tests
+- `pnpm dev` - Watch mode
+- `pnpm publish` - Publish to npm
+
+## Directory Structure
+```
+src/
+├── index.ts       # Main exports
+├── utils/         # Internal helpers
+└── types.ts       # Type definitions
+```
+
+## Publishing Checklist
+1. Update version in package.json
+2. Run tests: `pnpm test`
+3. Build: `pnpm build`
+4. Publish: `pnpm publish`
+
+## Conventions
+- Export types alongside functions
+- Document with JSDoc
+- Maintain backwards compatibility
+```
+</library_package>
+</project_patterns>
+
+<customization_notes>
+<adapt_sections>
+Each pattern is a starting point. Adapt by:
+
+1. Removing irrelevant sections
+2. Adding project-specific conventions
+3. Adjusting commands for your setup
+4. Including critical architectural decisions
+</adapt_sections>
+
+<keep_minimal>
+Even for complex projects, aim for under 150 lines. Move detailed documentation to separate files and link from CLAUDE.md.
+</keep_minimal>
+</customization_notes>