@0xobelisk/sui-cli 1.2.0-pre.12 → 1.2.0-pre.121

package/src/utils/utils.ts

@@ -1,23 +1,51 @@
 import * as fsAsync from 'fs/promises';
 import { mkdirSync, writeFileSync } from 'fs';
-import { dirname } from 'path';
+import { dirname, join as pathJoin } from 'path';
+import * as readline from 'readline';
 import { SUI_PRIVATE_KEY_PREFIX } from '@mysten/sui/cryptography';
 import { FsIibError } from './errors';
 import * as fs from 'fs';
 import chalk from 'chalk';
 import { spawn } from 'child_process';
-import { Dubhe, NetworkType, SuiMoveNormalizedModules } from '@0xobelisk/sui-client';
+import {
+  Dubhe,
+  NetworkType,
+  SuiMoveNormalizedModules,
+  loadMetadata,
+  getDefaultConfig
+} from '@0xobelisk/sui-client';
 import { DubheCliError } from './errors';
-import packageJson from '../../package.json';
+import { Component, MoveType, DubheConfig } from '@0xobelisk/sui-common';
 
 export type DeploymentJsonType = {
   projectName: string;
   network: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+  startCheckpoint: string;
   packageId: string;
-  schemaId: string;
+  /**
+   * The original (first-published) package ID of this dapp.
+   * Derived from type_name::with_defining_ids<DappKey>() in Move, so it is stable
+   * across upgrades and is the canonical identifier used in dapp_key and indexer filtering.
+   * Set once at publish time and never changed during upgrades.
+   */
+  originalPackageId: string;
+  /** Object ID of the Dubhe framework's DappHub shared object. */
+  dappHubId: string;
+  /**
+   * Published package ID of the Dubhe framework used by this deployment.
+   * Populated for localnet (ephemeral deploy); undefined for testnet/mainnet
+   * where the SDK already knows the well-known constant.
+   */
+  frameworkPackageId?: string;
+  /**
+   * Object ID of the DappStorage shared object created by genesis::run.
+   * Required for calling migrate_to_vN during upgrades.
+   */
+  dappStorageId?: string;
   upgradeCap: string;
   version: number;
-  schemas: Record<string, string>;
+  resources: Record<string, Component | MoveType>;
+  enums?: Record<string, string[]>;
 };
 
 export function validatePrivateKey(privateKey: string): false | string {
@@ -76,43 +104,63 @@ export async function getDeploymentJson(
   }
 }
 
-export async function getDeploymentSchemaId(projectPath: string, network: string): Promise<string> {
+export async function getDeploymentDappHubId(
+  projectPath: string,
+  network: string
+): Promise<string> {
   try {
     const data = await fsAsync.readFile(
       `${projectPath}/.history/sui_${network}/latest.json`,
       'utf8'
     );
     const deployment = JSON.parse(data) as DeploymentJsonType;
-    return deployment.schemaId;
-  } catch (error) {
+    return deployment.dappHubId;
+  } catch (_error) {
     return '';
   }
 }
 
-export async function getDubheSchemaId(network: string) {
+export async function getDubheDappHubId(network: string) {
   const path = process.cwd();
   const contractPath = `${path}/src/dubhe`;
 
-  switch (network) {
-    case 'mainnet':
-      return await getDeploymentSchemaId(contractPath, 'mainnet');
-    case 'testnet':
-      return await getDeploymentSchemaId(contractPath, 'testnet');
-    case 'devnet':
-      return await getDeploymentSchemaId(contractPath, 'devnet');
-    case 'localnet':
-      return await getDeploymentSchemaId(contractPath, 'localnet');
-    default:
-      throw new Error(`Invalid network: ${network}`);
+  if (network === 'localnet') {
+    return await getDeploymentDappHubId(contractPath, 'localnet');
   }
+
+  const config = getDefaultConfig(network as NetworkType);
+  if (!config.dappHubId) {
+    throw new Error(
+      `DappHub object ID is not configured for network "${network}". ` +
+        `Update MAINNET_DUBHE_HUB_OBJECT_ID / TESTNET_DUBHE_HUB_OBJECT_ID in @0xobelisk/sui-client.`
+    );
+  }
+  return config.dappHubId;
 }
 
-export async function getOnchainSchemas(
+export async function getOriginalDubhePackageId(network: string) {
+  const path = process.cwd();
+  const contractPath = `${path}/src/dubhe`;
+
+  if (network === 'localnet') {
+    return await getOldPackageId(contractPath, network);
+  }
+
+  const config = getDefaultConfig(network as NetworkType);
+  if (!config.frameworkPackageId) {
+    throw new Error(
+      `Framework package ID is not configured for network "${network}". ` +
+        `Update MAINNET_DUBHE_FRAMEWORK_PACKAGE_ID / TESTNET_DUBHE_FRAMEWORK_PACKAGE_ID in @0xobelisk/sui-client.`
+    );
+  }
+  return config.frameworkPackageId;
+}
+export async function getOnchainResources(
   projectPath: string,
   network: string
-): Promise<Record<string, string>> {
+): Promise<Record<string, Component | MoveType>> {
   const deployment = await getDeploymentJson(projectPath, network);
-  return deployment.schemas;
+  return deployment.resources;
 }
 
 export async function getVersion(projectPath: string, network: string): Promise<number> {
@@ -133,9 +181,22 @@ export async function getOldPackageId(projectPath: string, network: string): Pro
   return deployment.packageId;
 }
 
-export async function getSchemaId(projectPath: string, network: string): Promise<string> {
+export async function getDappHubId(projectPath: string, network: string): Promise<string> {
+  const deployment = await getDeploymentJson(projectPath, network);
+  return deployment.dappHubId;
+}
+
+export async function getFrameworkPackageIdFromDeployment(
+  projectPath: string,
+  network: string
+): Promise<string | undefined> {
+  const deployment = await getDeploymentJson(projectPath, network);
+  return deployment.frameworkPackageId;
+}
+
+export async function getDappStorageId(projectPath: string, network: string): Promise<string> {
   const deployment = await getDeploymentJson(projectPath, network);
-  return deployment.schemaId;
+  return deployment.dappStorageId ?? '';
 }
 
 export async function getUpgradeCap(projectPath: string, network: string): Promise<string> {
@@ -143,34 +204,78 @@ export async function getUpgradeCap(projectPath: string, network: string): Promi
   return deployment.upgradeCap;
 }
 
-export function saveContractData(
+export async function getStartCheckpoint(projectPath: string, network: string): Promise<string> {
+  const deployment = await getDeploymentJson(projectPath, network);
+  return deployment.startCheckpoint;
+}
+
+export async function saveContractData(
   projectName: string,
   network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  startCheckpoint: string,
   packageId: string,
-  schemaId: string,
+  originalPackageId: string,
+  dappHubId: string,
   upgradeCap: string,
   version: number,
-  schemas: Record<string, string>
+  resources: Record<string, Component | MoveType>,
+  enums?: Record<string, string[]>,
+  frameworkPackageId?: string,
+  dappStorageId?: string
 ) {
   const DeploymentData: DeploymentJsonType = {
     projectName,
     network,
+    startCheckpoint,
     packageId,
-    schemaId,
-    schemas,
+    originalPackageId,
+    dappHubId,
+    frameworkPackageId,
+    dappStorageId,
     upgradeCap,
-    version
+    version,
+    resources,
+    enums
   };
 
   const path = process.cwd();
   const storeDeploymentData = JSON.stringify(DeploymentData, null, 2);
-  writeOutput(
+  await writeOutput(
     storeDeploymentData,
     `${path}/src/${projectName}/.history/sui_${network}/latest.json`,
     'Update deploy log'
   );
 }
 
+export async function saveMetadata(
+  projectName: string,
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  packageId: string,
+  fullnodeUrls?: string[]
+) {
+  const path = process.cwd();
+
+  // Save metadata files
+  try {
+    const metadata = await loadMetadata(network, packageId, fullnodeUrls);
+    if (metadata) {
+      const metadataJson = JSON.stringify(metadata, null, 2);
+
+      // Save packageId-specific metadata file
+      await writeOutput(
+        metadataJson,
+        `${path}/src/${projectName}/.history/sui_${network}/${packageId}.json`,
+        'Save package metadata'
+      );
+
+      // Save latest metadata.json
+      await writeOutput(metadataJson, `${path}/metadata.json`, 'Save latest metadata');
+    }
+  } catch (error) {
+    console.warn(chalk.yellow(`Warning: Failed to save metadata: ${error}`));
+  }
+}
+
 export async function writeOutput(
   output: string,
   fullOutputPath: string,
@@ -184,55 +289,530 @@ export async function writeOutput(
   }
 }
 
-function getDubheDependency(network: 'mainnet' | 'testnet' | 'devnet' | 'localnet'): string {
-  switch (network) {
-    case 'localnet':
-      return 'Dubhe = { local = "../dubhe" }';
-    case 'testnet':
-      return `Dubhe = { git = "https://github.com/0xobelisk/dubhe-wip.git", subdir = "packages/sui-framework/contracts/dubhe", rev = "${packageJson.version}" }`;
-    case 'mainnet':
-      return `Dubhe = { git = "https://github.com/0xobelisk/dubhe-wip.git", subdir = "packages/sui-framework/src/dubhe", rev = "${packageJson.version}" }`;
-    default:
-      throw new Error(`Unsupported network: ${network}`);
-  }
-}
-
 export async function updateDubheDependency(
   filePath: string,
   network: 'mainnet' | 'testnet' | 'devnet' | 'localnet'
 ) {
-  const fileContent = fs.readFileSync(filePath, 'utf-8');
-  const newDependency = getDubheDependency(network);
-  const updatedContent = fileContent.replace(/Dubhe = \{.*\}/, newDependency);
-  fs.writeFileSync(filePath, updatedContent, 'utf-8');
-  console.log(`Updated Dubhe dependency in ${filePath} for ${network}.`);
+  // With the new --build-env mechanism, we keep Dubhe as local dependency for all networks.
+  // The Published.toml in ../dubhe resolves the correct on-chain address per environment.
+  // This function is kept for backward compatibility but is a no-op for non-localnet.
+  if (network === 'localnet') {
+    const fileContent = fs.readFileSync(filePath, 'utf-8');
+    const localDependency = 'Dubhe = { local = "../dubhe" }';
+    if (!fileContent.includes(localDependency)) {
+      const updatedContent = fileContent.replace(/Dubhe = \{[^}]*\}/, localDependency);
+      fs.writeFileSync(filePath, updatedContent, 'utf-8');
+      console.log(`Ensured local Dubhe dependency in ${filePath} for localnet.`);
+    }
+  }
+}
+
+// Published.toml management for the new Sui CLI (v1.44+) publishing mechanism.
+// Published.toml tracks on-chain package addresses per environment.
+// It SHOULD be committed to source control.
+
+interface PublishedEntry {
+  chainId: string;
+  publishedAt: string;
+  originalId: string;
+  version: number;
+}
+
+export function readPublishedToml(packagePath: string): Record<string, PublishedEntry> {
+  const filePath = pathJoin(packagePath, 'Published.toml');
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const result: Record<string, PublishedEntry> = {};
+
+  const sectionRegex = /\[published\.(\w+)\]([\s\S]*?)(?=\[published\.|$)/g;
+  let match;
+  while ((match = sectionRegex.exec(content)) !== null) {
+    const env = match[1];
+    const body = match[2];
+    const getValue = (key: string) => {
+      const m = body.match(new RegExp(`${key}\\s*=\\s*"([^"]*)"`));
+      return m ? m[1] : '';
+    };
+    const versionMatch = body.match(/version\s*=\s*(\d+)/);
+    result[env] = {
+      chainId: getValue('chain-id'),
+      publishedAt: getValue('published-at'),
+      originalId: getValue('original-id'),
+      version: versionMatch ? parseInt(versionMatch[1], 10) : 1
+    };
+  }
+  return result;
+}
+
+export function writePublishedToml(
+  packagePath: string,
+  entries: Record<string, PublishedEntry>
+): void {
+  const filePath = pathJoin(packagePath, 'Published.toml');
+  let content =
+    '# Generated by Move\n' +
+    '# This file contains metadata about published versions of this package in different environments\n' +
+    '# This file SHOULD be committed to source control\n';
+
+  for (const [env, entry] of Object.entries(entries)) {
+    content += `\n[published.${env}]\n`;
+    content += `chain-id = "${entry.chainId}"\n`;
+    content += `published-at = "${entry.publishedAt}"\n`;
+    content += `original-id = "${entry.originalId}"\n`;
+    content += `version = ${entry.version}\n`;
+  }
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+export function updatePublishedToml(
+  packagePath: string,
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  chainId: string,
+  packageId: string,
+  originalId?: string,
+  version?: number
+): void {
+  const entries = readPublishedToml(packagePath);
+  const existing = entries[network];
+
+  entries[network] = {
+    chainId,
+    publishedAt: packageId,
+    originalId: originalId ?? existing?.originalId ?? packageId,
+    version: version ?? (existing ? existing.version + 1 : 1)
+  };
+
+  writePublishedToml(packagePath, entries);
+  console.log(`Updated Published.toml in ${packagePath} for ${network}.`);
+}
+
+export function getPublishedTomlEntry(
+  packagePath: string,
+  network: string
+): PublishedEntry | undefined {
+  const entries = readPublishedToml(packagePath);
+  return entries[network];
+}
+
+/**
+ * Syncs the Dubhe framework address in `src/dubhe/Published.toml` with the
+ * canonical package ID from the SDK's `getDefaultConfig` for the given network.
+ *
+ * This prevents `VMVerificationOrDeserializationError` during `publish` and
+ * `upgrade` when the framework has been redeployed on testnet/mainnet but the
+ * local `Published.toml` still references the old address.  The function is a
+ * no-op for localnet and devnet (no stable canonical address exists there).
+ *
+ * @param contractsRootDir - The contracts working directory (process.cwd() in CLI context)
+ * @param network          - Target network
+ * @param chainId          - Live chain identifier obtained from the node
+ */
+export function syncDubheFrameworkAddress(
+  contractsRootDir: string,
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  chainId: string
+): void {
+  if (network === 'localnet' || network === 'devnet') return;
+
+  const frameworkPackageId = getDefaultConfig(network as NetworkType).frameworkPackageId;
+  if (!frameworkPackageId) return;
+
+  const dubhePath = pathJoin(contractsRootDir, 'src', 'dubhe');
+  if (!fs.existsSync(dubhePath)) return;
+
+  const existing = getPublishedTomlEntry(dubhePath, network);
+  if (existing?.publishedAt === frameworkPackageId) return;
+
+  updatePublishedToml(dubhePath, network, chainId, frameworkPackageId, frameworkPackageId, 1);
+  console.log(
+    chalk.gray(
+      `  ├─ Auto-synced dubhe framework address for ${network}: ${frameworkPackageId.slice(
+        0,
+        10
+      )}...`
+    )
+  );
+}
+
+export function clearPublishedTomlEntry(
+  packagePath: string,
+  network: string
+): PublishedEntry | undefined {
+  const entries = readPublishedToml(packagePath);
+  const existing = entries[network];
+  if (!existing) return undefined;
+
+  entries[network] = {
+    ...existing,
+    publishedAt: '0x0000000000000000000000000000000000000000000000000000000000000000',
+    originalId: '0x0000000000000000000000000000000000000000000000000000000000000000'
+  };
+  writePublishedToml(packagePath, entries);
+  return existing;
+}
+
+export function restorePublishedTomlEntry(
+  packagePath: string,
+  network: string,
+  entry: PublishedEntry
+): void {
+  const entries = readPublishedToml(packagePath);
+  entries[network] = entry;
+  writePublishedToml(packagePath, entries);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Ephemeral publication file (Pub.<env>.toml)
+//
+// Per the Sui package management docs (v1.63+), localnet / devnet deployments
+// should use ephemeral publication files rather than the shared Published.toml.
+// The ephemeral file holds the localnet addresses so that subsequent builds
+// (e.g. for upgrades) can resolve local dependencies correctly.
+//
+// Reference: https://docs.sui.io/guides/developer/packages/move-package-management
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface EphemeralPubEntry {
+  /** Absolute path to the package source directory */
+  source: string;
+  /** Current on-chain address of the package */
+  publishedAt: string;
+  /** Address of the first published version (same as publishedAt for v1) */
+  originalId: string;
+  /** Object ID of the upgrade capability */
+  upgradeCap: string;
+  /** Package version (required by Sui CLI parser) */
+  version?: number;
+}
+
+/**
+ * Return the canonical path for the ephemeral publication file.
+ * For localnet this is <contractsDir>/Pub.localnet.toml.
+ */
+export function getEphemeralPubFilePath(contractsDir: string, network: string): string {
+  return pathJoin(contractsDir, `Pub.${network}.toml`);
+}
+
+/**
+ * Update (or create) an entry in the ephemeral publication file.
+ * Preserves existing entries for other packages.
+ */
+export function updateEphemeralPubFile(
+  pubfilePath: string,
+  chainId: string,
+  buildEnv: string,
+  entry: EphemeralPubEntry
+): void {
+  const existing: EphemeralPubEntry[] = [];
+  // Always use the provided buildEnv and chainId parameters.
+  // The chainId passed in comes from the live network and is authoritative.
+  const currentBuildEnv = buildEnv;
+  const currentChainId = chainId;
+
+  if (fs.existsSync(pubfilePath)) {
+    const content = fs.readFileSync(pubfilePath, 'utf-8');
+
+    // Check if the file was written for a different chain (e.g. previous localnet run).
+    // If chain-id changed, discard all existing entries — they belong to a dead chain.
+    const chainIdMatch = content.match(/^chain-id\s*=\s*"([^"]*)"/m);
+    const fileChainId = chainIdMatch ? chainIdMatch[1] : '';
+    const chainChanged = fileChainId !== '' && fileChainId !== chainId;
+
+    if (!chainChanged) {
+      // Same chain: parse existing [[published]] blocks and preserve them.
+      // source field is an inline table: source = { local = "..." }
+      const blockRegex = /\[\[published\]\]([\s\S]*?)(?=\[\[published\]\]|$)/g;
+      let blockMatch;
+      while ((blockMatch = blockRegex.exec(content)) !== null) {
+        const block = blockMatch[1];
+        const get = (key: string) => {
+          const m = block.match(new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, 'm'));
+          return m ? m[1] : '';
+        };
+        // source = { local = "/path/to/package" }
+        const srcMatch = block.match(/^source\s*=\s*\{\s*local\s*=\s*"([^"]*)"\s*\}/m);
+        const src = srcMatch ? srcMatch[1] : '';
+        if (src) {
+          existing.push({
+            source: src,
+            publishedAt: get('published-at'),
+            originalId: get('original-id'),
+            upgradeCap: get('upgrade-cap')
+          });
+        }
+      }
+    } else {
+      console.log(`  Pub file chain-id changed (${fileChainId} → ${chainId}), resetting entries.`);
+    }
+  }
+
+  // Update override or add the entry
+  const idx = existing.findIndex((e) => e.source === entry.source);
+  if (idx >= 0) {
+    existing[idx] = entry;
+  } else {
+    existing.push(entry);
+  }
+
+  // Write the file
+  let content =
+    '# generated by dubhe cli\n' +
+    '# this file contains metadata from ephemeral publications\n' +
+    '# this file should NOT be committed to source control\n\n';
+  content += `build-env = "${currentBuildEnv}"\n`;
+  content += `chain-id = "${currentChainId}"\n`;
+
+  for (const e of existing) {
+    content += '\n[[published]]\n';
+    // source must be a LocalDepInfo struct (not a plain string)
+    content += `source = { local = "${e.source}" }\n`;
+    content += `published-at = "${e.publishedAt}"\n`;
+    content += `original-id = "${e.originalId}"\n`;
+    content += `upgrade-cap = "${e.upgradeCap}"\n`;
+    // version is required by Sui CLI parser (even though docs omit it)
+    content += `version = 1\n`;
+  }
+
+  fs.writeFileSync(pubfilePath, content, 'utf-8');
+  console.log(
+    `  Updated ${pathJoin(pubfilePath.split('/').slice(-1)[0])} for ${
+      entry.source.split('/').slice(-1)[0]
+    }.`
+  );
+}
+
+async function checkRpcAvailability(rpcUrl: string): Promise<boolean> {
+  try {
+    const response = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'sui_getLatestCheckpointSequenceNumber',
+        params: []
+      })
+    });
+
+    if (!response.ok) {
+      return false;
+    }
+
+    const data = await response.json();
+    return !data.error;
+  } catch (_error) {
+    return false;
+  }
+}
+
+export async function addEnv(
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  rpcUrl?: string
+): Promise<void> {
+  const rpcMap = {
+    localnet: 'http://127.0.0.1:9000',
+    devnet: 'https://fullnode.devnet.sui.io:443/',
+    testnet: 'https://fullnode.testnet.sui.io:443/',
+    mainnet: 'https://fullnode.mainnet.sui.io:443/'
+  };
+
+  const resolvedRpcUrl = rpcUrl || rpcMap[network];
+
+  // Check RPC availability first
+  const isRpcAvailable = await checkRpcAvailability(resolvedRpcUrl);
+  if (!isRpcAvailable) {
+    throw new Error(
+      `RPC endpoint ${resolvedRpcUrl} is not available. Please check your network connection or try again later.`
+    );
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    let errorOutput = '';
+    let stdoutOutput = '';
+
+    const suiProcess = spawn(
+      'sui',
+      ['client', 'new-env', '--alias', network, '--rpc', resolvedRpcUrl],
+      {
+        env: { ...process.env },
+        stdio: 'pipe'
+      }
+    );
+
+    // Capture standard output
+    suiProcess.stdout.on('data', (data) => {
+      stdoutOutput += data.toString();
+    });
+
+    // Capture error output
+    suiProcess.stderr.on('data', (data) => {
+      errorOutput += data.toString();
+    });
+
+    // Handle process errors (e.g., command not found)
+    suiProcess.on('error', (error) => {
+      console.error(chalk.red(`\n❌ Failed to execute sui command: ${error.message}`));
+      reject(new Error(`Failed to execute sui command: ${error.message}`));
+    });
+
+    // Handle process exit
+    suiProcess.on('exit', (code, signal) => {
+      // Check if "already exists" message is present
+      if (errorOutput.includes('already exists') || stdoutOutput.includes('already exists')) {
+        console.log(chalk.yellow(`Environment ${network} already exists, proceeding...`));
+        resolve();
+        return;
+      }
+
+      if (code === 0) {
+        console.log(chalk.green(`Successfully added environment ${network}`));
+        resolve();
+      } else {
+        let finalError: string;
+        if (code === null) {
+          // Process was killed by a signal
+          finalError =
+            errorOutput ||
+            stdoutOutput ||
+            `Process was terminated by signal ${signal || 'unknown'}`;
+        } else {
+          finalError = errorOutput || stdoutOutput || `Process exited with code ${code}`;
+        }
+        console.error(chalk.red(`\n❌ Failed to add environment ${network}`));
+        console.error(chalk.red(`  └─ ${finalError.trim()}`));
+        reject(new Error(finalError));
+      }
+    });
+  });
 }
-export async function switchEnv(network: 'mainnet' | 'testnet' | 'devnet' | 'localnet') {
+
+export type NetworkAlias = 'testnet' | 'mainnet' | 'devnet' | 'localnet';
+
+export interface Endpoint {
+  alias: NetworkAlias;
+  rpc: string;
+  ws: string | null;
+  basic_auth: { username: string; password: string } | null;
+}
+
+// mainly is a tuple of [endpoint list, current active alias]
+export type ConfigTuple = [Endpoint[], NetworkAlias];
+
+export async function envsJSON(): Promise<ConfigTuple> {
   try {
+    return new Promise<ConfigTuple>((resolve, reject) => {
+      let errorOutput = '';
+      let stdoutOutput = '';
+
+      const suiProcess = spawn('sui', ['client', 'envs', '--json'], {
+        env: { ...process.env },
+        stdio: 'pipe'
+      });
+
+      suiProcess.stdout.on('data', (data) => {
+        stdoutOutput += data.toString();
+      });
+
+      suiProcess.stderr.on('data', (data) => {
+        errorOutput += data.toString();
+      });
+
+      suiProcess.on('error', (error) => {
+        console.error(chalk.red(`\n❌ Failed to execute sui command: ${error.message}`));
+        reject(new Error(`Failed to execute sui command: ${error.message}`));
+      });
+
+      suiProcess.on('exit', (code, signal) => {
+        if (code === 0) {
+          resolve(JSON.parse(stdoutOutput) as ConfigTuple);
+        } else {
+          let finalError: string;
+          if (code === null) {
+            // Process was killed by a signal
+            finalError =
+              errorOutput ||
+              stdoutOutput ||
+              `Process was terminated by signal ${signal || 'unknown'}`;
+          } else {
+            finalError = errorOutput || stdoutOutput || `Process exited with code ${code}`;
+          }
+          console.error(chalk.red(`\n❌ Failed to get envs`));
+          console.error(chalk.red(`  └─ ${finalError.trim()}`));
+          reject(new Error(finalError));
+        }
+      });
+    });
+  } catch (error) {
+    // Re-throw the error for the caller to handle
+    throw error;
+  }
+}
+
+export async function getDefaultNetwork(): Promise<NetworkAlias> {
+  const [_, currentAlias] = await envsJSON();
+  return currentAlias as NetworkAlias;
+}
+
+export async function switchEnv(
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  rpcUrl?: string
+) {
+  try {
+    // First, try to add the environment
+    await addEnv(network, rpcUrl);
+
+    // Then switch to the specified environment
     return new Promise<void>((resolve, reject) => {
+      let errorOutput = '';
+      let stdoutOutput = '';
+
       const suiProcess = spawn('sui', ['client', 'switch', '--env', network], {
         env: { ...process.env },
         stdio: 'pipe'
       });
 
+      suiProcess.stdout.on('data', (data) => {
+        stdoutOutput += data.toString();
+      });
+
+      suiProcess.stderr.on('data', (data) => {
+        errorOutput += data.toString();
+      });
+
       suiProcess.on('error', (error) => {
-        console.error(chalk.red('\n❌ Failed to Switch Env'));
-        console.error(chalk.red(`  Error: ${error.message}`));
-        reject(error); // Reject promise on error
+        console.error(chalk.red(`\n❌ Failed to execute sui command: ${error.message}`));
+        reject(new Error(`Failed to execute sui command: ${error.message}`));
       });
 
-      suiProcess.on('exit', (code) => {
-        if (code !== 0) {
-          console.error(chalk.red(`\n❌ Process exited with code: ${code}`));
-          reject(new Error(`Process exited with code: ${code}`));
+      suiProcess.on('exit', (code, signal) => {
+        if (code === 0) {
+          console.log(chalk.green(`Successfully switched to environment ${network}`));
+          resolve();
         } else {
-          resolve(); // Resolve promise on successful exit
+          let finalError: string;
+          if (code === null) {
+            // Process was killed by a signal
+            finalError =
+              errorOutput ||
+              stdoutOutput ||
+              `Process was terminated by signal ${signal || 'unknown'}`;
+          } else {
+            finalError = errorOutput || stdoutOutput || `Process exited with code ${code}`;
+          }
+          console.error(chalk.red(`\n❌ Failed to switch to environment ${network}`));
+          console.error(chalk.red(`  └─ ${finalError.trim()}`));
+          reject(new Error(finalError));
         }
       });
     });
   } catch (error) {
-    console.error(chalk.red('\n❌ Failed to Switch Env'));
-    console.error(chalk.red(`  └─ Error: ${error}`));
+    // Re-throw the error for the caller to handle
+    throw error;
   }
 }
 
@@ -258,17 +838,415 @@ export function loadKey(): string {
 export function initializeDubhe({
   network,
   packageId,
-  metadata
+  metadata,
+  fullnodeUrls
 }: {
   network: NetworkType;
   packageId?: string;
   metadata?: SuiMoveNormalizedModules;
+  fullnodeUrls?: string[];
 }): Dubhe {
   const privateKey = loadKey();
   return new Dubhe({
     networkType: network,
     secretKey: privateKey,
     packageId,
-    metadata
+    metadata,
+    fullnodeUrls
   });
 }
+
+export function generateConfigJson(config: DubheConfig): string {
+  const serializeFields = (fields: Record<string, unknown> = {}) =>
+    Object.entries(fields).map(([fieldName, fieldType]) => ({
+      [fieldName]: fieldType
+    }));
+
+  const resources = Object.entries(config.resources ?? {}).map(([name, resource]) => {
+    // Simple type shorthand (e.g., counter1: 'u32') – entity-keyed by account (entity_id: String).
+    if (typeof resource === 'string') {
+      return {
+        [name]: {
+          fields: [{ entity_id: 'String' }, { value: resource }],
+          keys: ['entity_id'],
+          offchain: false
+        }
+      };
+    }
+
+    // Empty resource object – only the implicit entity key.
+    if (Object.keys(resource as object).length === 0) {
+      return {
+        [name]: {
+          fields: [{ entity_id: 'String' }],
+          keys: ['entity_id'],
+          offchain: false
+        }
+      };
+    }
+
+    const fields = (resource as any).fields || {};
+    const keys = (resource as any).keys || [];
+    const offchain = (resource as any).offchain ?? false;
+
+    // Full Component format with no explicit keys: auto-inject 'entity_id: String'.
+    if (keys.length === 0) {
+      const fieldEntries = Object.entries(fields);
+      const orderedFields: [string, unknown][] = [['entity_id', 'String'], ...fieldEntries];
+      return {
+        [name]: {
+          fields: orderedFields.map(([fieldName, fieldType]) => ({
+            [fieldName]: fieldType
+          })),
+          keys: ['entity_id'],
+          offchain: offchain
+        }
+      };
+    }
+
+    // Full Component format with explicit custom keys: inject 'entity_id: String' as the first
+    // field and first key so that key_tuple[0] (the BCS-encoded account injected by the indexer)
+    // maps correctly, followed by the user-defined keys.
+    const fieldEntries = Object.entries(fields);
+    const orderedFields: [string, unknown][] = [['entity_id', 'String'], ...fieldEntries];
+    return {
+      [name]: {
+        fields: orderedFields.map(([fieldName, fieldType]) => ({
+          [fieldName]: fieldType
+        })),
+        keys: ['entity_id', ...keys],
+        offchain: offchain
+      }
+    };
+  });
+
+  // handle enums
+  const enums = Object.entries(config.enums || {}).map(([name, enumFields]) => {
+    // Sort enum values by first letter
+    const sortedFields = enumFields.sort((a, b) => a.localeCompare(b)).map((value) => value);
+
+    return {
+      [name]: sortedFields
+    };
+  });
+
+  const objects = Object.entries(config.objects ?? {}).map(([name, object]) => ({
+    [name]: {
+      fields: serializeFields(object.fields),
+      accepts: object.accepts ?? [],
+      acceptsFrom: object.acceptsFrom ?? [],
+      adminOnly: object.adminOnly ?? false
+    }
+  }));
+
+  const scenes = Object.entries(config.scenes ?? {}).map(([name, scene]) => ({
+    [name]: {
+      fields: serializeFields(scene.fields),
+      authorization: scene.authorization,
+      accepts: scene.accepts ?? [],
+      acceptsFrom: scene.acceptsFrom ?? []
+    }
+  }));
+
+  const permits = Object.entries(config.permits ?? {}).map(([name, permit]) => ({
+    [name]: permit ?? {}
+  }));
+
+  return JSON.stringify(
+    {
+      resources,
+      objects,
+      scenes,
+      permits,
+      enums
+    },
+    null,
+    2
+  );
+}
+
+/**
+ * Updates the dubhe address and published-at in Move.toml file
+ * @param path - Directory path containing Move.toml file
+ * @param packageAddress - New dubhe package address to set
+ *
+ * Logic:
+ * - If packageAddress is "0x0": only set dubhe = "0x0", remove published-at line
+ * - Otherwise: set both dubhe and published-at to packageAddress
+ */
+export function updateMoveTomlAddress(path: string, packageAddress: string) {
+  const moveTomlPath = `${path}/Move.toml`;
+  const moveTomlContent = fs.readFileSync(moveTomlPath, 'utf-8');
+
+  let updatedContent = moveTomlContent;
+
+  if (packageAddress === '0x0') {
+    // Case 1: Address is "0x0" - set dubhe to "0x0" and remove published-at line
+    updatedContent = updatedContent.replace(/dubhe\s*=\s*"[^"]*"/, `dubhe = "0x0"`);
+
+    // Remove published-at line (including the line break)
+    updatedContent = updatedContent.replace(/published-at\s*=\s*"[^"]*"\r?\n?/, '');
+  } else {
+    // Case 2: Address is not "0x0" - set both dubhe and published-at
+    updatedContent = updatedContent.replace(/dubhe\s*=\s*"[^"]*"/, `dubhe = "${packageAddress}"`);
+
+    // Check if published-at already exists
+    if (/published-at\s*=\s*"[^"]*"/.test(updatedContent)) {
+      // Replace existing published-at
+      updatedContent = updatedContent.replace(
+        /published-at\s*=\s*"[^"]*"/,
+        `published-at = "${packageAddress}"`
+      );
+    } else {
+      // Add published-at after [package] line if it doesn't exist
+      updatedContent = updatedContent.replace(
+        /(\[package\][^\n]*\n)/,
+        `$1published-at = "${packageAddress}"\n`
+      );
+    }
+  }
+
+  fs.writeFileSync(moveTomlPath, updatedContent, 'utf-8');
+}
+
+export function updateGenesisUpgradeFunction(path: string, tables: string[]) {
+  const genesisPath = `${path}/sources/codegen/genesis.move`;
+  const genesisContent = fs.readFileSync(genesisPath, 'utf-8');
+
+  // Match the first pair of // ========================================== lines (with any content, including empty, between them)
+  const separatorRegex =
+    /(\/\/ ==========================================)[\s\S]*?(\/\/ ==========================================)/;
+  const match = genesisContent.match(separatorRegex);
+
+  if (!match) {
+    throw new Error('Could not find separator comments in genesis.move');
+  }
+
+  // Generate new table registration code
+  const registerTablesCode = tables
+    .map((table) => `    ${table}::register_table(dapp_hub, ctx);`)
+    .join('\n');
+
+  // Build new content, preserve separators, replace middle content
+  const newContent = `${match[1]}\n${registerTablesCode}\n${match[2]}`;
+
+  // Replace matched content
+  const updatedContent = genesisContent.replace(separatorRegex, newContent);
+
+  fs.writeFileSync(genesisPath, updatedContent, 'utf-8');
+}
+
+/**
+ * Appends a `migrate_to_vN` entry function to the package's migrate.move and
+ * bumps `ON_CHAIN_VERSION` to `newVersion`.
+ *
+ * Called by upgradeHandler when new resources are detected (pendingMigration.length > 0).
+ * The generated function:
+ *   1. Reads the new package ID via `dapp_key::package_id()` — available on the new package.
+ *   2. Reads the target version via `migrate::on_chain_version()` — equals newVersion after
+ *      this function bumps the constant.
+ *   3. Calls `dapp_system::upgrade_dapp` to register the new package ID and bump
+ *      `DappStorage.version`.
+ *   4. Calls `genesis::migrate` for any custom migration logic (extension point).
+ *
+ * `upgrade_dapp` accepts the new package's DappKey because its check was changed to compare
+ * the caller's package ID against the registered list OR the incoming new_package_id, rather
+ * than doing a full type-string comparison that would always fail after an upgrade.
+ */
+export function appendMigrateFunction(
+  projectPath: string,
+  packageName: string,
+  newVersion: number
+): void {
+  const migratePath = `${projectPath}/sources/scripts/migrate.move`;
+  if (!fs.existsSync(migratePath)) {
+    throw new Error(`migrate.move not found at ${migratePath}`);
+  }
+
+  let content = fs.readFileSync(migratePath, 'utf-8');
+
+  // Idempotency: skip entirely if the function already exists
+  if (content.includes(`migrate_to_v${newVersion}`)) {
+    return;
+  }
+
+  // ── Step 1: bump ON_CHAIN_VERSION to newVersion ──────────────────────────────
+  // Replace the first `ON_CHAIN_VERSION: u32 = <N>` constant in the file.
+  // This ensures on_chain_version() returns the correct value when upgrade_dapp
+  // reads it inside the generated migrate_to_vN function.
+  content = content.replace(
+    /const ON_CHAIN_VERSION:\s*u32\s*=\s*\d+\s*;/,
+    `const ON_CHAIN_VERSION: u32 = ${newVersion};`
+  );
+
+  // ── Step 2: append migrate_to_vN ─────────────────────────────────────────────
+  // new_package_id must be passed as a parameter because type_name::get<T>() in
+  // Sui Move always returns the ORIGINAL (genesis) package ID, not the upgraded one.
+  // The TypeScript upgradeHandler supplies the actual new package ID after the upgrade
+  // transaction completes and the on-chain package address is known.
+  const migrateFunction = `
+    public entry fun migrate_to_v${newVersion}(
+        dapp_hub: &mut dubhe::dapp_service::DappHub,
+        dapp_storage: &mut dubhe::dapp_service::DappStorage,
+        new_package_id: address,
+        ctx: &mut TxContext
+    ) {
+        let new_version = ${packageName}::migrate::on_chain_version();
+        dubhe::dapp_system::upgrade_dapp<${packageName}::dapp_key::DappKey>(
+            dapp_hub, dapp_storage, new_package_id, new_version, ctx
+        );
+        ${packageName}::genesis::migrate(dapp_hub, dapp_storage, ctx);
+    }
+`;
+
+  // Insert the new function before the closing brace of the module
+  const closingBraceIdx = content.lastIndexOf('}');
+  if (closingBraceIdx === -1) {
+    throw new Error(`Could not find closing brace in ${migratePath}`);
+  }
+
+  const updated =
+    content.slice(0, closingBraceIdx) + migrateFunction + content.slice(closingBraceIdx);
+  fs.writeFileSync(migratePath, updated, 'utf-8');
+}
+
+// ---------------------------------------------------------------------------
+// Guard lint
+// ---------------------------------------------------------------------------
+
+export type MissingGuardResult = {
+  /** Relative path to the Move source file (for display). */
+  file: string;
+  /** Name of the entry function missing the guard. */
+  fn: string;
+};
+
+/**
+ * Scans every `*.move` file under `<projectPath>/sources/systems/` and returns
+ * the list of `public entry fun` declarations that:
+ *   1. Accept a `DappStorage` parameter (so a version check is applicable), AND
+ *   2. Do NOT call `ensure_latest_version` anywhere in their body.
+ *
+ * The implementation uses brace-balancing to extract each function body rather
+ * than a full AST parse, which is sufficient for this structural check.
+ */
+export function lintSystemGuards(projectPath: string): MissingGuardResult[] {
+  const systemsDir = pathJoin(projectPath, 'sources', 'systems');
+  if (!fs.existsSync(systemsDir)) return [];
+
+  const results: MissingGuardResult[] = [];
+  const files = fs.readdirSync(systemsDir).filter((f) => f.endsWith('.move'));
+
+  for (const file of files) {
+    const fullPath = pathJoin(systemsDir, file);
+    const src = fs.readFileSync(fullPath, 'utf-8');
+
+    // Find every `public entry fun <name>` position.
+    const entryFunRe = /public\s+entry\s+fun\s+(\w+)\s*\(/g;
+    let match: RegExpExecArray | null;
+
+    while ((match = entryFunRe.exec(src)) !== null) {
+      const fnName = match[1];
+      const parenStart = match.index + match[0].length - 1; // position of '('
+
+      // Extract the parameter list (between the outermost parentheses).
+      let depth = 0;
+      let parenEnd = parenStart;
+      for (let i = parenStart; i < src.length; i++) {
+        if (src[i] === '(') depth++;
+        else if (src[i] === ')') {
+          depth--;
+          if (depth === 0) {
+            parenEnd = i;
+            break;
+          }
+        }
+      }
+      const paramList = src.slice(parenStart + 1, parenEnd);
+
+      // Only flag functions that receive a DappStorage parameter.
+      if (!/DappStorage/.test(paramList)) continue;
+
+      // Extract the function body (between the outermost braces after the params).
+      const braceStart = src.indexOf('{', parenEnd);
+      if (braceStart === -1) continue;
+
+      depth = 0;
+      let braceEnd = braceStart;
+      for (let i = braceStart; i < src.length; i++) {
+        if (src[i] === '{') depth++;
+        else if (src[i] === '}') {
+          depth--;
+          if (depth === 0) {
+            braceEnd = i;
+            break;
+          }
+        }
+      }
+      const body = src.slice(braceStart, braceEnd + 1);
+
+      if (!/ensure_latest_version/.test(body)) {
+        results.push({ file, fn: fnName });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Formats lint results as a human-readable warning block.
+ * Returns an empty string when there are no issues.
+ */
+export function formatLintWarnings(results: MissingGuardResult[]): string {
+  if (results.length === 0) return '';
+  const lines: string[] = [
+    chalk.yellow('⚠️  Missing ensure_latest_version in the following entry functions:'),
+    chalk.yellow('   Old-package callers can still invoke these functions after an upgrade.'),
+    ''
+  ];
+  for (const r of results) {
+    lines.push(chalk.yellow(`   • ${r.file}  →  ${r.fn}()`));
+  }
+  lines.push('');
+  lines.push(
+    chalk.yellow(
+      '   Fix: add  dubhe::dapp_system::ensure_latest_version(dapp_storage);  at the top of each function.'
+    )
+  );
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Prompts the user for a yes/no confirmation on stdout/stdin.
+ * Resolves `true` for "y/Y", `false` for everything else.
+ */
+export function confirm(question: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(chalk.yellow(`${question} [y/N] `), (answer: string) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+/**
+ * Append a new package ID to the `package_ids` array in dubhe.config.json.
+ * Idempotent — does nothing if the ID is already present or the file does not exist.
+ * Called by upgradeHandler after a successful on-chain upgrade so the indexer
+ * can verify event.type_.address against all known package versions on next startup.
+ */
+export function appendPackageIdToConfig(configJsonPath: string, newPackageId: string): void {
+  if (!fs.existsSync(configJsonPath)) return;
+  const configJson = JSON.parse(fs.readFileSync(configJsonPath, 'utf-8'));
+  const existingIds: string[] = Array.isArray(configJson.package_ids) ? configJson.package_ids : [];
+  if (!existingIds.includes(newPackageId)) {
+    configJson.package_ids = [...existingIds, newPackageId];
+    fs.writeFileSync(configJsonPath, JSON.stringify(configJson, null, 2));
+  }
+}