@claude-flow/cli 3.21.0 → 3.22.0

package/scripts/setup-ipfs-registry.md

@@ -1,366 +0,0 @@
-# IPFS Plugin Registry Setup Guide
-
-This guide walks through setting up a live IPFS plugin registry using Google Cloud and Pinata.
-
-## Prerequisites
-
-- Google Cloud account with billing enabled
-- Node.js 20+
-- `gcloud` CLI installed
-
-## Step 1: Pinata Setup (IPFS Pinning Service)
-
-### 1.1 Create Pinata Account
-
-1. Go to https://pinata.cloud and create an account
-2. Navigate to API Keys section
-3. Create a new API key with these permissions:
-   - `pinning/pinFileToIPFS`: true
-   - `pinning/pinJSONToIPFS`: true
-   - `pinning/unpin`: true
-
-### 1.2 Save Your Credentials
-
-```bash
-# Add to your shell profile (~/.zshrc or ~/.bashrc)
-export PINATA_JWT="your-jwt-token-here"
-```
-
-### 1.3 Generate IPNS Key (Optional - for stable addressing)
-
-If you have Pinata's paid plan with Dedicated Gateways:
-
-```bash
-# Via Pinata dashboard or API
-curl -X POST "https://api.pinata.cloud/v3/ipfs/keys" \
-  -H "Authorization: Bearer $PINATA_JWT" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "claude-flow-registry"}'
-```
-
-## Step 2: Google Cloud Setup
-
-### 2.1 Create Project
-
-```bash
-# Create new project
-gcloud projects create claude-flow-registry --name="Claude Flow Registry"
-
-# Set as active project
-gcloud config set project claude-flow-registry
-
-# Enable billing (required for Cloud Functions)
-gcloud beta billing projects link claude-flow-registry \
-  --billing-account=YOUR_BILLING_ACCOUNT_ID
-```
-
-### 2.2 Enable Required APIs
-
-```bash
-gcloud services enable \
-  cloudfunctions.googleapis.com \
-  cloudbuild.googleapis.com \
-  storage.googleapis.com \
-  secretmanager.googleapis.com
-```
-
-### 2.3 Create Storage Bucket
-
-```bash
-# Create bucket for registry source data
-gcloud storage buckets create gs://claude-flow-plugin-registry \
-  --location=US \
-  --uniform-bucket-level-access
-
-# Enable versioning for rollback
-gsutil versioning set on gs://claude-flow-plugin-registry
-
-# Make registry.json publicly readable (optional)
-gsutil iam ch allUsers:objectViewer gs://claude-flow-plugin-registry
-```
-
-### 2.4 Create Service Account
-
-```bash
-# Create service account
-gcloud iam service-accounts create plugin-registry-publisher \
-  --display-name="Plugin Registry Publisher"
-
-# Grant permissions
-gcloud projects add-iam-policy-binding claude-flow-registry \
-  --member="serviceAccount:plugin-registry-publisher@claude-flow-registry.iam.gserviceaccount.com" \
-  --role="roles/storage.objectAdmin"
-
-gcloud projects add-iam-policy-binding claude-flow-registry \
-  --member="serviceAccount:plugin-registry-publisher@claude-flow-registry.iam.gserviceaccount.com" \
-  --role="roles/secretmanager.secretAccessor"
-```
-
-### 2.5 Store Secrets
-
-```bash
-# Store Pinata JWT
-echo -n "$PINATA_JWT" | gcloud secrets create pinata-jwt --data-file=-
-
-# Generate and store Ed25519 signing key
-node -e "
-const crypto = require('crypto');
-const { subtle } = require('crypto').webcrypto;
-(async () => {
-  const keyPair = await subtle.generateKey(
-    { name: 'Ed25519', namedCurve: 'Ed25519' },
-    true,
-    ['sign', 'verify']
-  );
-  const privateKey = await subtle.exportKey('pkcs8', keyPair.privateKey);
-  const privateKeyHex = Buffer.from(privateKey).toString('hex');
-  console.log(privateKeyHex);
-})();
-" | gcloud secrets create registry-private-key --data-file=-
-```
-
-## Step 3: Deploy Cloud Function
-
-### 3.1 Create Function Directory
-
-```bash
-mkdir -p cloud-functions/publish-registry
-cd cloud-functions/publish-registry
-```
-
-### 3.2 Create package.json
-
-```json
-{
-  "name": "publish-registry",
-  "version": "1.0.0",
-  "main": "index.js",
-  "type": "module",
-  "dependencies": {
-    "@google-cloud/storage": "^7.0.0",
-    "@google-cloud/secret-manager": "^5.0.0",
-    "@noble/ed25519": "^2.0.0"
-  }
-}
-```
-
-### 3.3 Create index.js
-
-```javascript
-import { Storage } from '@google-cloud/storage';
-import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
-import * as ed from '@noble/ed25519';
-
-const storage = new Storage();
-const secretManager = new SecretManagerServiceClient();
-
-async function getSecret(name) {
-  const [version] = await secretManager.accessSecretVersion({
-    name: `projects/claude-flow-registry/secrets/${name}/versions/latest`,
-  });
-  return version.payload.data.toString();
-}
-
-export async function publishRegistry(req, res) {
-  try {
-    // Get secrets
-    const pinataJwt = await getSecret('pinata-jwt');
-    const privateKey = await getSecret('registry-private-key');
-
-    // Fetch registry from GCS
-    const bucket = storage.bucket('claude-flow-plugin-registry');
-    const file = bucket.file('registry.json');
-    const [content] = await file.download();
-    const registry = JSON.parse(content.toString());
-
-    // Update timestamp
-    registry.updatedAt = new Date().toISOString();
-
-    // Sign registry
-    const registryToSign = { ...registry };
-    delete registryToSign.registrySignature;
-    delete registryToSign.registryPublicKey;
-
-    const message = JSON.stringify(registryToSign);
-    const signature = await ed.signAsync(
-      new TextEncoder().encode(message),
-      Buffer.from(privateKey, 'hex')
-    );
-    const publicKey = await ed.getPublicKeyAsync(Buffer.from(privateKey, 'hex'));
-
-    registry.registrySignature = Buffer.from(signature).toString('hex');
-    registry.registryPublicKey = `ed25519:${Buffer.from(publicKey).toString('hex')}`;
-
-    // Pin to IPFS
-    const pinResponse = await fetch('https://api.pinata.cloud/pinning/pinJSONToIPFS', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${pinataJwt}`,
-      },
-      body: JSON.stringify({
-        pinataContent: registry,
-        pinataMetadata: {
-          name: 'claude-flow-plugin-registry',
-          keyvalues: {
-            version: registry.version,
-            updatedAt: registry.updatedAt,
-          },
-        },
-      }),
-    });
-
-    if (!pinResponse.ok) {
-      throw new Error(`Pinata error: ${await pinResponse.text()}`);
-    }
-
-    const pinResult = await pinResponse.json();
-
-    res.json({
-      success: true,
-      cid: pinResult.IpfsHash,
-      updatedAt: registry.updatedAt,
-      pluginCount: registry.plugins.length,
-      gateways: [
-        `https://gateway.pinata.cloud/ipfs/${pinResult.IpfsHash}`,
-        `https://ipfs.io/ipfs/${pinResult.IpfsHash}`,
-      ],
-    });
-  } catch (error) {
-    console.error('Publish failed:', error);
-    res.status(500).json({ error: error.message });
-  }
-}
-```
-
-### 3.4 Deploy Function
-
-```bash
-gcloud functions deploy publish-registry \
-  --gen2 \
-  --runtime=nodejs20 \
-  --region=us-central1 \
-  --source=. \
-  --entry-point=publishRegistry \
-  --trigger-http \
-  --allow-unauthenticated \
-  --service-account=plugin-registry-publisher@claude-flow-registry.iam.gserviceaccount.com \
-  --set-env-vars=GCP_PROJECT=claude-flow-registry
-```
-
-## Step 4: Create Initial Registry
-
-### 4.1 Upload Registry to GCS
-
-```bash
-# Generate initial registry
-npx tsx scripts/publish-registry.ts --dry-run > registry.json
-
-# Upload to GCS
-gsutil cp registry.json gs://claude-flow-plugin-registry/registry.json
-```
-
-### 4.2 Trigger First Publish
-
-```bash
-# Get function URL
-FUNCTION_URL=$(gcloud functions describe publish-registry \
-  --gen2 --region=us-central1 --format='value(serviceConfig.uri)')
-
-# Trigger publish
-curl -X POST "$FUNCTION_URL"
-```
-
-## Step 5: Automate with Cloud Build
-
-### 5.1 Create cloudbuild.yaml
-
-```yaml
-steps:
-  # Update registry from npm stats
-  - name: 'node:20'
-    entrypoint: 'npx'
-    args: ['tsx', 'scripts/publish-registry.ts', '--dry-run']
-    dir: 'v3/@claude-flow/cli'
-
-  # Upload to GCS
-  - name: 'gcr.io/cloud-builders/gsutil'
-    args: ['cp', 'registry.json', 'gs://claude-flow-plugin-registry/registry.json']
-
-  # Trigger Cloud Function
-  - name: 'gcr.io/cloud-builders/curl'
-    args: ['-X', 'POST', '${_FUNCTION_URL}']
-
-substitutions:
-  _FUNCTION_URL: 'https://us-central1-claude-flow-registry.cloudfunctions.net/publish-registry'
-
-# Run daily at 2am UTC
-options:
-  logging: CLOUD_LOGGING_ONLY
-```
-
-### 5.2 Create Cloud Scheduler Trigger
-
-```bash
-gcloud scheduler jobs create http publish-registry-daily \
-  --location=us-central1 \
-  --schedule="0 2 * * *" \
-  --uri="https://us-central1-claude-flow-registry.cloudfunctions.net/publish-registry" \
-  --http-method=POST
-```
-
-## Step 6: Update Claude Flow CLI
-
-Update `DEFAULT_PLUGIN_STORE_CONFIG` in `discovery.ts`:
-
-```typescript
-export const DEFAULT_PLUGIN_STORE_CONFIG: PluginStoreConfig = {
-  registries: [
-    {
-      name: 'claude-flow-official',
-      description: 'Official Claude Flow plugin registry',
-      // Use the CID from your first publish
-      ipnsName: 'YOUR_IPNS_KEY_OR_CID',
-      gateway: 'https://gateway.pinata.cloud',
-      // Use your public key from the signing step
-      publicKey: 'ed25519:YOUR_PUBLIC_KEY',
-      trusted: true,
-      official: true,
-    },
-  ],
-  // ... rest of config
-};
-```
-
-## Cost Estimate
-
-| Service | Free Tier | Paid Tier |
-|---------|-----------|-----------|
-| Pinata | 1GB storage, 100 pins | $20/mo for 100GB |
-| GCS | 5GB free | ~$0.02/GB/mo |
-| Cloud Functions | 2M invocations free | ~$0.40/million |
-| Cloud Scheduler | 3 jobs free | $0.10/job/mo |
-| **Total** | **$0** | **~$20/mo** |
-
-## Troubleshooting
-
-### IPNS Resolution Fails
-- Ensure the CID is pinned on Pinata
-- Try different gateways (ipfs.io, cloudflare-ipfs.com)
-- IPNS can take 5-10 minutes to propagate
-
-### Signature Verification Fails
-- Ensure the public key in config matches the signing key
-- Check that the registry wasn't modified after signing
-
-### Cloud Function Errors
-- Check Cloud Logging for detailed errors
-- Verify service account has correct permissions
-- Test secrets access manually
-
-## References
-
-- [Pinata Docs](https://docs.pinata.cloud/)
-- [Google Cloud Functions](https://cloud.google.com/functions/docs)
-- [IPFS Gateway Spec](https://docs.ipfs.tech/concepts/ipfs-gateway/)
-- [Ed25519 Signatures](https://ed25519.cr.yp.to/)