@intentsolutionsio/jeremy-firestore 2.0.0

package/commands/firestore-setup.md

@@ -0,0 +1,543 @@
+---
+name: firestore-setup
+description: Initialize Firebase Admin SDK, configure Firestore, and setup A2A/MCP...
+model: sonnet
+---
+# Firestore Setup Command
+
+Initialize Firebase Admin SDK in your project with support for:
+- Basic Firestore operations (CRUD, queries)
+- A2A (Agent-to-Agent) framework integration
+- MCP server communication patterns
+- Cloud Run service integration
+- Service account authentication
+
+## Your Mission
+
+Set up Firebase Admin SDK with proper configuration for both regular users and AI agents. Guide the user through:
+
+1. **Environment detection** - Check if Firebase is already configured
+2. **Dependency installation** - Install firebase-admin package
+3. **Credential setup** - Configure service account authentication
+4. **Firestore initialization** - Initialize and test connection
+5. **A2A/MCP setup** (optional) - Configure for agent communication
+6. **Security rules** (optional) - Deploy initial security rules
+
+## Step-by-Step Workflow
+
+### Step 1: Check Existing Setup
+
+First, check if Firebase is already configured:
+
+```bash
+# Check if firebase-admin is installed
+npm list firebase-admin
+
+# Check for existing Firebase initialization
+grep -r "firebase-admin" .
+
+# Check for service account credentials
+ls -la *.json | grep -i firebase
+```
+
+If Firebase is already set up, ask the user if they want to reconfigure.
+
+### Step 2: Install Dependencies
+
+```bash
+# Install firebase-admin
+npm install firebase-admin
+
+# For A2A/MCP integration, also install:
+npm install @google-cloud/firestore
+npm install dotenv  # For environment variables
+```
+
+### Step 3: Get Service Account Credentials
+
+Ask the user:
+
+**Option A: Download from Firebase Console**
+```
+1. Go to https://console.firebase.google.com
+2. Select your project
+3. Settings (gear icon) → Project Settings → Service Accounts
+4. Click "Generate new private key"
+5. Save JSON file to your project (e.g., serviceAccountKey.json)
+```
+
+**Option B: Use existing GCP credentials**
+```bash
+# If using Google Cloud SDK
+gcloud auth application-default login
+```
+
+**Option C: Environment variable (production)**
+```bash
+# Set environment variable
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"
+```
+
+### Step 4: Create Firebase Initialization File
+
+Create `src/firebase.js` (or `src/firebase.ts` for TypeScript):
+
+```javascript
+const admin = require('firebase-admin');
+
+// Initialize Firebase Admin SDK
+if (!admin.apps.length) {
+  // Option 1: Using service account key file
+  const serviceAccount = require('../serviceAccountKey.json');
+
+  admin.initializeApp({
+    credential: admin.credential.cert(serviceAccount),
+    databaseURL: `https://${serviceAccount.project_id}.firebaseio.com`
+  });
+
+  // Option 2: Using environment variable (recommended for production)
+  // admin.initializeApp({
+  //   credential: admin.credential.applicationDefault(),
+  //   projectId: process.env.FIREBASE_PROJECT_ID
+  // });
+}
+
+const db = admin.firestore();
+
+// Export for use in other files
+module.exports = { admin, db };
+```
+
+For TypeScript:
+```typescript
+import * as admin from 'firebase-admin';
+
+if (!admin.apps.length) {
+  const serviceAccount = require('../serviceAccountKey.json');
+
+  admin.initializeApp({
+    credential: admin.credential.cert(serviceAccount),
+    databaseURL: `https://${serviceAccount.project_id}.firebaseio.com`
+  });
+}
+
+export const db = admin.firestore();
+export { admin };
+```
+
+### Step 5: Test Connection
+
+Create a test script to verify Firestore works:
+
+```javascript
+const { db } = require('./src/firebase');
+
+async function testFirestore() {
+  try {
+    // Test write
+    const testRef = await db.collection('_test').add({
+      message: 'Firebase connected successfully!',
+      timestamp: admin.firestore.FieldValue.serverTimestamp()
+    });
+
+    console.log('✅ Write successful. Document ID:', testRef.id);
+
+    // Test read
+    const doc = await testRef.get();
+    console.log('✅ Read successful. Data:', doc.data());
+
+    // Clean up test document
+    await testRef.delete();
+    console.log('✅ Delete successful');
+
+    console.log('\n🎉 Firebase is configured correctly!');
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    process.exit(1);
+  }
+}
+
+testFirestore();
+```
+
+Run the test:
+```bash
+node test-firestore.js
+```
+
+### Step 6: A2A/MCP Setup (Optional)
+
+If the user needs A2A or MCP integration, create additional configuration:
+
+**A. Create A2A configuration file** (`src/a2a-config.js`):
+
+```javascript
+const { db } = require('./firebase');
+
+// A2A Framework Configuration
+const A2A_CONFIG = {
+  collections: {
+    sessions: 'agent_sessions',
+    memory: 'agent_memory',
+    tasks: 'a2a_tasks',
+    messages: 'a2a_messages',
+    logs: 'agent_logs'
+  },
+
+  serviceAccounts: [
+    'mcp-server@project-id.iam.gserviceaccount.com',
+    'agent-engine@project-id.iam.gserviceaccount.com'
+  ],
+
+  sessionTTL: 3600, // 1 hour in seconds
+  messageTTL: 86400, // 24 hours
+
+  rateLimits: {
+    maxRequestsPerMinute: 100,
+    maxConcurrentSessions: 50
+  }
+};
+
+// Initialize A2A collections
+async function initializeA2ACollections() {
+  const collections = Object.values(A2A_CONFIG.collections);
+
+  for (const collection of collections) {
+    const ref = db.collection(collection);
+
+    // Create initial document to establish collection
+    await ref.doc('_init').set({
+      initialized: true,
+      timestamp: new Date()
+    });
+
+    console.log(`✅ Initialized collection: ${collection}`);
+  }
+}
+
+module.exports = { A2A_CONFIG, initializeA2ACollections };
+```
+
+**B. Create MCP service integration** (`src/mcp-service.js`):
+
+```javascript
+const { db } = require('./firebase');
+const { A2A_CONFIG } = require('./a2a-config');
+
+class MCPService {
+  constructor(serviceAccountEmail) {
+    this.serviceAccountEmail = serviceAccountEmail;
+    this.db = db;
+  }
+
+  // Create a new agent session
+  async createSession(sessionData) {
+    const sessionRef = this.db.collection(A2A_CONFIG.collections.sessions).doc();
+
+    await sessionRef.set({
+      ...sessionData,
+      agentId: this.serviceAccountEmail,
+      status: 'active',
+      createdAt: admin.firestore.FieldValue.serverTimestamp(),
+      expiresAt: new Date(Date.now() + A2A_CONFIG.sessionTTL * 1000)
+    });
+
+    return sessionRef.id;
+  }
+
+  // Store agent memory/context
+  async storeContext(sessionId, contextData) {
+    const contextRef = this.db
+      .collection(A2A_CONFIG.collections.memory)
+      .doc(this.serviceAccountEmail)
+      .collection('contexts')
+      .doc(sessionId);
+
+    await contextRef.set({
+      ...contextData,
+      agentId: this.serviceAccountEmail,
+      sessionId,
+      timestamp: admin.firestore.FieldValue.serverTimestamp()
+    });
+  }
+
+  // Send message to another agent
+  async sendMessage(toAgent, payload) {
+    await this.db.collection(A2A_CONFIG.collections.messages).add({
+      from: this.serviceAccountEmail,
+      to: toAgent,
+      payload,
+      timestamp: admin.firestore.FieldValue.serverTimestamp(),
+      status: 'pending'
+    });
+  }
+
+  // Receive messages for this agent
+  async receiveMessages() {
+    const snapshot = await this.db
+      .collection(A2A_CONFIG.collections.messages)
+      .where('to', '==', this.serviceAccountEmail)
+      .where('status', '==', 'pending')
+      .orderBy('timestamp', 'asc')
+      .get();
+
+    const messages = [];
+    const batch = this.db.batch();
+
+    snapshot.forEach(doc => {
+      messages.push({ id: doc.id, ...doc.data() });
+      // Mark as processed
+      batch.update(doc.ref, { status: 'processed' });
+    });
+
+    await batch.commit();
+    return messages;
+  }
+
+  // Log agent activity
+  async logActivity(activity, level = 'info') {
+    await this.db.collection(A2A_CONFIG.collections.logs).add({
+      agentId: this.serviceAccountEmail,
+      activity,
+      level,
+      timestamp: admin.firestore.FieldValue.serverTimestamp()
+    });
+  }
+}
+
+module.exports = { MCPService };
+```
+
+**C. Create Cloud Run service integration** (`src/cloudrun-service.js`):
+
+```javascript
+const { db } = require('./firebase');
+
+class CloudRunService {
+  constructor() {
+    this.db = db;
+  }
+
+  // Log API requests from Cloud Run
+  async logRequest(endpoint, method, userId, metadata = {}) {
+    await this.db.collection('api_requests').add({
+      endpoint,
+      method,
+      userId,
+      metadata,
+      timestamp: admin.firestore.FieldValue.serverTimestamp()
+    });
+  }
+
+  // Store API response
+  async storeResponse(requestId, responseData) {
+    await this.db.collection('api_responses').doc(requestId).set({
+      ...responseData,
+      timestamp: admin.firestore.FieldValue.serverTimestamp()
+    });
+  }
+
+  // Get user data for Cloud Run service
+  async getUserData(userId) {
+    const doc = await this.db.collection('users').doc(userId).get();
+    if (!doc.exists) {
+      throw new Error('User not found');
+    }
+    return doc.data();
+  }
+}
+
+module.exports = { CloudRunService };
+```
+
+### Step 7: Setup Environment Variables
+
+Create `.env` file:
+
+```bash
+# Firebase Configuration
+GOOGLE_APPLICATION_CREDENTIALS=./serviceAccountKey.json
+FIREBASE_PROJECT_ID=your-project-id
+
+# A2A Configuration (if applicable)
+MCP_SERVICE_ACCOUNT_EMAIL=mcp-server@project-id.iam.gserviceaccount.com
+AGENT_ENGINE_SERVICE_ACCOUNT=agent-engine@project-id.iam.gserviceaccount.com
+
+# Cloud Run Configuration (if applicable)
+CLOUD_RUN_SERVICE_URL=https://your-service-abc123-uc.a.run.app
+```
+
+Add to `.gitignore`:
+```
+serviceAccountKey.json
+.env
+```
+
+### Step 8: Deploy Security Rules (Optional)
+
+Ask if the user wants to deploy initial security rules:
+
+```bash
+# Install Firebase CLI
+npm install -g firebase-tools
+
+# Login
+firebase login
+
+# Initialize Firestore rules
+firebase init firestore
+```
+
+Then use the `firestore-security-agent` to generate appropriate rules based on their use case.
+
+### Step 9: Create Example Usage File
+
+Create `examples/firestore-usage.js`:
+
+```javascript
+const { db, admin } = require('../src/firebase');
+
+// Example 1: Basic CRUD
+async function basicCRUD() {
+  // Create
+  const docRef = await db.collection('users').add({
+    name: 'John Doe',
+    email: '[email protected]',
+    createdAt: admin.firestore.FieldValue.serverTimestamp()
+  });
+
+  // Read
+  const doc = await docRef.get();
+  console.log('User data:', doc.data());
+
+  // Update
+  await docRef.update({
+    name: 'John Updated',
+    updatedAt: admin.firestore.FieldValue.serverTimestamp()
+  });
+
+  // Delete
+  await docRef.delete();
+}
+
+// Example 2: Queries
+async function queryExamples() {
+  // Simple query
+  const activeUsers = await db.collection('users')
+    .where('status', '==', 'active')
+    .limit(10)
+    .get();
+
+  activeUsers.forEach(doc => {
+    console.log(doc.id, doc.data());
+  });
+
+  // Complex query
+  const recentOrders = await db.collection('orders')
+    .where('userId', '==', 'user123')
+    .where('status', '==', 'pending')
+    .orderBy('createdAt', 'desc')
+    .limit(5)
+    .get();
+}
+
+// Example 3: Batch operations
+async function batchOperations() {
+  const batch = db.batch();
+
+  // Add multiple documents
+  for (let i = 0; i < 10; i++) {
+    const ref = db.collection('items').doc();
+    batch.set(ref, {
+      name: `Item ${i}`,
+      createdAt: admin.firestore.FieldValue.serverTimestamp()
+    });
+  }
+
+  await batch.commit();
+  console.log('Batch write completed');
+}
+
+// Example 4: A2A usage (if configured)
+async function a2aExample() {
+  const { MCPService } = require('../src/mcp-service');
+  const mcp = new MCPService('mcp-server@project.iam.gserviceaccount.com');
+
+  // Create session
+  const sessionId = await mcp.createSession({
+    task: 'process_user_data',
+    priority: 'high'
+  });
+
+  // Store context
+  await mcp.storeContext(sessionId, {
+    userId: 'user123',
+    action: 'data_processing'
+  });
+
+  // Send message to another agent
+  await mcp.sendMessage(
+    'agent-engine@project.iam.gserviceaccount.com',
+    { action: 'analyze', data: { userId: 'user123' } }
+  );
+
+  // Log activity
+  await mcp.logActivity('Processed user data', 'info');
+}
+
+module.exports = { basicCRUD, queryExamples, batchOperations, a2aExample };
+```
+
+## Post-Setup Checklist
+
+Verify the following after setup:
+
+- [ ] Firebase Admin SDK installed
+- [ ] Service account credentials configured
+- [ ] `.gitignore` includes serviceAccountKey.json and .env
+- [ ] Connection test passes
+- [ ] Example usage file works
+- [ ] A2A collections initialized (if applicable)
+- [ ] Security rules deployed (if applicable)
+- [ ] Environment variables set
+- [ ] Documentation updated
+
+## Next Steps
+
+Tell the user:
+
+1. **Test the setup** - Run `node test-firestore.js`
+2. **Read the examples** - Check `examples/firestore-usage.js`
+3. **Deploy security rules** - Use `/firestore-security-agent` to generate rules
+4. **Start building** - Use `/firebase-operations-agent` for CRUD operations
+
+## Common Issues
+
+### Issue 1: "Permission denied" errors
+- Check service account has Firestore permissions
+- Verify security rules allow the operation
+- Ensure GOOGLE_APPLICATION_CREDENTIALS is set correctly
+
+### Issue 2: "Firebase app already initialized"
+- This is normal - only initialize once
+- Check if Firebase is initialized in multiple files
+
+### Issue 3: "Cannot find module 'firebase-admin'"
+- Run `npm install firebase-admin`
+- Check package.json includes firebase-admin
+
+### Issue 4: A2A collections not accessible
+- Verify service account email is whitelisted in security rules
+- Check firestore.rules includes A2A patterns
+- Test with Firebase Emulator first
+
+## Security Reminders
+
+1. **Never commit serviceAccountKey.json** to version control
+2. **Use environment variables** in production
+3. **Whitelist service accounts** in security rules
+4. **Rotate credentials regularly** (every 90 days recommended)
+5. **Monitor usage** with Firebase console
+6. **Set up billing alerts** to avoid surprises
+
+Congratulations! Your Firestore setup is complete! 🎉

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@intentsolutionsio/jeremy-firestore",
+  "version": "2.0.0",
+  "description": "Firestore database specialist for schema design, queries, and real-time sync",
+  "keywords": [
+    "firebase",
+    "firestore",
+    "database",
+    "crud",
+    "security-rules",
+    "cloud-functions",
+    "batch-operations",
+    "data-migration",
+    "performance",
+    "cost-optimization",
+    "nosql",
+    "google-cloud",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/community/jeremy-firestore"
+  },
+  "homepage": "https://tonsofskills.com/plugins/jeremy-firestore",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "[email protected]",
+    "url": "https://intentsolutions.io"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "commands",
+    "agents"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install jeremy-firestore\\\\n  or /plugin install jeremy-firestore@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}