claudeinone-cli 1.0.1 → 1.0.3

package/kit/.claude/skills/api-graphql.md

@@ -0,0 +1,234 @@
+# GraphQL
+
+Query language for APIs with strong typing and efficient data fetching.
+
+## Setup
+
+```bash
+npm install apollo-server graphql
+```
+
+## Schema Definition
+
+```typescript
+import { gql } from 'apollo-server';
+
+const typeDefs = gql`
+  type User {
+    id: ID!
+    email: String!
+    name: String!
+    posts: [Post!]!
+    createdAt: String!
+  }
+
+  type Post {
+    id: ID!
+    title: String!
+    content: String!
+    author: User!
+    createdAt: String!
+  }
+
+  type Query {
+    user(id: ID!): User
+    users(limit: Int = 10, offset: Int = 0): [User!]!
+    post(id: ID!): Post
+    searchPosts(query: String!): [Post!]!
+  }
+
+  type Mutation {
+    createUser(email: String!, name: String!): User!
+    updateUser(id: ID!, name: String): User
+    deleteUser(id: ID!): Boolean!
+    
+    createPost(title: String!, content: String!): Post!
+    updatePost(id: ID!, title: String, content: String): Post
+    deletePost(id: ID!): Boolean!
+  }
+
+  type Subscription {
+    userCreated: User!
+    postCreated: Post!
+  }
+`;
+```
+
+## Resolvers
+
+```typescript
+const resolvers = {
+  Query: {
+    user: async (_, { id }) => {
+      return await userRepository.findById(id);
+    },
+    
+    users: async (_, { limit, offset }) => {
+      return await userRepository.find()
+        .limit(limit)
+        .offset(offset);
+    },
+    
+    searchPosts: async (_, { query }) => {
+      return await db('posts')
+        .whereRaw('MATCH(title, content) AGAINST(? IN BOOLEAN MODE)', [query]);
+    }
+  },
+
+  Mutation: {
+    createUser: async (_, { email, name }, context) => {
+      // Verify auth
+      if (!context.user) throw new Error('Unauthorized');
+      
+      const user = await userRepository.create({ email, name });
+      eventBus.emit('user:created', user);
+      return user;
+    },
+    
+    updatePost: async (_, { id, title, content }, context) => {
+      const post = await postRepository.findById(id);
+      
+      // Verify ownership
+      if (post.authorId !== context.user.id) {
+        throw new Error('Forbidden');
+      }
+
+      return await postRepository.update(id, { title, content });
+    }
+  },
+
+  Subscription: {
+    userCreated: {
+      subscribe: () => pubSub.asyncIterator(['USER_CREATED'])
+    }
+  },
+
+  // Field resolvers
+  User: {
+    posts: async (user) => {
+      return await postRepository.findByUserId(user.id);
+    }
+  },
+
+  Post: {
+    author: async (post) => {
+      return await userRepository.findById(post.authorId);
+    }
+  }
+};
+```
+
+## Apollo Server Setup
+
+```typescript
+import { ApolloServer } from 'apollo-server-express';
+import express from 'express';
+
+const app = express();
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  context: ({ req }) => ({
+    user: req.user,
+    loaders: createDataLoaders()
+  })
+});
+
+await server.start();
+server.applyMiddleware({ app });
+
+app.listen(4000, () => {
+  console.log('GraphQL server running on http://localhost:4000/graphql');
+});
+```
+
+## Data Loaders (N+1 Prevention)
+
+```typescript
+import DataLoader from 'dataloader';
+
+function createDataLoaders() {
+  const userLoader = new DataLoader(async (userIds) => {
+    return await userRepository.findByIds(userIds);
+  });
+
+  const postLoader = new DataLoader(async (postIds) => {
+    return await postRepository.findByIds(postIds);
+  });
+
+  return { userLoader, postLoader };
+}
+
+// Use in resolvers
+Post: {
+  author: (post, _, { loaders }) => {
+    return loaders.userLoader.load(post.authorId);
+  }
+}
+```
+
+## Client Usage
+
+```typescript
+import { gql, useMutation, useQuery } from '@apollo/client';
+
+const GET_USER = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      email
+      name
+      posts {
+        id
+        title
+      }
+    }
+  }
+`;
+
+const CREATE_POST = gql`
+  mutation CreatePost($title: String!, $content: String!) {
+    createPost(title: $title, content: $content) {
+      id
+      title
+    }
+  }
+`;
+
+function UserProfile({ userId }) {
+  const { data, loading } = useQuery(GET_USER, { 
+    variables: { id: userId } 
+  });
+
+  const [createPost] = useMutation(CREATE_POST);
+
+  const handleCreate = async (title, content) => {
+    await createPost({ variables: { title, content } });
+  };
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>{data.user.name}</h1>
+      <button onClick={() => handleCreate('New Post', 'Content')}>
+        Create Post
+      </button>
+    </div>
+  );
+}
+```
+
+## Best Practices
+
+✅ **Validate input** - Use custom scalar types
+✅ **Batch queries** - Use DataLoaders for N+1 prevention
+✅ **Rate limiting** - Protect against expensive queries
+✅ **Error handling** - Return meaningful errors
+✅ **Caching** - Use APQ (Automatic Persisted Queries)
+
+## Resources
+
+- [GraphQL Official](https://graphql.org/)
+- [Apollo Server Docs](https://www.apollographql.com/docs/apollo-server/)

package/kit/.claude/skills/api-openapi.md

@@ -0,0 +1,116 @@
+# OpenAPI / Swagger
+
+## Overview
+Document REST APIs with OpenAPI 3.x specs for auto-generated clients, validation, and interactive docs.
+
+## Setup with Swagger UI (Express)
+
+```bash
+npm install swagger-ui-express @asteasolutions/zod-to-openapi
+```
+
+```typescript
+import swaggerUi from 'swagger-ui-express';
+import { OpenAPIRegistry, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
+import { z } from 'zod';
+
+const registry = new OpenAPIRegistry();
+
+// Define schemas
+const UserSchema = registry.register('User', z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+  createdAt: z.string().datetime(),
+}));
+
+// Register paths
+registry.registerPath({
+  method: 'get',
+  path: '/api/users/{id}',
+  tags: ['Users'],
+  summary: 'Get user by ID',
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    200: {
+      description: 'User found',
+      content: { 'application/json': { schema: UserSchema } },
+    },
+    404: { description: 'User not found' },
+  },
+});
+
+// Generate spec
+const generator = new OpenApiGeneratorV3(registry.definitions);
+const spec = generator.generateDocument({
+  openapi: '3.0.0',
+  info: { title: 'My API', version: '1.0.0' },
+  servers: [{ url: 'https://api.example.com' }],
+});
+
+app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(spec));
+app.get('/api/openapi.json', (req, res) => res.json(spec));
+```
+
+## Next.js with next-swagger-doc
+
+```bash
+npm install next-swagger-doc swagger-ui-react
+```
+
+```typescript
+// pages/api/doc.ts
+import { withSwagger } from 'next-swagger-doc';
+
+const swaggerHandler = withSwagger({
+  definition: {
+    openapi: '3.0.0',
+    info: { title: 'Next.js API', version: '0.1.0' },
+  },
+  apiFolder: 'pages/api',
+});
+export default swaggerHandler;
+```
+
+## JSDoc Annotations
+
+```typescript
+/**
+ * @swagger
+ * /api/users:
+ *   post:
+ *     tags: [Users]
+ *     summary: Create a user
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [email, name]
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *               name:
+ *                 type: string
+ *     responses:
+ *       201:
+ *         description: Created
+ */
+export async function POST(req: Request) {
+  // handler...
+}
+```
+
+## Best Practices
+- Generate spec from code (not hand-write YAML) to keep it in sync
+- Use `zod-to-openapi` to reuse validation schemas as OpenAPI models
+- Document all error responses, not just success
+- Version the spec URL: `/api/v1/openapi.json`
+
+## Resources
+- [OpenAPI Specification](https://spec.openapis.org/oas/v3.0.0)
+- [zod-to-openapi](https://github.com/asteasolutions/zod-to-openapi)

package/kit/.claude/skills/api-pagination-filtering.md

@@ -0,0 +1,239 @@
+# Pagination & Filtering
+
+Techniques for handling large datasets efficiently.
+
+## Cursor-Based Pagination
+
+```typescript
+// More efficient for large datasets
+interface PaginationResult<T> {
+  items: T[];
+  nextCursor?: string;
+  prevCursor?: string;
+  hasMore: boolean;
+}
+
+async function getCursorPaginatedUsers(
+  cursor?: string,
+  limit: number = 20
+): Promise<PaginationResult<User>> {
+  let query = db.users.orderBy('id', 'asc');
+
+  // Fetch one extra to know if there are more
+  const pageSize = limit + 1;
+
+  if (cursor) {
+    // Decode cursor (base64 encoded id)
+    const decodedCursor = Buffer.from(cursor, 'base64').toString();
+    query = query.where('id', '>', decodedCursor);
+  }
+
+  const items = await query.limit(pageSize).toArray();
+
+  const hasMore = items.length > limit;
+  const results = items.slice(0, limit);
+
+  return {
+    items: results,
+    nextCursor: hasMore ? Buffer.from(results[results.length - 1].id).toString('base64') : undefined,
+    hasMore
+  };
+}
+```
+
+## Offset-Based Pagination
+
+```typescript
+// Simple but less efficient for large offsets
+async function getOffsetPaginatedUsers(page: number = 1, pageSize: number = 20) {
+  const offset = (page - 1) * pageSize;
+
+  const [items, total] = await Promise.all([
+    db.users.offset(offset).limit(pageSize).toArray(),
+    db.users.count()
+  ]);
+
+  return {
+    items,
+    pagination: {
+      page,
+      pageSize,
+      total,
+      totalPages: Math.ceil(total / pageSize),
+      hasNextPage: page < Math.ceil(total / pageSize),
+      hasPrevPage: page > 1
+    }
+  };
+}
+```
+
+## Filtering
+
+```typescript
+interface FilterOptions {
+  role?: string;
+  status?: string;
+  createdAfter?: Date;
+  createdBefore?: Date;
+  search?: string;
+}
+
+async function filterUsers(filters: FilterOptions, limit: number = 20) {
+  let query = db.users;
+
+  if (filters.role) {
+    query = query.where('role', filters.role);
+  }
+
+  if (filters.status) {
+    query = query.where('status', filters.status);
+  }
+
+  if (filters.createdAfter) {
+    query = query.where('createdAt', '>=', filters.createdAfter);
+  }
+
+  if (filters.createdBefore) {
+    query = query.where('createdAt', '<=', filters.createdBefore);
+  }
+
+  if (filters.search) {
+    query = query.whereRaw('CONCAT(firstName, lastName) LIKE ?', [`%${filters.search}%`]);
+  }
+
+  return await query.limit(limit).toArray();
+}
+```
+
+## Sorting
+
+```typescript
+type SortOrder = 'asc' | 'desc';
+
+interface SortOption {
+  field: string;
+  order: SortOrder;
+}
+
+async function getSortedUsers(sort: SortOption, limit: number = 20) {
+  // Whitelist allowed sort fields
+  const allowedFields = ['id', 'name', 'email', 'createdAt'];
+
+  if (!allowedFields.includes(sort.field)) {
+    throw new Error(`Invalid sort field: ${sort.field}`);
+  }
+
+  return await db.users
+    .orderBy(sort.field, sort.order)
+    .limit(limit)
+    .toArray();
+}
+```
+
+## Combined Filtering, Sorting, Pagination
+
+```typescript
+interface QueryOptions {
+  page?: number;
+  limit?: number;
+  sortBy?: string;
+  order?: 'asc' | 'desc';
+  role?: string;
+  status?: string;
+  search?: string;
+}
+
+async function queryUsers(options: QueryOptions) {
+  let query = db.users;
+
+  // Apply filters
+  if (options.role) {
+    query = query.where('role', options.role);
+  }
+
+  if (options.status) {
+    query = query.where('status', options.status);
+  }
+
+  if (options.search) {
+    query = query.whereRaw(
+      'CONCAT(firstName, lastName) LIKE ?',
+      [`%${options.search}%`]
+    );
+  }
+
+  // Apply sorting
+  const sortBy = options.sortBy || 'createdAt';
+  const order = options.order || 'desc';
+  query = query.orderBy(sortBy, order);
+
+  // Apply pagination
+  const page = options.page || 1;
+  const limit = Math.min(options.limit || 20, 100); // Max 100 items
+  const offset = (page - 1) * limit;
+
+  const [items, total] = await Promise.all([
+    query.offset(offset).limit(limit).toArray(),
+    query.count()
+  ]);
+
+  return {
+    data: items,
+    meta: {
+      page,
+      limit,
+      total,
+      pages: Math.ceil(total / limit)
+    }
+  };
+}
+```
+
+## Search Implementation
+
+```typescript
+// Full-text search
+async function searchUsers(query: string) {
+  // MySQL FULLTEXT search
+  return await db.users
+    .whereRaw(
+      'MATCH(firstName, lastName, email) AGAINST(? IN BOOLEAN MODE)',
+      [query]
+    )
+    .toArray();
+}
+
+// Elasticsearch integration
+import { Client } from '@elastic/elasticsearch';
+
+const client = new Client({ node: 'http://localhost:9200' });
+
+async function searchUsersES(query: string) {
+  const response = await client.search({
+    index: 'users',
+    body: {
+      query: {
+        multi_match: {
+          query,
+          fields: ['firstName', 'lastName', 'email']
+        }
+      }
+    }
+  });
+
+  return response.body.hits.hits;
+}
+```
+
+## Best Practices
+
+✅ **Cursor pagination** - For large datasets
+✅ **Limit results** - Cap maximum page size
+✅ **Index columns** - For fast filtering/sorting
+✅ **Whitelist fields** - Prevent injection
+✅ **Cache frequently used** - Popular filters/sorts
+
+## Resources
+
+- [Pagination Patterns](https://slack.engineering/a-method-for-pagination/)
+- [Elasticsearch Documentation](https://www.elastic.co/guide/index.html)