@0xsequence/catapult 1.1.0

package/src/commands/list.ts

@@ -0,0 +1,249 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import * as path from 'path'
+import { loadProject, projectOption, noStdOption, verbosityOption } from './common'
+import { loadNetworks } from '../lib/network-loader'
+import { setVerbosity } from '../index'
+
+interface ListOptions {
+  project: string
+  std: boolean
+  verbose: number
+}
+
+interface NetworksListOptions {
+  project: string
+  verbose: number
+  onlyTestnets?: boolean
+  onlyNonTestnets?: boolean
+}
+
+export function makeListCommand(): Command {
+  const list = new Command('list')
+    .description('List project resources like jobs, contracts, and networks')
+
+  const listJobs = new Command('jobs')
+    .description('List all available jobs in the project')
+  projectOption(listJobs)
+  noStdOption(listJobs)
+  verbosityOption(listJobs)
+  listJobs.action(async (options: ListOptions) => {
+    try {
+      // Set verbosity level for logging
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+      const loader = await loadProject(options.project, {
+        loadStdTemplates: options.std !== false
+      })
+      console.log(chalk.bold.underline('Available Jobs:'))
+      if (loader.jobs.size === 0) {
+        console.log(chalk.yellow('No jobs found in this project.'))
+        return
+      }
+      for (const job of loader.jobs.values()) {
+        const deprecatedMark = (job as { deprecated?: boolean }).deprecated ? ` ${chalk.yellow('(deprecated)')}` : ''
+        console.log(`- ${chalk.cyan(job.name)} (v${job.version})${deprecatedMark}`)
+        if (job.description) {
+          console.log(`  ${chalk.gray(job.description)}`)
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red('Error listing jobs:'), error instanceof Error ? error.message : String(error))
+      process.exit(1)
+    }
+  })
+
+  const listContracts = new Command('contracts')
+    .description('List all contracts found in the project')
+  projectOption(listContracts)
+  noStdOption(listContracts)
+  verbosityOption(listContracts)
+  listContracts.action(async (options: ListOptions) => {
+    try {
+      // Set verbosity level for logging
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+      const loader = await loadProject(options.project, {
+        loadStdTemplates: options.std !== false
+      })
+      const contracts = loader.contractRepository.getAll()
+      const ambiguousRefs = loader.contractRepository.getAmbiguousReferences()
+
+      // Display contracts
+      console.log(chalk.bold.underline('Available Contracts:'))
+      if (contracts.length === 0) {
+        console.log(chalk.yellow('No contracts found in this project.'))
+      } else {
+        for (const contract of contracts) {
+          const name = contract.contractName || 'Unknown'
+          const source = contract.sourceName || 'Unknown'
+          console.log(`- ${chalk.cyan(name)} (${source})`)
+          console.log(`  ${chalk.gray('Unique Hash:')} ${contract.uniqueHash}`)
+          if (contract.buildInfoId) {
+            console.log(`  ${chalk.gray('Build Info ID:')} ${contract.buildInfoId}`)
+          }
+          console.log(`  ${chalk.gray('Sources:')} ${Array.from(contract._sources).map(p => path.relative(options.project, p)).join(', ')}`)
+        }
+      }
+
+      // Display ambiguous references if any
+      if (ambiguousRefs.length > 0) {
+        console.log('\n' + chalk.bold.underline(chalk.yellow('Ambiguous References:')))
+        console.log(chalk.yellow('The following references point to multiple contracts:'))
+        for (const ref of ambiguousRefs) {
+          console.log(`- ${chalk.red(ref)}`)
+        }
+        console.log(chalk.yellow('Use the unique hash or a more specific path to reference these contracts.'))
+      }
+
+      if (contracts.length === 0) {
+        console.log('\n' + chalk.yellow('No contracts found in this project. Make sure you have artifact files or build-info files in your project.'))
+      }
+    } catch (error) {
+      console.error(chalk.red('Error listing contracts:'), error instanceof Error ? error.message : String(error))
+      process.exit(1)
+    }
+  })
+
+  const listTemplates = new Command('templates')
+    .description('List all available templates')
+  projectOption(listTemplates)
+  noStdOption(listTemplates)
+  verbosityOption(listTemplates)
+  listTemplates.action(async (options: ListOptions) => {
+    try {
+      // Set verbosity level for logging
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+      const loader = await loadProject(options.project, {
+        loadStdTemplates: options.std !== false
+      })
+      console.log(chalk.bold.underline('Available Templates:'))
+      if (loader.templates.size === 0) {
+        console.log(chalk.yellow('No templates found.'))
+        return
+      }
+      for (const template of loader.templates.values()) {
+        console.log(`- ${chalk.cyan(template.name)}`)
+        if (template.description) {
+          console.log(`  ${chalk.gray(template.description)}`)
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red('Error listing templates:'), error instanceof Error ? error.message : String(error))
+      process.exit(1)
+    }
+  })
+
+  const listNetworks = new Command('networks')
+    .description('List all configured networks')
+  projectOption(listNetworks)
+  verbosityOption(listNetworks)
+  listNetworks.option('--only-testnets', 'Show only test networks')
+  listNetworks.option('--only-non-testnets', 'Show only non-test networks')
+  listNetworks.option('--simple', 'Output only network names, one per line')
+  listNetworks.option('--simple-chain-ids', 'Output only chain IDs, one per line')
+  listNetworks.action(async (options: NetworksListOptions & { simple?: boolean; simpleChainIds?: boolean }) => {
+    try {
+      // Set verbosity level for logging
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+      const networks = await loadNetworks(options.project)
+      
+      // Apply filtering if specified
+      let filteredNetworks = networks
+      if (options.onlyTestnets) {
+        filteredNetworks = networks.filter(network => network.testnet === true)
+      } else if (options.onlyNonTestnets) {
+        filteredNetworks = networks.filter(network => network.testnet !== true)
+      }
+      
+      // Handle simple output formats
+      if (options.simple) {
+        if (filteredNetworks.length === 0) {
+          console.log('')
+          return
+        }
+        console.log(filteredNetworks.map(network => network.name).join('\n'))
+        return
+      }
+      
+      if (options.simpleChainIds) {
+        if (filteredNetworks.length === 0) {
+          console.log('')
+          return
+        }
+        console.log(filteredNetworks.map(network => network.chainId.toString()).join('\n'))
+        return
+      }
+      
+      // Default formatted output
+      console.log(chalk.bold.underline('Available Networks:'))
+      if (filteredNetworks.length === 0) {
+        if (options.onlyTestnets) {
+          console.log(chalk.yellow('No test networks configured.'))
+        } else if (options.onlyNonTestnets) {
+          console.log(chalk.yellow('No non-test networks configured.'))
+        } else {
+          console.log(chalk.yellow('No networks configured. Create a networks.yaml file in your project root.'))
+        }
+        return
+      }
+      
+      for (const network of filteredNetworks) {
+        const testnetIndicator = network.testnet ? chalk.green('(testnet)') : ''
+        console.log(`- ${chalk.cyan(network.name)} (Chain ID: ${network.chainId}) ${testnetIndicator}`)
+        console.log(`  ${chalk.gray(`RPC: ${network.rpcUrl}`)}`)
+      }
+    } catch (error) {
+      console.error(chalk.red('Error listing networks:'), error instanceof Error ? error.message : String(error))
+      process.exit(1)
+    }
+  })
+
+  // New: list constants
+  const listConstants = new Command('constants')
+    .description('List constants defined at top-level and per job')
+  projectOption(listConstants)
+  noStdOption(listConstants)
+  verbosityOption(listConstants)
+  listConstants.action(async (options: ListOptions) => {
+    try {
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+      const loader = await loadProject(options.project, {
+        loadStdTemplates: options.std !== false
+      })
+      console.log(chalk.bold.underline('Top-level Constants:'))
+      if (loader.constants.size === 0) {
+        console.log(chalk.yellow('No top-level constants found.'))
+      } else {
+        for (const [key, value] of loader.constants.entries()) {
+          // Only display keys to avoid dumping large values
+          console.log(`- ${chalk.cyan(key)}${options.verbose ? ` = ${JSON.stringify(value)}` : ''}`)
+        }
+      }
+      console.log(chalk.bold.underline('\nJob-level Constants:'))
+      let anyJobConstants = false
+      for (const job of loader.jobs.values()) {
+        const constants = job.constants
+        if (constants && Object.keys(constants).length > 0) {
+          anyJobConstants = true
+          console.log(`- ${chalk.cyan(job.name)}:`)
+          for (const key of Object.keys(constants)) {
+            console.log(`  • ${key}${options.verbose ? ` = ${JSON.stringify(constants[key])}` : ''}`)
+          }
+        }
+      }
+      if (!anyJobConstants) {
+        console.log(chalk.yellow('No job-level constants found.'))
+      }
+    } catch (error) {
+      console.error(chalk.red('Error listing constants:'), error instanceof Error ? error.message : String(error))
+      process.exit(1)
+    }
+  })
+
+  list.addCommand(listJobs)
+  list.addCommand(listContracts)
+  list.addCommand(listTemplates)
+  list.addCommand(listNetworks)
+  list.addCommand(listConstants)
+
+  return list
+}

package/src/commands/run.ts

@@ -0,0 +1,136 @@
+import { Command } from 'commander'
+import { Deployer, DeployerOptions } from '../lib/deployer'
+import { loadNetworks } from '../lib/network-loader'
+import { detectNetworkFromRpc, isValidRpcUrl } from '../lib/network-utils'
+import { deploymentEvents } from '../lib/events'
+import { Network } from '../lib/types'
+import { projectOption, dotenvOption, noStdOption, verbosityOption, loadDotenv } from './common'
+import { setVerbosity } from '../index'
+
+interface RunOptions {
+  project: string
+  privateKey?: string
+  network?: string[]
+  rpcUrl?: string
+  dotenv?: string
+  std: boolean
+  etherscanApiKey?: string
+  verbose: number
+  failEarly: boolean
+  noPostCheckConditions: boolean
+  flatOutput: boolean
+  summary: boolean
+}
+ 
+export function makeRunCommand(): Command {
+  const run = new Command('run')
+    .description('Run deployment jobs on specified networks')
+    .argument('[jobs...]', 'Specific job names or patterns to run (and their dependencies). Supports wildcards like "sequence/*" or "job?". If not provided, all jobs are run.')
+    .option('-k, --private-key <key>', 'Signer private key. Can also be set via PRIVATE_KEY env var.')
+    .option('-n, --network <chainIds...>', 'One or more network chain IDs to run on. If not provided, runs on all configured networks.')
+    .option('--rpc-url <url>', 'Custom RPC URL to run on. The system will automatically detect chainId and network information. This overrides networks.yaml configuration.')
+    .option('--etherscan-api-key <key>', 'Etherscan API key for contract verification. Can also be set via ETHERSCAN_API_KEY env var.')
+    .option('--fail-early', 'Stop execution as soon as any job fails. Default: false', false)
+    .option('--no-post-check-conditions', 'Skip post-execution check of skip conditions. Default: false (post-check enabled)', false)
+    .option('--flat-output', 'Write output files in a single flat directory instead of mirroring the jobs directory structure. Default: false', false)
+    .option('--no-summary', 'Hide final summary at the end of the run. Default: show', false)
+    .option('--run-deprecated', 'Allow running jobs marked as deprecated. By default deprecated jobs are skipped unless explicitly targeted.', false)
+
+  projectOption(run)
+  dotenvOption(run)
+  noStdOption(run)
+  verbosityOption(run)
+
+  run.action(async (jobs: string[], options: RunOptions) => {
+    try {
+      loadDotenv(options)
+      
+      // Set verbosity level for logging
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+      
+      const privateKey: string | undefined = options.privateKey || process.env.PRIVATE_KEY
+      if (!privateKey && !options.rpcUrl) {
+        throw new Error('A private key must be provided via the --private-key option or the PRIVATE_KEY environment variable, or an --rpc-url must be specified to attempt an implicit sender.')
+      }
+
+      const etherscanApiKey = options.etherscanApiKey || process.env.ETHERSCAN_API_KEY
+
+      const projectRoot = options.project
+      
+      // Load networks from YAML file
+      let networks = await loadNetworks(projectRoot)
+      
+      // Handle custom RPC URL if provided
+      if (options.rpcUrl) {
+        // Custom RPC URL provided
+        
+        // Validate RPC URL format
+        if (!isValidRpcUrl(options.rpcUrl)) {
+          throw new Error(`Invalid RPC URL format: ${options.rpcUrl}`)
+        }
+        
+        try {
+          // Detect network information from RPC URL
+          const detectedNetwork = await detectNetworkFromRpc(options.rpcUrl)
+          
+          // Create a complete network object
+          const customNetwork: Network = {
+            name: detectedNetwork.name || `custom-${detectedNetwork.chainId}`,
+            chainId: detectedNetwork.chainId!,
+            rpcUrl: options.rpcUrl,
+            // Optional fields with defaults
+            supports: detectedNetwork.supports || [],
+            gasLimit: detectedNetwork.gasLimit,
+            testnet: detectedNetwork.testnet
+          }
+          
+          // Custom network created from RPC detection
+          
+          // Replace networks array with just the custom network
+          networks = [customNetwork]
+        } catch (error) {
+          throw new Error(`Failed to detect network from RPC URL "${options.rpcUrl}": ${error instanceof Error ? error.message : String(error)}`)
+        }
+      }
+
+      if (networks.length === 0 && !options.rpcUrl) {
+        throw new Error('No networks configured. Please create a networks.yaml file in your project root or use --rpc-url to specify a custom network.')
+      }
+
+      const deployerOptions: DeployerOptions = {
+        projectRoot,
+        privateKey,
+        networks,
+        runJobs: jobs.length > 0 ? jobs : undefined,
+        runOnNetworks: options.network?.map(Number),
+        etherscanApiKey,
+        failEarly: options.failEarly,
+        noPostCheckConditions: options.noPostCheckConditions,
+        showSummary: options.summary !== false,
+        loaderOptions: {
+          loadStdTemplates: options.std !== false
+        },
+        flatOutput: options.flatOutput === true,
+        runDeprecated: (options as { runDeprecated?: boolean }).runDeprecated === true
+      } as DeployerOptions
+
+      const deployer = new Deployer(deployerOptions)
+      await deployer.run()
+
+    } catch (error) {
+      // The deployer emits its own rich error event, so we just log a generic one if something fails before that.
+      if (!(error instanceof Error && error.message.includes('deployment_failed'))) {
+        deploymentEvents.emitEvent({
+          type: 'cli_error',
+          level: 'error',
+          data: {
+            message: error instanceof Error ? error.message : String(error)
+          }
+        })
+      }
+      process.exit(1)
+    }
+  })
+
+  return run
+}

package/src/commands/utils.ts

@@ -0,0 +1,52 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { projectOption, verbosityOption } from './common'
+import { loadNetworks } from '../lib/network-loader'
+import { setVerbosity } from '../index'
+
+interface UtilsOptions {
+  project: string
+  verbose: number
+}
+
+export function makeUtilsCommand(): Command {
+  const utils = new Command('utils')
+    .description('Utility commands for project management')
+
+  const chainIdToName = new Command('chain-id-to-name')
+    .description('Convert a chain ID to network name')
+  projectOption(chainIdToName)
+  verbosityOption(chainIdToName)
+
+  chainIdToName.argument('<chain-id>', 'The chain ID to convert')
+  chainIdToName.action(async (chainId: string, options: UtilsOptions) => {
+    try {
+      // Set verbosity level for logging
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+      
+      const chainIdNumber = parseInt(chainId, 10)
+      if (isNaN(chainIdNumber)) {
+        console.error(chalk.red('Invalid chain ID. Please provide a valid number.'))
+        process.exit(1)
+      }
+
+      const networks = await loadNetworks(options.project)
+      
+      const network = networks.find(n => n.chainId === chainIdNumber)
+      
+      if (network) {
+        console.log(network.name)
+      } else {
+        console.error(chalk.red(`No network found with chain ID ${chainIdNumber}`))
+        process.exit(1)
+      }
+    } catch (error) {
+      console.error(chalk.red('Error converting chain ID to network name:'), error instanceof Error ? error.message : String(error))
+      process.exit(1)
+    }
+  })
+
+  utils.addCommand(chainIdToName)
+
+  return utils
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import { setupCommands } from './cli'
+import packageJson from '../package.json'
+
+import { deploymentEvents, CLIEventAdapter, VerbosityLevel } from './lib/events'
+
+// Set up CLI event adapter to convert events to console output
+const cliAdapter = new CLIEventAdapter(deploymentEvents)
+
+// Export function to update CLI verbosity
+export function setVerbosity(level: VerbosityLevel): void {
+  cliAdapter.setVerbosity(level)
+}
+
+// Setup global error handling
+process.on('unhandledRejection', (reason, promise) => {
+  deploymentEvents.emitEvent({
+    type: 'unhandled_rejection',
+    level: 'error',
+    data: {
+      reason,
+      promise
+    }
+  })
+  process.exit(1)
+})
+
+process.on('uncaughtException', (error) => {
+  deploymentEvents.emitEvent({
+    type: 'uncaught_exception',
+    level: 'error',
+    data: {
+      error
+    }
+  })
+  process.exit(1)
+})
+
+async function main() {
+  try {
+    // Configure the main program
+    program
+      .name('catapult')
+      .description('Ethereum contract deployment CLI tool')
+      .version(packageJson.version)
+
+    // Setup all commands
+    setupCommands(program)
+
+    // Parse arguments
+    await program.parseAsync(process.argv)
+  } catch (error) {
+    deploymentEvents.emitEvent({
+      type: 'cli_error',
+      level: 'error',
+      data: {
+        message: error instanceof Error ? error.message : String(error)
+      }
+    })
+    process.exit(1)
+  }
+}
+
+main()