@0xsequence/catapult 1.4.0 → 1.5.0

package/src/lib/events/types.ts

@@ -1,520 +0,0 @@
-/**
- * Event system for structured logging throughout the deployment process.
- * Replaces direct console.log calls with rich, structured events.
- */
-
-export interface BaseEvent {
-  type: string
-  timestamp: Date
-  level: 'info' | 'warn' | 'error' | 'debug'
-}
-
-// Deployment lifecycle events
-export interface DeploymentStartedEvent extends BaseEvent {
-  type: 'deployment_started'
-  level: 'info'
-  data: {
-    projectRoot: string
-  }
-}
-
-export interface DeploymentCompletedEvent extends BaseEvent {
-  type: 'deployment_completed'
-  level: 'info'
-}
-
-export interface DeploymentFailedEvent extends BaseEvent {
-  type: 'deployment_failed'
-  level: 'error'
-  data: {
-    error: string
-    stack?: string
-    failedJobs?: Array<{
-      jobName: string
-      networkName: string
-      chainId: number
-      error: string
-    }>
-  }
-}
-
-// Project loading events
-export interface ProjectLoadingStartedEvent extends BaseEvent {
-  type: 'project_loading_started'
-  level: 'info'
-  data: {
-    projectRoot: string
-  }
-}
-
-export interface ProjectLoadedEvent extends BaseEvent {
-  type: 'project_loaded'
-  level: 'info'
-  data: {
-    jobCount: number
-    templateCount: number
-  }
-}
-
-// Execution plan events
-export interface ExecutionPlanEvent extends BaseEvent {
-  type: 'execution_plan'
-  level: 'info'
-  data: {
-    targetNetworks: Array<{
-      name: string
-      chainId: number
-    }>
-    jobExecutionOrder: string[]
-  }
-}
-
-// Job execution events
-export interface JobStartedEvent extends BaseEvent {
-  type: 'job_started'
-  level: 'info'
-  data: {
-    jobName: string
-    jobVersion: string
-    networkName: string
-    chainId: number
-  }
-}
-
-export interface JobCompletedEvent extends BaseEvent {
-  type: 'job_completed'
-  level: 'info'
-  data: {
-    jobName: string
-    networkName: string
-    chainId: number
-  }
-}
-
-export interface JobSkippedEvent extends BaseEvent {
-  type: 'job_skipped'
-  level: 'warn'
-  data: {
-    jobName: string
-    networkName: string
-    reason: string
-  }
-}
-
-// Action execution events
-export interface ActionStartedEvent extends BaseEvent {
-  type: 'action_started'
-  level: 'info'
-  data: {
-    actionName: string
-    jobName: string
-  }
-}
-
-export interface ActionSkippedEvent extends BaseEvent {
-  type: 'action_skipped'
-  level: 'info'
-  data: {
-    actionName: string
-    reason: string
-  }
-}
-
-export interface ActionCompletedEvent extends BaseEvent {
-  type: 'action_completed'
-  level: 'info'
-  data: {
-    actionName: string
-    result: string
-  }
-}
-
-export interface ActionFailedEvent extends BaseEvent {
-  type: 'action_failed'
-  level: 'error'
-  data: {
-    message: string
-  }
-}
-
-export interface ActionInfoEvent extends BaseEvent {
-  type: 'action_info'
-  level: 'debug'
-  data: {
-    message: string
-  }
-}
-
-export interface DebugInfoEvent extends BaseEvent {
-  type: 'debug_info'
-  level: 'debug' | 'info' | 'warn'
-  data: {
-    message: string
-  }
-}
-
-// Template execution events
-export interface TemplateEnteredEvent extends BaseEvent {
-  type: 'template_entered'
-  level: 'debug'
-  data: {
-    templateName: string
-  }
-}
-
-export interface TemplateExitedEvent extends BaseEvent {
-  type: 'template_exited'
-  level: 'debug'
-  data: {
-    templateName: string
-  }
-}
-
-export interface TemplateSetupStartedEvent extends BaseEvent {
-  type: 'template_setup_started'
-  level: 'debug'
-  data: {
-    templateName: string
-  }
-}
-
-export interface TemplateSetupCompletedEvent extends BaseEvent {
-  type: 'template_setup_completed'
-  level: 'debug'
-  data: {
-    templateName: string
-  }
-}
-
-export interface TemplateSetupSkippedEvent extends BaseEvent {
-  type: 'template_setup_skipped'
-  level: 'info'
-  data: {
-    templateName: string
-    reason: string
-  }
-}
-
-export interface TemplateSkippedEvent extends BaseEvent {
-  type: 'template_skipped'
-  level: 'info'
-  data: {
-    templateName: string
-    reason: string
-  }
-}
-
-// Transaction events
-export interface PrimitiveActionEvent extends BaseEvent {
-  type: 'primitive_action'
-  level: 'debug'
-  data: {
-    actionType: string
-  }
-}
-
-export interface TransactionSentEvent extends BaseEvent {
-  type: 'transaction_sent'
-  level: 'info'
-  data: {
-    to: string
-    value: string
-    dataPreview: string
-    txHash: string
-  }
-}
-
-export interface TransactionConfirmedEvent extends BaseEvent {
-  type: 'transaction_confirmed'
-  level: 'info'
-  data: {
-    txHash: string
-    blockNumber: number
-  }
-}
-
-// Contract lifecycle events
-export interface ContractCreatedEvent extends BaseEvent {
-  type: 'contract_created'
-  level: 'info'
-  data: {
-    contractAddress: string
-    txHash: string
-    blockNumber: number
-  }
-}
-
-// Output events
-export interface OutputStoredEvent extends BaseEvent {
-  type: 'output_stored'
-  level: 'debug'
-  data: {
-    outputKey: string
-    value: any
-  }
-}
-
-export interface OutputFileWrittenEvent extends BaseEvent {
-  type: 'output_file_written'
-  level: 'info'
-  data: {
-    relativePath: string
-  }
-}
-
-export interface NoOutputsEvent extends BaseEvent {
-  type: 'no_outputs'
-  level: 'warn'
-}
-
-export interface OutputWritingStartedEvent extends BaseEvent {
-  type: 'output_writing_started'
-  level: 'info'
-}
-
-// Warning events
-export interface DuplicateArtifactWarningEvent extends BaseEvent {
-  type: 'duplicate_artifact_warning'
-  level: 'warn'
-  data: {
-    contractName: string
-    path: string
-  }
-}
-
-export interface MissingNetworkConfigWarningEvent extends BaseEvent {
-  type: 'missing_network_config_warning'
-  level: 'warn'
-  data: {
-    missingChainIds: number[]
-  }
-}
-
-export interface ContextDisposalWarningEvent extends BaseEvent {
-  type: 'context_disposal_warning'
-  level: 'warn'
-  data: {
-    jobName: string
-    networkName: string
-    error: string
-  }
-}
-
-export interface DeprecatedJobsSkippedEvent extends BaseEvent {
-  type: 'deprecated_jobs_skipped'
-  level: 'warn'
-  data: {
-    jobs: string[] | { name: string }[]
-  }
-}
-
-// Network events
-export interface NetworkStartedEvent extends BaseEvent {
-  type: 'network_started'
-  level: 'info'
-  data: {
-    networkName: string
-    chainId: number
-  }
-}
-
-/**
- * Emitted right after a network run starts to inform which address will be used
- * to send transactions and its current balance.
- */
-export interface NetworkSignerInfoEvent extends BaseEvent {
-  type: 'network_signer_info'
-  level: 'info'
-  data: {
-    networkName: string
-    chainId: number
-    address: string
-    balanceWei: string
-    balance: string // formatted in ETH
-  }
-}
-
-// Process error events
-export interface UnhandledRejectionEvent extends BaseEvent {
-  type: 'unhandled_rejection'
-  level: 'error'
-  data: {
-    error: string
-    origin: string
-  }
-}
-
-export interface UncaughtExceptionEvent extends BaseEvent {
-  type: 'uncaught_exception'
-  level: 'error'
-  data: {
-    error: Error
-  }
-}
-
-export interface CLIErrorEvent extends BaseEvent {
-  type: 'cli_error'
-  level: 'error'
-  data: {
-    message: string
-  }
-}
-
-export interface JobExecutionFailedEvent extends BaseEvent {
-  type: 'job_execution_failed'
-  level: 'error'
-  data: {
-    jobName: string
-    networkName: string
-    chainId: number
-    error: string
-  }
-}
-
-export interface VerificationStartedEvent extends BaseEvent {
-  type: 'verification_started'
-  level: 'info'
-  data: {
-    actionName: string
-    address: string
-    contractName: string
-    platform: string
-    networkName: string
-  }
-}
-
-export interface VerificationSubmittedEvent extends BaseEvent {
-  type: 'verification_submitted'
-  level: 'info'
-  data: {
-    actionName: string
-    platform: string
-    guid: string
-    message: string
-  }
-}
-
-export interface VerificationCompletedEvent extends BaseEvent {
-  type: 'verification_completed'
-  level: 'info'
-  data: {
-    actionName: string
-    address: string
-    contractName: string
-    platform: string
-    message: string
-  }
-}
-
-export interface VerificationFailedEvent extends BaseEvent {
-  type: 'verification_failed'
-  level: 'error'
-  data: {
-    actionName: string
-    address: string
-    contractName: string
-    platform: string
-    error: string
-  }
-}
-
-export interface VerificationRetryEvent extends BaseEvent {
-  type: 'verification_retry'
-  level: 'info'
-  data: {
-    platform: string
-    attempt: number
-    maxRetries: number
-    error: string
-  }
-}
-
-export interface VerificationSkippedEvent extends BaseEvent {
-  type: 'verification_skipped'
-  level: 'warn'
-  data: {
-    actionName: string
-    reason: string
-  }
-}
-
-export interface VerificationWarningsReportEvent extends BaseEvent {
-  type: 'verification_warnings_report'
-  level: 'warn'
-  data: {
-    totalWarnings: number
-    warnings: Array<{
-      actionName: string
-      address: string
-      contractName: string
-      platform: string
-      error: string
-      jobName?: string
-      networkName?: string
-    }>
-  }
-}
-
-// End-of-run summary
-export interface RunSummaryEvent extends BaseEvent {
-  type: 'run_summary'
-  level: 'info' | 'warn'
-  data: {
-    networkCount: number
-    jobCount: number
-    successCount: number
-    failedCount: number
-    skippedCount: number
-    keyContracts: Array<{ job: string; action: string; address: string }>
-  }
-}
-
-// Union type of all events
-export type DeploymentEvent =
-  | DeploymentStartedEvent
-  | DeploymentCompletedEvent
-  | DeploymentFailedEvent
-  | ProjectLoadingStartedEvent
-  | ProjectLoadedEvent
-  | ExecutionPlanEvent
-  | JobStartedEvent
-  | JobCompletedEvent
-  | JobSkippedEvent
-  | ActionStartedEvent
-  | ActionSkippedEvent
-  | ActionCompletedEvent
-  | ActionFailedEvent
-  | ActionInfoEvent
-  | DebugInfoEvent
-  | TemplateEnteredEvent
-  | TemplateExitedEvent
-  | TemplateSetupStartedEvent
-  | TemplateSetupCompletedEvent
-  | TemplateSetupSkippedEvent
-  | TemplateSkippedEvent
-  | PrimitiveActionEvent
-  | TransactionSentEvent
-  | TransactionConfirmedEvent
-  | ContractCreatedEvent
-  | OutputStoredEvent
-  | OutputFileWrittenEvent
-  | NoOutputsEvent
-  | OutputWritingStartedEvent
-  | DuplicateArtifactWarningEvent
-  | MissingNetworkConfigWarningEvent
-  | ContextDisposalWarningEvent
-  | DeprecatedJobsSkippedEvent
-  | NetworkStartedEvent
-  | NetworkSignerInfoEvent
-  | UnhandledRejectionEvent
-  | UncaughtExceptionEvent
-  | CLIErrorEvent
-  | JobExecutionFailedEvent
-  | VerificationStartedEvent
-  | VerificationSubmittedEvent
-  | VerificationCompletedEvent
-  | VerificationFailedEvent
-  | VerificationRetryEvent
-  | VerificationSkippedEvent
-  | VerificationWarningsReportEvent
-  | RunSummaryEvent

package/src/lib/index.ts

@@ -1,17 +0,0 @@
-// Export all types
-export * from './types'
-
-// Export core classes
-export * from './contracts/repository'
-
-// Export all parsers
-export * as parsers from './parsers'
-
-// Export the deployer
-export * from './deployer'
-
-// Export provenance helpers
-export * from './provenance'
-
-// This will be the main entry point for the lib
-// Additional functionality will be added here as the lib grows

package/src/lib/network-loader.ts

@@ -1,90 +0,0 @@
-import * as fs from 'fs/promises'
-import * as path from 'path'
-import { parse as parseYaml } from 'yaml'
-import { Network } from './types'
-
-function isValidNetwork(obj: unknown): obj is Network {
-  return (
-    typeof obj === 'object' &&
-    obj !== null &&
-    'name' in obj &&
-    'chainId' in obj &&
-    'rpcUrl' in obj &&
-    typeof (obj as Record<string, unknown>).name === 'string' &&
-    typeof (obj as Record<string, unknown>).chainId === 'number' &&
-    typeof (obj as Record<string, unknown>).rpcUrl === 'string' &&
-    // supports field is optional and should be an array of strings if present
-    (!('supports' in obj) ||
-     (Array.isArray((obj as Record<string, unknown>).supports) &&
-      ((obj as Record<string, unknown>).supports as unknown[]).every((item: unknown) => typeof item === 'string'))) &&
-    // gasLimit field is optional and should be a number if present
-    (!('gasLimit' in obj) || typeof (obj as Record<string, unknown>).gasLimit === 'number') &&
-    // testnet field is optional and should be a boolean if present
-    (!('testnet' in obj) || typeof (obj as Record<string, unknown>).testnet === 'boolean') &&
-    // evmVersion field is optional and should be a string if present
-    (!('evmVersion' in obj) || typeof (obj as Record<string, unknown>).evmVersion === 'string') &&
-    // params field is optional and must be a plain object if present
-    (!('params' in obj) || (
-      typeof (obj as Record<string, unknown>).params === 'object' &&
-      (obj as Record<string, unknown>).params !== null &&
-      !Array.isArray((obj as Record<string, unknown>).params)
-    ))
-  )
-}
-
-function resolveRpcUrlTokens(rpcUrl: string): string {
-  // Replace placeholders like {{RPC_SOMETHING}} with process.env.RPC_SOMETHING
-  // Only tokens starting with "RPC" are considered. Others are left as-is.
-  const TOKEN_REGEX = /\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g
-  return rpcUrl.replace(TOKEN_REGEX, (match: string, varName: string) => {
-    if (!varName.startsWith('RPC')) {
-      // Leave non-RPC tokens intact
-      return match
-    }
-    const value = process.env[varName]
-    if (typeof value === 'undefined') {
-      // Default to empty string if missing
-      return ''
-    }
-    return value
-  })
-}
-
-/**
- * Loads and validates network configurations from a `networks.yaml` file in the project root.
- * @param projectRoot The root directory of the project.
- * @returns A promise that resolves to an array of Network objects.
- * @throws An error if the file exists but is malformed or contains invalid network data.
- */
-export async function loadNetworks(projectRoot: string): Promise<Network[]> {
-  const filePath = path.join(projectRoot, 'networks.yaml')
-  try {
-    const content = await fs.readFile(filePath, 'utf-8')
-    const parsed = parseYaml(content)
-
-    if (!Array.isArray(parsed)) {
-      throw new Error('networks.yaml must contain an array of network configurations.')
-    }
-
-    const networks: Network[] = []
-    for (const item of parsed) {
-      if (!isValidNetwork(item)) {
-        throw new Error(`Invalid network configuration found in networks.yaml: ${JSON.stringify(item)}`)
-      }
-      // Resolve RPC URL tokens using environment variables
-      const resolvedRpcUrl = resolveRpcUrlTokens(item.rpcUrl)
-      networks.push({ ...item, rpcUrl: resolvedRpcUrl })
-    }
-    return networks
-  } catch (error: unknown) {
-    if (error && typeof error === 'object' && 'code' in error) {
-      const errWithCode = error as { code?: unknown }
-      if (errWithCode.code === 'ENOENT') {
-        // It's okay if the file doesn't exist, just return an empty array.
-        return []
-      }
-    }
-    const message = error instanceof Error ? error.message : String(error)
-    throw new Error(`Failed to load or parse networks.yaml: ${message}`)
-  }
-}

package/src/lib/network-selection.ts

@@ -1,73 +0,0 @@
-import { Network } from './types'
-
-/**
- * Parses a comma-separated selector string into chain IDs, supporting numeric IDs and network names.
- * - Numeric tokens (e.g., "1") are treated as chain IDs
- * - String tokens (e.g., "mainnet") are matched against Network.name case-insensitively
- * - When a name matches multiple networks, all of them are included
- * - Order is preserved by token then by appearance order in `networks`
- * - Duplicates are removed
- *
- * Throws if any token cannot be resolved to at least one chain ID.
- */
-export function resolveSelectedChainIds(
-  selectors: string | undefined,
-  networks: Network[]
-): number[] | undefined {
-  if (selectors == null) return undefined
-  const normalized = String(selectors).trim()
-  if (normalized.length === 0) return undefined
-
-  const tokens = normalized
-    .split(',')
-    .map(t => t.trim())
-    .filter(t => t.length > 0)
-
-  if (tokens.length === 0) return undefined
-
-  const result: number[] = []
-  const seen = new Set<number>()
-
-  for (const token of tokens) {
-    if (/^\d+$/.test(token)) {
-      const id = Number(token)
-      if (!seen.has(id)) {
-        seen.add(id)
-        result.push(id)
-      }
-      continue
-    }
-
-    const tokenLc = token.toLowerCase()
-    const matches = networks.filter(n => n.name.toLowerCase() === tokenLc)
-    if (matches.length === 0) {
-      const available = Array.from(new Set(networks.map(n => n.name))).sort()
-      throw new Error(
-        `Unknown network selector "${token}". Use a chain ID (e.g., 1) or a network name. Available names: ${available.join(', ')}`
-      )
-    }
-    for (const net of matches) {
-      if (!seen.has(net.chainId)) {
-        seen.add(net.chainId)
-        result.push(net.chainId)
-      }
-    }
-  }
-
-  return result
-}
-
-/**
- * Resolves a single selector into one chain ID. If a name maps to multiple networks,
- * returns the first matching network in the order provided.
- */
-export function resolveSingleChainId(
-  selector: string | undefined,
-  networks: Network[]
-): number | undefined {
-  const ids = resolveSelectedChainIds(selector, networks)
-  if (!ids || ids.length === 0) return undefined
-  return ids[0]
-}
-
-