@sage-protocol/cli 0.3.0 → 0.3.2

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}` }] };
     }

package/dist/cli/services/mcp/quick-start.js

@@ -0,0 +1,287 @@
+const path = require('path');
+const fs = require('fs');
+const { LibraryManager } = require('../../library-manager');
+
+function createQuickStart({
+    libraryManager = new LibraryManager(),
+    logger = console,
+}) {
+
+    function ensureDefaultLibrary() {
+        const pinned = libraryManager.listPinned();
+        // Look for "My Library" or "default"
+        let defaultLib = pinned.find(p => p.name === 'My Library' || p.name === 'default');
+
+        if (!defaultLib) {
+            // Create "My Library"
+            const result = libraryManager.createLibrary('My Library', 'Default library for quick prompts');
+            defaultLib = { cid: result.cid, name: 'My Library' };
+        }
+        return defaultLib;
+    }
+
+    function generateKey(name) {
+        return name.toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '');
+    }
+
+    async function quickCreatePrompt({ name, content, description = '', library = '', tags } = {}) {
+        if (!name || !content) {
+            throw new Error('Name and content are required');
+        }
+
+        let targetLib;
+        if (library) {
+            const pinned = libraryManager.listPinned();
+            targetLib = pinned.find(p =>
+                p.name.toLowerCase() === library.toLowerCase() ||
+                p.cid === library
+            );
+            if (!targetLib) {
+                // If library doesn't exist, create it
+                const result = libraryManager.createLibrary(library, '');
+                targetLib = { cid: result.cid, name: library };
+            }
+        } else {
+            targetLib = ensureDefaultLibrary();
+        }
+
+        const key = generateKey(name);
+
+        // Check if key exists
+        const { manifest } = libraryManager.loadPinned(targetLib.cid);
+        if (manifest.prompts?.some(p => p.key === key)) {
+            throw new Error(`Prompt with key "${key}" already exists in library "${targetLib.name}". Use quick_iterate_prompt to update it.`);
+        }
+
+        // Add prompt
+        // We need to use the library manager's internal methods or replicate logic
+        // Since LibraryManager doesn't expose "addPrompt", we'll implement it here for now
+        // In a real refactor, we should move this to LibraryManager
+
+        const libDir = libraryManager.ensureLibrariesDir();
+        const manifestPath = path.join(libDir, `${targetLib.cid}.json`);
+
+        // Create prompt file
+        // We'll store it in a 'prompts' subdirectory next to the manifest if possible, 
+        // but for local libraries, they are flat in ~/.sage/libraries/
+        // Let's create a prompts directory inside ~/.sage/libraries/prompts/
+        const promptsDir = path.join(libDir, 'prompts');
+        if (!fs.existsSync(promptsDir)) {
+            fs.mkdirSync(promptsDir, { recursive: true });
+        }
+
+        const promptFileName = `${targetLib.cid}_${key}.md`;
+        const promptFilePath = path.join(promptsDir, promptFileName);
+        fs.writeFileSync(promptFilePath, content, 'utf8');
+
+        // Normalise tags (optional)
+        let promptTags = [];
+        if (tags !== undefined) {
+            let normalized = tags;
+            if (typeof normalized === 'string') {
+                try {
+                    const parsed = JSON.parse(normalized);
+                    if (Array.isArray(parsed)) {
+                        normalized = parsed;
+                    } else {
+                        normalized = String(normalized)
+                            .split(/[,;]/)
+                            .map((t) => t.trim())
+                            .filter(Boolean);
+                    }
+                } catch {
+                    normalized = String(normalized)
+                        .split(/[,;]/)
+                        .map((t) => t.trim())
+                        .filter(Boolean);
+                }
+            }
+            if (Array.isArray(normalized)) {
+                promptTags = normalized.map((t) => String(t));
+            }
+        }
+
+        // Update manifest
+        if (!manifest.prompts) manifest.prompts = [];
+        manifest.prompts.push({
+            key,
+            name,
+            description,
+            files: [`prompts/${promptFileName}`], // Relative path
+            tags: promptTags,
+            cid: '' // Local prompt
+        });
+
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+
+        return {
+            success: true,
+            key,
+            library: targetLib.name,
+            cid: targetLib.cid,
+            message: `Created prompt "${name}" (${key}) in "${targetLib.name}"`
+        };
+    }
+
+  async function quickIteratePrompt({ key, content, name, description, tags }) {
+        if (!key) throw new Error('Key is required');
+
+        // Find the prompt
+        const pinned = libraryManager.listPinned();
+        let found = null;
+        let foundLib = null;
+
+        for (const lib of pinned) {
+            const { manifest } = libraryManager.loadPinned(lib.cid);
+            const prompt = manifest.prompts?.find(p => p.key === key);
+            if (prompt) {
+                found = prompt;
+                const libDir = libraryManager.ensureLibrariesDir();
+                foundLib = { ...lib, manifest, manifestPath: path.join(libDir, `${lib.cid}.json`) };
+                break;
+            }
+        }
+
+        if (!found) {
+            throw new Error(`Prompt with key "${key}" not found. Use quick_create_prompt to create it.`);
+        }
+
+        // Update content if provided
+        if (content) {
+            const libDir = libraryManager.ensureLibrariesDir();
+            let promptFilePath;
+
+            if (found.files && found.files.length > 0) {
+                // Use existing file
+                const relativePath = found.files[0];
+                // Handle potential path issues
+                promptFilePath = path.join(libDir, relativePath);
+
+                // Backup existing
+                if (fs.existsSync(promptFilePath)) {
+                    const backupPath = `${promptFilePath}.v${Date.now()}.bak`;
+                    fs.copyFileSync(promptFilePath, backupPath);
+                }
+            } else {
+                // Create new file if none existed (legacy/imported)
+                const promptsDir = path.join(libDir, 'prompts');
+                if (!fs.existsSync(promptsDir)) fs.mkdirSync(promptsDir, { recursive: true });
+                const promptFileName = `${foundLib.cid}_${key}.md`;
+                promptFilePath = path.join(promptsDir, promptFileName);
+                found.files = [`prompts/${promptFileName}`];
+            }
+
+            fs.writeFileSync(promptFilePath, content, 'utf8');
+        }
+
+        // Update metadata
+        if (name) {
+            found.name = name;
+        }
+        if (typeof description === 'string') {
+            found.description = description;
+        }
+        if (tags !== undefined) {
+            let normalized = tags;
+            if (typeof normalized === 'string') {
+                // Accept JSON array string or comma/space separated list
+                try {
+                    const parsed = JSON.parse(normalized);
+                    if (Array.isArray(parsed)) {
+                        normalized = parsed;
+                    } else {
+                        normalized = String(normalized)
+                          .split(/[,;]/)
+                          .map((t) => t.trim())
+                          .filter(Boolean);
+                    }
+                } catch {
+                    normalized = String(normalized)
+                      .split(/[,;]/)
+                      .map((t) => t.trim())
+                      .filter(Boolean);
+                }
+            }
+            if (Array.isArray(normalized)) {
+                found.tags = normalized.map((t) => String(t));
+            }
+        }
+
+        // Save manifest
+        fs.writeFileSync(foundLib.manifestPath, JSON.stringify(foundLib.manifest, null, 2), 'utf8');
+
+        return {
+            success: true,
+            key,
+            library: foundLib.name,
+            message: `Updated prompt "${key}" (name: ${found.name || name || key})`
+        };
+    }
+
+    async function renamePrompt({ key, newKey, name }) {
+        if (!key) throw new Error('Key is required');
+        if (!newKey && !name) throw new Error('newKey or name required');
+
+        const pinned = libraryManager.listPinned();
+        let found = null;
+        let foundLib = null;
+
+        for (const lib of pinned) {
+            const { manifest } = libraryManager.loadPinned(lib.cid);
+            const prompt = manifest.prompts?.find((p) => p.key === key);
+            if (prompt) {
+                const libDir = libraryManager.ensureLibrariesDir();
+                found = prompt;
+                foundLib = {
+                    ...lib,
+                    manifest,
+                    manifestPath: path.join(libDir, `${lib.cid}.json`),
+                };
+                break;
+            }
+        }
+
+        if (!found || !foundLib) {
+            throw new Error(`Prompt with key "${key}" not found. Use list_prompts or search_prompts to discover keys.`);
+        }
+
+        // Handle key change with collision check
+        let finalKey = key;
+        if (newKey && newKey !== key) {
+            const exists = (foundLib.manifest.prompts || []).some(
+                (p) => p !== found && p.key === newKey,
+            );
+            if (exists) {
+                throw new Error(
+                    `Prompt with key "${newKey}" already exists in library "${foundLib.name}". Choose a different key.`,
+                );
+            }
+            found.key = newKey;
+            finalKey = newKey;
+        }
+
+        if (name) {
+            found.name = name;
+        }
+
+        fs.writeFileSync(foundLib.manifestPath, JSON.stringify(foundLib.manifest, null, 2));
+
+        return {
+            success: true,
+            oldKey: key,
+            key: finalKey,
+            library: foundLib.name,
+            message: `Renamed prompt "${key}" to "${finalKey}" (display name: ${found.name || finalKey})`,
+        };
+    }
+
+    return {
+        quickCreatePrompt,
+        quickIteratePrompt,
+        renamePrompt,
+    };
+}
+
+module.exports = { createQuickStart };

package/dist/cli/services/mcp/stdio-runner.js

@@ -35,12 +35,37 @@ function createStdIoRunner(baseOptions = {}) {
       terminal: false,
     });
 
+    let outputClosed = false;
+    if (output && typeof output.on === 'function') {
+      output.on('error', (err) => {
+        if (err && err.code === 'EPIPE') {
+          // Client closed the pipe; mark closed and let the process exit cleanly.
+          outputClosed = true;
+          try { rl.close(); } catch (_) {}
+        } else if (debugEnabled) {
+          errorWriter(`stdout error: ${err.message || String(err)}`);
+        }
+      });
+    }
+
     const writeJson = (payload) => {
-      const text = typeof payload === 'string' ? payload : JSON.stringify(payload);
-      if (typeof output?.write === 'function') {
-        output.write(`${text}\n`);
-      } else {
-        console.log(text); // eslint-disable-line no-console
+      if (outputClosed) return;
+      try {
+        const text = typeof payload === 'string' ? payload : JSON.stringify(payload);
+        if (typeof output?.write === 'function') {
+          output.write(`${text}\n`);
+        } else {
+          console.log(text); // eslint-disable-line no-console
+        }
+      } catch (err) {
+        if (err && err.code === 'EPIPE') {
+          outputClosed = true;
+          try { rl.close(); } catch (_) {}
+          return;
+        }
+        if (debugEnabled) {
+          errorWriter(`writeJson error: ${err.message || String(err)}`);
+        }
       }
     };