@sage-protocol/cli 0.2.9 → 0.3.2

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

package/dist/cli/services/mcp/manifest-downloader.js

@@ -1,18 +1,20 @@
 const DEFAULT_GATEWAYS = [
+  'https://cloudflare-ipfs.com',
+  'https://gateway.pinata.cloud',
+  'https://ipfs.io',
   'https://dweb.link',
   'https://nftstorage.link',
-  'https://ipfs.io',
 ];
 
 function buildGatewayList({ cid, preferredGateway }) {
   const trimmedPreferred = preferredGateway ? preferredGateway.replace(/\/$/, '') : '';
   const candidates = [];
   if (trimmedPreferred) {
-    candidates.push(`${trimmedPreferred}/ipfs/${cid}`);
+    candidates.push(`${trimmedPreferred} /ipfs/${cid} `);
   }
   for (const base of DEFAULT_GATEWAYS) {
     const formattedBase = base.replace(/\/$/, '');
-    const url = `${formattedBase}/ipfs/${cid}`;
+    const url = `${formattedBase} /ipfs/${cid} `;
     if (!candidates.includes(url)) {
       candidates.push(url);
     }

package/dist/cli/services/mcp/manifest-fetcher.js

@@ -22,6 +22,20 @@ function createManifestFetcher({
   }
 
   async function downloadManifest(manifestCid) {
+    // Check if this is a local manifest (stored in ~/.sage/libraries/)
+    if (manifestCid && manifestCid.startsWith('local_')) {
+      try {
+        const { loadPinnedManifest } = require('../library/local-cache');
+        const cliConfig = require('../../utils/cli-config');
+        const { manifest } = loadPinnedManifest({ config: cliConfig, cid: manifestCid });
+        return manifest;
+      } catch (error) {
+        logger?.debug?.('local_manifest_load_failed', { cid: manifestCid, err: error.message || String(error) });
+        throw new Error(`Failed to load local manifest ${manifestCid}: ${error.message}`);
+      }
+    }
+
+    // For IPFS CIDs, try gateways
     const gateways = buildGatewayList(manifestCid);
     let lastError;
     for (const gateway of gateways) {
@@ -84,7 +98,9 @@ function createManifestFetcher({
         let content = '';
         if (includeContent && prompt?.cid && ipfsManager) {
           try {
-            content = await ipfsManager.downloadPrompt(prompt.cid);
+            // Download prompt JSON directly from IPFS and extract content
+            const data = await ipfsManager.downloadJson(prompt.cid);
+            content = data?.content || data?.prompt?.content || JSON.stringify(data);
           } catch (error) {
             logger?.debug?.('prompt_content_fetch_failed', { cid: prompt.cid, err: error.message || String(error) });
           }

package/dist/cli/services/mcp/manifest-workflows.js

@@ -18,6 +18,63 @@ function defaultAddFormats(ajv) {
   }
 }
 
+// Lightweight embedded fallback schema for environments where docs/schemas are not present
+const FALLBACK_MANIFEST_SCHEMA = {
+  $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' },
+    },
+  },
+};
+
 function createManifestWorkflows({
   provider,
   addressResolution,
@@ -27,8 +84,11 @@ function createManifestWorkflows({
   logger = console,
   processEnv = process.env,
   schemaPaths = [
+    // Package-relative path (for published CLI)
+    path.join(__dirname, '..', '..', 'schemas', 'manifest.schema.json'),
+    // Monorepo docs locations (dev)
     path.join(process.cwd(), 'docs', 'schemas', 'manifest.schema.json'),
-    path.join(__dirname, '..', '..', '..', 'docs', 'schemas', 'manifest.schema.json'),
+    path.join(__dirname, '..', '..', '..', '..', 'docs', 'schemas', 'manifest.schema.json'),
   ],
   fsModule = fs,
   pathModule = path,
@@ -53,7 +113,9 @@ function createManifestWorkflows({
         logger?.warn?.('manifest_schema_load_failed', { path: schemaPath, err: error.message || String(error) });
       }
     }
-    throw new Error('Manifest schema not found (docs/schemas/manifest.schema.json)');
+    // Fallback: embedded schema so MCP/CLI can still validate outside the monorepo.
+    logger?.warn?.('manifest_schema_fallback_used');
+    return FALLBACK_MANIFEST_SCHEMA;
   }
 
   async function validateManifest({ manifest }) {
@@ -67,8 +129,23 @@ function createManifestWorkflows({
       if (ok) {
         return { content: [{ type: 'text', text: '✅ Manifest is valid' }] };
       }
-      const lines = (validate.errors || []).map((err) => `- ${err.instancePath || '/'} ${err.message || 'invalid'}`).join('\n');
-      return { content: [{ type: 'text', text: `❌ Manifest validation failed:\n${lines}` }] };
+      const errors = validate.errors || [];
+      const lines = errors.map((err) => `- ${err.instancePath || '/'} ${err.message || 'invalid'}`).join('\n');
+
+      // Add targeted hints for common pitfalls (version, library)
+      const hasVersionError = errors.some((e) => (e.instancePath === '/version'));
+      const hasLibraryError = errors.some((e) => e.instancePath === '' && /library/.test(e.message || ''));
+
+      let hint = '';
+      if (hasVersionError) {
+        hint += '\n\nHint: use "version": 2 or "version": "2.0.0" for v2 manifests.';
+      }
+      if (hasLibraryError || !manifest?.library) {
+        hint += '\nHint: manifest must include a top-level "library" object, e.g.:\n' +
+          '{\n  "version": 2,\n  "library": { "name": "My Library", "description": "..." },\n  "prompts": []\n}';
+      }
+
+      return { content: [{ type: 'text', text: `❌ Manifest validation failed:\n${lines}${hint}` }] };
     } catch (error) {
       return { content: [{ type: 'text', text: `Error validating manifest: ${error.message}` }] };
     }
@@ -81,7 +158,15 @@ function createManifestWorkflows({
       const cid = await ipfs.uploadJson(manifest, name);
       return { content: [{ type: 'text', text: `✅ Manifest uploaded to IPFS\nCID: ${cid}` }], cid };
     } catch (error) {
-      return { content: [{ type: 'text', text: `Error uploading manifest: ${error.message}` }] };
+      const msg = error?.message || String(error);
+      let help = msg;
+      if (/All IPFS providers failed/i.test(msg)) {
+        help = 'All IPFS providers failed. Ensure your IPFS settings are configured.\n' +
+          '- For worker: set SAGE_IPFS_WORKER_URL (and SAGE_IPFS_UPLOAD_TOKEN if required)\n' +
+          '- For Pinata: set PINATA_JWT or PINATA_API_KEY/SECRET\n' +
+          '- Or switch provider via SAGE_IPFS_PROVIDER=pinata|worker';
+      }
+      return { content: [{ type: 'text', text: `Error uploading manifest: ${help}` }] };
     }
   }
 
@@ -117,7 +202,7 @@ function createManifestWorkflows({
       let mode = { operator: false, governance: 'Unknown' };
       try {
         mode = await detectGovMode({ provider, subdao, governor, timelock });
-      } catch (_) {}
+      } catch (_) { }
 
       const payload = { targets, values, calldatas, description: desc };
       const hints = [];
@@ -202,7 +287,7 @@ function createManifestWorkflows({
     }
   }
 
-  async function publishManifestFlow({ manifest, subdao = '', description = '' }) {
+  async function publishManifestFlow({ manifest, subdao = '', description = '', dry_run = false }) {
     try {
       const validation = await validateManifest({ manifest });
       const firstText = validation.content?.[0]?.text || '';
@@ -210,22 +295,49 @@ function createManifestWorkflows({
         return { content: [{ type: 'text', text: `❌ Validation failed. Fix issues first.\n\n${firstText}` }] };
       }
 
-      const pushed = await pushManifestToIpfs({ manifest });
-      const match = /CID:\s*([^\s]+)/.exec(pushed.content?.[0]?.text || '');
-      const cid = match?.[1] || pushed.cid;
-      if (!cid) {
-        return { content: [{ type: 'text', text: '❌ Failed to upload manifest (no CID)' }] };
+      let cid = null;
+      let pushText = '';
+      if (!dry_run) {
+        const pushed = await pushManifestToIpfs({ manifest });
+        pushText = pushed.content?.[0]?.text || '';
+        const match = /CID:\s*([^\s]+)/.exec(pushText);
+        cid = match?.[1] || pushed.cid;
+        if (!cid) {
+          return { content: [{ type: 'text', text: '❌ Failed to upload manifest (no CID)' }] };
+        }
       }
 
       const proposed = await proposeManifest({
-        cid,
+        cid: cid || '(dry-run)',
         subdao,
         description,
         promptCount: Array.isArray(manifest?.prompts) ? manifest.prompts.length : 0,
         manifest,
       });
-      const text = `✅ Manifest valid\nCID: ${cid}\n\n${proposed.content?.[0]?.text || ''}`;
-      return { content: [{ type: 'text', text }], cid, payload: proposed.payload };
+      const textLines = [];
+      textLines.push('✅ Manifest valid');
+      if (cid) textLines.push(`CID: ${cid}`);
+      if (dry_run) {
+        textLines.push('');
+        textLines.push('Dry run: no IPFS upload performed. Use this payload and CLI hints to publish when ready.');
+        textLines.push('');
+        textLines.push('When you are ready to publish from your terminal:');
+        textLines.push('1) Save this manifest JSON to a file (e.g. ./manifest.json).');
+        if (subdao) {
+          textLines.push(`2) Upload & schedule/propose via CLI:`);
+          textLines.push(`   sage library push ./manifest.json --subdao ${subdao} --pin --wait`);
+        } else {
+          textLines.push('2) Upload & schedule/propose via CLI (replace SUBDAO):');
+          textLines.push('   sage library push ./manifest.json --subdao 0xYourSubDAO --pin --wait');
+        }
+      } else if (pushText) {
+        textLines.push('');
+        textLines.push(pushText);
+      }
+      textLines.push('');
+      textLines.push(proposed.content?.[0]?.text || '');
+
+      return { content: [{ type: 'text', text: textLines.join('\n') }], cid, payload: proposed.payload };
     } catch (error) {
       return { content: [{ type: 'text', text: `Error publishing manifest flow: ${error.message}` }] };
     }