@sage-protocol/cli 0.3.0 → 0.3.3

package/dist/cli/schemas/manifest.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sage-protocol.org/schemas/manifest.schema.json",
+  "title": "Sage Library Manifest",
+  "type": "object",
+  "required": ["version", "library", "prompts"],
+  "additionalProperties": true,
+  "properties": {
+    "version": {
+      "anyOf": [
+        { "type": "string", "const": "2.0.0" },
+        { "type": "integer", "const": 2 }
+      ]
+    },
+    "library": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "previous": { "type": "string" }
+      }
+    },
+    "prompts": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "required": ["key"],
+        "additionalProperties": true,
+        "properties": {
+          "key": { "type": "string", "minLength": 1 },
+          "cid": { "type": "string", "minLength": 46 },
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "tags": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "files": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "minItems": 0
+          }
+        }
+      }
+    },
+    "compositions": { "type": "object" },
+    "dependencies": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+} 

package/dist/cli/services/doctor/fixers.js

@@ -0,0 +1,134 @@
+const inquirer = (require('inquirer').default || require('inquirer'));
+const config = require('../../config');
+const { execSync } = require('child_process');
+const { ethers } = require('ethers');
+
+async function fixRpcUrl(context = {}) {
+    console.log('\n🔧 Fixing RPC URL...');
+    const { diagnoseRpcIssues, checkRpcHealth } = require('../../utils/rpc-health');
+    const envCandidates = [
+        process.env.RPC_URL,
+        process.env.BASE_SEPOLIA_RPC,
+        'https://base-sepolia.publicnode.com',
+        'https://sepolia.base.org',
+        'https://base-sepolia.gateway.tenderly.co'
+    ].filter(Boolean);
+
+    let recommended = null;
+    try {
+        const results = await diagnoseRpcIssues({ rpcUrls: envCandidates, timeout: 8000 });
+        const healthy = results.filter(r => r.healthy).sort((a,b)=> (a.latency ?? 1e9) - (b.latency ?? 1e9));
+        if (healthy.length) recommended = healthy[0].url;
+    } catch (_) { /* best-effort */ }
+
+    let url = recommended || envCandidates[0] || 'https://base-sepolia.publicnode.com';
+    if (!context.auto) {
+        const { url: picked } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'url',
+                message: 'Select a new RPC URL:',
+                choices: [url, ...envCandidates.filter(u => u !== url)]
+            }
+        ]);
+        url = picked;
+    }
+
+    // Fetch chainId and persist
+    let chainId = null;
+    try {
+        const provider = new ethers.JsonRpcProvider(url);
+        const net = await provider.getNetwork();
+        chainId = Number(net.chainId);
+    } catch (e) {
+        console.log('⚠️  Failed to detect chainId:', e.message);
+    }
+
+    const profile = config.readProfiles().activeProfile || 'default';
+    const current = config.readProfiles().profiles[profile] || {};
+    config.writeProfileSettings({ ...current, rpcUrl: url, chainId: chainId ?? current.chainId }, profile);
+    console.log(`✅ RPC URL updated to ${url} for profile '${profile}'${chainId ? ` (chainId=${chainId})` : ''}`);
+}
+
+async function fixIpfsKeys(context = {}) {
+    console.log('\n🔧 Fixing IPFS Configuration...');
+    let provider = 'pinata';
+    if (!context.auto) {
+        const ans = await inquirer.prompt([
+            { type: 'list', name: 'provider', message: 'Select IPFS Provider:', choices: ['pinata'] }
+        ]);
+        provider = ans.provider;
+    }
+
+    if (provider === 'pinata') {
+        let answers = { apiKey: process.env.PINATA_API_KEY, secret: process.env.PINATA_SECRET_API_KEY, jwt: process.env.PINATA_JWT };
+        if (!context.auto) {
+            answers = await inquirer.prompt([
+                { type: 'input', name: 'apiKey', message: 'Pinata API Key:', default: answers.apiKey || '' },
+                { type: 'password', name: 'secret', message: 'Pinata Secret Key:', default: answers.secret || '' },
+                { type: 'password', name: 'jwt', message: 'Pinata JWT (optional):', default: answers.jwt || '' }
+            ]);
+        }
+
+        if (answers.apiKey && answers.secret) {
+            // Write to profile IPFS config
+            config.writeIpfsConfig({
+                provider: 'pinata',
+                pinataApiKey: answers.apiKey,
+                pinataSecret: answers.secret,
+                pinataJwt: answers.jwt || undefined
+            });
+            console.log('✅ Saved Pinata configuration to profile (.sage/config.json)');
+
+            if (!context.auto) {
+                // Optional .env convenience (insecure for prod)
+                const { addToEnv } = await inquirer.prompt([{ type: 'confirm', name: 'addToEnv', message: 'Also add to .env for dev convenience? (insecure)', default: false }]);
+                if (addToEnv) {
+                    const fs = require('fs');
+                    const path = require('path');
+                    const envPath = path.join(process.cwd(), '.env');
+                    let envContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
+                    if (!envContent.includes('PINATA_API_KEY=')) envContent += `\nPINATA_API_KEY=${answers.apiKey}`;
+                    if (!envContent.includes('PINATA_SECRET_API_KEY=')) envContent += `\nPINATA_SECRET_API_KEY=${answers.secret}`;
+                    if (answers.jwt && !envContent.includes('PINATA_JWT=')) envContent += `\nPINATA_JWT=${answers.jwt}`;
+                    fs.writeFileSync(envPath, envContent);
+                    try { require('dotenv').config(); } catch(_){}
+                    console.log('✅ Added Pinata keys to .env');
+                }
+            }
+        }
+    }
+}
+
+async function fixAllowance(tokenAddress, spenderAddress, spenderName = 'Spender', context = {}) {
+    console.log(`\n🔧 Fixing Allowance for ${spenderName}...`);
+    let proceed = !!context.auto;
+    if (!proceed) {
+        const ans = await inquirer.prompt([
+            { type: 'confirm', name: 'confirm', message: `Approve ${spenderName} to spend SXXX?`, default: true }
+        ]);
+        proceed = !!ans.confirm;
+    }
+
+    if (!proceed) return;
+
+    const walletArgs = config.getCastWalletArgs();
+    const rpcUrl = process.env.RPC_URL || 'https://base-sepolia.publicnode.com';
+    
+    // Max uint256
+    const amount = '115792089237316195423570985008687907853269984665640564039457584007913129639935';
+    
+    try {
+        console.log('⏳ Submitting approval...');
+        execSync(`cast send ${tokenAddress} "approve(address,uint256)" ${spenderAddress} ${amount} --rpc-url ${rpcUrl} ${walletArgs} --legacy`, { stdio: 'inherit' });
+        console.log('✅ Approved.');
+    } catch (e) {
+        console.error('❌ Approval failed:', e.message);
+    }
+}
+
+module.exports = {
+    fixRpcUrl,
+    fixIpfsKeys,
+    fixAllowance
+};

package/dist/cli/services/mcp/bulk-operations.js

@@ -0,0 +1,272 @@
+const fs = require('fs');
+const path = require('path');
+const { LibraryManager } = require('../../library-manager');
+
+/**
+ * Bulk metadata helpers for pinned library manifests.
+ *
+ * These helpers intentionally mirror the semantics of quick-start flows:
+ * - Operate on pinned manifests in ~/.sage/libraries (or project .sage/libraries).
+ * - Reuse LibraryManager for directory resolution & manifest loading.
+ * - Back up prompt files when content changes.
+ */
+function createBulkOperations({
+  libraryManager = new LibraryManager(),
+  fsModule = fs,
+  pathModule = path,
+  logger = console,
+} = {}) {
+  function resolvePinnedLibrary(libraryId) {
+    const all = libraryManager.listPinned() || [];
+    const id = String(libraryId || '').trim();
+    if (!id) {
+      throw new Error('library parameter is required');
+    }
+
+    // Exact CID match first
+    const byCid = all.find((row) => row.cid === id);
+    if (byCid) {
+      const { manifest, path: manifestPath } = libraryManager.loadPinned(byCid.cid);
+      return { row: byCid, manifest, manifestPath };
+    }
+
+    const lower = id.toLowerCase();
+    const matches = all
+      .map((row) => {
+        try {
+          const { manifest, path: manifestPath } = libraryManager.loadPinned(row.cid);
+          const libName = String(manifest?.library?.name || row.name || '').toLowerCase();
+          return { row, manifest, manifestPath, libName };
+        } catch (e) {
+          logger?.warn?.('bulk_ops_manifest_load_failed', { cid: row.cid, err: e.message || String(e) });
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .filter((entry) => entry.libName === lower);
+
+    if (matches.length === 0) {
+      throw new Error(`No pinned library found matching "${libraryId}". Try using the CID from ~/.sage/libraries/*.json.`);
+    }
+    if (matches.length > 1) {
+      const cids = matches.map((m) => `${m.row.cid} (${m.manifest?.library?.name || m.row.name || 'unnamed'})`);
+      throw new Error(
+        `Ambiguous library match for "${libraryId}". Candidates:\n- ${cids.join('\n- ')}\nPass an explicit CID to disambiguate.`,
+      );
+    }
+
+    return matches[0];
+  }
+
+  function normalizeTagsInput(tags) {
+    if (tags === undefined) return undefined;
+    if (Array.isArray(tags)) {
+      return tags.map((t) => String(t).trim()).filter(Boolean);
+    }
+    // Single string: split on commas/semicolons
+    const str = String(tags);
+    return str
+      .split(/[,;]/)
+      .map((t) => t.trim())
+      .filter(Boolean);
+  }
+
+  function uniq(arr) {
+    const out = [];
+    const seen = new Set();
+    for (const v of arr) {
+      if (!seen.has(v)) {
+        seen.add(v);
+        out.push(v);
+      }
+    }
+    return out;
+  }
+
+  async function updateLibraryMetadata({
+    library,
+    name,
+    description,
+    tags,
+    apply_to_prompts = false,
+    merge_mode = 'merge',
+  } = {}) {
+    const { row, manifest, manifestPath } = resolvePinnedLibrary(library);
+    const updatedFields = [];
+
+    if (!manifest.library || typeof manifest.library !== 'object') {
+      manifest.library = {};
+    }
+
+    if (typeof name === 'string' && name.trim().length) {
+      manifest.library.name = name;
+      updatedFields.push('name');
+    }
+    if (typeof description === 'string') {
+      manifest.library.description = description;
+      updatedFields.push('description');
+    }
+
+    const normalizedTags = normalizeTagsInput(tags);
+    if (normalizedTags) {
+      manifest.library.tags = normalizedTags;
+      updatedFields.push('tags');
+    }
+
+    let updatedPromptCount = 0;
+    if (apply_to_prompts && normalizedTags && Array.isArray(manifest.prompts)) {
+      const mode = merge_mode === 'replace' ? 'replace' : 'merge';
+      for (const prompt of manifest.prompts) {
+        if (!prompt || typeof prompt !== 'object') continue;
+        const existing = Array.isArray(prompt.tags)
+          ? prompt.tags.map((t) => String(t).trim()).filter(Boolean)
+          : [];
+        if (mode === 'replace') {
+          prompt.tags = normalizedTags.slice();
+        } else {
+          prompt.tags = uniq([...existing, ...normalizedTags]);
+        }
+        updatedPromptCount += 1;
+      }
+    }
+
+    fsModule.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    return {
+      success: true,
+      library: manifest.library?.name || row.name || library,
+      cid: row.cid,
+      updatedLibraryFields: updatedFields,
+      updatedPromptCount,
+      manifestPath,
+    };
+  }
+
+  async function bulkUpdatePrompts({ library, updates, dry_run = false } = {}) {
+    if (!Array.isArray(updates) || updates.length === 0) {
+      throw new Error('updates must be a non-empty array');
+    }
+    const { row, manifest, manifestPath } = resolvePinnedLibrary(library);
+    const prompts = Array.isArray(manifest.prompts) ? manifest.prompts : [];
+    const byKey = new Map();
+    prompts.forEach((p) => {
+      if (p && typeof p.key === 'string') {
+        byKey.set(p.key, p);
+      }
+    });
+
+    const missingKeys = [];
+    const wouldUpdatePrompts = [];
+    const backedUpFiles = [];
+    const changedKeys = new Set();
+
+    const libDir = libraryManager.ensureLibrariesDir();
+
+    for (const update of updates) {
+      const key = String(update.key || '').trim();
+      if (!key) continue;
+      const prompt = byKey.get(key);
+      if (!prompt) {
+        missingKeys.push(key);
+        continue;
+      }
+
+      const changes = {};
+      let changedThisPrompt = false;
+
+      // Content update
+      if (typeof update.content === 'string') {
+        const files = Array.isArray(prompt.files) ? prompt.files : [];
+        let targetPath;
+        if (files.length > 0) {
+          const relativePath = files[0];
+          targetPath = pathModule.isAbsolute(relativePath)
+            ? relativePath
+            : pathModule.join(libDir, relativePath);
+        } else {
+          const promptsDir = pathModule.join(libDir, 'prompts');
+          if (!fsModule.existsSync(promptsDir)) {
+            fsModule.mkdirSync(promptsDir, { recursive: true });
+          }
+          const fileName = `${row.cid}_${key}.md`;
+          targetPath = pathModule.join(promptsDir, fileName);
+          prompt.files = [`prompts/${fileName}`];
+        }
+
+        const beforeContent = !dry_run && fsModule.existsSync(targetPath)
+          ? fsModule.readFileSync(targetPath, 'utf8')
+          : null;
+
+        if (dry_run) {
+          changes.content = { from: beforeContent === null ? '(new file)' : '(existing file)', to: '(would change)' };
+          changedThisPrompt = true;
+        } else {
+          if (beforeContent !== null) {
+            const backupPath = `${targetPath}.v${Date.now()}.bak`;
+            fsModule.copyFileSync(targetPath, backupPath);
+            backedUpFiles.push(backupPath);
+          }
+          fsModule.writeFileSync(targetPath, update.content, 'utf8');
+          changes.content = { from: '(previous content)', to: '(updated content)' };
+          changedThisPrompt = true;
+        }
+      }
+
+      // Name / description
+      if (typeof update.name === 'string') {
+        changes.name = { from: prompt.name || '', to: update.name };
+        if (!dry_run) {
+          prompt.name = update.name;
+          changedThisPrompt = true;
+        }
+      }
+      if (typeof update.description === 'string') {
+        changes.description = { from: prompt.description || '', to: update.description };
+        if (!dry_run) {
+          prompt.description = update.description;
+          changedThisPrompt = true;
+        }
+      }
+
+      if (update.tags !== undefined) {
+        const normalizedTags = normalizeTagsInput(update.tags) || [];
+        const beforeTags = Array.isArray(prompt.tags) ? prompt.tags.slice() : [];
+        changes.tags = { from: beforeTags, to: normalizedTags };
+        if (!dry_run) {
+          prompt.tags = normalizedTags;
+          changedThisPrompt = true;
+        }
+      }
+
+      if (Object.keys(changes).length > 0) {
+        wouldUpdatePrompts.push({ key, changes });
+        changedKeys.add(key);
+      }
+    }
+
+    if (!dry_run) {
+      fsModule.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    }
+
+    return {
+      success: true,
+      library: manifest.library?.name || row.name || library,
+      cid: row.cid,
+      dryRun: !!dry_run,
+      updatedCount: changedKeys.size,
+      missingKeys,
+      backedUpFiles: dry_run ? [] : backedUpFiles,
+      wouldUpdatePrompts,
+      manifestPath,
+    };
+  }
+
+  return {
+    updateLibraryMetadata,
+    bulkUpdatePrompts,
+  };
+}
+
+module.exports = {
+  createBulkOperations,
+};

package/dist/cli/services/mcp/dependency-analyzer.js

@@ -0,0 +1,202 @@
+const fs = require('fs');
+const path = require('path');
+const { LibraryManager } = require('../../library-manager');
+
+function createDependencyAnalyzer({
+  libraryManager = new LibraryManager(),
+  fsModule = fs,
+  pathModule = path,
+  logger = console,
+} = {}) {
+  function resolvePinnedLibrary(libraryId) {
+    const all = libraryManager.listPinned() || [];
+    const id = String(libraryId || '').trim();
+    if (!id) {
+      throw new Error('library parameter is required');
+    }
+
+    const byCid = all.find((row) => row.cid === id);
+    if (byCid) {
+      const { manifest, path: manifestPath } = libraryManager.loadPinned(byCid.cid);
+      return { row: byCid, manifest, manifestPath };
+    }
+
+    const lower = id.toLowerCase();
+    const matches = all
+      .map((row) => {
+        try {
+          const { manifest, path: manifestPath } = libraryManager.loadPinned(row.cid);
+          const libName = String(manifest?.library?.name || row.name || '').toLowerCase();
+          return { row, manifest, manifestPath, libName };
+        } catch (e) {
+          logger?.warn?.('dep_analyzer_manifest_load_failed', { cid: row.cid, err: e.message || String(e) });
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .filter((entry) => entry.libName === lower);
+
+    if (matches.length === 0) {
+      throw new Error(`No pinned library found matching "${libraryId}". Try using the CID from ~/.sage/libraries/*.json.`);
+    }
+    if (matches.length > 1) {
+      const cids = matches.map((m) => `${m.row.cid} (${m.manifest?.library?.name || m.row.name || 'unnamed'})`);
+      throw new Error(
+        `Ambiguous library match for "${libraryId}". Candidates:\n- ${cids.join('\n- ')}\nPass an explicit CID to disambiguate.`,
+      );
+    }
+
+    return matches[0];
+  }
+
+  function extractVariables(content) {
+    const text = String(content || '');
+    const pattern = /\$\{([A-Za-z0-9_]+)\}/g;
+    const vars = [];
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      if (!vars.includes(match[1])) {
+        vars.push(match[1]);
+      }
+    }
+    return vars;
+  }
+
+  function groupInconsistencies(variableUsage) {
+    const names = Object.keys(variableUsage || {});
+    const lowerMap = new Map();
+    for (const name of names) {
+      const base = name.toLowerCase();
+      if (!lowerMap.has(base)) lowerMap.set(base, []);
+      lowerMap.get(base).push(name);
+    }
+
+    const groups = [];
+    for (const [base, variants] of lowerMap.entries()) {
+      if (variants.length <= 1) continue;
+      groups.push({
+        base,
+        variants,
+        totalPrompts: variants.reduce((acc, v) => acc + (variableUsage[v]?.count || 0), 0),
+      });
+    }
+    return groups;
+  }
+
+  async function analyzeDependencies({ library, analysis_type = 'variables' } = {}) {
+    const { row, manifest, manifestPath } = resolvePinnedLibrary(library);
+    const prompts = Array.isArray(manifest.prompts) ? manifest.prompts : [];
+    const libDir = pathModule.dirname(manifestPath);
+
+    const perPrompt = [];
+    const variableUsage = {};
+
+    for (const prompt of prompts) {
+      if (!prompt || typeof prompt !== 'object') continue;
+      const key = prompt.key || '(no-key)';
+      let content = '';
+
+      if (Array.isArray(prompt.files) && prompt.files.length) {
+        const firstFile = prompt.files[0];
+        const candidatePath = pathModule.isAbsolute(firstFile)
+          ? firstFile
+          : pathModule.join(libDir, firstFile);
+        try {
+          content = fsModule.readFileSync(candidatePath, 'utf8');
+        } catch (error) {
+          logger?.debug?.('dep_analyzer_read_failed', { file: candidatePath, err: error.message || String(error) });
+        }
+      }
+
+      const vars = extractVariables(content);
+      perPrompt.push({
+        key,
+        name: prompt.name || key,
+        variables: vars,
+      });
+
+      for (const v of vars) {
+        if (!variableUsage[v]) {
+          variableUsage[v] = { count: 0, prompts: [] };
+        }
+        variableUsage[v].count += 1;
+        variableUsage[v].prompts.push(key);
+      }
+    }
+
+    const sharedVariables = Object.keys(variableUsage).filter((v) => variableUsage[v].count > 1);
+    const uniqueVariables = Object.keys(variableUsage).filter((v) => variableUsage[v].count === 1);
+    const inconsistencyGroups = groupInconsistencies(variableUsage);
+
+    const lines = [];
+    lines.push(`📊 Variable Usage Analysis for "${manifest.library?.name || row.name || library}"`);
+    lines.push('');
+    if (!perPrompt.length) {
+      lines.push('No prompts found in this library.');
+    } else {
+      lines.push(`Prompts analyzed: ${perPrompt.length}`);
+      lines.push(`Total distinct variables: ${Object.keys(variableUsage).length}`);
+      lines.push('');
+      if (sharedVariables.length) {
+        lines.push('Shared variables (used in multiple prompts):');
+        sharedVariables.slice(0, 10).forEach((v) => {
+          lines.push(`- ${v} (${variableUsage[v].count} prompts)`);
+        });
+        if (sharedVariables.length > 10) {
+          lines.push(`… and ${sharedVariables.length - 10} more`);
+        }
+        lines.push('');
+      } else {
+        lines.push('No shared variables detected across prompts.');
+        lines.push('');
+      }
+
+      if (inconsistencyGroups.length) {
+        lines.push('Potential naming inconsistency groups:');
+        inconsistencyGroups.slice(0, 5).forEach((g) => {
+          lines.push(`- ${g.base}: ${g.variants.join(', ')} (approx. ${g.totalPrompts} prompt usages)`);
+        });
+        if (inconsistencyGroups.length > 5) {
+          lines.push(`… and ${inconsistencyGroups.length - 5} more groups`);
+        }
+        lines.push('');
+      }
+    }
+
+    return {
+      content: [
+        { type: 'text', text: lines.join('\n') },
+        {
+          type: 'text',
+          text:
+            '```json\n' +
+            JSON.stringify(
+              {
+                library: {
+                  cid: row.cid,
+                  name: manifest.library?.name || row.name || library,
+                },
+                perPrompt,
+                variableUsage,
+                sharedVariables,
+                uniqueVariables,
+                inconsistencyGroups,
+              },
+              null,
+              2,
+            ) +
+            '\n```',
+        },
+      ],
+    };
+  }
+
+  return {
+    analyzeDependencies,
+  };
+}
+
+module.exports = {
+  createDependencyAnalyzer,
+};
+

package/dist/cli/services/mcp/library-listing.js

@@ -49,7 +49,7 @@ function createLibraryLister({
         return {
           content: [
             { type: 'text', text: formatted },
-            { type: 'json', text: JSON.stringify(data ?? {}, null, DEFAULT_INDENT) },
+            { type: 'text', text: '```json\n' + JSON.stringify(data ?? {}, null, DEFAULT_INDENT) + '\n```' },
           ],
         };
       }
@@ -64,7 +64,7 @@ function createLibraryLister({
       return {
         content: [
           { type: 'text', text: formatted },
-          { type: 'json', text: JSON.stringify(data ?? {}, null, DEFAULT_INDENT) },
+          { type: 'text', text: '```json\n' + JSON.stringify(data ?? {}, null, DEFAULT_INDENT) + '\n```' },
         ],
       };
     } catch (error) {

package/dist/cli/services/mcp/local-prompt-collector.js

@@ -96,6 +96,7 @@ function collectLocalPrompts({
       if (normalizedQuery) {
         const matchesQuery =
           promptName.toLowerCase().includes(normalizedQuery) ||
+          (prompt.key && prompt.key.toLowerCase().includes(normalizedQuery)) ||
           promptDescription.toLowerCase().includes(normalizedQuery) ||
           loweredPromptTags.some((tag) => tag.includes(normalizedQuery));
         if (!matchesQuery) continue; // eslint-disable-line no-continue