autoworkflow 3.1.4 → 3.5.0

package/.claude/skills/mongodb.md

@@ -0,0 +1,319 @@
+# MongoDB Skill
+
+## Schema Design Patterns
+\`\`\`javascript
+// Embedding (denormalization) - for data accessed together
+{
+  _id: ObjectId("..."),
+  title: "Blog Post",
+  content: "...",
+  author: {
+    _id: ObjectId("..."),
+    name: "John Doe",
+    email: "john@example.com"
+  },
+  comments: [
+    { user: "Jane", text: "Great post!", date: ISODate("...") },
+    { user: "Bob", text: "Thanks!", date: ISODate("...") }
+  ]
+}
+
+// Referencing (normalization) - for unbounded or frequently updated data
+{
+  _id: ObjectId("..."),
+  title: "Blog Post",
+  content: "...",
+  authorId: ObjectId("..."),  // Reference to users collection
+  commentIds: [ObjectId("..."), ObjectId("...")]  // Bounded array
+}
+
+// Bucket pattern - for time series data
+{
+  sensorId: "sensor_001",
+  date: ISODate("2024-01-15"),
+  readings: [
+    { time: ISODate("2024-01-15T00:00:00Z"), value: 23.5 },
+    { time: ISODate("2024-01-15T00:01:00Z"), value: 23.6 },
+    // ... up to 1440 readings per day
+  ],
+  count: 1440
+}
+
+// Polymorphic pattern - for different item types
+{
+  _id: ObjectId("..."),
+  itemType: "book",
+  title: "MongoDB Guide",
+  author: "Jane Doe",
+  isbn: "978-..."
+}
+{
+  _id: ObjectId("..."),
+  itemType: "movie",
+  title: "The Matrix",
+  director: "Wachowskis",
+  runtime: 136
+}
+\`\`\`
+
+## Indexes
+\`\`\`javascript
+// Single field index
+db.users.createIndex({ email: 1 })  // 1 = ascending, -1 = descending
+
+// Unique index
+db.users.createIndex({ email: 1 }, { unique: true })
+
+// Compound index (order matters for queries!)
+db.posts.createIndex({ authorId: 1, createdAt: -1 })
+
+// Partial index (smaller, more efficient)
+db.users.createIndex(
+  { email: 1 },
+  { partialFilterExpression: { status: "active" } }
+)
+
+// TTL index (auto-expire documents)
+db.sessions.createIndex({ createdAt: 1 }, { expireAfterSeconds: 3600 })
+
+// Text index for full-text search
+db.posts.createIndex({ title: "text", content: "text" })
+
+// Wildcard index (flexible schema)
+db.products.createIndex({ "attributes.$**": 1 })
+
+// Geospatial index
+db.locations.createIndex({ coordinates: "2dsphere" })
+
+// Check index usage
+db.users.aggregate([{ $indexStats: {} }])
+\`\`\`
+
+## CRUD Operations
+\`\`\`javascript
+// Insert
+db.users.insertOne({ email: "user@example.com", name: "John" })
+db.users.insertMany([
+  { email: "user1@example.com", name: "User 1" },
+  { email: "user2@example.com", name: "User 2" }
+])
+
+// Find
+db.users.findOne({ email: "user@example.com" })
+db.users.find({ status: "active" }).limit(20).skip(0).sort({ createdAt: -1 })
+
+// Projection (select fields)
+db.users.find({ status: "active" }, { email: 1, name: 1, _id: 0 })
+
+// Update
+db.users.updateOne(
+  { _id: ObjectId("...") },
+  { $set: { name: "Jane", updatedAt: new Date() } }
+)
+
+// Upsert
+db.users.updateOne(
+  { email: "user@example.com" },
+  { $set: { name: "John" }, $setOnInsert: { createdAt: new Date() } },
+  { upsert: true }
+)
+
+// Update operators
+db.posts.updateOne({ _id }, {
+  $set: { title: "New Title" },
+  $inc: { views: 1 },
+  $push: { tags: "mongodb" },
+  $addToSet: { likes: userId },  // Only add if not exists
+  $pull: { dislikes: userId },   // Remove from array
+  $currentDate: { updatedAt: true }
+})
+
+// Delete
+db.users.deleteOne({ _id: ObjectId("...") })
+db.users.deleteMany({ status: "inactive", lastLogin: { $lt: oneYearAgo } })
+\`\`\`
+
+## Query Operators
+\`\`\`javascript
+// Comparison
+db.users.find({ age: { $gt: 18, $lte: 65 } })
+db.posts.find({ status: { $in: ["published", "featured"] } })
+db.users.find({ deletedAt: { $exists: false } })
+
+// Logical
+db.users.find({
+  $and: [
+    { status: "active" },
+    { $or: [
+      { role: "admin" },
+      { email: { $regex: /@company\\.com$/ } }
+    ]}
+  ]
+})
+
+// Array queries
+db.posts.find({ tags: "mongodb" })  // Array contains
+db.posts.find({ tags: { $all: ["mongodb", "database"] } })  // Contains all
+db.posts.find({ "tags.0": "featured" })  // First element
+db.posts.find({ tags: { $size: 3 } })  // Exact array length
+db.posts.find({ comments: { $elemMatch: { user: "John", score: { $gte: 5 } } } })
+
+// Text search
+db.posts.find({ $text: { $search: "mongodb tutorial" } })
+  .sort({ score: { $meta: "textScore" } })
+\`\`\`
+
+## Aggregation Pipeline
+\`\`\`javascript
+// Basic aggregation
+db.orders.aggregate([
+  { $match: { status: "completed" } },
+  { $group: {
+    _id: "$customerId",
+    totalSpent: { $sum: "$total" },
+    orderCount: { $sum: 1 },
+    avgOrder: { $avg: "$total" }
+  }},
+  { $sort: { totalSpent: -1 } },
+  { $limit: 10 }
+])
+
+// Lookup (join)
+db.posts.aggregate([
+  { $match: { published: true } },
+  { $lookup: {
+    from: "users",
+    localField: "authorId",
+    foreignField: "_id",
+    as: "author"
+  }},
+  { $unwind: "$author" },  // Convert array to object
+  { $project: {
+    title: 1,
+    "author.name": 1,
+    "author.email": 1
+  }}
+])
+
+// Faceted search (multiple aggregations)
+db.products.aggregate([
+  { $match: { status: "active" } },
+  { $facet: {
+    results: [
+      { $sort: { createdAt: -1 } },
+      { $skip: 0 },
+      { $limit: 20 }
+    ],
+    totalCount: [
+      { $count: "count" }
+    ],
+    categories: [
+      { $group: { _id: "$category", count: { $sum: 1 } } }
+    ],
+    priceRange: [
+      { $group: {
+        _id: null,
+        min: { $min: "$price" },
+        max: { $max: "$price" }
+      }}
+    ]
+  }}
+])
+
+// Unwind arrays
+db.posts.aggregate([
+  { $unwind: "$tags" },
+  { $group: { _id: "$tags", count: { $sum: 1 } } },
+  { $sort: { count: -1 } }
+])
+
+// Date operations
+db.orders.aggregate([
+  { $group: {
+    _id: {
+      year: { $year: "$createdAt" },
+      month: { $month: "$createdAt" }
+    },
+    revenue: { $sum: "$total" }
+  }},
+  { $sort: { "_id.year": 1, "_id.month": 1 } }
+])
+\`\`\`
+
+## Transactions (Replica Set required)
+\`\`\`javascript
+const session = client.startSession();
+
+try {
+  session.startTransaction();
+
+  await users.insertOne({ email, name }, { session });
+  await posts.insertOne({ title, authorId: userId }, { session });
+
+  await session.commitTransaction();
+} catch (error) {
+  await session.abortTransaction();
+  throw error;
+} finally {
+  session.endSession();
+}
+
+// With callback (auto-retry)
+await session.withTransaction(async () => {
+  await users.updateOne({ _id: senderId }, { $inc: { balance: -100 } }, { session });
+  await users.updateOne({ _id: receiverId }, { $inc: { balance: 100 } }, { session });
+});
+\`\`\`
+
+## Change Streams
+\`\`\`javascript
+// Watch for changes (real-time)
+const changeStream = db.collection('users').watch([
+  { $match: { operationType: { $in: ['insert', 'update'] } } }
+]);
+
+changeStream.on('change', (change) => {
+  console.log('Change detected:', change.operationType);
+  console.log('Document:', change.fullDocument);
+});
+
+// Resume after failure
+const resumeToken = change._id;
+const resumedStream = collection.watch([], { resumeAfter: resumeToken });
+\`\`\`
+
+## Performance & Monitoring
+\`\`\`javascript
+// Explain query plan
+db.users.find({ email: "test@example.com" }).explain("executionStats")
+
+// Index recommendations
+db.users.aggregate([{ $indexStats: {} }])
+
+// Current operations
+db.currentOp({ "active": true })
+
+// Server status
+db.serverStatus()
+
+// Collection stats
+db.users.stats()
+\`\`\`
+
+## ❌ DON'T
+- Store unbounded arrays (use bucketing or references)
+- Create too many indexes (write overhead)
+- Use \`$where\` or JavaScript execution in queries
+- Skip index for frequently queried fields
+- Embed frequently changing data
+- Use find() without limits on large collections
+
+## ✅ DO
+- Design schema for query patterns
+- Use compound indexes matching query shapes
+- Use aggregation pipeline for complex queries
+- Use change streams for real-time updates
+- Set appropriate read/write concerns
+- Use TTL indexes for expiring data
+- Monitor index usage and slow queries
+- Use projection to limit returned fields

package/.claude/skills/mongoose.md

@@ -0,0 +1,355 @@
+# Mongoose Skill
+
+## Connection Setup
+\`\`\`typescript
+import mongoose from 'mongoose';
+
+// Connection with options
+await mongoose.connect(process.env.MONGODB_URI!, {
+  maxPoolSize: 10,
+  serverSelectionTimeoutMS: 5000,
+  socketTimeoutMS: 45000,
+});
+
+// Connection events
+mongoose.connection.on('connected', () => console.log('MongoDB connected'));
+mongoose.connection.on('error', (err) => console.error('MongoDB error:', err));
+mongoose.connection.on('disconnected', () => console.log('MongoDB disconnected'));
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  await mongoose.connection.close();
+  process.exit(0);
+});
+\`\`\`
+
+## Schema Definition with TypeScript
+\`\`\`typescript
+import { Schema, model, Document, Types, Model } from 'mongoose';
+
+// TypeScript interfaces
+interface IUser {
+  email: string;
+  name: string;
+  password: string;
+  role: 'user' | 'admin';
+  settings: Record<string, unknown>;
+  posts: Types.ObjectId[];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// Methods interface
+interface IUserMethods {
+  comparePassword(candidate: string): Promise<boolean>;
+  generateAuthToken(): string;
+}
+
+// Static methods interface
+interface UserModel extends Model<IUser, {}, IUserMethods> {
+  findByEmail(email: string): Promise<IUser | null>;
+}
+
+// Schema definition
+const userSchema = new Schema<IUser, UserModel, IUserMethods>({
+  email: {
+    type: String,
+    required: [true, 'Email is required'],
+    unique: true,
+    lowercase: true,
+    trim: true,
+    validate: {
+      validator: (v: string) => /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(v),
+      message: 'Invalid email format',
+    },
+  },
+  name: {
+    type: String,
+    required: true,
+    trim: true,
+    minlength: [2, 'Name must be at least 2 characters'],
+    maxlength: [100, 'Name cannot exceed 100 characters'],
+  },
+  password: {
+    type: String,
+    required: true,
+    select: false, // Excluded from queries by default
+  },
+  role: {
+    type: String,
+    enum: ['user', 'admin'],
+    default: 'user',
+  },
+  settings: {
+    type: Schema.Types.Mixed,
+    default: {},
+  },
+  posts: [{
+    type: Schema.Types.ObjectId,
+    ref: 'Post',
+  }],
+}, {
+  timestamps: true, // Adds createdAt, updatedAt
+  toJSON: { virtuals: true },
+  toObject: { virtuals: true },
+});
+
+// Indexes
+userSchema.index({ email: 1 });
+userSchema.index({ role: 1, createdAt: -1 });
+
+export const User = model<IUser, UserModel>('User', userSchema);
+\`\`\`
+
+## Virtuals
+\`\`\`typescript
+// Virtual property (not stored in DB)
+userSchema.virtual('fullName').get(function() {
+  return \`\${this.firstName} \${this.lastName}\`;
+});
+
+// Virtual populate (referenced documents)
+userSchema.virtual('postCount', {
+  ref: 'Post',
+  localField: '_id',
+  foreignField: 'author',
+  count: true,
+});
+
+// Usage
+const user = await User.findById(id).populate('postCount');
+console.log(user.postCount); // Number of posts
+\`\`\`
+
+## Instance & Static Methods
+\`\`\`typescript
+// Instance method
+userSchema.methods.comparePassword = async function(candidate: string): Promise<boolean> {
+  return bcrypt.compare(candidate, this.password);
+};
+
+userSchema.methods.generateAuthToken = function(): string {
+  return jwt.sign({ id: this._id, role: this.role }, process.env.JWT_SECRET!);
+};
+
+// Static method
+userSchema.statics.findByEmail = function(email: string) {
+  return this.findOne({ email: email.toLowerCase() });
+};
+
+// Usage
+const user = await User.findByEmail('test@example.com'); // Static
+const isValid = await user.comparePassword('password123'); // Instance
+const token = user.generateAuthToken(); // Instance
+\`\`\`
+
+## Middleware (Hooks)
+\`\`\`typescript
+// Pre-save hook (hash password)
+userSchema.pre('save', async function(next) {
+  if (!this.isModified('password')) return next();
+  this.password = await bcrypt.hash(this.password, 12);
+  next();
+});
+
+// Pre-find hook (exclude deleted)
+userSchema.pre(/^find/, function(next) {
+  // 'this' is the query
+  this.where({ deletedAt: { $exists: false } });
+  next();
+});
+
+// Post-save hook
+userSchema.post('save', function(doc) {
+  console.log('User saved:', doc._id);
+  // Send welcome email, log audit, etc.
+});
+
+// Pre-remove hook (cascade delete)
+userSchema.pre('deleteOne', { document: true }, async function() {
+  await Post.deleteMany({ author: this._id });
+});
+\`\`\`
+
+## Query Patterns
+\`\`\`typescript
+// Find operations
+const user = await User.findById(id);
+const user = await User.findOne({ email });
+const users = await User.find({ role: 'user' });
+
+// With population (joins)
+const user = await User.findById(id)
+  .populate('posts')
+  .populate({
+    path: 'posts',
+    match: { published: true },
+    select: 'title createdAt',
+    options: { sort: { createdAt: -1 }, limit: 10 },
+  });
+
+// Select specific fields
+const user = await User.findById(id).select('email name role');
+const user = await User.findById(id).select('-password -settings'); // Exclude
+
+// Include normally excluded field
+const user = await User.findById(id).select('+password');
+
+// Lean queries (plain JS objects, faster)
+const user = await User.findById(id).lean();
+
+// Pagination
+const page = 1;
+const limit = 20;
+const users = await User.find({ role: 'user' })
+  .sort({ createdAt: -1 })
+  .skip((page - 1) * limit)
+  .limit(limit)
+  .lean();
+
+const total = await User.countDocuments({ role: 'user' });
+
+// Complex queries
+const users = await User.find({
+  $and: [
+    { role: 'user' },
+    { createdAt: { $gte: new Date('2024-01-01') } },
+    { $or: [
+      { email: { $regex: '@company.com$' } },
+      { name: { $regex: /^admin/i } },
+    ]},
+  ],
+});
+\`\`\`
+
+## Aggregation Pipeline
+\`\`\`typescript
+// Basic aggregation
+const stats = await User.aggregate([
+  { $match: { role: 'user' } },
+  { $group: {
+    _id: '$status',
+    count: { $sum: 1 },
+    avgAge: { $avg: '$age' },
+  }},
+  { $sort: { count: -1 } },
+]);
+
+// With lookup (join)
+const usersWithPosts = await User.aggregate([
+  { $match: { role: 'user' } },
+  { $lookup: {
+    from: 'posts',
+    localField: '_id',
+    foreignField: 'author',
+    as: 'posts',
+    pipeline: [
+      { $match: { published: true } },
+      { $sort: { createdAt: -1 } },
+      { $limit: 5 },
+    ],
+  }},
+  { $addFields: { postCount: { $size: '$posts' } } },
+  { $project: { password: 0 } },
+]);
+
+// Pagination with facet
+const result = await User.aggregate([
+  { $match: { role: 'user' } },
+  { $facet: {
+    data: [
+      { $sort: { createdAt: -1 } },
+      { $skip: (page - 1) * limit },
+      { $limit: limit },
+    ],
+    meta: [
+      { $count: 'total' },
+    ],
+  }},
+]);
+\`\`\`
+
+## Transactions
+\`\`\`typescript
+const session = await mongoose.startSession();
+
+try {
+  session.startTransaction();
+
+  const user = await User.create([{ email, name }], { session });
+
+  await Post.create([{
+    title: 'Welcome Post',
+    author: user[0]._id,
+  }], { session });
+
+  await session.commitTransaction();
+} catch (error) {
+  await session.abortTransaction();
+  throw error;
+} finally {
+  session.endSession();
+}
+
+// With withTransaction helper
+await session.withTransaction(async () => {
+  await User.create([userData], { session });
+  await Post.create([postData], { session });
+});
+\`\`\`
+
+## Validation
+\`\`\`typescript
+const productSchema = new Schema({
+  price: {
+    type: Number,
+    required: true,
+    min: [0, 'Price cannot be negative'],
+    validate: {
+      validator: Number.isFinite,
+      message: 'Price must be a finite number',
+    },
+  },
+  category: {
+    type: String,
+    enum: {
+      values: ['electronics', 'clothing', 'food'],
+      message: '{VALUE} is not a valid category',
+    },
+  },
+  tags: {
+    type: [String],
+    validate: {
+      validator: (v: string[]) => v.length <= 10,
+      message: 'Cannot have more than 10 tags',
+    },
+  },
+});
+
+// Custom async validator
+userSchema.path('email').validate({
+  validator: async function(email: string) {
+    const count = await User.countDocuments({ email, _id: { $ne: this._id } });
+    return count === 0;
+  },
+  message: 'Email already exists',
+});
+\`\`\`
+
+## ❌ DON'T
+- Store unbounded arrays in documents (use references)
+- Forget to create indexes for query patterns
+- Use \`find()\` without limits on large collections
+- Nest populations deeply (performance killer)
+- Use \`new Model()\` + \`save()\` when \`create()\` works
+- Skip \`.lean()\` when you don't need Mongoose features
+
+## ✅ DO
+- Design schemas around query patterns
+- Use \`lean()\` for read-only operations
+- Create compound indexes for common queries
+- Use aggregation for complex data transformations
+- Use transactions for multi-document operations
+- Validate data at schema level
+- Use virtuals for computed properties
+- Set \`select: false\` for sensitive fields