claudeinone-cli 1.0.2 → 1.0.3

package/kit/.claude/skills/arch-cqrs.md

@@ -0,0 +1,229 @@
+# CQRS (Command Query Responsibility Segregation)
+
+Separate read and write models for scalability and clarity.
+
+## Basic CQRS Pattern
+
+```typescript
+// Command: modifies state
+interface Command {
+  execute(): Promise<void>;
+}
+
+class CreateUserCommand implements Command {
+  constructor(private userData: CreateUserInput) {}
+
+  async execute() {
+    const user = new User(this.userData);
+    await userRepository.save(user);
+    
+    // Publish event for read model update
+    eventBus.publish('UserCreated', user);
+  }
+}
+
+// Query: reads state
+interface Query<T> {
+  execute(): Promise<T>;
+}
+
+class GetUserQuery implements Query<UserDTO> {
+  constructor(private userId: string) {}
+
+  async execute(): Promise<UserDTO> {
+    // Read from optimized read model
+    return userReadModel.findById(this.userId);
+  }
+}
+
+// Command Handler
+class CommandBus {
+  async execute(command: Command) {
+    return command.execute();
+  }
+}
+
+// Query Handler
+class QueryBus {
+  async execute<T>(query: Query<T>): Promise<T> {
+    return query.execute();
+  }
+}
+```
+
+## Separate Read/Write Models
+
+```typescript
+// Write Model (normalized, consistent)
+interface User {
+  id: string;
+  email: string;
+  password_hash: string;
+  created_at: Date;
+}
+
+// Read Model (denormalized, optimized)
+interface UserReadModel {
+  id: string;
+  email: string;
+  display_name: string;
+  avatar_url: string;
+  created_at: Date;
+  post_count: number;      // Denormalized
+  follower_count: number;  // Denormalized
+}
+
+// Commands update write model
+async function createUser(data: CreateUserInput) {
+  const user = await db('users').insert(data);
+  eventBus.emit('user:created', user);
+}
+
+// Events update read model
+eventBus.on('user:created', async (user) => {
+  // Hydrate read model with denormalized data
+  await readModelDb('users').insert({
+    id: user.id,
+    email: user.email,
+    display_name: user.email.split('@')[0],
+    post_count: 0,
+    follower_count: 0
+  });
+});
+
+eventBus.on('post:created', async (post) => {
+  // Update denormalized post_count
+  await readModelDb('users')
+    .where('id', post.user_id)
+    .increment('post_count', 1);
+});
+```
+
+## Projections
+
+```typescript
+// Projection: builds read model from events
+class UserProjection {
+  async handle(event: DomainEvent) {
+    switch (event.type) {
+      case 'UserCreated':
+        await this.onUserCreated(event);
+        break;
+      case 'UserProfileUpdated':
+        await this.onUserProfileUpdated(event);
+        break;
+      case 'UserFollowedUser':
+        await this.onUserFollowedUser(event);
+        break;
+    }
+  }
+
+  private async onUserCreated(event: any) {
+    await readModel.insert({
+      id: event.data.id,
+      email: event.data.email,
+      follower_count: 0,
+      following_count: 0
+    });
+  }
+
+  private async onUserFollowedUser(event: any) {
+    await readModel
+      .where('id', event.data.followerId)
+      .increment('following_count', 1);
+
+    await readModel
+      .where('id', event.data.followedId)
+      .increment('follower_count', 1);
+  }
+}
+
+// Replay events
+async function rebuildReadModel() {
+  const events = await eventStore.getAll();
+  const projection = new UserProjection();
+
+  for (const event of events) {
+    await projection.handle(event);
+  }
+}
+```
+
+## API Layer
+
+```typescript
+// Routes use Command/Query buses
+app.post('/users', async (req, res) => {
+  const command = new CreateUserCommand(req.body);
+  const user = await commandBus.execute(command);
+  res.json(user);
+});
+
+app.get('/users/:id', async (req, res) => {
+  const query = new GetUserQuery(req.params.id);
+  const user = await queryBus.execute(query);
+  res.json(user);
+});
+
+app.get('/users/:id/posts', async (req, res) => {
+  // Query read model directly (optimized)
+  const posts = await readModel.query()
+    .where('user_id', req.params.id)
+    .orderBy('created_at', 'desc');
+  res.json(posts);
+});
+```
+
+## Consistency Handling
+
+```typescript
+// Handling eventual consistency
+
+async function getUserWithRetry(userId: string, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    const user = await readModel.findById(userId);
+    if (user) return user;
+    
+    // Exponential backoff
+    await sleep(Math.pow(2, i) * 100);
+  }
+
+  throw new Error(`User ${userId} not found after retries`);
+}
+
+// Version tracking
+interface VersionedEntity {
+  id: string;
+  version: number;
+  data: any;
+}
+
+// Client provides expected version
+app.patch('/users/:id', async (req, res) => {
+  const { version, ...data } = req.body;
+  
+  const current = await readModel.findById(req.params.id);
+  
+  if (current.version !== version) {
+    return res.status(409).json({ 
+      error: 'Conflict: resource has been modified' 
+    });
+  }
+
+  await commandBus.execute(new UpdateUserCommand(req.params.id, data));
+  res.json({ ok: true });
+});
+```
+
+## Best Practices
+
+✅ **Separate databases** - Use different DBs for read/write models
+✅ **Event versioning** - Handle schema changes
+✅ **Projection rebuilding** - Replay events to fix read model
+✅ **Consistency guarantees** - Document eventual consistency window
+✅ **Monitoring** - Track event processing lag
+
+## Resources
+
+- [CQRS Pattern](https://martinfowler.com/bliki/CQRS.html)
+- [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html)

package/kit/.claude/skills/arch-ddd.md

@@ -0,0 +1,85 @@
+# Domain-Driven Design (DDD)
+
+## Overview
+DDD aligns software with business domains using aggregates, value objects, entities, and domain events.
+
+## Value Object
+
+```typescript
+export class Money {
+  private constructor(public readonly amount: number, public readonly currency: string) {}
+
+  static of(amount: number, currency: string): Money {
+    if (amount < 0) throw new Error('Amount must be non-negative');
+    return new Money(Math.round(amount * 100) / 100, currency);
+  }
+
+  add(other: Money): Money {
+    if (other.currency !== this.currency) throw new Error('Currency mismatch');
+    return Money.of(this.amount + other.amount, this.currency);
+  }
+
+  equals(other: Money): boolean {
+    return this.amount === other.amount && this.currency === other.currency;
+  }
+}
+```
+
+## Aggregate Root
+
+```typescript
+export class Order {
+  private _events: DomainEvent[] = [];
+  private _items: OrderItem[] = [];
+  private _status: 'draft' | 'confirmed' | 'shipped' = 'draft';
+
+  private constructor(public readonly id: string, public readonly customerId: string) {}
+
+  static create(customerId: string): Order {
+    const order = new Order(crypto.randomUUID(), customerId);
+    order._events.push({ type: 'OrderCreated', orderId: order.id, customerId });
+    return order;
+  }
+
+  addItem(productId: string, price: Money): void {
+    if (this._status !== 'draft') throw new Error('Order is already confirmed');
+    this._items.push({ productId, price });
+  }
+
+  confirm(): void {
+    if (this._items.length === 0) throw new Error('Cannot confirm empty order');
+    this._status = 'confirmed';
+    this._events.push({ type: 'OrderConfirmed', orderId: this.id });
+  }
+
+  get events() { return [...this._events]; }
+  clearEvents() { this._events.length = 0; }
+}
+```
+
+## Domain Service (publish events after save)
+
+```typescript
+export class OrderService {
+  constructor(private repo: OrderRepository, private eventBus: EventBus) {}
+
+  async confirmOrder(orderId: string): Promise<void> {
+    const order = await this.repo.findById(orderId);
+    if (!order) throw new Error('Order not found');
+    order.confirm();
+    await this.repo.save(order);
+    for (const event of order.events) await this.eventBus.publish(event);
+    order.clearEvents();
+  }
+}
+```
+
+## Best Practices
+- Model ubiquitous language — use domain terms directly in code
+- Aggregates should be small — avoid deep joins
+- Always update aggregates through their roots
+- Use outbox pattern for reliable event publishing
+- Keep bounded contexts loosely coupled via events
+
+## Resources
+- [DDD Reference (Eric Evans)](https://www.domainlanguage.com/ddd/)

package/kit/.claude/skills/arch-event-driven.md

@@ -0,0 +1,189 @@
+# Event-Driven Architecture
+
+Decouple services through asynchronous event publishing and consumption.
+
+## Event Emitter Pattern
+
+```typescript
+import EventEmitter from 'events';
+
+class EventBus extends EventEmitter {}
+
+const eventBus = new EventBus();
+
+// Subscribe to events
+eventBus.on('user:created', (user) => {
+  console.log(`User created: ${user.email}`);
+  // Send welcome email
+  sendWelcomeEmail(user.email);
+});
+
+eventBus.on('user:created', (user) => {
+  console.log(`Tracking user signup: ${user.id}`);
+  // Track analytics
+  analytics.track('user_signup', user);
+});
+
+// Publish events
+async function createUser(data) {
+  const user = await db.users.create(data);
+  eventBus.emit('user:created', user);
+  return user;
+}
+```
+
+## Message Queue Pattern (RabbitMQ)
+
+```typescript
+import amqp from 'amqplib';
+
+const connection = await amqp.connect('amqp://localhost');
+const channel = await connection.createChannel();
+
+// Declare queue
+await channel.assertQueue('user.created', { durable: true });
+
+// Publish
+async function publishUserCreated(user) {
+  channel.sendToQueue(
+    'user.created',
+    Buffer.from(JSON.stringify(user)),
+    { persistent: true }
+  );
+}
+
+// Consume
+channel.consume('user.created', async (msg) => {
+  const user = JSON.parse(msg.content.toString());
+  
+  // Send welcome email
+  await emailService.sendWelcome(user.email);
+  
+  // Acknowledge
+  channel.ack(msg);
+}, { noAck: false });
+```
+
+## Pub/Sub Pattern (Redis)
+
+```typescript
+import Redis from 'ioredis';
+
+const redis = new Redis();
+
+// Subscribe
+redis.subscribe('user:created', (err, count) => {
+  if (err) console.error('Subscribe error:', err);
+});
+
+redis.on('message', (channel, message) => {
+  if (channel === 'user:created') {
+    const user = JSON.parse(message);
+    console.log(`Welcome email sent to ${user.email}`);
+  }
+});
+
+// Publish
+async function createUser(data) {
+  const user = await db.users.create(data);
+  
+  redis.publish('user:created', JSON.stringify(user));
+  
+  return user;
+}
+```
+
+## Event Sourcing
+
+```typescript
+interface Event {
+  id: string;
+  type: string;
+  aggregate_id: string;
+  data: any;
+  timestamp: Date;
+}
+
+// Store events
+async function createUserEvent(userId: string, userData: any) {
+  const event: Event = {
+    id: uuid(),
+    type: 'UserCreated',
+    aggregate_id: userId,
+    data: userData,
+    timestamp: new Date()
+  };
+
+  await db('events').insert(event);
+  return event;
+}
+
+// Rebuild state from events
+async function getUserState(userId: string) {
+  const events = await db('events')
+    .where('aggregate_id', userId)
+    .orderBy('timestamp');
+
+  let state = { id: userId };
+
+  for (const event of events) {
+    switch (event.type) {
+      case 'UserCreated':
+        state = { ...state, ...event.data };
+        break;
+      case 'UserUpdated':
+        state = { ...state, ...event.data };
+        break;
+      case 'UserDeleted':
+        state = { ...state, deleted: true };
+        break;
+    }
+  }
+
+  return state;
+}
+```
+
+## Saga Pattern (Choreography)
+
+```typescript
+// Order saga coordinated by events
+
+// 1. Order created → publish event
+eventBus.on('order:created', async (order) => {
+  // Payment service listens and processes payment
+  eventBus.emit('payment:requested', order);
+});
+
+// 2. Payment processed → publish event
+eventBus.on('payment:processed', async (payment) => {
+  // Inventory service listens and reserves stock
+  eventBus.emit('inventory:reserve', payment.order);
+});
+
+// 3. Stock reserved → publish event
+eventBus.on('inventory:reserved', async (inventory) => {
+  // Shipping service listens and creates shipment
+  eventBus.emit('shipment:created', inventory.order);
+});
+
+// Handle failures with compensating transactions
+eventBus.on('payment:failed', async (payment) => {
+  // Compensating: Release reserved inventory
+  eventBus.emit('inventory:release', payment.order);
+});
+```
+
+## Best Practices
+
+✅ **Idempotency** - Handle duplicate event processing
+✅ **Dead letter queues** - Capture failed messages
+✅ **Event versioning** - Support multiple event versions
+✅ **Eventual consistency** - Accept temporary inconsistency
+✅ **Monitoring** - Track event lag and processing times
+
+## Resources
+
+- [Event Sourcing Pattern](https://martinfowler.com/eaaDev/EventSourcing.html)
+- [RabbitMQ Tutorials](https://www.rabbitmq.com/getstarted.html)
+- [Redis Pub/Sub](https://redis.io/docs/manual/pubsub/)

package/kit/.claude/skills/arch-microservices.md

@@ -0,0 +1,80 @@
+# Microservices Architecture
+
+Decompose applications into small, independent services communicating via APIs.
+
+## Service Definition
+
+```typescript
+// User Service
+export interface IUserService {
+  getUser(id: string): Promise<User>;
+  createUser(data: CreateUserInput): Promise<User>;
+  updateUser(id: string, data: UpdateUserInput): Promise<User>;
+}
+
+// Post Service
+export interface IPostService {
+  getPost(id: string): Promise<Post>;
+  getUserPosts(userId: string): Promise<Post[]>;
+  createPost(data: CreatePostInput): Promise<Post>;
+}
+```
+
+## Inter-Service Communication
+
+```typescript
+// HTTP/REST
+const user = await fetch('http://user-service/api/users/123')
+  .then(r => r.json());
+
+// gRPC (efficient binary protocol)
+const user = await userServiceClient.getUser({ id: '123' });
+
+// Message Queue (async)
+await messageQueue.publish('user-updated', { userId: '123' });
+```
+
+## API Gateway
+
+```typescript
+// Centralized entry point
+const gateway = express();
+
+gateway.use('/users', userServiceProxy);
+gateway.use('/posts', postServiceProxy);
+gateway.use('/comments', commentServiceProxy);
+
+// Handle cross-service calls
+gateway.get('/users/:id/posts', async (req, res) => {
+  const user = await getUserService(req.params.id);
+  const posts = await getPostService(user.id);
+  res.json({ user, posts });
+});
+```
+
+## Service Discovery
+
+```yaml
+# Kubernetes automatically discovers services
+# Service DNS: <service-name>.<namespace>.svc.cluster.local
+
+# Docker Compose
+services:
+  user-service:
+    container_name: user-service
+    # Other services access via: http://user-service:3000
+```
+
+## Best Practices
+
+✅ **Bounded contexts** - Clear service boundaries
+✅ **Database per service** - Data independence
+✅ **Async communication** - Use message queues
+✅ **Service discovery** - Dynamic registration
+✅ **Health checks** - Monitor service health
+✅ **Logging aggregation** - Centralized logs
+
+## Resources
+
+- [Microservices Patterns](https://microservices.io/patterns/)
+- [12 Factor App](https://12factor.net/)

package/kit/.claude/skills/arch-monorepo.md

@@ -0,0 +1,87 @@
+# Monorepo with Turborepo
+
+## Overview
+Host multiple apps and packages in one repo with shared code, tooling, and independent deployments.
+
+## Setup
+
+```bash
+npx create-turbo@latest my-monorepo
+```
+
+## Structure
+
+```
+my-monorepo/
+├── apps/
+│   ├── web/        # Next.js frontend
+│   └── api/        # Express backend
+├── packages/
+│   ├── ui/         # Shared React components
+│   ├── types/      # Shared TypeScript types
+│   └── config/     # Shared ESLint, Tailwind, TS configs
+├── turbo.json
+└── package.json
+```
+
+## turbo.json
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": { "dependsOn": ["^build"], "outputs": [".next/**", "dist/**"] },
+    "dev": { "cache": false, "persistent": true },
+    "lint": {},
+    "test": { "outputs": ["coverage/**"] }
+  }
+}
+```
+
+## Shared UI Package
+
+```json
+// packages/ui/package.json
+{
+  "name": "@repo/ui",
+  "exports": {
+    "./button": "./src/button/index.tsx"
+  }
+}
+```
+
+```tsx
+// packages/ui/src/button/index.tsx
+export function Button({ children, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) {
+  return <button className="px-4 py-2 bg-blue-600 text-white rounded" {...props}>{children}</button>;
+}
+```
+
+## Using Shared Packages
+
+```json
+// apps/web/package.json
+{ "dependencies": { "@repo/ui": "*" } }
+```
+
+```tsx
+import { Button } from '@repo/ui/button';
+```
+
+## Commands
+
+```bash
+turbo dev              # all apps in dev mode
+turbo build            # build all
+turbo build --filter=web  # build specific app
+turbo test             # test all packages
+```
+
+## Best Practices
+- Use `workspace:*` to link internal packages
+- Enable Vercel Remote Cache for fast CI builds
+- Keep `packages/config` for shared ESLint and Tailwind configs
+- Build shared packages before dependent apps (`dependsOn: ["^build"]`)
+
+## Resources
+- [Turborepo docs](https://turbo.build/repo/docs)