@sage-protocol/cli 0.2.9 → 0.3.2

package/dist/cli/commands/config.js

@@ -92,6 +92,34 @@ function register(program) {
               }
             })
         )
+        .addCommand(
+          new Command('set-github')
+            .description('Persist GitHub token for private repository access (stored in keychain by default)')
+            .option('--token <value>', 'GitHub token (classic or fine-grained)')
+            .option('--profile <name>', 'Profile name to update (default: active)')
+            .option('--global', 'Persist in XDG config (~/.config/sage/config.json)', false)
+            .option('--allow-plain-secret', 'Store plaintext in config instead of keychain (not recommended)', false)
+            .action(async (opts) => {
+              try {
+                if (!opts.token) throw new Error('Provide --token');
+                const payload = {};
+                if (opts.allowPlainSecret) {
+                  payload.githubToken = opts.token;
+                } else {
+                  const secrets = require('../services/secrets');
+                  const profile = opts.profile;
+                  await secrets.set('github.token', opts.token, { profile }).catch(() => {});
+                  payload.githubTokenRef = 'github.token';
+                }
+                config.writeGitConfig(payload, { global: !!opts.global, profile: opts.profile });
+                console.log(`✅ Saved GitHub token to ${opts.profile || 'active'} profile${opts.global ? ' (global)' : ''}`);
+                console.log('Tip: CLI also respects GITHUB_TOKEN/GH_TOKEN environment variables at runtime.');
+              } catch (error) {
+                console.error('❌ Failed to save GitHub token:', error.message);
+                process.exit(1);
+              }
+            })
+        )
     )
     .addCommand(
       new Command('governance-helper')

package/dist/cli/commands/doctor.js

@@ -32,6 +32,9 @@ async function checkArtifacts(roots) {
 async function runDoctor(opts = {}) {
     const out = [];
     const warn = [];
+    const diagnostics = [];
+    const { fixRpcUrl, fixIpfsKeys, fixAllowance } = require('../services/doctor/fixers');
+
   const useSpinner = opts.disableSpinner !== true;
   const runWithProgress = async (label, task) => {
     if (!useSpinner) return task();
@@ -55,7 +58,7 @@ async function runDoctor(opts = {}) {
     warn.push('Test mode: diagnostics skipped');
     console.log('Warnings:');
     warn.forEach((w) => console.log(`- ${w}`));
-    return;
+    return { diagnostics: [] };
   }
 
   // 1) Cast availability
@@ -64,7 +67,14 @@ async function runDoctor(opts = {}) {
   out.push(`${hasCast ? '✅' : '❌'} Foundry (cast)`);
 
   // 2) RPC reachability + chainId (env vs profile)
-  const rpcUrl = process.env.RPC_URL || 'https://sepolia.base.org';
+  // Prefer env RPC over profile for testing/debugging
+  let profileRpc = null;
+  try {
+    const prof = config.readProfiles();
+    const ap = prof.activeProfile || 'default';
+    profileRpc = prof?.profiles?.[ap]?.rpcUrl || null;
+  } catch (_) {}
+  const rpcUrl = process.env.RPC_URL || profileRpc || 'https://sepolia.base.org';
   const expectedChainId = Number(process.env.CHAIN_ID || 84532);
   
   // Check RPC health
@@ -74,15 +84,19 @@ async function runDoctor(opts = {}) {
     out.push(`${c.green('✅')} RPC healthy (${rpcHealth.latency}ms)`);
   } else {
     out.push(`${c.red('❌')} RPC unhealthy: ${rpcHealth.errors.join(', ')}`);
+    diagnostics.push({
+        level: 'error',
+        code: 'RPC_UNHEALTHY',
+        message: `RPC endpoint is unhealthy: ${rpcHealth.errors.join(', ')}`,
+        fix: fixRpcUrl
+    });
   }
   rpcHealth.warnings.forEach(w => warn.push(`${c.yellow('⚠️')} RPC: ${w}`));
-  let profileRpc = null;
   let profileChainId = null;
   try {
     const prof = config.readProfiles();
     const ap = prof.activeProfile || 'default';
     const p = prof?.profiles?.[ap] || {};
-    profileRpc = p.rpcUrl || null;
     profileChainId = p.chainId ? Number(p.chainId) : null;
   } catch (_) {}
   let provider, network;
@@ -103,6 +117,15 @@ async function runDoctor(opts = {}) {
   } catch (e) {
     out.push(`❌ RPC unreachable: ${rpcUrl}`);
     warn.push(`RPC error: ${e.message}`);
+    // Duplicate check but safe
+    if (!diagnostics.find(d => d.code === 'RPC_UNHEALTHY')) {
+        diagnostics.push({
+            level: 'error',
+            code: 'RPC_UNREACHABLE',
+            message: `RPC unreachable: ${e.message}`,
+            fix: fixRpcUrl
+        });
+    }
   }
 
   // 2b) Subgraph status (URL + last indexed block, with lag vs RPC)
@@ -308,7 +331,15 @@ async function runDoctor(opts = {}) {
           const tok = new ethers.Contract(sxxxAddr, ERC20, provider);
           const allowance = await tok.allowance(proposer, governorAddr);
           out.push(`💳 SXXX allowance to Governor: ${ethers.formatEther(allowance)} SXXX`);
-          if (allowance === 0n) warn.push('SXXX allowance is 0. Approve before proposing library updates.');
+          if (allowance === 0n) {
+              warn.push('SXXX allowance is 0. Approve before proposing library updates.');
+              diagnostics.push({
+                  level: 'warn',
+                  code: 'ALLOWANCE_ZERO',
+                  message: 'SXXX allowance to Governor is 0',
+                  fix: () => fixAllowance(sxxxAddr, governorAddr, 'Governor')
+              });
+          }
         }
         if (sxxxAddr) {
           const BurnChk = ['function authorizedBurners(address) view returns (bool)'];
@@ -372,7 +403,7 @@ async function runDoctor(opts = {}) {
 
   // 7) LibraryRegistry role diagnostics (optional)
   try {
-    if (process.argv.includes('--registry')) {
+    if (opts.registry) {
       const { resolveRegistryAddress } = require('../utils/address-resolution');
       const { registry: regAddr } = resolveRegistryAddress();
       const facAddr = process.env.SUBDAO_FACTORY_ADDRESS;
@@ -600,6 +631,26 @@ async function runDoctor(opts = {}) {
     }
   } catch (e) { warn.push('SimpleKeyStore checks failed: ' + e.message); }
 
+  // 12b) IPFS configuration (Pinata keys)
+  try {
+    const ipfsCfg = config.readIpfsConfig ? config.readIpfsConfig() : {};
+    if (!ipfsCfg.provider) {
+      warn.push('IPFS provider not configured');
+      diagnostics.push({ level: 'warn', code: 'IPFS_KEYS_MISSING', message: 'IPFS not configured', fix: fixIpfsKeys });
+    } else if (String(ipfsCfg.provider).toLowerCase() === 'pinata') {
+      const hasJwt = !!ipfsCfg.pinataJwt;
+      const hasKeys = !!ipfsCfg.pinataApiKey && !!ipfsCfg.pinataSecret;
+      if (!hasJwt && !hasKeys) {
+        warn.push('IPFS (pinata) lacks credentials (JWT or API key/secret)');
+        diagnostics.push({ level: 'warn', code: 'IPFS_KEYS_MISSING', message: 'IPFS Pinata keys not configured', fix: fixIpfsKeys });
+      } else {
+        out.push(`✅ IPFS configured: pinata (${hasJwt ? 'jwt' : 'api-key'})`);
+      }
+    } else {
+      out.push(`✅ IPFS configured: ${ipfsCfg.provider}`);
+    }
+  } catch (e) { warn.push('IPFS config check failed: ' + e.message); }
+
   // Print report
   console.log(c.cyan('🔎 Sage Doctor Report'));
   // SAGE_HOME/project-local path
@@ -615,9 +666,10 @@ async function runDoctor(opts = {}) {
   }
   console.log('');
   console.log('Tips:');
-  console.log(' - Set addresses via: sage config addresses import --file packages-protocol-protocol/contracts/deployment/addresses/sepolia.json');
+  console.log(' - Set addresses via: sage config addresses import --file packages/contracts/deployment/addresses/sepolia.json');
   console.log(' - Set working SubDAO: sage subdao use <0x...>');
   console.log(' - Verify env: sage config env show');
+  return { diagnostics };
 }
 
 function _resolveSageHome() {
@@ -650,6 +702,8 @@ function register(program) {
     .option('--registry', 'Also check LibraryRegistry roles (FACTORY_ROLE, LIBRARY_ADMIN_ROLE)', false)
     .option('--cid <cid>', 'Optional CID to warm-test IPFS gateways')
     .option('--subdao <address>', 'Target SubDAO for mode/roles diagnostics')
+    .option('--fix', 'Attempt to fix detected issues interactively', false)
+    .option('--auto-fix', 'Attempt to fix non-interactively with safe defaults', false)
     .action(async (opts) => {
       const previousQuiet = process.env.SAGE_QUIET_JSON;
       if (opts.json) process.env.SAGE_QUIET_JSON = '1';
@@ -659,7 +713,9 @@ function register(program) {
         if (opts.json) {
           console.log = (...args) => capture.push(args.join(' '));
         }
-        await runDoctor({ ...opts, disableSpinner: opts.json });
+        
+        const { diagnostics } = await runDoctor({ ...opts, disableSpinner: opts.json });
+        
         if (opts.cid) {
           try {
             let normalizeCidV1Base32;
@@ -680,6 +736,28 @@ function register(program) {
             }
           } catch (e) { console.log('⚠️  Gateway warm test skipped:', e.message); }
         }
+
+        // Handle Fixes
+        if (opts.fix && diagnostics && diagnostics.length > 0) {
+            console.log('\n🔧 Scanning for fixable issues...');
+            const fixable = diagnostics.filter(d => d.fix);
+            if (fixable.length === 0) {
+                console.log('   No auto-fixable issues found.');
+            } else {
+                for (const diag of fixable) {
+                    // Ensure user context
+                    if (!opts.json) {
+                        console.log(`\nFound issue: ${diag.message}`);
+                    }
+                    try {
+                        await diag.fix({ auto: opts.autoFix });
+                    } catch (e) {
+                        console.error(`   ❌ Fix failed: ${e.message}`);
+                    }
+                }
+            }
+        }
+
         if (opts.json) {
           // Build JSON object with key facts
           const rpcUrl = process.env.RPC_URL || 'https://sepolia.base.org';
@@ -697,6 +775,7 @@ function register(program) {
               TIMELOCK: process.env.TIMELOCK || null
             },
             sageHome,
+            diagnostics: diagnostics?.map(d => ({ level: d.level, message: d.message, code: d.code, fixable: !!d.fix })) || [],
             logs: capture
           };
           console.log = oldLog; // restore

package/dist/cli/commands/gov-config.js

@@ -188,6 +188,87 @@ function register(program) {
       })
   );
 
+  // Voting configuration proposal (set voting period/quorum/threshold via governance)
+  cmd.addCommand(
+    new Command('voting')
+      .description('Propose updates to voting parameters (voting period, quorum bps, proposal threshold)')
+      .option('--voting-period <duration>', 'Voting period duration (e.g., 7 days, 36 hours)')
+      .option('--quorum-bps <bps>', 'Quorum basis points (e.g., 200 for 2%)')
+      .option('--proposal-threshold <amount>', 'Proposal threshold (string/wei)')
+      .option('--block-time-sec <n>', 'Override block time (seconds per block); auto-detected if omitted')
+      .option('--subdao <address>', 'Resolve governor from this SubDAO')
+      .option('--gov <address>', 'Governor address (overrides --subdao resolution)')
+      .option('--title <text>', 'Proposal title/description', 'Update voting parameters')
+      .action(async (opts) => {
+        try {
+          const { ethers } = require('ethers');
+          const { resolveGovContext } = require('../utils/gov-context');
+          const { parseDurationToBlocks } = require('../services/subdao/planner');
+          const config = require('../config');
+          const wm = new (require('@sage-protocol/wallet-manager'))(); await wm.connect();
+          const signer = wm.getSigner(); const provider = wm.getProvider();
+          const ctx = await resolveGovContext({ govOpt: opts.gov, subdaoOpt: opts.subdao, provider });
+          const govAddr = ctx.governor; if (!govAddr) throw new Error('Governor not resolved; pass --subdao or --gov');
+
+          const targets = []; const values = []; const calldatas = [];
+          const iface = new ethers.Interface([
+            'function setVotingPeriod(uint256)',
+            'function setProposalThreshold(uint256)',
+            'function setQuorumBps(uint256)',
+            // fallback OZ method name when available
+            'function updateQuorumNumerator(uint256)'
+          ]);
+
+          const rpc = (config.resolveRpcUrl ? config.resolveRpcUrl() : (process.env.RPC_URL || 'https://base-sepolia.publicnode.com'));
+          const providerTmp = new ethers.JsonRpcProvider(rpc);
+          const detectBlockTimeSec = async () => {
+            try {
+              const latest = await providerTmp.getBlockNumber();
+              const older = latest > 100 ? latest - 100 : (latest > 1 ? 1 : 0);
+              const [bLatest, bOlder] = await Promise.all([providerTmp.getBlock(latest), providerTmp.getBlock(older)]);
+              const dt = Number(bLatest.timestamp) - Number(bOlder.timestamp);
+              if (dt <= 0) return 12; return Math.max(1, Math.round(dt / Math.max(1, latest - older)));
+            } catch (_) { return 12; }
+          };
+
+          // votingPeriod → blocks
+          if (opts.votingPeriod) {
+            const bt = opts.blockTimeSec ? Number(opts.blockTimeSec) : await detectBlockTimeSec();
+            const blocks = parseDurationToBlocks(String(opts.votingPeriod), bt);
+            targets.push(govAddr); values.push(0);
+            calldatas.push(iface.encodeFunctionData('setVotingPeriod', [BigInt(blocks)]));
+          }
+
+          if (opts.proposalThreshold) {
+            targets.push(govAddr); values.push(0);
+            calldatas.push(iface.encodeFunctionData('setProposalThreshold', [BigInt(String(opts.proposalThreshold))]));
+          }
+
+          if (opts.quorumBps) {
+            // Prefer setQuorumBps; fallback to OZ updateQuorumNumerator
+            try {
+              calldatas.push(iface.encodeFunctionData('setQuorumBps', [Number(opts.quorumBps)]));
+              targets.push(govAddr); values.push(0);
+            } catch (_) {
+              targets.push(govAddr); values.push(0);
+              calldatas.push(iface.encodeFunctionData('updateQuorumNumerator', [Number(opts.quorumBps)]));
+            }
+          }
+
+          if (!targets.length) throw new Error('Provide at least one of --voting-period, --quorum-bps, --proposal-threshold');
+
+          const gov = new ethers.Contract(govAddr, ['function propose(address[],uint256[],bytes[],string) returns (uint256)'], signer);
+          const desc = opts.title || 'Update voting parameters';
+          const tx = await gov.propose(targets, values, calldatas, desc);
+          console.log('🗳️  propose tx:', tx.hash);
+          console.log('➡️  Submit votes, then queue and execute to apply new parameters');
+        } catch (e) {
+          console.error('❌ voting config failed:', e.message);
+          process.exit(1);
+        }
+      })
+  );
+
   program.addCommand(cmd);
 }
 

package/dist/cli/commands/governance.js

@@ -3,6 +3,7 @@ const { Command } = require('commander');
 const SXXXManager = require('../sxxx-manager');
 const SubDAOManager = require('../subdao-manager');
 const LibraryManager = require('../library-manager');
+const GovernanceManager = require('../governance-manager');
 const { ethers } = require('ethers');
 const axios = require('axios');
 const { execSync } = require('child_process');
@@ -15,51 +16,6 @@ const { handleCLIError } = require('../utils/error-handler');
 const logger = require('../utils/logger');
 const hooks = require('../utils/hooks');
 
-async function resolveGovContext(options) {
-  let subdao = options.subdao || process.env.WORKING_SUBDAO_ADDRESS || process.env.SUBDAO;
-  let governorAddr = process.env.GOV;
-  
-  if (subdao) {
-    // Get governor address from SubDAO contract
-    const rpcUrl = process.env.RPC_URL || 'https://base-sepolia.publicnode.com';
-    try {
-      governorAddr = execSync(`cast call ${subdao} "governor()" --rpc-url ${rpcUrl}`, { encoding: 'utf8' }).trim();
-    } catch (e) {
-      console.log(`⚠️  Could not get governor from SubDAO: ${e.message}`);
-      governorAddr = process.env.GOV;
-    }
-  } else {
-    // Fallback to wizard to select a SubDAO or main gov
-    const inquirer = (require('inquirer').default || require('inquirer'));
-    const { scope } = await inquirer.prompt([
-      { type: 'list', name: 'scope', message: 'Select governance context', choices: [
-        { name: 'A SubDAO (recommended)', value: 'subdao' },
-        { name: 'Main protocol (use GOV from env)', value: 'main' }
-      ]}
-    ]);
-    
-    if (scope === 'subdao') {
-      // For now, use a simple prompt for SubDAO address
-      const { subdaoAddr } = await inquirer.prompt([
-        { type: 'input', name: 'subdaoAddr', message: 'Enter SubDAO address:' }
-      ]);
-      subdao = subdaoAddr;
-      const rpcUrl = process.env.RPC_URL || 'https://base-sepolia.publicnode.com';
-      try {
-        governorAddr = execSync(`cast call ${subdao} "governor()" --rpc-url ${rpcUrl}`, { encoding: 'utf8' }).trim();
-      } catch (e) {
-        console.log(`⚠️  Could not get governor from SubDAO: ${e.message}`);
-        governorAddr = process.env.GOV;
-      }
-      process.env.SUBDAO = subdao;
-      process.env.WORKING_SUBDAO_ADDRESS = subdao;
-      cliConfig.writeAddresses({ SUBDAO: subdao, WORKING_SUBDAO_ADDRESS: subdao, GOV: governorAddr });
-    }
-  }
-  
-  return { governorAddr, subdao };
-}
-
 function register(program) {
   const governanceCommand = new Command('governance')
     .description('Governance management commands')
@@ -861,6 +817,8 @@ function register(program) {
         .action(async () => {
           try {
             const inquirer = (require('inquirer').default || require('inquirer'));
+            const GovernanceManager = require('../governance-manager');
+            const SubDAOManager = require('../subdao-manager');
             const gm = new GovernanceManager();
             const sdm = new SubDAOManager();
             await sdm.initialize();
@@ -871,16 +829,18 @@ function register(program) {
                 { name: 'Main protocol (use GOV from env)', value: 'main' }
               ]}
             ]);
+            let subdaoAddr = null;
             if (ctx.scope === 'subdao') {
-              const subdaoAddr = await sdm.resolveSubDAOAddress(null, { title: 'Select a SubDAO' });
+              subdaoAddr = await sdm.resolveSubDAOAddress(null, { title: 'Select a SubDAO' });
               await gm.initialize(subdaoAddr);
               // Persist SUBDAO and derived GOV for future runs
               try {
+                const LibraryManager = require('../library-manager');
                 const lm = new LibraryManager();
                 process.env.SUBDAO = subdaoAddr;
                 process.env.WORKING_SUBDAO_ADDRESS = subdaoAddr;
                 const gov = await lm.getGovernorAddress();
-                cliConfig.writeAddresses({ SUBDAO: subdaoAddr, WORKING_SUBDAO_ADDRESS: subdaoAddr, GOV: gov });
+                require('../config').writeAddresses({ SUBDAO: subdaoAddr, WORKING_SUBDAO_ADDRESS: subdaoAddr, GOV: gov });
               } catch (_) {}
             } else {
               await gm.initialize();
@@ -1810,7 +1770,10 @@ function register(program) {
             }
 
             // Update configuration via governance proposal
-            const { governorAddr } = await resolveGovContext(opts);
+            const { resolveGovContext } = require('../utils/gov-context');
+            const _prov = new ethers.JsonRpcProvider(process.env.RPC_URL || 'https://base-sepolia.publicnode.com');
+            const _ctx = await resolveGovContext({ govOpt: null, subdaoOpt: opts.subdao, provider: _prov });
+            const governorAddr = _ctx.governor;
             const targets = [];
             const values = [];
             const calldatas = [];
@@ -1959,7 +1922,9 @@ function register(program) {
         .option('--subdao <address>', 'SubDAO context')
         .action(async (proposalId, support, opts) => {
           try {
-            const { governorAddr } = await resolveGovContext(opts);
+            const { resolveGovContext } = require('../utils/gov-context');
+            const provider = new ethers.JsonRpcProvider(process.env.RPC_URL || 'https://base-sepolia.publicnode.com');
+            const ctx = await resolveGovContext({ govOpt: opts.gov, subdaoOpt: opts.subdao, provider });
             const rpcUrl = process.env.RPC_URL || 'https://base-sepolia.publicnode.com';
             
             const supportInt = parseInt(support);
@@ -2008,14 +1973,24 @@ function register(program) {
         .option('--description <description>', 'Proposal description')
         .option('--targets <addresses>', 'Comma-separated target contract addresses')
         .option('--values <amounts>', 'Comma-separated ETH values (in ether)')
-        .option('--calldatas <data>', 'Comma-separated calldata strings')
+        .option('--calldatas <data>', 'Comma-separated calldata (0x hex)')
+        .option('--target <address>', 'Target address (repeatable)', (v, p = []) => { p.push(v); return p; }, [])
+        .option('--value <eth>', 'ETH value in ether (repeatable)', (v, p = []) => { p.push(v); return p; }, [])
+        .option('--calldata <data>', 'Calldata 0x hex (repeatable)', (v, p = []) => { p.push(v); return p; }, [])
+        .option('--sigs <signatures>', 'Comma-separated function signatures (optional)')
         .option('--subdao <address>', 'SubDAO context')
+        .option('--gov <address>', 'Governor address (overrides SubDAO)')
+        .option('--dry-run', 'Validate proposal without creating it', false)
+        .option('--yes', 'Skip confirmation prompt', false)
+        .option('--verbose', 'Enable verbose logging', false)
         .action(async (opts) => {
           try {
-            const { governorAddr } = await resolveGovContext(opts);
+            const { resolveGovContext } = require('../utils/gov-context');
+            const provider = new ethers.JsonRpcProvider(process.env.RPC_URL || 'https://base-sepolia.publicnode.com');
+            const ctx = await resolveGovContext({ govOpt: opts.gov, subdaoOpt: opts.subdao, provider });
             
             // If no options provided, use interactive mode
-            if (!opts.title && !opts.targets) {
+            if (!opts.targets && (!opts.target || opts.target.length === 0) && !opts.calldatas && (!opts.calldata || opts.calldata.length === 0)) {
               console.log('🏛️ Interactive proposal creation');
               console.log('Tip: Use the governance wizard for guided proposal creation: sage governance wizard');
               
@@ -2031,44 +2006,149 @@ function register(program) {
               Object.assign(opts, answers);
             }
 
-            if (!opts.title || !opts.targets || !opts.calldatas) {
-              throw new Error('Missing required fields: title, targets, and calldatas are required');
-            }
+            const splitCsv = (s) => String(s || '').split(',').map(x => x.trim()).filter(Boolean);
+            const targetsRaw = [ ...(opts.target || []), ...(opts.targets ? splitCsv(opts.targets) : []) ];
+            const valuesRaw = [ ...(opts.value || []), ...(opts.values ? splitCsv(opts.values) : []) ];
+            const calldatasRaw = [ ...(opts.calldata || []), ...(opts.calldatas ? splitCsv(opts.calldatas) : []) ];
 
-            const targets = opts.targets.split(',').map(s => s.trim());
-            const values = (opts.values || '0').split(',').map(v => ethers.parseEther(v.trim()));
-            const calldatas = opts.calldatas.split(',').map(s => s.trim());
-            
-            if (targets.length !== values.length || targets.length !== calldatas.length) {
-              throw new Error('Targets, values, and calldatas arrays must have the same length');
+            if (targetsRaw.length === 0 || calldatasRaw.length === 0) {
+              throw new Error('Missing required fields: targets and calldatas are required');
             }
 
-            const description = opts.description || opts.title;
+            let targets;
+            try {
+              targets = targetsRaw.map((t) => ethers.getAddress(t));
+            } catch (_) {
+              throw new Error('Invalid target address provided');
+            }
+            let values = valuesRaw.length ? valuesRaw.map((v) => ethers.parseEther(String(v))) : Array(targets.length).fill(0n);
+            if (values.length !== targets.length) {
+              throw new Error('Values length must equal targets length (or omit values to default to 0)');
+            }
+            const isHex = (s) => /^0x[0-9a-fA-F]*$/.test(String(s));
+            const calldatas = calldatasRaw.map(String);
+            if (calldatas.length !== targets.length) {
+              throw new Error('Calldatas length must equal targets length');
+            }
+            if (opts.sigs && calldatas.some((c) => !isHex(c))) {
+              throw new Error('Non-hex calldata with --sigs is not supported. Provide 0x-encoded calldatas.');
+            }
+            if (calldatas.some((c) => !isHex(c))) {
+              throw new Error('Calldata entries must be 0x hex-encoded');
+            }
+            const description = opts.description || opts.title || '';
 
             console.log('--- Proposal Preview ---');
-            console.log('Title:', opts.title);
-            console.log('Description:', description);
+            if (opts.title) console.log('Title:', opts.title);
+            if (description) console.log('Description:', description);
             console.log('Targets:', targets);
             console.log('Values:', values.map(v => v.toString()));
             console.log('Calldatas:', calldatas.map(c => c.substring(0, 20) + '...'));
 
-            const inquirer = (require('inquirer').default || require('inquirer'));
-            const { confirm } = await inquirer.prompt([{ type: 'confirm', name: 'confirm', message: 'Create proposal?', default: true }]);
-            if (!confirm) return;
+            if (opts.dryRun) {
+              console.log('✅ Proposal validation passed (dry-run)');
+              return;
+            }
 
-            const rpcUrl = process.env.RPC_URL || 'https://base-sepolia.publicnode.com';
-            const proposalData = execSync(`cast calldata "propose(address[],uint256[],bytes[],string)" '["${targets.join('","')}"]' '[${values.join(',')}]' '["${calldatas.join('","')}"]' "${description}"`, { encoding: 'utf8' }).trim();
+            if (!opts.yes && String(process.env.SAGE_FORCE || '').trim() !== '1') {
+              const inquirer = (require('inquirer').default || require('inquirer'));
+              const { confirm } = await inquirer.prompt([{ type: 'confirm', name: 'confirm', message: 'Create proposal?', default: true }]);
+              if (!confirm) return;
+            }
+
+            if (opts.verbose || process.env.SAGE_VERBOSE === '1') {
+              console.log('🔗 Connecting wallet...');
+            }
+            const gm = new GovernanceManager();
+            await gm.initialize(ctx.subdao || opts.subdao || null);
             
-            const walletArgs = cliConfig.getCastWalletArgs();
-            execSync(`cast send ${governorAddr} "${proposalData}" --rpc-url ${rpcUrl} ${walletArgs}`, { encoding: 'utf8' });
+            if (opts.verbose || process.env.SAGE_VERBOSE === '1') {
+              console.log('📝 Creating proposal...');
+            }
+            await gm.createProposal(targets, values, calldatas, description);
             console.log('✅ Proposal created successfully');
 
           } catch (e) {
-            console.error('❌ Failed to create proposal:', e.message);
+            try {
+              const { handleCLIError } = require('../utils/error-handler');
+              handleCLIError('governance:propose-custom', e, { context: { subdao: opts?.subdao, gov: opts?.gov } });
+            } catch (_) {
+              console.error('❌ Failed to create proposal:', e.message);
+            }
+            process.exit(1);
+          }
+        })
+    )
+    .addCommand(
+      new Command('wait')
+        .description('Wait for a proposal to reach a target state')
+        .argument('<proposalId>', 'Proposal ID')
+        .option('--target <state>', 'Target state (Active, Canceled, Defeated, Succeeded, Queued, Expired, Executed)', 'Executed')
+        .option('--timeout <seconds>', 'Timeout in seconds', '300')
+        .option('--interval <seconds>', 'Poll interval in seconds', '5')
+        .option('--subdao <address>', 'SubDAO address')
+        .action(async (proposalId, opts) => {
+          try {
+            const { ethers } = require('ethers');
+            const { resolveGovContext } = require('../utils/gov-context');
+            const provider = new ethers.JsonRpcProvider(process.env.RPC_URL || 'https://base-sepolia.publicnode.com');
+            const ctx = await resolveGovContext({ govOpt: null, subdaoOpt: opts.subdao, provider });
+            const GovABI = require('../utils/artifacts').resolveArtifact('contracts/cloneable/PromptGovernorCloneable.sol/PromptGovernorCloneable.json').abi;
+            const gov = new ethers.Contract(ctx.governor, GovABI, provider);
+
+            const states = ['Pending', 'Active', 'Canceled', 'Defeated', 'Succeeded', 'Queued', 'Expired', 'Executed'];
+            const targetState = String(opts.target).charAt(0).toUpperCase() + String(opts.target).slice(1).toLowerCase();
+            const targetIdx = states.indexOf(targetState);
+            if (targetIdx === -1) throw new Error(`Invalid target state: ${targetState}. Valid: ${states.join(', ')}`);
+
+            const pid = BigInt(proposalId);
+            const timeout = Number(opts.timeout) * 1000;
+            const interval = Number(opts.interval) * 1000;
+            const start = Date.now();
+
+            console.log(`⏳ Waiting for proposal ${proposalId} to reach ${targetState}...`);
+
+            while (true) {
+                if (Date.now() - start > timeout) {
+                    throw new Error(`Timeout waiting for state ${targetState}`);
+                }
+
+                let currentStateIdx;
+                try {
+                    currentStateIdx = Number(await gov.state(pid));
+                } catch (e) {
+                    // Ignore transient RPC errors
+                    await new Promise(r => setTimeout(r, interval));
+                    continue;
+                }
+
+                const currentState = states[currentStateIdx] || 'Unknown';
+                
+                // Success?
+                if (currentStateIdx === targetIdx) {
+                    console.log(`\n✅ Proposal reached target state: ${currentState}`);
+                    return;
+                }
+
+                // Failure check (terminal states)
+                if (targetIdx > currentStateIdx) {
+                    if (currentState === 'Canceled' || currentState === 'Defeated' || currentState === 'Expired') {
+                         throw new Error(`Proposal reached terminal state ${currentState} before ${targetState}`);
+                    }
+                }
+
+                process.stdout.write(`\r   Current state: ${currentState} (${Math.round((timeout - (Date.now() - start))/1000)}s remaining)   `);
+                
+                await new Promise(r => setTimeout(r, interval));
+            }
+
+          } catch (e) {
+            console.error(`\n❌ Wait failed: ${e.message}`);
             process.exit(1);
           }
         })
     );
+
   program.addCommand(governanceCommand);
 }
 

package/dist/cli/commands/library.js

@@ -1311,6 +1311,15 @@ function register(program) {
               { exec: !!options.exec, libraryId: options.libraryId || 'main', ctx: { govOpt: ctx.governor || undefined, subdaoOpt: ctx.subdao || undefined, timelockOpt: ctx.timelock || undefined } }
             );
             console.log(`🆔 Proposal ID: ${proposalId}`);
+            // Print next steps hints via suggestions system
+            printSuggestions('library:push', {
+              manifestCID,
+              proposalId: proposalId.toString(),
+              subdao: ctx.subdao || options.subdao || null,
+              exec: !!options.exec,
+              route: 'governance',
+              manifestPath: manifestPath
+            });
           } catch (error) {
             const { handleCLIError } = require('../utils/error-handler');
             handleCLIError('library:propose', error, { context: { manifest: manifestPath, subdao: options.subdao, gov: options.gov } });