@0xobelisk/sui-cli 1.2.0-pre.98 → 2.0.0

package/src/utils/utils.ts

@@ -1,25 +1,49 @@
 import * as fsAsync from 'fs/promises';
 import { mkdirSync, writeFileSync } from 'fs';
 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, loadMetadata } from '@0xobelisk/sui-client';
+import {
+  Dubhe,
+  NetworkType,
+  SuiMoveNormalizedModules,
+  loadMetadata,
+  getDefaultConfig
+} from '@0xobelisk/sui-client';
 import { DubheCliError } from './errors';
-import { Component, MoveType, EmptyComponent, DubheConfig } from '@0xobelisk/sui-common';
-import { TESTNET_DUBHE_HUB_OBJECT_ID, TESTNET_ORIGINAL_DUBHE_PACKAGE_ID } from './constants';
+import { Component, MoveType, DubheConfig } from '@0xobelisk/sui-common';
 
 export type DeploymentJsonType = {
   projectName: string;
   network: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
   startCheckpoint: string;
   packageId: string;
-  dappHub: 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;
-  components: Record<string, Component | MoveType | EmptyComponent>;
   resources: Record<string, Component | MoveType>;
   enums?: Record<string, string[]>;
 };
@@ -80,62 +104,57 @@ export async function getDeploymentJson(
   }
 }
 
-export async function getDeploymentDappHub(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.dappHub;
+    return deployment.dappHubId;
   } catch (_error) {
     return '';
   }
 }
 
-export async function getDubheDappHub(network: string) {
+export async function getDubheDappHubId(network: string) {
   const path = process.cwd();
   const contractPath = `${path}/src/dubhe`;
 
-  switch (network) {
-    case 'mainnet':
-      return TESTNET_DUBHE_HUB_OBJECT_ID;
-    case 'testnet':
-      return TESTNET_DUBHE_HUB_OBJECT_ID;
-    case 'devnet':
-      return TESTNET_DUBHE_HUB_OBJECT_ID;
-    case 'localnet':
-      return await getDeploymentDappHub(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 getOriginalDubhePackageId(network: string) {
   const path = process.cwd();
   const contractPath = `${path}/src/dubhe`;
 
-  switch (network) {
-    case 'mainnet':
-      return TESTNET_ORIGINAL_DUBHE_PACKAGE_ID;
-    case 'testnet':
-      return TESTNET_ORIGINAL_DUBHE_PACKAGE_ID;
-    case 'devnet':
-      return TESTNET_ORIGINAL_DUBHE_PACKAGE_ID;
-    case 'localnet':
-      return await getOldPackageId(contractPath, network);
-    default:
-      throw new Error(`Invalid network: ${network}`);
+  if (network === 'localnet') {
+    return await getOldPackageId(contractPath, network);
   }
-}
-export async function getOnchainComponents(
-  projectPath: string,
-  network: string
-): Promise<Record<string, Component | MoveType | EmptyComponent>> {
-  const deployment = await getDeploymentJson(projectPath, network);
-  return deployment.components;
-}
 
+  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
@@ -162,9 +181,22 @@ export async function getOldPackageId(projectPath: string, network: string): Pro
   return deployment.packageId;
 }
 
-export async function getDappHub(projectPath: string, network: string): Promise<string> {
+export async function getDappHubId(projectPath: string, network: string): Promise<string> {
   const deployment = await getDeploymentJson(projectPath, network);
-  return deployment.dappHub;
+  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.dappStorageId ?? '';
 }
 
 export async function getUpgradeCap(projectPath: string, network: string): Promise<string> {
@@ -182,22 +214,26 @@ export async function saveContractData(
   network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
   startCheckpoint: string,
   packageId: string,
-  dappHub: string,
+  originalPackageId: string,
+  dappHubId: string,
   upgradeCap: string,
   version: number,
-  components: Record<string, Component | MoveType | EmptyComponent>,
   resources: Record<string, Component | MoveType>,
-  enums?: Record<string, string[]>
+  enums?: Record<string, string[]>,
+  frameworkPackageId?: string,
+  dappStorageId?: string
 ) {
   const DeploymentData: DeploymentJsonType = {
     projectName,
     network,
     startCheckpoint,
     packageId,
-    dappHub,
+    originalPackageId,
+    dappHubId,
+    frameworkPackageId,
+    dappStorageId,
     upgradeCap,
     version,
-    components,
     resources,
     enums
   };
@@ -214,13 +250,14 @@ export async function saveContractData(
 export async function saveMetadata(
   projectName: string,
   network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
-  packageId: string
+  packageId: string,
+  fullnodeUrls?: string[]
 ) {
   const path = process.cwd();
 
   // Save metadata files
   try {
-    const metadata = await loadMetadata(network, packageId);
+    const metadata = await loadMetadata(network, packageId, fullnodeUrls);
     if (metadata) {
       const metadataJson = JSON.stringify(metadata, null, 2);
 
@@ -360,6 +397,46 @@ export function getPublishedTomlEntry(
   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
@@ -534,7 +611,8 @@ async function checkRpcAvailability(rpcUrl: string): Promise<boolean> {
 }
 
 export async function addEnv(
-  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet'
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  rpcUrl?: string
 ): Promise<void> {
   const rpcMap = {
     localnet: 'http://127.0.0.1:9000',
@@ -543,13 +621,13 @@ export async function addEnv(
     mainnet: 'https://fullnode.mainnet.sui.io:443/'
   };
 
-  const rpcUrl = rpcMap[network];
+  const resolvedRpcUrl = rpcUrl || rpcMap[network];
 
   // Check RPC availability first
-  const isRpcAvailable = await checkRpcAvailability(rpcUrl);
+  const isRpcAvailable = await checkRpcAvailability(resolvedRpcUrl);
   if (!isRpcAvailable) {
     throw new Error(
-      `RPC endpoint ${rpcUrl} is not available. Please check your network connection or try again later.`
+      `RPC endpoint ${resolvedRpcUrl} is not available. Please check your network connection or try again later.`
     );
   }
 
@@ -559,7 +637,7 @@ export async function addEnv(
 
     const suiProcess = spawn(
       'sui',
-      ['client', 'new-env', '--alias', network, '--rpc', rpcMap[network]],
+      ['client', 'new-env', '--alias', network, '--rpc', resolvedRpcUrl],
       {
         env: { ...process.env },
         stdio: 'pipe'
@@ -680,10 +758,13 @@ export async function getDefaultNetwork(): Promise<NetworkAlias> {
   return currentAlias as NetworkAlias;
 }
 
-export async function switchEnv(network: 'mainnet' | 'testnet' | 'devnet' | 'localnet') {
+export async function switchEnv(
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet',
+  rpcUrl?: string
+) {
   try {
     // First, try to add the environment
-    await addEnv(network);
+    await addEnv(network, rpcUrl);
 
     // Then switch to the specified environment
     return new Promise<void>((resolve, reject) => {
@@ -757,70 +838,31 @@ 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 components = Object.entries(config.components).map(([name, component]) => {
-    if (typeof component === 'string') {
-      return {
-        [name]: {
-          fields: [{ entity_id: 'address' }, { value: component }],
-          keys: ['entity_id'],
-          offchain: false
-        }
-      };
-    }
-
-    if (Object.keys(component as object).length === 0) {
-      return {
-        [name]: {
-          fields: [{ entity_id: 'address' }],
-          keys: ['entity_id'],
-          offchain: false
-        }
-      };
-    }
-
-    const fields = (component as any).fields || {};
-    const keys = (component as any).keys || ['entity_id'];
-    const offchain = (component as any).offchain ?? false;
-
-    // ensure entity_id field exists
-    if (!fields.entity_id && keys.includes('entity_id')) {
-      fields.entity_id = 'address';
-    }
-
-    // prepare fields with entity_id first
-    const fieldEntries = Object.entries(fields);
-    const entityIdField = fieldEntries.find(([key]) => key === 'entity_id');
-    const otherFields = fieldEntries.filter(([key]) => key !== 'entity_id');
-    const orderedFields = entityIdField ? [entityIdField, ...otherFields] : otherFields;
-
-    return {
-      [name]: {
-        fields: orderedFields.map(([fieldName, fieldType]) => ({
-          [fieldName]: fieldType
-        })),
-        keys: keys,
-        offchain: offchain
-      }
-    };
-  });
+  const serializeFields = (fields: Record<string, unknown> = {}) =>
+    Object.entries(fields).map(([fieldName, fieldType]) => ({
+      [fieldName]: fieldType
+    }));
 
-  const resources = Object.entries(config.resources).map(([name, resource]) => {
+  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 {
@@ -878,25 +920,6 @@ export function generateConfigJson(config: DubheConfig): string {
     };
   });
 
-  // Auto-append Dubhe framework fee state resource (entity-keyed by account string).
-  if (!resources.some((resource) => 'dapp_fee_state' in resource)) {
-    resources.push({
-      dapp_fee_state: {
-        fields: [
-          { entity_id: 'String' },
-          { base_fee: 'u256' },
-          { byte_fee: 'u256' },
-          { free_credit: 'u256' },
-          { total_bytes_size: 'u256' },
-          { total_recharged: 'u256' },
-          { total_paid: 'u256' }
-        ],
-        keys: ['entity_id'],
-        offchain: false
-      }
-    });
-  }
-
   // handle enums
   const enums = Object.entries(config.enums || {}).map(([name, enumFields]) => {
     // Sort enum values by first letter
@@ -907,10 +930,34 @@ export function generateConfigJson(config: DubheConfig): string {
     };
   });
 
+  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(
     {
-      components,
       resources,
+      objects,
+      scenes,
+      permits,
       enums
     },
     null,
@@ -988,3 +1035,238 @@ export function updateGenesisUpgradeFunction(path: string, tables: string[]) {
 
   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));
+  }
+}
+
+/**
+ * Strip the [env.<network>] section from a Move.lock file before a build.
+ *
+ * Move.lock is owned by the Sui CLI and should never be written by our CLI.
+ * We only remove stale [env.*] entries so the Sui CLI does not pick up an
+ * old non-zero address and fail with PublishErrorNonZeroAddress. After the
+ * publish/upgrade the entry is intentionally left absent — Published.toml is
+ * the canonical source of truth for deployed addresses across our toolchain.
+ */
+export function removeEnvFromMoveLock(
+  filePath: string,
+  networkType: 'mainnet' | 'testnet' | 'devnet' | 'localnet'
+): void {
+  if (!fs.existsSync(filePath)) return;
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const regex = new RegExp(`\\[env\\.${networkType}\\][\\s\\S]*?(?=\\[|$)`, 'g');
+  const updated = content.replace(regex, '');
+  fs.writeFileSync(filePath, updated, 'utf-8');
+}